Author: mstruk Date: 2010-03-23 07:50:41 -0400 (Tue, 23 Mar 2010) New Revision: 2348 Modified: portal/trunk/docs/reference-guide/en/modules/Foundations.xml portal/trunk/docs/reference-guide/en/modules/Introduction.xml portal/trunk/docs/reference-guide/en/modules/configuration/Authentication_Token_Configuration.xml portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml portal/trunk/docs/reference-guide/en/modules/configuration/Default_Portal_Configuration.xml portal/trunk/docs/reference-guide/en/modules/configuration/EMailService_Configuration.xml portal/trunk/docs/reference-guide/en/modules/configuration/IDM_Configuration.xml portal/trunk/docs/reference-guide/en/modules/configuration/Portal_Navigation_Configuration.xml Log: reference-guide edits - first, and second chapter mostly Modified: portal/trunk/docs/reference-guide/en/modules/Foundations.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Foundations.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/Foundations.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -9,11 +9,14 @@ <section id="sect-Reference_Guide-Foundations-Kernel"> <title>GateIn Kernel</title> <para> - &PRODUCT; is built on top of a kernel, and a set of services that exist in two scopes. - First scope is represented by <emphasis role="bold">RootContainer</emphasis> - it contains services that exist independently of any portal container, and can be accessed by all portals. + &PRODUCT; is built as a set of services on top of a dependency injection kernel. The kernel provides configuration, lifecycle handling, component scopes, and some core services. </para> <para> - Second scope is portal-private in the form of <emphasis role="bold">PortalContainer</emphasis>. Each portal live in an instance of PortalContainer. + Service components exist in two scopes. First scope is represented by <emphasis role="bold">RootContainer</emphasis> - it contains services that exist independently of any portal, and can be + accessed by all portals. + </para> + <para> + Second scope is portal-private in the form of <emphasis role="bold">PortalContainer</emphasis>. Each portal lives in an instance of PortalContainer. This scope contains services that are common for a set of portals, and services which should not be shared by all portals. </para> <para> @@ -525,7 +528,7 @@ try { SourceStorage sourceStorage = - (SourceStorage) pcontainer.getComponentInstanceOfType(SourceStorage.class); + (SourceStorage) portalContainer.getComponentInstanceOfType(SourceStorage.class); ... } catch (RuntimeException e) Modified: portal/trunk/docs/reference-guide/en/modules/Introduction.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Introduction.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/Introduction.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -7,7 +7,7 @@ <title>Introduction</title> <para> - &PRODUCT; is the merge of two mature Java projects; JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single j2ee deployment archive. The aim is to provide an intuitive user-friendly portal and a framework to address the needs of today's Web 2.0 applications. + &PRODUCT; is the merge of two mature Java projects; JBoss Portal and eXo Portal. This new community project takes the best of both offerings and incorporates them into a single portal framework. The aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today's Web 2.0 applications. </para> <mediaobject> <imageobject role="html"> @@ -18,7 +18,7 @@ </imageobject> </mediaobject> <para> - This book provides deep-dive information about the installation and configuration of the services provide by GateIn. + This book provides a deep-dive information about installation and configuration of the services provided by GateIn. </para> <!-- <para> Modified: portal/trunk/docs/reference-guide/en/modules/configuration/Authentication_Token_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/Authentication_Token_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/Authentication_Token_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -6,22 +6,24 @@ <section id="sect-Reference_Guide-Authentication_Token_Configuration"> <title>Authentication Token Configuration</title> <section id="sect-Reference_Guide-Authentication_Token_Configuration-What_is_token_service"> - <title>What is token service</title> + <title>What is Token Service?</title> <para> - <emphasis>Token service</emphasis> is used in authentication. + <emphasis>Token Service</emphasis> is used in authentication. </para> <para> The token system prevents user account information being sent in clear text mode for inbound requests. This increases authentication security. </para> <para> - Token service allows adminitrators to create, delete, retrieve and clean tokens as required. The service also defines the validity period of any given token. The token becomes invalid once this period has expired, . The life-time definition must be configured. + Token service allows administrators to create, delete, retrieve and clean tokens as required. The service also defines a validity period of any given token. + The token becomes invalid once this period expires. This period can be configured through <emphasis>life-time</emphasis> configuration property. </para> </section> <section id="sect-Reference_Guide-Authentication_Token_Configuration-Implement_token_services_API"> - <title>Implement token service&#39;s API</title> + <title>Implementing the Token Service API</title> <para> - All token services used in &PRODUCT;&#39;s authentication must be a subclass of an abstract class <emphasis role="bold">AbstractTokenService</emphasis>. The following example shows how the token-service manipulates its tokens. + All token services used in &PRODUCT;&#39;s authentication must be implemented by subclassing an <emphasis role="bold">AbstractTokenService</emphasis> abstract class. + The following <emphasis role="bold">AbstractTokenService</emphasis> methods represent the contract between authentication runtime, and a token service implementation. </para> <programlisting role="JAVA"> @@ -37,15 +39,15 @@ </section> <section id="sect-Reference_Guide-Authentication_Token_Configuration-Configure_token_services"> - <title>Configure token services</title> + <title>Configuring token services</title> <para> - Token services configuration includes specifying the validity period time of token in the configuration file. The token service is configured as a portal component. + Token services configuration includes specifying the token validity period. The token service is configured as a portal component (in portal scope, as opposed to root scope - more about that in Foundations chapter). </para> <para> In the example below, <emphasis>CookieTokenService</emphasis> is a subclass of <emphasis role="bold">AbstractTokenService</emphasis> so it has a property which specifies the validity period of the token. </para> <para> - The token service will initiate this validity property by looking for an <parameter>init-param</parameter> named &#34;<emphasis role="bold">service.configuration</emphasis>&#34;. + The token service will initialize this validity property by looking for an <parameter>init-param</parameter> named &#34;<emphasis role="bold">service.configuration</emphasis>&#34;. </para> <para> This property must have three values. @@ -89,7 +91,7 @@ </programlistingco> <para> - In this case, the service&#39;s name is &#34;<emphasis role="bold">jcr-token</emphasis>&#34; and the token&#39;s expiration time is a week. + In this case, the service&#39;s name is &#34;<emphasis role="bold">jcr-token</emphasis>&#34; and the token&#39;s expiration time is one week. </para> <para> &PRODUCT; supports <emphasis>four</emphasis> timing units: Modified: portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -13,9 +13,9 @@ <title>Overview</title> <para>&PRODUCT; has two different database dependencies. One is the - identity service configuration, which depends on the Hibernate. The other + identity service configuration, which depends on Hibernate. The other database dependency is Java content repository (JCR) service, which - depends on the native JDBC API and it can integrate with any existing + depends on JDBC API, and can integrate with any existing datasource implementation.</para> <para>When you change the database configuration for the first time, @@ -23,8 +23,8 @@ database user has the appropriate permissions).</para> <para>&PRODUCT; assumes the default encoding for your database is - <literal>latin1</literal> . You will need to change this parameter for - your database in order to work properly.</para> + <literal>latin1</literal>. You may need to change this parameter for + your database in order for &PRODUCT; to work properly.</para> </section> <section id="sect-Reference_Guide-Database_Configuration-JCR_database_configuration"> @@ -36,7 +36,7 @@ <para>For Tomcat, the file is located at <programlisting>$TOMCAT_HOME/gatein/conf/configuration.properties</programlisting></para> <para>And edit the values of driver, url, username and password with the - values for your JDBC connection (Please refer to your database JDBC driver + values for your JDBC connection (please, refer to your database JDBC driver documentation).</para> <programlisting role="XML">gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver @@ -45,37 +45,36 @@ gatein.jcr.datasource.password= </programlisting> - <para>In that case, the name of the database is "jdbcjcr_${name}", ${name} - should be part of the database name, as it is dynamically replaced by the - name of the portal container extension (for instance + <para>By default, the name of the database is "jdbcjcr_${name}" - ${name} + should be a part of the database name, as it is dynamically replaced by the + name of the portal container extension (for instance, gatein-sample-portal.ear defines "sample-portal" as container name and the default portal defines "portal" as container name).</para> - <para>In the case of HSQL the databases are created automatically, for any + <para>In the case of HSQL the databases are created automatically. For any other database you will need to create a database named jdbcjcr_portal - (and "jdbcjcr_sample-portal" if you kept gatein-sample-portal.ear in - $JBOSS_HOME/server/default/deploy. Note that some database wont accept '-' - in a database name and you will have to delete + (and "jdbcjcr_sample-portal" if you have gatein-sample-portal.ear in + $JBOSS_HOME/server/default/deploy - note that some databases don't accept '-' + in the database name, so you may have to remove $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear)</para> - <para>Make sure the user has rights to create tables on jdbcjcr_portal and - to update them as during the first startup they will be automatically - created.</para> + <para>Make sure the user has rights to create tables on jdbcjcr_portal, and + to update them as they will be automatically created during the first startup .</para> - <para>Also add the JDBC driver into the classpath, for instance in - $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib if you are running on + <para>Also add your database's JDBC driver into the classpath - you can put it in + $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib, if you are running on Tomcat)</para> <para>MySQL example:</para> - <para>Let's configure our JCR to store data in MySQL, let's pretend we + <para>Let's configure our JCR to store data in MySQL. Let's pretend we have a user named "gateinuser" with a password "gateinpassword". We would - create a database "mygateindb_portal" (Remember that _portal is required) - and assign him the rights to create tables.</para> + create a database "mygateindb_portal" (remember that _portal is required), + and assign our user the rights to create tables.</para> - <para>Then we need to add the MySQL JDBC connector in the classpath and + <para>Then we need to add MySQL's JDBC driver to the classpath, and finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration - with:<programlisting>gatein.jcr.datasource.driver=com.mysql.jdbc.Driver + to contain the following:<programlisting>gatein.jcr.datasource.driver=com.mysql.jdbc.Driver gatein.jcr.datasource.url=jdbc:mysql://localhost:3306/mygateindb${container.name.suffix} gatein.jcr.datasource.username=gateinuser gatein.jcr.datasource.password=gateinpassword @@ -85,13 +84,13 @@ <section> <title>Configuring the database for the default identity store</title> - <para>By default users are stored in database. To change the database to + <para>By default, users are stored in a database. To change the database in which to store users, you will need to edit the file:</para> <para><programlisting>$JBOSS_HOME/server/default/conf/gatein/configuration.properties</programlisting>For Tomcat, the file is located at <programlisting>$TOMCAT_HOME/gatein/conf/configuration.properties</programlisting></para> - <para>You will find the same configuration as in + <para>You will find the same kind of configuration as in jcr-configuration.xml:<programlisting>gatein.idm.datasource.driver=org.hsqldb.jdbcDriver gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name} gatein.idm.datasource.username=sa Modified: portal/trunk/docs/reference-guide/en/modules/configuration/Default_Portal_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/Default_Portal_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/Default_Portal_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -8,14 +8,23 @@ <section id="sect-Reference_Guide-Default_Portal_Configuration-Overview"> <title>Overview</title> <para> - The default portal will be accessed if the user doesn&#39;t specify another portal. For example: <literal>http://hostname:port/portal/</literal>. The default portal also be used at startup to determine if the database is empty. + &PRODUCT;'s default home page URL is <literal>http://${hostname}:${port}/portal/</literal>. + There may be multiple independent portals deployed in parallel at any given time, each of which has its root + context (i.e.: <literal>http://${hostname}:${port}/sample-portal/</literal>). + Each portal is internally composed of one or more, what we again call 'portals'. There needs to be at least + one such portal - the default one is called 'classic'. When accessing &PRODUCT;'s default home page URL, you + are automatically redirected to 'classic' portal. + + The default portal performs another important task. When starting up &PRODUCT; for the first time, its + JCR database will be empty (that's where portals keep their runtime-configurable settings). + It's the default portal that's used to detect this, and to trigger automatic data initialization. </para> </section> <section id="sect-Reference_Guide-Default_Portal_Configuration-Configuration"> <title>Configuration</title> <para> - The example configuration file below is found at: &#34;<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>&#34;. + The following example configuration can be found at: &#34;<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>&#34;. </para> <programlisting role="XML">&#60;component&#62; @@ -33,15 +42,23 @@ &#60;description&#62;The default portal for checking db is empty or not&#60;/description&#62; &#60;value&#62;classic&#60;/value&#62; &#60;/value-param&#62; - .......... + ... &#60;/init-params&#62; &#60;/component-plugin&#62; &#60;/component-plugins&#62; &#60;/component&#62; </programlisting> <para> - In this example the <emphasis role="bold">classic</emphasis> portal has been set as the default. Note that the definition should be as a initial parameter of the NewPortalConfigListener component-plugin. + In this example the <emphasis role="bold">classic</emphasis> portal has been set as the default. </para> + <note> + <para> + Components, component-plugins, and init-params are explained in Foundations chapter. For now just note how + <literal>NewPortalConfigListener</literal> component-plugin is used to add configuration to + <literal>UserPortalConfigService</literal>, which is designed in this way to allow other components + to add configuration to it. + </para> + </note> </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/configuration/EMailService_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/EMailService_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/EMailService_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -10,18 +10,18 @@ <section id="sect-Reference_Guide-EMail_Service_Configuration-Overview"> <title>Overview</title> - <para>&PRODUCT; has a service to send e-mails that requires to be configured - before it can work properly. This service is used to send e-mails to users who forgot - their username or password for instance.</para> + <para>&PRODUCT; includes an e-mail sending service that needs to be configured + before it can function properly. This service, for instance, is used to send e-mails to users who forgot + their password or username.</para> </section> <section id="sect-Reference_Guide-EMail_Service_Configuration-Parameters"> - <title>Configuring the e-mail outgoing account</title> + <title>Configuring the outgoing e-mail account</title> - <para>The e-mail service can use any SMTP account that needs to be configured in + <para>The e-mail service can use any SMTP account configured in $JBOSS_HOME/server/default/conf/gatein/configuration.properties - (Or $TOMCAT_HOME/gatein/conf/configuration.properties if you are using Tomcat).</para> + (or $TOMCAT_HOME/gatein/conf/configuration.properties if you are using Tomcat).</para> <para>The relevant section looks like:</para> @@ -35,7 +35,12 @@ gatein.email.smtp.socketFactory.port=465 gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory</programlisting> - <para>It is preconfigured for GMail so that any GMail account can be easily used (Just use a full gmail address - as username and fill-in the password.</para> + <para>It is preconfigured for GMail, so that any GMail account can easily be used (simply use the full GMail address + as username, and fill-in the password.</para> + + <para>In corporate environments you will want to use your corporate SMTP gateway. When using it over SSL, + like in default configuration, you may need to configure a certificate truststore, containing your SMTP server's + public certificate. Depending on the key sizes, you may then also need to install Java Cryptography Extension (JCE) + Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.</para> </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/configuration/IDM_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/IDM_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/IDM_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -2,16 +2,16 @@ <!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; -<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> -%BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-PicketLink_IDM_integration"> <title>PicketLink IDM integration</title> <para> - &PRODUCT; uses the PicketLink IDM component to retain necessary identity information (user, groups, memberships, etc.). While legacy interfaces are still used (org.exoplatform.services.organization) for identity management, the wrapper implementation delegates to the PicketLink IDM framework. + &PRODUCT; uses PicketLink IDM component to keep the necessary identity information (users, groups, memberships, etc.). + While legacy interfaces are still used (org.exoplatform.services.organization) for identity management, + there is a wrapper implementation that delegates to PicketLink IDM framework. </para> <para> - This section doesn&#39;t provide information about PicketLink IDM and its configuration. Please refer to the appropriate project documentation (<ulink url="http://jboss.org/picketlink/IDM.html" />) for further information. + This section doesn&#39;t provide information about PicketLink IDM and its configuration. Please, refer to the appropriate project documentation (<ulink url="http://jboss.org/picketlink/IDM.html" />) for further information. </para> <note> <para> @@ -21,16 +21,18 @@ <para> The identity model represented in &#39;<emphasis role="bold">org.exoplatform.services.organization</emphasis>&#39; interfaces and the one used in <emphasis role="bold">PicketLink IDM</emphasis> have some major differences. </para> + <para>TODO: tell more about org.exoplatform.services.organization</para> <para> - For example: the <emphasis role="bold">PicketLink IDM</emphasis> provides greater abstraction. It is possible for groups in the <emphasis role="bold">IDM</emphasis> framework to form memberships with many parents (which requires recursive ID translation) while the GateIn model allows only pure tree like membership structures. + For example: <emphasis role="bold">PicketLink IDM</emphasis> provides greater abstraction. It is possible for groups in <emphasis role="bold">IDM</emphasis> framework to form memberships with many parents (which requires recursive ID translation), + while GateIn model allows only pure tree-like membership structures. </para> <para> - Additionally the GateIn <emphasis>membership</emphasis> concept needs to be translated into the IDM <emphasis>Role</emphasis> concept. Therefore <emphasis role="bold">PicketLink IDM</emphasis> model is used in a limited way. All these translations are applied by the integration layer. + Additionally, GateIn <emphasis>membership</emphasis> concept needs to be translated into the IDM <emphasis>Role</emphasis> concept. Therefore <emphasis role="bold">PicketLink IDM</emphasis> model is used in a limited way. All these translations are applied by the integration layer. </para> <section id="sect-Reference_Guide-PicketLink_IDM_integration-Configuration_files"> <title>Configuration files</title> <para> - The main configuration file is <emphasis role="bold">idm-configuration</emphasis>: + The main configuration file is <emphasis role="bold">idm-configuration.xml</emphasis>: </para> <programlistingco> <areaspec> @@ -121,7 +123,7 @@ <calloutlist> <callout arearefs="area-Reference_Guide-PicketLink_IDM_integration-Configuration_files-JBossIDMServiceImpl"> <para> - The <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</emphasis> service has following options: + The <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMServiceImpl</emphasis> service has the following options: </para> <variablelist> <varlistentry> @@ -150,7 +152,7 @@ <term>hibernate.annotations</term> <listitem> <para> - A list of annotated classes that will be added to hibernate configuration. + A list of annotated classes that will be added to Hibernate configuration. </para> </listitem> </varlistentry> @@ -169,7 +171,7 @@ (value-param) </para> <para> - If the &#39;config&#39; parameter is not provided this parameter will be used to perform JNDI lookup for IdentitySessionFactory + If the &#39;config&#39; parameter is not provided, this parameter will be used to perform JNDI lookup for IdentitySessionFactory </para> </listitem> </varlistentry> @@ -180,7 +182,7 @@ (value-param) </para> <para> - The name of a realm that should be used to obtain proper IdentitySession. The default is &#39;PortalRealm&#39;. + The realm name that should be used to obtain proper IdentitySession. The default is &#39;PortalRealm&#39;. </para> </listitem> </varlistentry> @@ -194,7 +196,7 @@ </para> <para> <emphasis role="bold">org.exoplatform.services.organization.idm.PicketLinkIDMOrganizationServiceImpl</emphasis> - service has following options defined as fields of object-param type + service has the following options defined as fields of object-param of type <emphasis role="bold">org.exoplatform.services.organization.idm.Config</emphasis>: </para> <variablelist> @@ -226,7 +228,8 @@ <term>useParentIdAsGroupType</term> <listitem> <para> - This parameter stores the parent ID path as a group type in PicketLink IDM for any IDs not mapped with a specific type in 'groupTypeMappings'. If this option is set to false and no mappings are provided under 'groupTypeMappings' only one group with a given name can exist in the &PRODUCT; group tree. + This parameter stores the parent ID path as a group type in PicketLink IDM for any IDs not mapped with a specific type in 'groupTypeMappings'. + If this option is set to false, and no mappings are provided under 'groupTypeMappings', then only one group with the given name can exist in the &PRODUCT; group tree. </para> </listitem> </varlistentry> @@ -242,7 +245,7 @@ <term>associationMembershipType</term> <listitem> <para> - If this option is used then each Membership created with MembrshipType that is equal to the value specified here will be stored in PicketLink IDM as simple Group-User association. + If this option is used, then each Membership, created with MembrshipType that is equal to the value specified here, will be stored in PicketLink IDM as simple Group-User association. </para> </listitem> </varlistentry> @@ -250,13 +253,13 @@ <term>groupTypeMappings</term> <listitem> <para> - This parameter maps groups added with the &PRODUCT; API as a child of a given group ID and stores them with a given group type name in PicketLink IDM. + This parameter maps groups added with &PRODUCT; API as children of a given group ID, and stores them with a given group type name in PicketLink IDM. </para> <para> - If the parent ID ends with "/*" then all child groups will have the mapped group type. Otherwise only direct (first level) children will use this type. + If the parent ID ends with "/*", then all child groups will have the mapped group type. Otherwise, only direct (first level) children will use this type. </para> <para> - This can be leveraged by LDAP if LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in the &PRODUCT; group tree while all other groups will remain in the database. + This can be leveraged by LDAP if LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in &PRODUCT; group tree, while all other groups will remain in the database. </para> </listitem> </varlistentry> @@ -264,10 +267,10 @@ <term>forceMembershipOfMappedTypes</term> <listitem> <para> - Groups stored in PicketLink IDM with a type mapped in 'groupTypeMappings' will automatically be a member under the mapped parent. Group relationships linked by PicketLink IDM group association will not be necessary. + Groups stored in PicketLink IDM with a type mapped in 'groupTypeMappings' will automatically be members under the mapped parent. Group relationships linked by PicketLink IDM group association will not be necessary. </para> <para> - This parameter can be set to false if all groups are added via &PRODUCT; APIs. This may be useful with LDAP configuration as, when set to true, it will make every entry added to LDAP appear in &PRODUCT;. This is not true for entries added via the &PRODUCT; management UI, however. + This parameter can be set to false if all groups are added via &PRODUCT; APIs. This may be useful with LDAP configuration as, when set to true, it will make every entry added to LDAP appear in &PRODUCT;. This, however, is not true for entries added via &PRODUCT; management UI. </para> </listitem> </varlistentry> @@ -275,13 +278,13 @@ <term>ignoreMappedMembershipType</term> <listitem> <para> - If "associationMembershipType" option is used and this option is set to true then Membership with MembershipType configured to be stored as PicketLink IDM association will not be stored as PicketLink IDM Role. + If "associationMembershipType" option is used, and this option is set to true, then Membership with MembershipType configured to be stored as PicketLink IDM association will not be stored as PicketLink IDM Role. </para> </listitem> </varlistentry> </variablelist> <para> - Additionally <emphasis role="bold">JBossIDMOrganizationServiceImpl</emphasis> uses those defaults to perform identity management operations + Additionally, <emphasis role="bold">JBossIDMOrganizationServiceImpl</emphasis> uses those defaults to perform identity management operations </para> <itemizedlist> <listitem> @@ -306,10 +309,10 @@ <para> - A sample <emphasis role="bold">PicketLink IDM</emphasis> configuration file is shown below. To understand all the options present in it please refer to the PicketLink IDM Reference Guide + A sample <emphasis role="bold">PicketLink IDM</emphasis> configuration file is shown below. To understand all the options it contains, please refer to the PicketLink IDM Reference Guide </para> -<programlisting>&#60;jboss-identity xmlns=&#34;urn:jboss:identity:idm:config:v1_0_beta&#34; +<programlisting role="XML">&#60;jboss-identity xmlns=&#34;urn:jboss:identity:idm:config:v1_0_beta&#34; xmlns:xsi=&#34;http://www.w3.org/2001/XMLSchema-instance&#34; xsi:schemaLocation=&#34;urn:jboss:identity:idm:config:v1_0_alpha identity-config.xsd&#34;&#62; &#60;realms&#62; Modified: portal/trunk/docs/reference-guide/en/modules/configuration/Portal_Navigation_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/configuration/Portal_Navigation_Configuration.xml 2010-03-23 10:52:21 UTC (rev 2347) +++ portal/trunk/docs/reference-guide/en/modules/configuration/Portal_Navigation_Configuration.xml 2010-03-23 11:50:41 UTC (rev 2348) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Portal_Navigation_Configuration-Overview"> <title>Overview</title> <para> - Three types of navigation are available to portal users: + There are three types of navigation available to portal users: </para> <itemizedlist> <listitem> @@ -28,7 +28,7 @@ </listitem> </itemizedlist> <para> - These navigations are configured with standard XML syntax in the file; &#34;<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>&#34;. + These navigations are configured using standard XML syntax in the file; &#34;<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>&#34;. </para> <programlisting role="XML">&#60;component&#62; @@ -97,24 +97,29 @@ &#60;/component-plugins&#62; </programlisting> <para> - This XML file defines, for the three navigations, which sets of portals, groups or users will have XML files inside the apprpriate <literal>war</literal>. 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 is then modifiable from the portal UI. - </para> + This XML configuration defines where in the portal's war to look for configuration, and what portals, groups, and user specific views + to include in portal/group/user navigation. Those files will be used to create an initial navigation, the first time the portal is launched. + That information will then be stored in JCR content repository, and can then be modified, and managed from the portal UI. + </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 when the user is not logged in (if the applicable permissions allow public access). For example; several portal navigations are used when a company has multiple trademarks and each trade has its own website. + The portal navigation incorporates the pages that can be accessed even when a user is not logged in + (assuming the applicable permissions allow public access). For example; several portal navigations are used + when a company owns multiple trademarks, and sets up a web site 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: + The <emphasis role="bold">classic</emphasis> portal is configured by four XML files in <filename>02portal.war:/WEB-INF/conf/portal/portal/classic</filename> directory: </para> <variablelist> <varlistentry> - <term>Portal.xml</term> + <term>portal.xml</term> <listitem> <para> - This file describes the layout and portlets that will be shown on all pages. Usually the layout contains the banner, footer, menu and breadcrumbs portlets. &PRODUCT; is extremely configurable as every area (even the banner and footer) is a portlet. + This file describes the layout and portlets that will be shown on all pages. Usually the layout 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">&#60;?xml version=&#34;1.0&#34; encoding=&#34;ISO-8859-1&#34;?&#62; @@ -153,7 +158,7 @@ &#60;/portal-config&#62; </programlisting> <para> - It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible of the layout of their child portlets. + 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> @@ -167,13 +172,14 @@ </listitem> </varlistentry> <varlistentry> - <term>Navigation.xml</term> + <term>navigation.xml</term> <listitem> <para> - This file defines all the navigation nodes the portal will have. The syntax is simple, using nested node tags. Each node references a page that is defined in the next XML file. + This file defines all the navigation nodes the portal will have. The syntax is simple, using nested node tags. Each node references a page defined in pages.xml file (explained next). </para> <para> - If the label <literal>#{}</literal> node label is used, the internationalization mechanism is activated and the actual label to render is taken from an associated properties file for the current locale. + When <literal>#{...}</literal> syntax is used, the enclosed property name serves as a key that is automatically passed to internationalization mechanism + so the literal property name is replaced by a localized value taken from the associated properties file matching the current locale. </para> <programlisting role="XML">&#60;?xml version=&#34;1.0&#34; encoding=&#34;UTF-8&#34;?&#62; @@ -202,16 +208,18 @@ </para> <warning> <para> - For top nodes, the <emphasis role="bold">uri</emphasis> and the <emphasis role="bold">name</emphasis> of your navigation nodes must have the <emphasis>same</emphasis> value. For the other nodes the <emphasis role="bold">uri</emphasis> is composed like <emphasis><uri>contentmanagement/fileexplorer</uri></emphasis> where &#39;<literal>contentmanagement</literal> &#39; is the name of the parent node and &#39;<literal>fileexplorer</literal>&#39; is the name of the node ( <emphasis>&#60;name&#62;fileexplorer&#60;/name&#62; </emphasis> ). + For top nodes, the <emphasis role="bold">uri</emphasis> and the <emphasis role="bold">name</emphasis> of your navigation nodes must have the <emphasis>same</emphasis> value. + For other nodes the <emphasis role="bold">uri</emphasis> is a relative path. For example, <emphasis><uri>contentmanagement/fileexplorer</uri></emphasis> where &#39;<literal>contentmanagement</literal> &#39; is the name of the parent node and &#39;<literal>fileexplorer</literal>&#39; is the name of the node ( <emphasis>&#60;name&#62;fileexplorer&#60;/name&#62; </emphasis> ). </para> </warning> </listitem> </varlistentry> <varlistentry> - <term>Pages.xml</term> + <term>pages.xml</term> <listitem> <para> - This XML 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 icons or the mode. + 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">&#60;?xml version=&#34;1.0&#34; encoding=&#34;ISO-8859-1&#34;?&#62; @@ -252,10 +260,10 @@ </listitem> </varlistentry> <varlistentry> - <term>Portlet-preferences.xml</term> + <term>portlet-preferences.xml</term> <listitem> <para> - Porlet instances can be associated with <literal>portlet-preferences</literal> that override the one defined in <filename>portlet.xml </filename>file of the portlet application <literal>war</literal> . + Porlet instances can be associated with <literal>portlet-preferences</literal> that override the ones defined in <filename>portlet.xml</filename> of the portlet application <literal>war</literal> (TODO: clarify which file in which war). </para> <programlisting role="XML">&#60;?xml version=&#34;1.0&#34; encoding=&#34;ISO-8859-1&#34;?&#62; @@ -503,29 +511,29 @@ <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 all the pages assigned to any groups they belong to in the menu. + Group navigations are dynamically added to the user navigation at login. This allows users to see in the menu all the 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 located in the <filename>portal/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>portal/WEB-INF/conf/portal/group/platform/administrators/</filename>). + They are located in <filename>portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (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> - The user navigation is the set of nodes and pages that are owned by a user. They are part of the user dashboard. + User navigation is the set of nodes and pages that are owned by a 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 directory &#34;<filename>portal/WEB-INF/conf/portal/users/{userName}</filename>&#34;. + 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 directory &#34;<filename>portal.war/WEB-INF/conf/portal/users/{userName}</filename>&#34;. </para> <para> - This directory also contains a <filename>gadgets.xml</filename> file (which was formerly called <filename>widgets.xml</filename>). This file defines the gadgets located in the user workspace. + This directory also contains a <filename>gadgets.xml</filename> file (formerly called <filename>widgets.xml</filename>). This file defines the gadgets located in the user's workspace. </para> <para> - The user workspace is located at the left hand side of the page and access is restricted to some privileged users, see <xref linkend="sect-Reference_Guide-Predefined_User_Configuration" /> + The user's workspace is located at the left hand side of the page and access is restricted to some privileged users, see <xref linkend="sect-Reference_Guide-Predefined_User_Configuration" /> </para> <programlisting role="XML">&#60;?xml version=&#34;1.0&#34; encoding=&#34;ISO-8859-1&#34;?&#62; @@ -573,7 +581,8 @@ <section id="sect-Reference_Guide-Tips-Direct_External_Links"> <title>Direct External Links</title> <para> - If you wish to add a link to a URL outside the portal you you first have to define a &#34;page&#34; which will not be used. Then add the URL to the navigation. + If you wish to add a link to a URL outside the portal you first have to define a &#34;page&#34; that will only serve as a navigation placeholder for external redirect - it will not be used for any portlets. + Then add the URL to the navigation. (TODO: check for correctness) </para> <variablelist> <varlistentry>