Portal Navigation Configuration
1 Overview
When a user logs in he sees three types of navigation tree:
- Portal Navigation
- Group Navigation
- User Navigation
they all are configured thanks to the usual XML configuration syntax in a file: "portal/WEB-INF/conf/portal/portal-configuration.xml"
<component>
<key>org.exoplatform.portal.config.UserPortalConfigService</key>
<type>org.exoplatform.portal.config.UserPortalConfigService</type>
<component-plugins>
<component-plugin>
<name>new.portal.config.user.listener</name>
<set-method>initListener</set-method>
<type>org.exoplatform.portal.config.NewPortalConfigListener</type>
<description>this listener init the portal configuration</description>
<init-params>
<value-param>
<name>default.portal</name>
<description>The default portal for checking db is empty or not</description>
<value>classic</value>
</value-param>
<object-param>
<name>portal.configuration</name>
<description>description</description>
<object type="org.exoplatform.portal.config.NewPortalConfig">
<field name="predefinedOwner">
<collection type="java.util.HashSet">
<value><string>classic</string></value>
<value><string>webos</string></value>
</collection>
</field>
<field name="ownerType"><string>portal</string></field>
<field name="templateLocation"><string>war:/conf/portal</string></field>
</object>
</object-param>
<object-param>
<name>group.configuration</name>
<description>description</description>
<object type="org.exoplatform.portal.config.NewPortalConfig">
<field name="predefinedOwner">
<collection type="java.util.HashSet">
<value><string>platform/administrators</string></value>
<value><string>platform/users</string></value>
<value><string>platform/guests</string></value>
<value><string>organization/management/executive-board</string></value>
</collection>
</field>
<field name="ownerType"><string>group</string></field>
<field name="templateLocation"><string>war:/conf/portal</string></field>
</object>
</object-param>
<object-param>
<name>user.configuration</name>
<description>description</description>
<object type="org.exoplatform.portal.config.NewPortalConfig">
<field name="predefinedOwner">
<collection type="java.util.HashSet">
<value><string>root</string></value>
<value><string>john</string></value>
<value><string>marry</string></value>
<value><string>demo</string></value>
</collection>
</field>
<field name="ownerType"><string>user</string></field>
<field name="templateLocation"><string>war:/conf/portal</string></field>
</object>
</object-param>
</init-params>
</component-plugin>
</component-plugins>
In the previous XML file we define, for the 3 navigation types, some sets of predefined portal, groups or users that will have some XML files inside the war. Those files will be used to create an initial navigation the first time the portal is launched. That information will then be stored in the JCR and hence only modifiable from the portal UI.
2 Portal Navigation
The portal navigation incorporates the pages that can be accessed even when the user is not logged in (if the permission allow a public access). Several portal navigations are used for example when a company has several trademarks and each trade would have its own website.
The configuration of a portal called "classic" is made by providing 4 XML files under the directory portal/WEB_INF/conf/portal/portal/classic:
2.1 Portal.xml
That file describes the layout and portlets that will be shown for all pages. Usually the layout contains the banner, footer, menu, breadcrumbs portlets. Indeed, in eXo, every area is a portlet even the banner and footer which makes the platform extremely configurable.
<?xml version="1.0" encoding="ISO-8859-1"?>
<portal-config>
<portal-name>classic</portal-name>
<locale>en</locale>
<!--factory-id>office</factory-id--> <!-- factory-id has been used until portal 2.2 -->
<access-permissions>Everyone</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
<creator>root</creator>
<portal-layout>
<application>
<instance-id>portal#classic:/web/BannerPortlet/banner</instance-id>
<show-info-bar>false</show-info-bar>
</application>
<application>
<instance-id>portal#classic:/web/NavigationPortlet/toolbar</instance-id>
<show-info-bar>false</show-info-bar>
</application>
<application>
<instance-id>portal#classic:/web/BreadcumbsPortlet/breadcumbs</instance-id>
<show-info-bar>false</show-info-bar>
</application>
<page-body> </page-body>
<application>
<instance-id>portal#classic:/web/FooterPortlet/footer</instance-id>
<show-info-bar>false</show-info-bar>
</application>
</portal-layout>
</portal-config>
Even if not shown in the previous XML file, it is also possible to apply a nested container that can also contain portlets. Containers are then responsible of the layout of their children (row, column or tabs containers exist).
Each application references a portlet using the id portal#{portalName}:/{portletWarName}/{portletName}/{uniqueId}
In order to define at which location eXo Portal shall render the current page use the page-body tag.
The defined classic portal is accessible to "Everyone" (that means it can be accessed through the URL /portal/public/classic) but only members of the group /platform/administrators can edit it.
2.2 Navigation.xml
This file defines all the navigation nodes the portal will have. The syntax is simple as we get nested node tags. Each node references a page that is defined in the next XML file.
If the label #{} is used then it means the i18n mechanism is activated and that the real label to render is taken from an associated properties file for the current locale.
<?xml version="1.0" encoding="UTF-8"?>
<node-navigation>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<priority>1</priority>
<page-nodes>
<node>
<uri>home</uri>
<name>home</name>
<label>#{portal.classic.home}</label>
<page-reference>portal::classic::homepage</page-reference>
</node>
<node>
<uri>webexplorer</uri>
<name>webexplorer</name>
<label>#{portal.classic.webexplorer}</label>
<page-reference>portal::classic::webexplorer</page-reference>
</node>
</page-nodes>
</node-navigation>
This navigation tree can have multiple views inside portlets such as the breadcrumbs that render the current view node, the site map or the menu portlets.
Warning: For top nodes, the
uri and the
name of your navigation nodes must have the
same value. For the other nodes the uri is composed like
<uri>contentmanagement/fileexplorer</uri> where 'contentmanagement' is the name of the parent node and 'fileexplorer' the name of the node (
<name>fileexplorer</name>).
2.3 Pages.xml
This XML file structure is very similar to portal.xml and it can also contain container tags. Each application can decide if it wishes to render the portlet border, the window state icons or the mode.
<?xml version="1.0" encoding="ISO-8859-1"?>
<page-set>
<page>
<page-id>portal::classic::homepage</page-id>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<name>homepage</name>
<title>Home Page</title>
<access-permissions>Everyone</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
<application>
<instance-id>portal#classic:/web/HomePagePortlet/homepageportlet</instance-id>
<title>Home Page portlet</title>
<show-info-bar>false</show-info-bar>
<show-application-state>false</show-application-state>
<show-application-mode>false</show-application-mode>
</application>
</page>
<page>
<page-id>portal::classic::webexplorer</page-id>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<name>webexplorer</name>
<title>Web Explorer</title>
<access-permissions>*:/platform/users</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
<application>
<instance-id>group#platform/users:/web/BrowserPortlet/WebExplorer</instance-id>
<title>Web Explorer</title>
<show-info-bar>false</show-info-bar>
</application>
</page>
</page-set>2.4 Portlet-preferences.xml
Porlet instances can be associated with portlet-preferences that override the one defined in the usual portlet.xml file of the portlet application WAR.
<?xml version="1.0" encoding="ISO-8859-1"?>
<portlet-preferences-set>
<portlet-preferences>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<window-id>portal#classic:/web/BannerPortlet/banner</window-id>
<preference>
<name>template</name>
<value>par:/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</value>
<read-only>false</read-only>
</preference>
</portlet-preferences>
<portlet-preferences>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<window-id>portal#classic:/web/NavigationPortlet/toolbar</window-id>
<preference>
<name>useAJAX</name>
<value>true</value>
<read-only>false</read-only>
</preference>
</portlet-preferences>
<portlet-preferences>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<window-id>portal#classic:/web/FooterPortlet/footer</window-id>
<preference>
<name>template</name>
<value>par:/groovy/groovy/webui/component/UIFooterPortlet.gtmpl</value>
<read-only>false</read-only>
</preference>
</portlet-preferences>
<portlet-preferences>
<owner-type>portal</owner-type>
<owner-id>classic</owner-id>
<window-id>portal#classic:/web/GroovyPortlet/groovyportlet</window-id>
<preference>
<name>template</name>
<value>par:/groovy/groovy/webui/component/UIGroovyPortlet.gtmpl</value>
<read-only>false</read-only>
</preference>
</portlet-preferences>
</portlet-preferences-set>3 Group Navigation
Group navigations are dynamically added (mounted) to the user navigation when he logs in. This means that a user sees in his menu also all the pages that are assigned to the groups to which he belongs to.
Here only 3 XML files are necessary: navigation.xml, pages.xml and portlet-preferences.xml. The syntax is the same as for portal navigations.
The 3 files are located in the directory: "portal/WEB-INF/conf/portal/group/group-name-path/" like for example "portal/WEB-INF/conf/portal/group/platform/administrators/"
4 User Navigation
The user navigation is the set of nodes and pages that is owned by a user. You can see that part as the user dashboard. The files needed are navigation.xml, pages.xml, portlet-preferences.xml. You will also find gadgets.xml (formerly called widgets.xml) which defines the gadgets (widgets) that will be located in the user workspace. The user workspace is located at the left hand side, the access is restricted to some privileged users, see
Predefined User Configuration.
Those files are located in the directory "portal/WEB-INF/conf/portal/users/{userName}"
<?xml version="1.0" encoding="ISO-8859-1"?>
<widgets>
<owner-type>user</owner-type>
<owner-id>root</owner-id>
<container id="Information">
<name>Information</name>
<description>Information's Description</description>
<application>
<instance-id>user#root:/eXoWidgetWeb/WelcomeWidget/WelcomeWidget1</instance-id>
<application-type>eXoWidget</application-type>
</application>
<application>
<instance-id>user#root:/eXoWidgetWeb/StickerWidget/StickerWidget</instance-id>
<application-type>eXoWidget</application-type>
</application>
<application>
<instance-id>user#root:/eXoWidgetWeb/InfoWidget/InfoWidget1</instance-id>
<application-type>eXoWidget</application-type>
</application>
</container>
<container id="Calendar">
<name>Calendar</name>
<description>Calendar's Description</description>
<application>
<instance-id>user#root:/eXoWidgetWeb/CalendarWidget/CalendarWidget</instance-id>
<application-type>eXoWidget</application-type>
</application>
</container>
</widgets>
Note that when you develop a portal, we advise you to use the XML instead of the User Interface as XML will allow you to provide a preconfigured package to your customer. But as each time you start the server the first time, the XML files are stored in the JCR, it will be necessary to remove the database (the jcr leverages a database). During the development phase using tomcat it simply means to delete the directory: exo-tomcat/temp
5 Tips
5.1 Direct External Links
If you wish to add a link to a URL outside the portal you you first have to define a "page" which will not be used. Then add the URL to the navigation.
pages.xml:
<!-- Community Documentation -->
<page>
<owner-type>portal</owner-type>
<owner-id>website</owner-id>
<name>documentation</name>
<title>Documentation</title>
<access-permissions>Everyone</access-permissions>
<edit-permission>*:/platform/administrators</edit-permission>
</page>:
<node>
<uri>http://wiki.exoplatform.com/xwiki/bin/view/Main/WebHome</uri>
<name>documentation</name>
<label>#{portal.classic.documentation}</label>
<page-reference>portal::website::documentation</page-reference>
</node>: Direct external links were not a design goal. Currently you cannot modify the URL using the portal interface, you must change it in the configuration files or modify the underlying database table.
