6:50 a.m.
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's API</title>
+ <title>Implementing the Token Service API</title>
<para>
- All token services used in &PRODUCT;'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;'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 "<emphasis
role="bold">service.configuration</emphasis>".
+ The token service will initialize this validity property by looking for an
<parameter>init-param</parameter> named "<emphasis
role="bold">service.configuration</emphasis>".
</para>
<para>
This property must have three values.
@@ -89,7 +91,7 @@
</programlistingco>
<para>
- In this case, the service's name is "<emphasis
role="bold">jcr-token</emphasis>" and the token's
expiration time is a week.
+ In this case, the service's name is "<emphasis
role="bold">jcr-token</emphasis>" and the token'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'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:
"<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>".
+ The following example configuration can be found at:
"<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>".
</para>
<programlisting role="XML"><component>
@@ -33,15 +42,23 @@
<description>The default portal for checking db is empty or
not</description>
<value>classic</value>
</value-param>
- ..........
+ ...
</init-params>
</component-plugin>
</component-plugins>
</component>
</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'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'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 '<emphasis
role="bold">org.exoplatform.services.organization</emphasis>'
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 'config' parameter is not provided this parameter will be
used to perform JNDI lookup for IdentitySessionFactory
+ If the 'config' 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 'PortalRealm'.
+ The realm name that should be used to obtain proper IdentitySession. The default
is 'PortalRealm'.
</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><jboss-identity
xmlns="urn:jboss:identity:idm:config:v1_0_beta"
+<programlisting role="XML"><jboss-identity
xmlns="urn:jboss:identity:idm:config:v1_0_beta"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:jboss:identity:idm:config:v1_0_alpha
identity-config.xsd">
<realms>
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;
"<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>".
+ These navigations are configured using standard XML syntax in the file;
"<filename>02portal.war:/WEB-INF/conf/portal/portal-configuration.xml</filename>".
</para>
<programlisting role="XML"><component>
@@ -97,24 +97,29 @@
</component-plugins>
</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"><?xml version="1.0"
encoding="ISO-8859-1"?>
@@ -153,7 +158,7 @@
</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 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"><?xml version="1.0"
encoding="UTF-8"?>
@@ -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 '<literal>contentmanagement</literal> ' is the name of
the parent node and '<literal>fileexplorer</literal>' is the
name of the node (
<emphasis><name>fileexplorer</name>
</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 '<literal>contentmanagement</literal> ' is the name of
the parent node and '<literal>fileexplorer</literal>' is the
name of the node (
<emphasis><name>fileexplorer</name>
</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"><?xml version="1.0"
encoding="ISO-8859-1"?>
@@ -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"><?xml version="1.0"
encoding="ISO-8859-1"?>
@@ -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
"<filename>portal/WEB-INF/conf/portal/users/{userName}</filename>".
+ 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
"<filename>portal.war/WEB-INF/conf/portal/users/{userName}</filename>".
</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"><?xml version="1.0"
encoding="ISO-8859-1"?>
@@ -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
"page" 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
"page" 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>