<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Portal_Navigation_Configuration">
	<title>Portal Navigation Configuration</title>
	<section id="sect-Reference_Guide-Portal_Navigation_Configuration-Overview">
		<title>Overview</title>
		<para>
			There are three navigation types available to portal users:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					<xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation" />
				</para>
			</listitem>
			<listitem>
				<para>
					<xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation" />
				</para>
			</listitem>
			<listitem>
				<para>
					<xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation" />
				</para>
			</listitem>
		</itemizedlist>
		<para>
			These navigations are configured using the standard XML syntax in the file; &#34;<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>&#34;.
		</para>
		
<programlisting role="XML"><![CDATA[<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>
            <value-param>
               <name>page.templates.location</name>
               <description>the path to the location that contains Page templates</description>
               <value>war:/conf/portal/template/pages</value>
            </value-param>
            <value-param>
               <name>override</name>
               <description>The flag parameter to decide if portal metadata is overriden on restarting server
            </description>
               <value>false</value>
            </value-param>
            <object-param>
               <name>site.templates.location</name>
               <description>description</description>
               <object type="org.exoplatform.portal.config.SiteConfigTemplates">
                  <field name="location">
                     <string>war:/conf/portal</string>
                  </field>
                  <field name="portalTemplates">
                     <collection type="java.util.HashSet">
                        <value><string>basic</string></value>
                        <value><string>classic</string></value>
                     </collection>
                  </field>
                  <field name="groupTemplates">
                     <collection type="java.util.HashSet">
                        <value><string>group</string></value>
                     </collection>
                  </field>
                  <field name="userTemplates">
                     <collection type="java.util.HashSet">
                        <value><string>user</string></value>
                     </collection>
                  </field>
               </object>
            </object-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>
                     </collection>
                  </field>
                  <field name="ownerType">
                     <string>portal</string>
                  </field>
                  <field name="templateLocation">
                     <string>war:/conf/portal/</string>
                  </field>
                  <field name="importMode">
                     <string>conserve</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>
                  <field name="importMode">
                     <string>conserve</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>mary</string></value>
                        <value><string>demo</string></value>
                        <value><string>user</string></value>
                     </collection>
                  </field>
                  <field name="ownerType">
                     <string>user</string>
                  </field>
                  <field name="templateLocation">
                     <string>war:/conf/portal</string>
                  </field>
                  <field name="importMode">
                     <string>conserve</string>
                  </field>
               </object>
            </object-param>
         </init-params>
      </component-plugin>
   </component-plugins>
</component>]]>
</programlisting>
<para>
 This XML configuration defines where in the portal's war to look for configuration, and which portals, groups, and user specific views
 to include in <literal>portal/group/user</literal> navigation. Those files will be used to create an initial navigation when the portal is launched in the first time.
 That information will then be stored in the JCR content repository, and can then be modified and managed from the portal UI.
 </para>
		 
<para>
Each portal, groups and users navigation is indicated by a configuration paragraph, for example:

<programlistingco>
			<areaspec>
			<area coords="5" id="area-Reference_Guide.Portalconf.predifinedOwner" />
			<area coords="10" id="area-Reference_Guide.Portalconf.ownerType" />
			<area coords="13" id="area-Reference_Guide.Portalconf.templateLocation" />
			<area coords="16" id="area-Reference_Guide.Portalconf.importMode" />
			</areaspec>
<programlisting language="xml"><![CDATA[<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>
         </collection>
      </field>
      <field name="ownerType">
         <string>portal</string>
      </field>
      <field name="templateLocation">
         <string>war:/conf/portal/</string>
      </field>
      <field name="importMode">
         <string>conserve</string>
      </field>
   </object>
</object-param>]]>
</programlisting>
</programlistingco>

<calloutlist>
				<callout arearefs="area-Reference_Guide.Portalconf.predifinedOwner">
					<para>
						<emphasis> predefinedOwner</emphasis> define the navigation owner, portal will look for the configuration files in folder with this name, if there is no suiable folder, a default portal will be created with name is this value.
					</para>
				</callout>
				<callout arearefs="area-Reference_Guide.Portalconf.ownerType">
					<para>
						<emphasis> ownerType</emphasis> define the type of portal navigation. It may be a portal, group or user
					</para>
				</callout>
				<callout arearefs="area-Reference_Guide.Portalconf.templateLocation">
					<para>
						<emphasis> templateLocation</emphasis> the classpath where contains all portal configuration files
					</para>
				</callout>
				<callout arearefs="area-Reference_Guide.Portalconf.importMode">
					<para>
						<emphasis> importMode</emphasis> The mode for navigation import. There are 4 types of import mode:
					</para>
					<itemizedlist>
						<listitem>
						<emphasis>conserve</emphasis>: Import data when it does not exist, otherwise do nothing.
						</listitem>
						<listitem>
						<emphasis>insert</emphasis>: Import data when it does not exist, otherwise performs a strategy that adds new data only.
						</listitem>
						<listitem>
						<emphasis>merge</emphasis>: Import data when it does not exist, update data when it exists.
						</listitem>
						<listitem>
						<emphasis>rewrite</emphasis>: Overwrite data whatsoever.
						</listitem>
						</itemizedlist>
				</callout>
</calloutlist>
		</para>
	
	<para>	
Base on these parameters, portal will look for the configuration files and create a relevant portal navigation, pages and data import strategy. The portal configuration files will be stored in folders with path look like <literal>{templateLocation}/{ownerType}/{predefinedOwner}</literal>, all navigations are defined in the <literal>navigation.xml</literal> file, pages are defined in pages.xml and portal configuration is defined in <literal>{ownerType}.xml</literal>.
For example, with the above configuration, prtal will look for all configuration files from <literal>war:/conf/portal/portal/classic path.</literal>
	</para>
	</section>
	
	<section id="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation">
		<title>Portal Navigation</title>
		<para>
		The portal navigation incorporates the pages that can be accessed even when the user is not logged in assuming the applicable permissions allow the public access). For example, several portal navigations are used when a company owns multiple trademarks, and sets up a website for each of them.
		</para>
		<para>
			The <emphasis role="bold">classic</emphasis> portal is configured by four XML files in the <filename>02portal.war:/WEB-INF/conf/portal/portal/classic</filename> directory:
		</para>
		<variablelist>
			<varlistentry>
				<term>portal.xml</term>
				<listitem>
					<para>
						This file describes the layout and portlets that will be shown on all pages. The layout usually contains the banner, footer, menu and breadcrumbs portlets.
                  &PRODUCT; is extremely configurable as every view element (even the banner and footer) is a portlet.
					</para>
					
<programlisting role="XML"><![CDATA[<portal-config 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0"
   xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0">
   <portal-name>classic</portal-name>
   <locale>en</locale>
   <access-permissions>Everyone</access-permissions>
   <edit-permission>*:/platform/administrators</edit-permission>
   <properties>
      <entry key="sessionAlive">onDemand</entry>
      <entry key="showPortletInfo">1</entry>
   </properties>

   <portal-layout>
      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>BannerPortlet</portlet-ref>
            <preferences>
               <preference>
                  <name>template</name>
                  <value>par:/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</value>
                  <read-only>false</read-only>
               </preference>
            </preferences>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>NavigationPortlet</portlet-ref>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>BreadcumbsPortlet</portlet-ref>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

      <page-body> </page-body>

      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>FooterPortlet</portlet-ref>
            <preferences>
               <preference>
                  <name>template</name>
                  <value>par:/groovy/groovy/webui/component/UIFooterPortlet.gtmpl</value>
                  <read-only>false</read-only>
               </preference>
            </preferences>
         </portlet>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>

   </portal-layout>
   
</portal-config>]]>
</programlisting>
					<para>
						It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets.
					</para>
					<para>
						Each application references a portlet using the id <literal>portal#{portalName}:/{portletWarName}/{portletName}/{uniqueId}</literal>
					</para>
					<para>
						Use the <literal>page-body</literal> tag to define where &PRODUCT; should render the current page.
					</para>
					<para>
						The defined <emphasis role="bold">classic</emphasis> portal is accessible to &#34;Everyone&#34; (at <literal>/portal/public/classic</literal>) but only members of the group <literal>/platform/administrators</literal> can edit it.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>navigation.xml</term>
				<listitem>
					<para>
						This file defines all the navigation nodes of the portal. The syntax is simple using the nested node tags. Each node refers to a page defined in the <literal>pages.xml</literal> file (explained next).
					</para>
					<para>
						If the administrator want to create node labels for each language, they will have to use <literal>xml:lang</literal> attribute in the label tag with value of <literal>xml:lang</literal> is the relevant locale.
					</para>
					<para>
						Otherwise, if they want the node label is localized by resource bundle files, the <literal>#{...}</literal> syntax will be used, the enclosed property name serves as a key that is automatically passed to the internationalization mechanism. Thus the literal property name is replaced by a localized value taken from the associated properties file matching the current locale. 
					<para>	
						For example:
					</para>
					</para>

<programlisting role="XML"><![CDATA[<node-navigation 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_2 http://www.gatein.org/xml/ns/gatein_objects_1_2"
   xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_2">
   <priority>1</priority>
   <page-nodes>
      <node>
         <name>home</name>
         <label xml:lang="en">Home</label>
         <page-reference>portal::classic::homepage</page-reference>
      </node>
      <node>
         <name>sitemap</name>
         <label xml:lang="en">SiteMap</label>
         <visibility>DISPLAYED</visibility>
         <page-reference>portal::classic::sitemap</page-reference>
      </node>
      ..........
   </page-nodes>
</node-navigation>]]>
</programlisting>
					
					<para>
						This navigation tree can have multiple views inside portlets (such as the breadcrumbs portlet) that render the current view node, the site map or the menu portlets.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>pages.xml</term>
				<listitem>
					<para>
						This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags.
                  Each application can decide whether to render the portlet border, the window state, the icons or portlet's mode.
					</para>

<programlisting role="XML"><![CDATA[<page-set
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gatein_objects_1_0" 
   xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_0">

   <page>
      <name>homepage</name>
      <title>Home Page</title>
      <access-permissions>Everyone</access-permissions>
      <edit-permission>*:/platform/administrators</edit-permission>
      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>HomePagePortlet</portlet-ref>
            <preferences>
               <preference>
                  <name>template</name>
                  <value>system:/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</value>
                  <read-only>false</read-only>
               </preference>
            </preferences>
         </portlet>
         <title>Home Page portlet</title>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
         <show-application-state>false</show-application-state>
         <show-application-mode>false</show-application-mode>
      </portlet-application>
   </page>

   <page>
      <name>sitemap</name>
      <title>Site Map</title>
      <access-permissions>Everyone</access-permissions>
      <edit-permission>*:/platform/administrators</edit-permission>
      <portlet-application>
         <portlet>
            <application-ref>web</application-ref>
            <portlet-ref>SiteMapPortlet</portlet-ref>
         </portlet>
         <title>SiteMap</title>
         <access-permissions>Everyone</access-permissions>
         <show-info-bar>false</show-info-bar>
      </portlet-application>
   </page>
   .......
</page-set>]]>
</programlisting>
					
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	
	<section id="sect-Reference_Guide-Portal_Navigation_Configuration-Group_Navigation">
		<title>Group Navigation</title>
		<para>
			Group navigations are dynamically added to the user navigation at login. This allows users to see the menu of all pages assigned to any groups they belong to.
		</para>
		<para>
			The group navigation menu is configured by three XML files (<filename>navigation.xml</filename>, <filename>pages.xml</filename> and <filename>portlet-preferences.xml</filename>). The syntax used in these files is the same as those covered in <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation" />.
		</para>
		<para>
			They are also located in the <filename>{templateLocation}/{ownerType}/{predefinedOwner}</filename> directory with <literal>ownerType</literal> is <literal>group</literal> and <literal>predefinedOwner</literal> is the path to the group. For example, <filename>portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>.
		</para>
	</section>
	
	<section id="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation">
		<title>User Navigation</title>
		<para>
			User navigation is the set of nodes and pages that are owned by the user. They are part of the user's dashboard.
		</para>
		<para>
			Three files configure the user navigation (<filename>navigation.xml</filename>, <filename>pages.xml</filename> and <filename>portlet-preferences.xml</filename>). They are located in the <filename>{templateLocation}/{ownerType}/{predefinedOwner}</filename> directory with <literal>ownerType</literal> is <literal>user</literal> and <literal>predefinedOwner</literal> is username that want to create the navigation. For example, if administrator want to create navigation for user <literal>root</literal>, he has to locate the configuration files in <filename>portal.war/WEB-INF/conf/portal/user/root </filename>
		</para>
	</section>
</section>


