Author: smumford Date: 2011-11-14 21:23:37 -0500 (Mon, 14 Nov 2011) New Revision: 8064 Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml Log: Edits in prep for beta release Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml 2011-11-15 01:32:28 UTC (rev 8063) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-2-GDG_Architectural_choices.xml 2011-11-15 02:23:37 UTC (rev 8064) @@ -4,131 +4,132 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Developer_Guide-Architectural_choices"> - <title>Architectural choices</title> - <para> - Depending on environment and goals, decisions has to be made regarding the components that will make up the final website. Some elements may already be in place (such as an identity server) and some elements may still be free to choose. This section aims at helping taking the right decisions. - </para> - <section id="sect-Developer_Guide-Architectural_choices-Identity_server"> - <title>Identity server</title> - <para> - EPP 5.2 comes with a component named PicketLink IDM, which is made to adapt to store and retrieve users and groups from various identity servers. We can separate the different options into three: - </para> - <orderedlist> - <listitem> - <para> - <emphasis role="strong">Database</emphasis> : users, groups and their relationships are stored in a RDBMS database. Tables names and column names can be changed, but the overall relationship between tables remains the same. This solution is particularly adapted to a new identity server that will handle thousands of users. - </para> + <title>Architectural choices</title> + <para> + Depending on environment and goals, decisions has to be made regarding the components that will make up the final website. Some elements may already be in place (such as an identity server) and some elements may still be free to choose. This section aims at helping taking the right decisions. + </para> + <section id="sect-Developer_Guide-Architectural_choices-Identity_server"> + <title>Identity server</title> + <para> + JBoss Enterprise Portal Platform &VY; comes with a component named PicketLink IDM, which is made to adapt to store and retrieve users and groups from various identity servers. We can separate the different options into three: + </para> + <orderedlist> + <listitem> + <para> + <emphasis role="strong">Database</emphasis> : users, groups and their relationships are stored in a RDBMS database. Tables names and column names can be changed, but the overall relationship between tables remains the same. This solution is particularly adapted to a new identity server that will handle thousands of users. + </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">LDAP</emphasis> : users, groups and their relationships are stored in an LDAP (or ActiveDirectory) server, the directory structure can be adapted by configuration to the most common scenarios. This solution is particularly adapted to infrastructure that are already using an LDAP server, for infrastructure that will share the server identity among multiple service (and the website being one of them) or for very large set of users (millions). When using LDAP with large number of users, it is recommended to use LDAP tools to do the provisioning of users. - </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">LDAP</emphasis> : users, groups and their relationships are stored in an LDAP (or ActiveDirectory) server, the directory structure can be adapted by configuration to the most common scenarios. This solution is particularly adapted to infrastructure that are already using an LDAP server, for infrastructure that will share the server identity among multiple service (and the website being one of them) or for very large set of users (millions). When using LDAP with large number of users, it is recommended to use LDAP tools to do the provisioning of users. + </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Custom</emphasis> : when retrieving users, groups and their relationship cannot be done by configuration, it is possible to implement the Picketlink IDM SPI to implement the methods in charge of retrieving and storing user information. - </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Custom</emphasis> : when retrieving users, groups and their relationship cannot be done by configuration, it is possible to implement the Picketlink IDM SPI to implement the methods in charge of retrieving and storing user information. + </para> - </listitem> + </listitem> - </orderedlist> - <para> - Picketlink IDM also supports mix environments, this is very useful when an LDAP infrastructure is provided but in a read-only mode. Since the website may need to store additional information about users (such as his preferred language or skin), it can combine LDAP + Database, to retrieve users from LDAP but store additional properties in a database. During the calls to the identity API, the information from both sources will be transparently merged. For more information about PicketLink IDM, please check the EPP 5.2 reference guide and the PicketLink IDM documentation. - </para> + </orderedlist> + <para> + Picketlink IDM also supports mix environments, this is very useful when an LDAP infrastructure is provided but in a read-only mode. Since the website may need to store additional information about users (such as his preferred language or skin), it can combine LDAP + Database, to retrieve users from LDAP but store additional properties in a database. During the calls to the identity API, the information from both sources will be transparently merged. For more information about PicketLink IDM, please check the JBoss Enterprise Portal Platform &VY; reference guide and the PicketLink IDM documentation. + </para> - </section> - - <section id="sect-Developer_Guide-Architectural_choices-Storage"> - <title>Storage</title> - <para> - The portal framework stores page compositions, portlet preferences, gadget code in a database through a Java Content Repository (JCR) API. A set of database servers and JDBC connectors are part of our quality assurance cycles and the certified environments are mentioned <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . - </para> - <para> - It is important to choose one of the combination or check with a Red Hat contact for specific environments that would differ from this list. - </para> - <para> - The database schema will be automatically created during the very first startup of the website and then it is required that the database users has sufficient rights to create tables. This privilege can be revoked after the initial startup, also the database content can be exported and imported in a new server. This makes the installation of the product very easy in most cases. - </para> - <para> - We do not provide additional recommendation to choose a database server over another as long as it is part of our certified environment. - </para> - <para> - As said earlier content is stored through a JCR API, RDBMS aren't a great fit to store large files and it is possible to configure eXo JCR to store such files in the filesystem instead of database, metadata about the files would still be stored into the database. Note that if the website is running on a cluster the filesystem will need to be accessible from all nodes and a NFS solution needs to be setup. For more details see the notion of "value storage" in the reference guide. - </para> + </section> + + <section id="sect-Developer_Guide-Architectural_choices-Storage"> + <title>Storage</title> + <para> + The portal framework stores page compositions, portlet preferences, gadget code in a database through a Java Content Repository (JCR) API. A set of database servers and JDBC connectors are part of our quality assurance cycles and the certified environments are mentioned <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . + </para> + <para> + It is important to choose one of the combination or check with a Red Hat contact for specific environments that would differ from this list. + </para> + <para> + The database schema will be automatically created during the very first startup of the website and then it is required that the database users has sufficient rights to create tables. This privilege can be revoked after the initial startup, also the database content can be exported and imported in a new server. This makes the installation of the product very easy in most cases. + </para> + <para> + We do not provide additional recommendation to choose a database server over another as long as it is part of our certified environment. + </para> + <para> + As said earlier content is stored through a JCR API, RDBMS aren't a great fit to store large files and it is possible to configure eXo JCR to store such files in the filesystem instead of database, metadata about the files would still be stored into the database. Note that if the website is running on a cluster the filesystem will need to be accessible from all nodes and a NFS solution needs to be setup. For more details see the notion of "value storage" in the reference guide. + </para> - </section> - - <section id="sect-Developer_Guide-Architectural_choices-Cluster"> - <title>Cluster</title> - <para> - Clustering for failover or load-balancing requirements requires to spend more time configuring it for your environment, we made it easy to handle common situations though. There is a cost associated to clustering (EPP 5.2 has some optimization when running on a single node) but the product is designed to linearly scale up so that same performance is added every time a new node is added. All critical parts are kept in sync among nodes and the less critical ones left aside to achieve better performance. It will be equally critical that applications developed for the final websites pay the same attention when it comes to replicate data across a cluster of nodes. - </para> - <para> - The number of nodes will vary a lot depending on the applications developed and used on the final website. We recommend to do early performance analysis with tools such as JMeter, Grinder etc to measure the impact of heavy loads. - </para> - <para> - It is usually recommended to run a cluster to achieve high availability. - </para> + </section> + + <section id="sect-Developer_Guide-Architectural_choices-Cluster"> + <title>Cluster</title> + <para> + Clustering for failover or load-balancing requirements requires to spend more time configuring it for your environment, we made it easy to handle common situations though. There is a cost associated to clustering (JBoss Enterprise Portal Platform &VY; has some optimization when running on a single node) but the product is designed to linearly scale up so that same performance is added every time a new node is added. All critical parts are kept in sync among nodes and the less critical ones left aside to achieve better performance. It will be equally critical that applications developed for the final websites pay the same attention when it comes to replicate data across a cluster of nodes. + </para> + <para> + The number of nodes will vary a lot depending on the applications developed and used on the final website. We recommend to do early performance analysis with tools such as JMeter, Grinder etc to measure the impact of heavy loads. + </para> + <para> + It is usually recommended to run a cluster to achieve high availability. + </para> - </section> - - <section id="sect-Developer_Guide-Architectural_choices-SSO"> - <title>SSO</title> - <para> - If the website is part of a more global infrastructure with various components (the website being one of several), it may be in the benefit of users to put a Single-Sign-On solution in place among them. Various SSO solutions are supported by EPP 5.2 as seen <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . In some cases it can be better to have the token manager service on a specific server. - </para> - <para> - Summary - </para> - <para> - By now you should know what infrastructure you will need: - </para> - <para> - - A database - </para> - <para> - - Optionally LDAP, depending on your choice - </para> - <para> - - Optionally NFS, depending on the configuration (mandatory on a cluster with default settings: TODO: More QA on a setup without NFS) - </para> - <para> - - Optionally an SSO token service - </para> - <para> - - Optionally, a cluster of nodes - </para> - <para> - Here is an example of the simplest setup: - </para> - <figure id="figu-Developer_Guide-SSO-Simple_Infrastructure"> - <title>Simple Infrastructure</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372876/simpleinfra.png" width="444" /> - </imageobject> + </section> + + <section id="sect-Developer_Guide-Architectural_choices-SSO"> + <title>SSO</title> + <para> + If the website is part of a more global infrastructure with various components (the website being one of several), it may be in the benefit of users to put a Single-Sign-On solution in place among them. Various SSO solutions are supported by JBoss Enterprise Portal Platform &VY; as seen <ulink url="http://www.jboss.com/products/platforms/portals/testedconfigura... . In some cases it can be better to have the token manager service on a specific server. + </para> + <para> + Summary + </para> + <para> + By now you should know what infrastructure you will need: + </para> + <para> + - A database + </para> + <para> + - Optionally LDAP, depending on your choice + </para> + <para> + - Optionally NFS, depending on the configuration (mandatory on a cluster with default settings: + <!--TODO: More QA on a setup without NFS)--> + </para> + <para> + - Optionally an SSO token service + </para> + <para> + - Optionally, a cluster of nodes + </para> + <para> + Here is an example of the simplest setup: + </para> + <figure id="figu-Developer_Guide-SSO-Simple_Infrastructure"> + <title>Simple Infrastructure</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372876/simpleinfra.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> - <para> - Here is an example of a more complex setup: - </para> - <figure id="figu-Developer_Guide-SSO-Complex_Infrastructure"> - <title>Complex Infrastructure</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372876/complexinfra.png" width="444" /> - </imageobject> + </figure> + <para> + Here is an example of a more complex setup: + </para> + <figure id="figu-Developer_Guide-SSO-Complex_Infrastructure"> + <title>Complex Infrastructure</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372876/complexinfra.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> + </figure> - </section> - + </section> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml 2011-11-15 01:32:28 UTC (rev 8063) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-3-GDG_Design_choices.xml 2011-11-15 02:23:37 UTC (rev 8064) @@ -4,174 +4,174 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Developer_Guide-Design_choices"> - <title>Design choices</title> - <para> - Now that the main components of the architecture has been decided, choices must be made on the overall design. - </para> - <section id="sect-Developer_Guide-Design_choices-Dashboards"> - <title>Dashboards</title> - <para> - User dashboards may be very costly in a website, as each user will have the opportunity to design his own personal website, it comes with the cost of storing all that information. Efforts have been made (and are still made) to reduce this cost, but there will always be an overhead. - </para> - <para> - This overhead might be hard to estimate as this will depend a lot on how the users will navigate the website, maybe only a minority will use this functionality, or maybe the website is only made of dashboards. In any case the impact of making this feature available must be measured by: - </para> - <itemizedlist> - <listitem> - <para> - estimating the number of dashboards and pages that will be created - </para> + <title>Design choices</title> + <para> + Now that the main components of the architecture has been decided, choices must be made on the overall design. + </para> + <section id="sect-Developer_Guide-Design_choices-Dashboards"> + <title>Dashboards</title> + <para> + User dashboards may be very costly in a website, as each user will have the opportunity to design his own personal website, it comes with the cost of storing all that information. Efforts have been made (and are still made) to reduce this cost, but there will always be an overhead. + </para> + <para> + This overhead might be hard to estimate as this will depend a lot on how the users will navigate the website, maybe only a minority will use this functionality, or maybe the website is only made of dashboards. In any case the impact of making this feature available must be measured by: + </para> + <itemizedlist> + <listitem> + <para> + Estimating the number of dashboards and pages that will be created + </para> - </listitem> - <listitem> - <para> - observing the impact on the database (through JCR) in terms of size - </para> + </listitem> + <listitem> + <para> + Observing the impact on the database (through JCR) in terms of size + </para> - </listitem> + </listitem> - </itemizedlist> + </itemizedlist> - </section> - - <section id="sect-Developer_Guide-Design_choices-JCR_index_replication_for_cluster_setup"> - <title>JCR index replication for cluster setup</title> - <para> - The JCR implementation uses Apache Lucene for indexing the data. The indexes are used to search for content (It can be page nodes or WCM content for instance). Lucene isn't cluster-ready but on a cluster, each node will need to be able to search for content and will need to have access to the lucene indexes. When is comes to searching, there is always a tradeoff. Everyone would want to achieve all of the following: - </para> - <itemizedlist> - <listitem> - <para> - Fast to search - </para> + </section> + + <section id="sect-Developer_Guide-Design_choices-JCR_index_replication_for_cluster_setup"> + <title>JCR index replication for cluster setup</title> + <para> + The JCR implementation uses Apache Lucene for indexing the data. The indexes are used to search for content (it can be page nodes or WCM content for instance). Lucene is not cluster-ready but on a cluster, each node will need to be able to search for content and will need to have access to the lucene indexes. All search implementations would want to achieve all of the following: + </para> + <itemizedlist> + <listitem> + <para> + Fast to search + </para> - </listitem> - <listitem> - <para> - Fast to index - </para> + </listitem> + <listitem> + <para> + Fast to index + </para> - </listitem> - <listitem> - <para> - Same search result on each node at the same time - </para> + </listitem> + <listitem> + <para> + Same search result on each node at the same time + </para> - </listitem> - <listitem> - <para> - No need to rebuild the index ever (No inconsistency) - </para> + </listitem> + <listitem> + <para> + No need to rebuild the index ever (No inconsistency) + </para> - </listitem> - <listitem> - <para> - No impact on overall performance - </para> + </listitem> + <listitem> + <para> + No impact on overall performance + </para> - </listitem> - <listitem> - <para> - Easy to setup (no infrastructure change) - </para> + </listitem> + <listitem> + <para> + Easy to setup (no infrastructure change) + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - But there are choices to be made. The JCR implementation used by EPP (eXo JCR) makes it possible to configure the storage and retrieval of indexes according to architect's choice on where it is acceptable to lose-up some constraints. For configuration details please refer to the EPP Reference Guide. - </para> - <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Standalone_index"> - <title>Standalone index</title> - <para> - This is only for a non-cluster environment, this is obviously the easiest setup, with a combination of in-memory and file based indexes. There is no replication involved so any entry can be found by a search as soon as they are created. - <figure id="figu-Developer_Guide-Standalone_index-Standalone_Index"> - <title>Standalone Index</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372952/diagram-standalone-index.png" /> - </imageobject> + </itemizedlist> + <para> + The JCR implementation used by JBoss Enterprise Portal Platform (eXo JCR) makes it possible to configure the storage and retrieval of indexes according to architect's choice on where it is acceptable to lose-up some constraints. For configuration details please refer to the JBoss Enterprise Portal Platform Reference Guide. + </para> + <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Standalone_index"> + <title>Standalone index</title> + <para> + This is only for a non-cluster environment, this is obviously the easiest setup, with a combination of in-memory and file based indexes. There is no replication involved so any entry can be found by a search as soon as they are created. + <figure id="figu-Developer_Guide-Standalone_index-Standalone_Index"> + <title>Standalone Index</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372952/diagram-standalone-index.png" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> + </figure> - </para> + </para> - </section> - - <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Local_index"> - <title>Local index</title> - <para> - This environment is easy to setup, each node keeps a local copy of the full indexes so that when a search is requested on a node, there is no network communication requested. The downside is that when a node indexes an item, it requires to replicate that index on each and every node. If a node is unavailable at that time, it may miss an index update request and then the different nodes may be inconsistent. Also when a node is added it has to recreate it's own full index. An alternative to this setup is to ask a node to retrieve the info from a coordinator on each search, it makes the startup of the new node faster but impacts its performance during the runtime. This setup is new to EPP 5.2. - </para> - <para> - <figure id="figu-Developer_Guide-Local_index-Local_Index"> - <title>Local Index</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372952/diagram-local-index.png" width="444" /> - </imageobject> + </section> + + <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Local_index"> + <title>Local index</title> + <para> + This environment is easy to setup, each node keeps a local copy of the full indexes so that when a search is requested on a node, there is no network communication requested. The downside is that when a node indexes an item, it requires to replicate that index on each and every node. If a node is unavailable at that time, it may miss an index update request and then the different nodes may be inconsistent. Also when a node is added it has to recreate its own full index. An alternative to this setup is to ask a node to retrieve the information from a coordinator on each search, it makes the startup of the new node faster but impacts its performance during the runtime. This setup is new to JBoss Enterprise Portal Platform &VY;. + </para> + <para> + <figure id="figu-Developer_Guide-Local_index-Local_Index"> + <title>Local Index</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372952/diagram-local-index.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> + </figure> - </para> + </para> - </section> - - <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Shared_index"> - <title>Shared index</title> - <para> - In this setup there is a unique index created and shared among all nodes. It requires to configure the infrastructure so that a network file system is installed where all nodes can read content. Advantages: - </para> - <itemizedlist> - <listitem> - <para> - Consistency, all the nodes see the same data - </para> + </section> + + <section id="sect-Developer_Guide-JCR_index_replication_for_cluster_setup-Shared_index"> + <title>Shared index</title> + <para> + In this setup there is a unique index created and shared among all nodes. It requires to configure the infrastructure so that a network file system is installed where all nodes can read content. Advantages: + </para> + <itemizedlist> + <listitem> + <para> + Consistency, all the nodes see the same data + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - Drawback: - </para> - <itemizedlist> - <listitem> - <para> - Requires a highly available NFS setup (NFS 4 is recommended) - </para> + </itemizedlist> + <para> + Drawback: + </para> + <itemizedlist> + <listitem> + <para> + Requires a highly available NFS setup (NFS 4 is recommended) + </para> - </listitem> - <listitem> - <para> - More network communication - </para> + </listitem> + <listitem> + <para> + More network communication + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - <figure id="figu-Developer_Guide-Shared_index-Shared_Index"> - <title>Shared Index</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372952/diagram-shared-index.png" width="444" /> - </imageobject> + </itemizedlist> + <para> + <figure id="figu-Developer_Guide-Shared_index-Shared_Index"> + <title>Shared Index</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372952/diagram-shared-index.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> + </figure> - </para> + </para> - </section> - + </section> + - </section> - + </section> + </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2011-11-15 01:32:28 UTC (rev 8063) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2011-11-15 02:23:37 UTC (rev 8064) @@ -4,112 +4,97 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Developer_Guide-Portal_Development"> - <title>Portal Development</title> - <section id="sect-Developer_Guide-Portal_Development-Portal_containers"> - <title>Portal containers</title> - <para> - In a single instance (or cluster) of EPP, multiple portals can be running and share resources with other portals with two level of granularities: - </para> - <itemizedlist> - <listitem> - <para> - Portal Containers: A portal container can host multiple sites, and an EPP instance can host multiple portal containers - </para> + <title>Portal Development</title> + <section id="sect-Developer_Guide-Portal_Development-Portal_containers"> + <title>Portal containers</title> + <para> + In a single instance (or cluster) of JBoss Enterprise Portal Platform, multiple portals can be running and share resources with other portals with two level of granularities: + </para> + <itemizedlist> + <listitem> + <para> + Portal Containers: A portal container can host multiple sites, and an JBoss Enterprise Portal Platform instance can host multiple portal containers + </para> - </listitem> - <listitem> - <para> - Site: A site can have a unique identity, with its own skin applied, set of pages... - </para> + </listitem> + <listitem> + <para> + Site: A site can have a unique identity, with its own skin applied, set of pages... + </para> - </listitem> + </listitem> - </itemizedlist> - <para> - The biggest granularity is what is called "Portal Containers", a Portal Container can host multiple "Sites". Those two components have a unique identifier that can be found in the default URL Mapping according to the following scheme: <ulink url="http://localhost:8080/" /> &lt;portalcontainer&gt;/&lt;site&gt; - </para> - <para> - When creating a website, it is possible to create a portal container from scratch or extend an existing one. It is then possible to extend the portal container which is accessed at <ulink url="http://localhost:8080/portal" /> on the out of the box solution, this is the recommended way. While running multiple portal containers is possible, it's usually better to keep those on separate installation, note that multiple websites can run in a single portal container and share some services. - </para> - <para> - By providing an extension you can benefit from the portal provided by EPP and be able to customize the parts you want. The benefits over directly modifying the shipped files is that it will make the updates much easier (By just replacing the archives provided by EPP). - <figure id="figu-Developer_Guide-Portal_containers-Portal_Extension_Structure"> - <title>Portal Extension Structure</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372962/portalextensionstructure.png" width="444" /> - </imageobject> + </itemizedlist> + <para> + The biggest granularity is what is called "Portal Containers", a Portal Container can host multiple "Sites". Those two components have a unique identifier that can be found in the default URL Mapping according to the following scheme: <ulink url="http://localhost:8080/" /> &lt;portalcontainer&gt;/&lt;site&gt; + </para> + <para> + When creating a website, it is possible to create a portal container from scratch or extend an existing one. It is then possible to extend the portal container which is accessed at <ulink url="http://localhost:8080/portal" /> on the out of the box solution, this is the recommended way. While running multiple portal containers is possible, it's usually better to keep those on separate installation, note that multiple websites can run in a single portal container and share some services. + </para> + <para> + By providing an extension you can benefit from the portal provided by JBoss Enterprise Portal Platform and be able to customize the parts you want. The benefits over directly modifying the shipped files is that it will make the updates much easier (By just replacing the archives provided by JBoss Enterprise Portal Platform). + <figure id="figu-Developer_Guide-Portal_containers-Portal_Extension_Structure"> + <title>Portal Extension Structure</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372962/portalextensionstructure.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> + </figure> - </para> - <section id="sect-Developer_Guide-Portal_containers-Portal_extension"> - <title>Portal extension</title> - <para> - A portal extension is packaged as an Enterprise ARchive (EAR), a configuration file allows to define which services are required and by ordering those, it is possible to modify some elements. It can be a configuration setting, a translation, a visual template, a page to add... - </para> - <para> - Portal extensions can shadow existing services, a portal will usually be composed of various extensions, each of them usually add services. - <figure id="figu-Developer_Guide-Portal_extension-Portal_Extensions"> - <title>Portal Extensions</title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/7372962/portalExtensions.png" width="444" /> - </imageobject> + </para> + <section id="sect-Developer_Guide-Portal_containers-Portal_extension"> + <title>Portal extension</title> + <para> + A portal extension is packaged as an Enterprise ARchive (EAR), a configuration file allows to define which services are required and by ordering those, it is possible to modify some elements. It can be a configuration setting, a translation, a visual template, a page to add... + </para> + <para> + Portal extensions can shadow existing services, a portal will usually be composed of various extensions, each of them usually add services. + <figure id="figu-Developer_Guide-Portal_extension-Portal_Extensions"> + <title>Portal Extensions</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/7372962/portalExtensions.png" width="444" /> + </imageobject> - </mediaobject> + </mediaobject> - </figure> - In a portal extension, elements are shadowed by using the same directory location, so if one wants to rewrite the groovy template of the HomePagePortlet which is located in: gatein.ear/02portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl it would be located in an extension such as myExtension/myWar.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl. The ordering will be defined by the portal extension configuration. - </para> + </figure> + In a portal extension, elements are shadowed by using the same directory location, so if one wants to rewrite the groovy template of the HomePagePortlet which is located in: gatein.ear/02portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl it would be located in an extension such as myExtension/myWar.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl. The ordering will be defined by the portal extension configuration. + </para> - </section> - + </section> + - </section> - - <section id="sect-Developer_Guide-Portal_Development-Visual_identity"> - <title>Visual identity</title> - <para> - A portal visual identity will be made of the HTML produced by the result of the portal aggregation (the components that makes a page like columns, rows combined with the content produced by the portlets) and associated CSS files. - </para> - <para> - EPP allows to deploy multiple skins which consists of CSS files, it makes it possible to apply styling on the page compositions and components of a page (Portlets). Different skins can be applied to the different websites, also if made available to the users, they can choose their preferred skin. - </para> - <section id="sect-Developer_Guide-Visual_identity-Customizing_the_login_page"> - <title>Customizing the login page</title> - <para> - When accessing a page that requires privileges, a login page is showing up, that page can be customized by using an extension. To do so it would be enough to copy the file located at: - </para> - <example id="exam-Developer_Guide-Customizing_the_login_page-login.jsp"> - <title><filename>login.jsp</filename></title> - -<programlisting>gatein.ear/02portal.war/login/jsp/login.jsp</programlisting> + </section> + + <section id="sect-Developer_Guide-Portal_Development-Visual_identity"> + <title>Visual identity</title> + <para> + A portal visual identity will be made of the HTML produced by the result of the portal aggregation (the components that makes a page like columns, rows combined with the content produced by the portlets) and associated CSS files. + </para> + <para> + JBoss Enterprise Portal Platform allows to deploy multiple skins which consists of CSS files, it makes it possible to apply styling on the page compositions and components of a page (Portlets). Different skins can be applied to the different websites, also if made available to the users, they can choose their preferred skin. + </para> + <section id="sect-Developer_Guide-Visual_identity-Customizing_the_login_page"> + <title>Customizing the login page</title> + <para> + When accessing a page that requires privileges, a login page is showing up, that page can be customized by using an extension. To do so it would be enough to copy the file located at <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> and include it in the portal extension such as <filename>myExtension.ear/myWar.war/login/jsp/login.jsp</filename>. + </para> + <para> + All the logic must be carefully kept in the login page so that the portal will keep working as it should. + </para> + <para> + To modify the modal window which pops up when the user decides to sign-in, the extension would have a modified copy of <filename>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename> + </para> + + </section> + - </example> - <para> - and include it in the portal extension such as myExtension.ear/myWar.war/login/jsp/login.jsp - </para> - <para> - All the logic must be carefully kept in the login page so that the portal will keep working as it should. - </para> - <para> - To modify the modal window which pops up when the user decides to sign-in, the extension would have a modified copy of: - </para> - <example id="exam-Developer_Guide-Customizing_the_login_page-UILoginForm.gtmpl"> - <title><filename>UILoginForm.gtmpl</filename></title> - -<programlisting>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</programlisting> + </section> + - </example> - - </section> - - - </section> - - </chapter> Modified: epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml =================================================================== --- epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml 2011-11-15 01:32:28 UTC (rev 8063) +++ epp/docs/branches/5.2/Developer_Guide/en-US/chapter-5-GDG_Application_development.xml 2011-11-15 02:23:37 UTC (rev 8064) @@ -4,45 +4,45 @@ %BOOK_ENTITIES; ]> <chapter id="chap-Developer_Guide-Application_development"> - <title>Application development</title> - <section id="sect-Developer_Guide-Application_development-Gadget_Development"> - <title>Gadget Development</title> - <section id="sect-Developer_Guide-Gadget_Development-Introduction"> - <title>Introduction</title> - <para> - In the context of EPP, gadgets are those as defined by the Google OpenSocial specifications. Since EPP 5.2, the portal framework includes Apache Shindig 2.0 which is made to support the version 0.9 and 1.0 of OpenSocial. - </para> - <para> - Within a portal it is possible to embed any OpenSocial gadget on a page or within the user dashboards, gadgets can be added to the application registry, or links can be added within the mini-composer (see the User Guide). - </para> + <title>Application development</title> + <section id="sect-Developer_Guide-Application_development-Gadget_Development"> + <title>Gadget Development</title> + <section id="sect-Developer_Guide-Gadget_Development-Introduction"> + <title>Introduction</title> + <para> + In the context of JBoss Enterprise Portal Platform, gadgets are those as defined by the Google OpenSocial specifications. Since JBoss Enterprise Portal Platform 5.2, the portal framework includes Apache Shindig 2.0 which is made to support the version 0.9 and 1.0 of OpenSocial. + </para> + <para> + Within a portal it is possible to embed any OpenSocial gadget on a page or within the user dashboards, gadgets can be added to the application registry, or links can be added within the mini-composer (see the User Guide). + </para> - </section> - - <section id="sect-Developer_Guide-Gadget_Development-Developing_Gadgets"> - <title>Developing Gadgets</title> - <para> - OpenSocial gadgets are made of standard HTML and javascript. The container offers an API for which the documentation is available <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.0/Core-Ga... . - </para> - <para> - Note that unlike portlets, a gadget has very little knowledge of its context (the portal) and its integration within the portal may be more limited (in terms of visual integration for instance). - </para> - <para> - Google Web Toolkit (GWT) applications can also be used as gadgets, it makes it easy to write user-friendly applications. - </para> + </section> + + <section id="sect-Developer_Guide-Gadget_Development-Developing_Gadgets"> + <title>Developing Gadgets</title> + <para> + OpenSocial gadgets are made of standard HTML and javascript. The container offers an API for which the documentation is available <ulink url="http://opensocial-resources.googlecode.com/svn/spec/1.0/Core-Ga... . + </para> + <para> + Note that unlike portlets, a gadget has very little knowledge of its context (the portal) and its integration within the portal may be more limited (in terms of visual integration for instance). + </para> + <para> + Google Web Toolkit (GWT) applications can also be used as gadgets, it makes it easy to write user-friendly applications. + </para> - </section> - + </section> + - </section> - - <section id="sect-Developer_Guide-Application_development-Portlet_Development"> - <title>Portlet Development</title> - <para> - ToDo. - </para> + </section> + + <section id="sect-Developer_Guide-Application_development-Portlet_Development"> + <title>Portlet Development</title> + <para> + ToDo. + </para> - </section> - + </section> + </chapter>