1:05 a.m.
Author: jaredmorgs
Date: 2013-01-18 02:05:47 -0500 (Fri, 18 Jan 2013)
New Revision: 9064
Added:
epp/docs/branches/6.0/Developer_Guide/en-US/images/Kinds+of+Navigation.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/complexinfra.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-local-index.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-shared-index.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-standalone-index.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/navigation-bar.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/portalExtensions.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/portalextensionstructure.png
epp/docs/branches/6.0/Developer_Guide/en-US/images/simpleinfra.png
Modified:
epp/docs/branches/6.0/Developer_Guide/en-US/Book_Info.xml
epp/docs/branches/6.0/Developer_Guide/en-US/Developer_Guide.xml
epp/docs/branches/6.0/Developer_Guide/en-US/Revision_History.xml
epp/docs/branches/6.0/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml
Log:
Incorporated changes to Portal Extension chapter, but there is an XML error I just
can't track down. I don't want to risk not checking in my day's changes, but I
srsly can't track down the effing thing. So pushing in with the error and will look on
Monday to try and resolve
Modified: epp/docs/branches/6.0/Developer_Guide/en-US/Book_Info.xml
===================================================================
--- epp/docs/branches/6.0/Developer_Guide/en-US/Book_Info.xml 2013-01-18 04:45:43 UTC (rev
9063)
+++ epp/docs/branches/6.0/Developer_Guide/en-US/Book_Info.xml 2013-01-18 07:05:47 UTC (rev
9064)
@@ -5,7 +5,7 @@
]>
<bookinfo id="book-Developer_Guide-Developer_Guide">
<title>Developer Guide</title>
- <subtitle>for use with JBoss Portal Platform 6 and it's patch
releases.</subtitle>
+ <subtitle>for use with JBoss Portal Platform 6.</subtitle>
<productname>JBoss Portal Platform</productname>
<productnumber>6</productnumber>
<edition>6.0.0</edition>
Modified: epp/docs/branches/6.0/Developer_Guide/en-US/Developer_Guide.xml
===================================================================
--- epp/docs/branches/6.0/Developer_Guide/en-US/Developer_Guide.xml 2013-01-18 04:45:43
UTC (rev 9063)
+++ epp/docs/branches/6.0/Developer_Guide/en-US/Developer_Guide.xml 2013-01-18 07:05:47
UTC (rev 9064)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Freeform XML Formatting.
--><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!-- This document was created with Syntext Serna Freeform XML Formatting.
--><!-- This document was created with Syntext Serna Free. --><!DOCTYPE book
PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
%BOOK_ENTITIES;
]>
Modified: epp/docs/branches/6.0/Developer_Guide/en-US/Revision_History.xml
===================================================================
--- epp/docs/branches/6.0/Developer_Guide/en-US/Revision_History.xml 2013-01-18 04:45:43
UTC (rev 9063)
+++ epp/docs/branches/6.0/Developer_Guide/en-US/Revision_History.xml 2013-01-18 07:05:47
UTC (rev 9064)
@@ -4,7 +4,23 @@
<title>Revision History</title>
<simpara>
<revhistory>
- <revision>
+ <revision>
+ <revnumber>6.0.0-6</revnumber>
+ <date>Fri Jan 18 2013</date>
+ <author>
+ <firstname>Jared</firstname>
+ <surname>Morgan</surname>
+ <email/>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Added all the raw changes from the Portal Extension section on
Confluence.</member>
+ <member>Incorporated changes up to Rev 4 from
https://docs.jboss.org/author/display/GTNPORTAL35/Custom+Groovy+Template+...
</member>
+ <member>Incorporated changes up to Rev 4 from
https://docs.jboss.org/author/display/GTNPORTAL35/Custom+Skin+for+a+Portlet with a
question about how Quickstarts will be delivered.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
<revnumber>6.0.0-5</revnumber>
<date>Tue Oct 30 2012</date>
<author>
Modified:
epp/docs/branches/6.0/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml
===================================================================
---
epp/docs/branches/6.0/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2013-01-18
04:45:43 UTC (rev 9063)
+++
epp/docs/branches/6.0/Developer_Guide/en-US/chapter-4-GDG_Portal_Development.xml 2013-01-18
07:05:47 UTC (rev 9064)
@@ -1,125 +1,790 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
- <chapter id="sid-8094155">
- <title>Portal Development</title>
-
- <section id="sid-7372962">
- <title>Portal containers</title>
-
- <para>
+<chapter id="sid-8094155">
+ <title>Portal Development</title>
+ <section id="sid-7372962">
+ <title>Portal containers</title>
+ <para>
In a single instance (or cluster) of JBoss Portal Platform, multiple portals
can be running and share resources with other portals with two levels of granularity:
</para>
-
- <itemizedlist>
- <listitem>
- <para>
+ <itemizedlist>
+ <listitem>
+ <para>
Portal Containers: A portal container can host multiple sites, and a
JBoss Portal Platform instance can host multiple portal containers
</para>
- </listitem>
-
- <listitem>
- <para>
+ </listitem>
+ <listitem>
+ <para>
Site: A site can have a unique identity, with its own skin applied to a
set of pages.
</para>
- </listitem>
- </itemizedlist>
-
- <para>
+ </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: <code><ulink
url="http://localhost:8080/"/><portalcontainer>/<site>
</code>
</para>
-
- <para>
+ <para>
When creating a website, you can either create a portal container or extend
an existing one. Extending an existing portal container, such as the default one provided
with JBoss Portal Platform, is the recommended option because you only need to customize
it to suit your requirements. Another benefit of the extension method is that upgrades
consist of copying the newer distribution archives in place of the originals. This upgrade
method is not possible if the distribution archives have been modified.
</para>
-
- <para>
+ <para>
While running multiple portal containers is possible, it's
recommended to keep those on separate installations. Note that multiple websites can run
in a single portal container and share some services.
</para>
-
- <para>
+ <para>
The procedure for creating portal containers and extending existing portal
containers is similar: create an enterprise archive (EAR) containing configuration
details, runnable code and static resources.
</para>
-
- <figure>
- <title>Example</title>
-
+ <figure>
+ <title>Example</title>
+ <mediaobject>
+ <imageobject role="html">
+ <imagedata align="center" scale="100"
fileref="images/7372962/portalextensionstructure.png"
format="PNG"/>
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata width="150mm" align="center"
fileref="images/7372962/portalextensionstructure.png"
format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <section id="Portal_Extension">
+ <title>Portal Extension</title>
+ <remark>Source taken from:
https://docs.jboss.org/author/display/GTNPORTAL35/Portal+Extension</re...
+ <para>When extending an existing Portal Container, the name of the portal in
the Extension configuration is the same as the name of the existing Portal Container. The
configuration (and other aspects) of the existing Portal Container can therefore be
shadowed by the Extension. Using this approach, many aspects of an available Portal
Container can be customized, such as (but not limited to) the following topics described
in the indicated sections:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="Custom_Groovy_Template_For_Portlet"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Custom_Skin_For_Portlet"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para><xref linkend="CSS_and_Images"/></para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Custom_Navigation_And_Pages"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Internationalization_Navigation_Nodes"/>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="How_The_Shadowing_Mechanism_Works">
+ <title>How the Shadowing Mechanism Works</title>
+ <para>A schematic representation of the shadowing mechanism can be seem in
<xref linkend="fig-Shadowing_Mechanism"/>.</para>
+ <figure id="fig-Shadowing_Mechanism">
+ <title>Shadowing Mechanism</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/portalextensionstructure.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ The Extension EAR's <code>conf/configuration.xml</code>
file plays a crucial role in shadowing. Consider the following code extract present in the
+ <ulink
url="https://github.com/gatein/gatein-portal-quickstart/tree/master/...
Extension Quickstart</ulink>
+ . In this code extract, the
+ <code>name</code>
+ parameter of the
+ <code>PortalContainerDefinition</code>
+ is set to
+ <code>"portal"</code>
+ . Because a portal container called "portal" already exists
in the default JBoss Portal Platform 6 installation, the container name is redefined in
this file:
+ </para>
+ <example>
+ <title>configuration.xml</title>
+ <programlisting lang="XML"><configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd
http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"...
+ <external-component-plugins>
+ <!-- The full qualified name of the PortalContainerConfig -->
+
<target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
+ <component-plugin>
+ <!-- The name of the plugin -->
+ <name>Add PortalContainer Definitions</name>
+ <!-- The name of the method to call on the PortalContainerConfig in
order to register the PortalContainerDefinitions -->
+ <set-method>registerPlugin</set-method>
+ <!-- The full qualified name of the PortalContainerDefinitionPlugin
-->
+
<type>org.exoplatform.container.definition.PortalContainerDefinitionPlugin</type>
+ <init-params>
+ <object-param>
+ <name>portal</name>
+ <object
type="org.exoplatform.container.definition.PortalContainerDefinition">
+ <!-- The name of the Portal Container: note that a Portal
Container called "portal"
+ already exists in the default GateIn installation.
Therefore, we actually redefine
+ that existing Portal Container here. -->
+ <field name="name">
+ <string>portal</string>
+ </field>
+ <!-- The name of the context name of the rest web
application -->
+ <field name="restContextName">
+ <string>rest</string>
+ </field>
+ <!-- The name of the realm -->
+ <field name="realmName">
+ <string>gatein-domain</string>
+ </field>
+ <field
name="externalSettingsPath">
+
<string>configuration.properties</string>
+ </field>
+ <!--
+ The list of all the context names that are needed to
initialize the Portal Container properly.
+ The order of the dependencies will define the initialization
order and also the order for
+ loading resources. When a resource with the same path, say
/dir/subdir/resource, is available
+ in more than one of the listed contexts, the one from the
context closest to the end of this list
+ will be chosen. Here we want the resources available in
gatein-portal-extension to win over all
+ other resources. Therefore we have added
gatein-portal-extension as the last element of the list.
+ -->
+ <field name="dependencies">
+ <collection
type="java.util.ArrayList">
+ <value>
+
<string>eXoResources</string>
+ </value>
+ <value>
+ <string>portal</string>
+ </value>
+ <value>
+
<string>dashboard</string>
+ </value>
+ <value>
+
<string>exoadmin</string>
+ </value>
+ <value>
+
<string>eXoGadgets</string>
+ </value>
+ <value>
+
<string>gwtGadgets</string>
+ </value>
+ <value>
+
<string>eXoGadgetServer</string>
+ </value>
+ <value>
+ <string>rest</string>
+ </value>
+ <value>
+ <string>web</string>
+ </value>
+ <value>
+
<string>gatein-portal-extension</string>
+ </value>
+ </collection>
+ </field>
+ </object>
+ </object-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins>
+</configuration></programlisting>
+ </example>
+ <para>Other resources available in an existing Portal Container can be
customized in a similar way. Please refer to the following sections for more
details.</para>
+ </section>
+ <section id="Custom_Groovy_Template_For_Portlet">
+ <title>Custom Groovy Template for a Portlet</title>
+ <remark>Source:
https://docs.jboss.org/author/display/GTNPORTAL35/Custom+Groovy+Template+...
+ <para>
+ After having set up the
+ <code>conf/configuration.xml</code>
+ file as described in
+ <xref linkend="How_The_Shadowing_Mechanism_Works"/> you can
proceed with customizing the Groovy templates of portlets.
+ </para>
+ <para>Shadowing of built-in Groovy templates is controlled by the order of
+ <code><dependencies></code>
+ in the configuration of the Portal Container (or Extension) as described in
<xref linkend="How_The_Shadowing_Mechanism_Works"/>. </para>
+ <para>If a template with the same path (for example,
+ <filename>/dir/subdir/template.gtmpl</filename>) is available
in more than one of the dependencies, the template from the
context closest to the end of the list of dependencies is chosen. To ensure that the
template created in <xref linkend="proc-Customizing_HomePagePortlet"/> is
chosen,
+ <code>gatein-portal-extension</code>
+is added as the last element in the list.
+ </para>
+ <note>
+ <para> This section mentions code directly available from the
Portal Extension Example in the
+ JBoss Portal Platform Quickstarts
+ collection.
+ </para>
+ </note>
+ <procedure id="proc-Customizing_HomePagePortlet">
+ <title>Customizing HomePagePortlet</title>
+ <para>Complete this procedure to change the text and layout used in the
default HomePagePortlet shipped with the platform in a custom Extension. </para>
+ <step>
+ <para>Copy
<filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</filename>
</para>
+ </step>
+ <step>
+ <para>Paste the file into the
<filename>war/src/main/webapp/templates/groovy/webui/component/</filename>
folder of the Extension EAR. </para>
+ <important>
+ <para>The file location in the custom extension must mirror the
original location of the file for shadowing to work correctly.</para>
+ </important>
+ </step>
+ <step>
+ <para>Make the desired changes to the text and layout of the
HomePagePortlet in the custom extension.</para>
+ </step>
+ <step>
+ <para>Deploy the extension EAR to the portal platform. The
HomePagePortlet mirrors the changes made in the custom extension.</para>
+ </step>
+ </procedure>
+ </section>
+ <section id="Custom_Skin_For_Portlet">
+ <title>Custom Skin for a Portlet</title>
+ <remark>Source:
https://docs.jboss.org/author/display/GTNPORTAL35/Custom+Skin+for+a+Portl...
+ <para>
+ This section mentions code from the Portal Extension Examples available for
download from <ulink url="https://access.redhat.com/"/>;. as part of your
JBoss Portal Platform subscription.
+ </para>
+ <para>The same guidelines that apply when creating a new portlet skin also
apply when creating a custom skin for a built-in portlet distributed with JBoss Portal
Platform. </para>
+ <para>Declare the skin first in the
+ <code>gatein-resources.xml</code>
+ file, and then create the CSS and other supporting files such as
backgrounds.
+ </para>
+ <para>Shadowing of built-in Groovy templates is controlled by the order of
+ <code><dependencies></code>
+ in the configuration of the Portal Container (or Extension) as described in
<xref linkend="How_The_Shadowing_Mechanism_Works"/>. </para>
+ <para>When the
+ <code>HomePagePortlet</code>
+skin defined in
+ <code>web.war</code>
+is available in more than one of the dependencies, the template from the context closest
to the end of the list of dependencies is chosen. To ensure that the skin available in
+ <code>gatein-portal-extension</code> is chosen,
+ <code>gatein-portal-extension</code>
+is added as the last element in the list.
+ </para>
+ <section id="gatein-resources-xml">
+ <title>gatein-resources.xml</title>
+ <para>
+ In our case
+ <code>gatein-resources.xml</code>
+ is located in the
+ <filename>war/src/main/webapp/WEB-INF</filename>
+ sub-folder of the Portal Extension Quickstart project.
+ </para>
+ <example>
+ <title>gatein-resources.xml</title>
+ <programlisting language="XML">
+<gatein-resources
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_resource...
http://www.gatein.org/xml/ns/gatein_resources_1_3"
+ xmlns="http://www.gatein.org/xml/ns/gatein_resources_1_3&quo...
+
+ <!-- GateIn will load this CSS for HomePagePortlet instead of the default one.
-->
+ <portlet-skin>
+ <!--
+ The name of the web application containing the portlet.xml file in which
+ BannerPortlet is definded. The application name is usually the same as
+ the name of the WAR through which the application was deployed.
+ -->
+ <application-name>web</application-name>
+ <!-- <portlet-name> value from the portlet.xml referenced
above -->
+ <portlet-name>HomePagePortlet</portlet-name>
+ <skin-name>Default</skin-name>
+
<css-path>/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css</css-path>
+ </portlet-skin></programlisting>
+ </example>
+ </section>
+ <section id="CSS_and_Images">
+ <title>CSS and Images</title>
+ <para>
+ In the
+ <code>gatein-resources.xml</code> file in <xref
linkend="gatein-resources-xml"/>, the custom skin is set to use the CSS
file
+
<filename>/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css</filename>
+ which translates to the Portal Extension Quickstart project
+
<filename>war/src/main/webapp/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css</filename>
+file.
+
+ In the CSS file itself, image files use relative paths as demonstrated in
<xref linkend="exam-DefaultStylesheetCss"/>:
+ </para>
+ <example id="exam-DefaultStylesheetCss">
+ <title>DefaultStylesheet.css</title>
+ <programlisting>
+051. .UIHomePagePortlet .TRContainer .DotLine {
+052. background: url("DefaultSkin/background/Line.gif") no-repeat
-2px top;
+053. height: 1px;
+054. width: 182px;
+055. margin: 7px auto;
+056. }
+</programlisting>
+ </example>
+ <note>
+ <para>For further information about creating portlets skins, refer
to<citetitle> Skinning the Portal</citetitle> in the JBoss Portal Platform
<citetitle>Reference Guide</citetitle>.</para>
+ </note>
+ </section>
+ </section>
+ <section id="Custom_Navigation_And_Pages">
+ <title>Custom Navigation and Pages</title>
+ <para>
+ This section mentions code from the Portal Extension Examples available for
download from <ulink url="https://access.redhat.com/"/>;. as part of your
JBoss Portal Platform subscription.
+ </para>
+ <para>In Portal Extension quickstart, we have added a couple of navigation
nodes and pages to the ones available in the default GateIn Portal
installation.</para>
+ <section id="portal-configuration-xml">
+ <title>portal-configuration.xml</title>
+ <para>
+ In Portal Extension quickstart, this configuration file is located in
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/portal</code>
+ directory. It is the starting point of the navigation customization. We
will not say more about this file here as there is usually no need to change it. Please
refer to
+ <ulink
url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426...
Navigation Configuration</ulink>
+ section of GateIn Portal Reference Guide for more information.
+ </para>
+ </section>
+ <section id="Three_Kinds_Of_Navigation">
+ <title>Three kinds of Navigation</title>
+ <para>Rather than using too many words to explain what and why, let us
look at the following image:</para>
+ <figure>
+ <title>TODO InformalFigure image title empty</title>
<mediaobject>
- <imageobject role="html">
- <imagedata align="center" scale="100"
fileref="images/7372962/portalextensionstructure.png"
format="PNG"/>
- </imageobject>
-
- <imageobject role="fo">
- <imagedata width="150mm" align="center"
fileref="images/7372962/portalextensionstructure.png"
format="PNG"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="images/Kinds+of+Navigation.png"/>
+ </imageobject>
</mediaobject>
- </figure>
-
- <section id="sid-7372962_GDG-Portalcontainers-Portalextension">
- <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.
+ </figure>
+ </section>
+ <section id="Adding_Navigation_Node_Site_Navigation">
+ <title>Adding a Navigation Node to a Site Navigation</title>
+ <para>
+ Let us have a look at
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/portal/portal/classic/navigation.xml</code>
+ . Note that in this path,
+ <emphasis role="italics">classic</emphasis>
+ is the name of the site the navigation of which we are which we want to
define.
</para>
-
- <para>
- Portal extensions can shadow existing services, a portal will usually be
composed of various extensions, which usually add services.
+ <example>
+ <title>Site-wide navigation.xml</title>
+ <programlisting>
+19. <node-navigation
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+20. xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_3
http://www.gatein.org/xml/ns/gatein_objects_1_3"
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+21. <!-- Priority has no significance in site navigations. But it is required.
See GTNPORTAL-2751 -->
+22. <priority>1</priority>
+23.
+24. <!--
+25. In this file, we are adding a navigation node to the navigation of the site
called "classic".
+26. The site-wide navigation is used e.g. in NavigationPortlet.
+27. Visibility of navigation nodes depends on <access-permissions>
set in the sibling pages.xml file.
+28. See also portal.configuration section of the file
../../portal-configuration.xml.
+29. -->
+30. <page-nodes>
+31. <node>
+32. <name>page-just-added</name>
+33. <!--
+34. #{portal.extension.justAddedPage} is place holder for an
internationalized string.
+35. See WEB-INF/classes/locale/navigation/portal/classic_en.properties
+36. -->
+37.
<label>#{portal.extension.justAddedPage}</label>
+</programlisting>
+ </example>
+ <para>
+ In this file, we have added
+ <code>page-just-added</code>
+ navigation node into the portal navigation. It can be seen in the
navigation bar.
</para>
-
- <figure>
- <title>Example</title>
-
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" scale="100"
fileref="images/7372962/portalExtensions.png" format="PNG"/>
- </imageobject>
- </mediaobject>
+ <para>
+ <figure>
+ <title>TODO InformalFigure image title empty</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/navigation-bar.png"/>
+ </imageobject>
+ </mediaobject>
</figure>
-
- <para>
- In a portal extension, elements are shadowed by using the same directory
location, so if you want to rewrite the groovy template of the HomePagePortlet which is
located in
<filename>gatein.ear/02portal.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</filename>,
it would be in an extension at a location such as
<filename>myExtension/myWar.war/templates/groovy/webui/component/UIHomePagePortlet.gtmpl</filename>.
The ordering will be defined by the portal extension configuration.
</para>
- </section>
+ <para>
+ The
+ <code>page-just-added</code>
+ navigation node refers to
+ <code>portal::classic::justAddedPage</code>
+ which we define in
+ <code>pages.xml</code>
+ file located in the same directory as the above
+ <code>navigation.xml</code>
+ .
+ </para>
+ <example>
+ <title>Site-wide pages.xml</title>
+ <programlisting>
+19. <page-set
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_3
http://www.gatein.org/xml/ns/gatein_objects_1_3"
+20.
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+21. <page>
+22. <name>justAddedPage</name>
+23. <title>Page Just Added</title>
+24. <!-- This page and any navigation nodes refering to it will be visible
to all visitors (signed in or anonymous). -->
+25.
<access-permissions>Everyone</access-permissions>
+26.
<edit-permission>*:/platform/administrators</edit-permission>
+27. <portlet-application>
+28. <portlet>
+29.
<application-ref>gatein-portal-extension</application-ref>
+30.
<portlet-ref>JustAddedPortlet</portlet-ref>
+31. </portlet>
+32. <title>Just Added Portlet</title>
+33.
<access-permissions>Everyone</access-permissions>
+34. <show-info-bar>false</show-info-bar>
+35.
<show-application-state>false</show-application-state>
+36.
<show-application-mode>false</show-application-mode>
+37. </portlet-application>
+38. </page>
+39. </page-set>
+</programlisting>
+ </example>
+ <para>
+ Note that
+ <code>page-just-added</code>
+ navigation node and the related pages are visible to all portal visitors
(signed in or anonymous) due to
+ <code><access-permissions></code>
+ set to
+ <code>Everyone</code>
+ in the above file.
+ </para>
+ </section>
+ <section id="Adding_Navigation_Node_Group_Navigation">
+ <title>Adding a Navigation Node to a Group Navigation</title>
+ <para>
+ To add a new navigation node visible to the members of
+ <code>/platform/administrators</code>
+ group we need to create a
+ <code>navigation.xml</code>
+ file located in
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/portal/group/platform/administrators/navigation.xml</code>
+ . Note that the name of the user group
+ <code>/platform/administrators</code>
+ is a part of the path.
+ </para>
+ <example>
+ <title>navigation.xml of /platform/administrators group</title>
+ <programlisting>
+19. <node-navigation
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+20. xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_3
http://www.gatein.org/xml/ns/gatein_objects_1_3"
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+21. <!-- Priority is currently ignored for importMode merge. But it is
required. See GTNPORTAL-2751 -->
+22. <priority>1</priority>
+23.
+24. <page-nodes>
+25. <node>
+26. <name>admins-sitemap</name>
+27. <!--
+28. #{platform.administrators.adminsSitemap} is place holder for an
internationalized string.
+29. See
WEB-INF/classes/locale/navigation/group/platform/administrators_en.properties
+30. -->
+31.
<label>#{platform.administrators.adminsSitemap}</label>
+32.
<page-reference>group::/platform/administrators::adminsSitemap</page-reference>
+33. </node>
+34. </page-nodes>
+35. </node-navigation>
+</programlisting>
+ </example>
+ <para>
+ The navigation node
+ <code>admins-sitemap</code>
+ refers to
+ <code>adminsSitemap</code>
+ page defined in the sibling
+ <code>pages.xml</code>
+ file:
+ </para>
+ <example>
+ <title>pages.xml of /platform/administrators group</title>
+ <programlisting>
+19.
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+20. <!--
+21. adminsSitemap page contains just SiteMapPortlet. There is nothing special
about it.
+22. It is here just to demonstrate the adding of nodes to group navigation in the
sibling
+23. navigation.xml file.
+24. -->
+25. <page>
+26. <name>adminsSitemap</name>
+27. <title>Admins' Sitemap</title>
+28.
<access-permissions>*:/platform/administrators</access-permissions>
+29.
<edit-permission>*:/platform/administrators</edit-permission>
+30. <portlet-application>
+31. <portlet>
+32. <application-ref>web</application-ref>
+33.
<portlet-ref>SiteMapPortlet</portlet-ref>
+34. </portlet>
+35. <title>Sitemap</title>
+36.
<access-permissions>*:/platform/administrators</access-permissions>
+37. <show-info-bar>false</show-info-bar>
+38. </portlet-application>
+39. </page>
+40. </page-set>
+</programlisting>
+ </example>
+ </section>
+ <section id="Adding_Navigation_Node_User_Navigation">
+ <title>Adding a Navigation Node to a User Navigation</title>
+ <para>
+ To add a new navigation node visible to a particular user, say
+ <code>root</code>
+ we need to create a
+ <code>navigation.xml</code>
+ file located in
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/portal/user/root/navigation.xml</code>
+ . Note that the name of the user
+ <code>root</code>
+ is a part of the path.
+ </para>
+ <example>
+ <title>navigation.xml of user root</title>
+ <programlisting>
+19. <node-navigation
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+20. xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_3
http://www.gatein.org/xml/ns/gatein_objects_1_3"
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+21. <!-- Priority has no significance in user navigations. But it is required.
See GTNPORTAL-2751 -->
+22. <priority>1</priority>
+23.
+24. <page-nodes>
+25. <node>
+26. <name>roots-extra-dashboard</name>
+27.
<label>#{user.root.RootsExtraDashboard}</label>
+28.
<page-reference>user::root::roots-dashboard</page-reference>
+29. </node>
+30. </page-nodes>
+31. </node-navigation>
+</programlisting>
+ </example>
+ <para>
+ The navigation node
+ <code>roots-extra-dashboard</code>
+ refers to
+ <code>roots-dashboard</code>
+ page defined in the sibling
+ <code>pages.xml</code>
+ file:
+ </para>
+ <example>
+ <title>pages.xml of user root</title>
+ <programlisting>
+19. <page-set
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_3
http://www.gatein.org/xml/ns/gatein_objects_1_3"
+20.
xmlns="http://www.gatein.org/xml/ns/gatein_objects_1_3"...
+21. <!--
+22. roots-dashboard page contains just DashboardPortlet. There is nothing special
about it.
+23. It is here just to demonstrate the adding of nodes to user navigation in the
sibling
+24. navigation.xml file.
+25. -->
+26. <page>
+27. <name>roots-dashboard</name>
+28. <title>Root's Extra Dashboard</title>
+29.
<access-permissions>*:/platform/users</access-permissions>
+30.
<edit-permission>*:/platform/administrators</edit-permission>
+31. <portlet-application>
+32. <portlet>
+33.
<application-ref>dashboard</application-ref>
+34.
<portlet-ref>DashboardPortlet</portlet-ref>
+35. </portlet>
+36. <title>Root's Extra
Dashboard</title>
+37.
<access-permissions>*:/platform/users</access-permissions>
+38. <show-info-bar>false</show-info-bar>
+39. </portlet-application>
+40. </page>
+41. </page-set>
+42.
+</programlisting>
+ </example>
+ </section>
+ <section id="Internationalization_Navigation_Nodes">
+ <title>Internationalization of Navigation Nodes</title>
+ <para>
+ As you can see in the above
+ <code>navigation.xml</code>
+ files the labels of navigation nodes can be internationalized. The files
containing translation resources live under
+
<code>war/src/main/webapp/WEB-INF/classes/locale/navigation</code>
+ . The directory layout is similar to the one used for
+ <code>navigation.xml</code>
+ and
+ <code>pages.xml</code>
+ files:
+ </para>
+ <para>
+ Note that the navigation resource bundles also need to be named in
+ <code>init.resources</code>
+ parameter of
+ <code>BaseResourceBundlePlugin</code>
+ in
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/common/common-configuration.xml</code>
+ :
+ </para>
+ <example>
+ <title>common-configuration.xml containing declarations of navigation
resource bundles</title>
+ <programlisting>
+19. <configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+20. xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd
http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"...
+21. <external-component-plugins>
+22. <!-- The full qualified name of the ResourceBundleService -->
+23.
<target-component>org.exoplatform.services.resources.ResourceBundleService</target-component>
+24. <component-plugin>
+25. <!-- The name of the plugin -->
+26. <name>Sample ResourceBundle Plugin</name>
+27. <!-- The name of the method to call on the ResourceBundleService
in order to register the ResourceBundles -->
+28. <set-method>addResourceBundle</set-method>
+29. <!-- The full qualified name of the BaseResourceBundlePlugin
-->
+30.
<type>org.exoplatform.services.resources.impl.BaseResourceBundlePlugin</type>
+31. <init-params>
+32. <values-param>
+33. <name>init.resources</name>
+34. <description>Initiate the following resources
during the first launch.</description>
+35.
<value>locale.portal.extension</value>
+36.
<value>locale.navigation.user.root</value>
+37. <!--
+38. Note that we actually do not need to name
locale.navigation.portal.classic and
+39. locale.navigation.group.platform.administrators here as they
are in init.resources
+40. of the default GateIn installation. But it makes no harm to
include them once again here.
+41. -->
+42.
<value>locale.navigation.portal.classic</value>
+43.
<value>locale.navigation.group.platform.administrators</value>
+44. </values-param>
+45. <values-param>
+</programlisting>
+ </example>
+ </section>
</section>
-
- <section id="sid-8094158">
- <title>Visual identity</title>
-
- <para>
+ <section id="Custom_Internationalization_Resource_Bundles">
+ <title>Custom Internationalization Resource Bundles</title>
+ <para>
+ This section mentions code from the Portal Extension Examples available for
download from <ulink url="https://access.redhat.com/"/>;. as part of your
JBoss Portal Platform subscription.
+ </para>
+ <para>There are two resource bundle customization scenarios possible with a
Portal Extension:</para>
+ <itemizedlist>
+ <listitem>
+ <para>to add new resource bundle items to the ones available in default
GateIn Portal installation and</para>
+ </listitem>
+ <listitem>
+ <para>to assign new values to resource bundle items available in
default GateIn Portal installation</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Both scenarios can be demonstrated on
+ <code>locale.portal.extension</code>
+ resource bundle. To use this bundle we need to include it in both
+ <code>init.resources</code>
+ and
+ <code>portal.resource.names</code>
+ parameters of
+ <code>BaseResourceBundlePlugin</code>
+ in
+
<code>war/src/main/webapp/WEB-INF/conf/sample-ext/common/common-configuration.xml</code>
+ :
+ </para>
+ <example>
+ <title>common-configuration.xml containing declarations of navigation
resource bundles</title>
+ <programlisting>
+19. <configuration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+20. xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd
http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"
xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd"...
+21. <external-component-plugins>
+22. <!-- The full qualified name of the ResourceBundleService -->
+23.
<target-component>org.exoplatform.services.resources.ResourceBundleService</target-component>
+24. <component-plugin>
+25. <!-- The name of the plugin -->
+26. <name>Sample ResourceBundle Plugin</name>
+27. <!-- The name of the method to call on the ResourceBundleService
in order to register the ResourceBundles -->
+28. <set-method>addResourceBundle</set-method>
+29. <!-- The full qualified name of the BaseResourceBundlePlugin
-->
+30.
<type>org.exoplatform.services.resources.impl.BaseResourceBundlePlugin</type>
+31. <init-params>
+32. <values-param>
+33. <name>init.resources</name>
+34. <description>Initiate the following resources
during the first launch.</description>
+35.
<value>locale.portal.extension</value>
+36.
<value>locale.navigation.user.root</value>
+37. <!--
+38. Note that we actually do not need to name
locale.navigation.portal.classic and
+39. locale.navigation.group.platform.administrators here as they
are in init.resources
+40. of the default GateIn installation. But it makes no harm to
include them once again here.
+41. -->
+42.
<value>locale.navigation.portal.classic</value>
+43.
<value>locale.navigation.group.platform.administrators</value>
+44. </values-param>
+45. <values-param>
+46. <name>portal.resource.names</name>
+47. <description>These resources are merged to a single
resource bundle which is accessible from anywhere
+48. in GateIn. All these keys are located in the same bundle,
which is separated from the navigation
+49. resource bundles.</description>
+50.
<value>locale.portal.extension</value>
+51. </values-param>
+52. </init-params>
+53. </component-plugin>
+54. </external-component-plugins>
+55. </configuration>
+</programlisting>
+ </example>
+ <para>
+ The English version of
+ <code>locale.portal.extension</code>
+ can be found under
+
<code>war/src/main/webapp/WEB-INF/classes/locale/portal/extension_en.properties</code>
+ :
+ </para>
+ <example>
+ <title>English version of locale.portal.extension</title>
+ <programlisting>
+17. UIHomePagePortlet.Label.Slogan=Congratulations!
+18. UIHomePagePortlet.Label.SubSlogan=You have just installed the GateIn Portal
Extension
+19. UIHomePagePortlet.Label.Title=Sign in as:
+</programlisting>
+ </example>
+ <para>
+ <code>UIHomePagePortlet.Label.SubSlogan</code>
+ is a new key which is not available in default GateIn Portal installation.
+ </para>
+ <para>
+ However,
+ <code>UIHomePagePortlet.Label.Slogan</code>
+ is redefined in
+ <code>extension_en.properties</code>
+ shown above. In
+
<code>gatein.ear/web.war/WEB-INF/classes/locale/portlet/web/GroovyPortlet_en.properties</code>
+ it is already defined as
+ </para>
+ <programlisting>UIHomePagePortlet.Label.Slogan=The Best of eXo and JBoss
Portal<div>GateIn
#{gatein.version}</div></programlisting>
+ <para>
+ and here, within the Portal Extension we assign a new value
+ <code>Congratulations!</code>
+ to it.
+ </para>
+ <para>
+ Please refer to the
+ <link
linkend="Adding_Navigation_Node_Group_Navigation">previous
section</link>
+ for more details on internationalization of navigation nodes.
+ </para>
+ </section>
+ <section id="Custom_Sign_In_Page">
+ <title>Custom Sign in Page</title>
+ <para>When accessing a page that requires privileges, a Sign in page is
shown and it can be customized by using an extension. To do so, it would be enough to copy
the file located at:</para>
+ <example>
+ <title>Login JSP</title>
+ <programlisting>
+gatein.ear/portal.war/login/jsp/login.jsp
+</programlisting>
+ </example>
+ <para>and include it in a 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>
+ <title>Login Form</title>
+ <programlisting>
+gatein.ear/portal.war/groovy/portal/webui/UILoginForm.gtmpl
+</programlisting>
+ </example>
+ </section>
+ </section>
+ </section>
+ <section id="Visual_Identity">
+ <title>Visual identity</title>
+ <para>
A portal visual identity is made of HTML produced as a result of portal
aggregation (the components that make a page like columns and rows combined with the
content produced by the portlets) and associated CSS files.
</para>
-
- <para>
+ <para>
JBoss Portal Platform allows to deploy multiple skins consisting of CSS
files, which makes it possible to apply styling to 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="sid-8094158_GDG-Visualidentity-Customizingtheloginpage">
- <title>Customizing the login page</title>
-
- <para>
+ <section id="Customizing_Login_Page">
+ <title>Customizing the login page</title>
+ <para>
When accessing a page that requires privileges, a login page is shown and
it can be customized by using an extension. To do so, it would be enough to copy the file
located at:
</para>
-
- <example>
- <title>Login JSP</title>
-<programlisting>gatein.ear/02portal.war/login/jsp/login.jsp</programlisting>
- </example>
-
- <para>
+ <example>
+ <title>Login JSP</title>
+
<programlisting>gatein.ear/02portal.war/login/jsp/login.jsp</programlisting>
+ </example>
+ <para>
and include it in a portal extension such as
myExtension.ear/myWar.war/login/jsp/login.jsp
</para>
-
- <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>
+ <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>
- <title>Login Form</title>
-<programlisting>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</programlisting>
- </example>
- </section>
- </section>
- </chapter>
+ <example>
+ <title>Login Form</title>
+
<programlisting>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</programlisting>
+ </example>
+ </section>
+ </section>
+</chapter>
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/Kinds+of+Navigation.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/Kinds+of+Navigation.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/complexinfra.png
===================================================================
(Binary files differ)
Property changes on: epp/docs/branches/6.0/Developer_Guide/en-US/images/complexinfra.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-local-index.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-local-index.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-shared-index.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-shared-index.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-standalone-index.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/diagram-standalone-index.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/navigation-bar.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/navigation-bar.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/portalExtensions.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/portalExtensions.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/portalextensionstructure.png
===================================================================
(Binary files differ)
Property changes on:
epp/docs/branches/6.0/Developer_Guide/en-US/images/portalextensionstructure.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: epp/docs/branches/6.0/Developer_Guide/en-US/images/simpleinfra.png
===================================================================
(Binary files differ)
Property changes on: epp/docs/branches/6.0/Developer_Guide/en-US/images/simpleinfra.png
___________________________________________________________________
Added: svn:mime-type
+ image/png