[gatein-commits] gatein SVN: r8849 - in epp/docs/branches/6.0/Reference_Guide/en-US: extras/PortletBridge_Configuration and 4 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Sep 19 02:42:19 EDT 2012
Author: jaredmorgs
Date: 2012-09-19 02:42:19 -0400 (Wed, 19 Sep 2012)
New Revision: 8849
Modified:
epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml
epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default197.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default200.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default202.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default218.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default219.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default224.xml
epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default225.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml
epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml
Log:
BZ#856417 - First draft of Portlet Bridge rework
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -3,66 +3,20 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent">
%BOOK_ENTITIES;
]>
-<book>
+<book status="draft">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Introduction.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/PortalDevelopment.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/PortletDevelopment.xml"/>
-<!-- <xi:include href="modules/GadgetDevelopment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <part>
+ <part>
<title>Authentication and Authorization</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/AuthenticationAndIdentity.xml"/>
</part>
<part>
- <title>Portlet Bridge</title>
- <chapter>
- <title><remark/>Overview</title>
- <section>
- <title>Portlet Bridge</title>
- <para>A portlet bridge allows non-native application frameworks to run in a portal environment, independent to the underlying portlet API, or portlet concept. This functionality provides a developer flexibility to continue writing applications in a preferred language, and allows a controlled transition to new technologies. </para>
- </section>
- <section>
- <title>JBoss Portlet Bridge</title>
- <para>The JBoss Portlet Bridge is a non-final draft implementation of the JSR-329 specification which supports the JSF 1.2 and 2.0 runtime within a JSR 168 or 286 portlet and with added enhancements to support other web frameworks (such as Seam and RichFaces).
-
-The project follows the spec from JSR-301 to JSR-329 and now maintains an alpha version (3.0) compatible with JSF 2.0 and RichFaces 4.0.</para>
- </section>
- <section>
- <title>File Locations</title>
- <remark>BZ#856417 - NEEDINFO - Do not have the root configuration directory for Portlet Bridge. Asked Ken in email on 17th Sep.</remark>
- <para>Configuration files for Portlet Bridge are located in the <DIRECTORY PATH GOES HERE>.</para>
- <para><variablelist>
- <varlistentry>
- <term>portlet.xml</term>
- <listitem>
- <para>Contains the primary configuration information for the portlet. Information such as the GenericFacesPortlet location, and which Java Server Faces (JSF) pages to render are stored in this file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>faces-config.xml</term>
- <listitem>
- <para>Contains</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>web.xml</term>
- <listitem>
- <para/>
- </listitem>
- </varlistentry>
- </variablelist></para>
- </section>
- </chapter>
- <chapter>
- <title>Configuration </title>
- <section/>
- </chapter>
- </part>
- <part>
<title>Web Services for Remote Portlets (WSRP)</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/WSRP.xml"/>
</part>
- <part/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Advanced.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -8,8 +8,8 @@
<simpara>
<revhistory>
<revision>
- <revnumber>5.2.2-100</revnumber>
- <date>Wed Sep 05 2012</date>
+ <revnumber>6.0.0-1</revnumber>
+ <date>Thu Sep 19 2012</date>
<author>
<firstname>Jared</firstname>
<surname>Morgan</surname>
@@ -17,38 +17,10 @@
</author>
<revdescription>
<simplelist>
- <member>Prepared guide for JBoss Enterprise Portal Platform 5.2.2 GA. Refer to 5.2.2 Release Notes for a summary of changes to this guide.</member>
+ <member>BZ#856417 - First draft containing Portlet Bridge work. </member>
</simplelist>
</revdescription>
</revision>
- <revision>
- <revnumber>5.2.1-100</revnumber>
- <date>Tue Apr 17 2012</date>
- <author>
- <firstname>Jared</firstname>
- <surname>Morgan</surname>
- <email/>
- </author>
- <revdescription>
- <simplelist>
- <member>Prepared guide for JBoss Enterprise Portal Platform 5.2.1 GA. Refer to 5.2.1 Release Notes for a summary of changes to this guide.</member>
- </simplelist>
- </revdescription>
- </revision>
- <revision>
- <revnumber>5.2.0-100</revnumber>
- <date>Wed Dec 14 2011</date>
- <author>
- <firstname>Scott</firstname>
- <surname>Mumford</surname>
- <email/>
- </author>
- <revdescription>
- <simplelist>
- <member>Publication build.</member>
- </simplelist>
- </revdescription>
- </revision>
</revhistory>
</simpara>
</appendix>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default197.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default197.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default197.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1,20 +1,54 @@
-<portlet>
+<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+ version="2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
+ <portlet>
<portlet-name>yourPortletName</portlet-name>
<portlet-class>
javax.portlet.faces.GenericFacesPortlet
</portlet-class>
-
+<!-- MANDATORY -->
<init-param>
<name>javax.portlet.faces.defaultViewId.view</name>
<value>/welcome.xhtml</value>
</init-param>
-
+<!-- OPTIONAL -->
<init-param>
<name>javax.portlet.faces.defaultViewId.edit</name>
<value>/jsf/edit.xhtml</value>
</init-param>
-
+<!-- OPTIONAL -->
<init-param>
<name>javax.portlet.faces.defaultViewId.help</name>
<value>/jsf/help.xhtml</value>
</init-param>
+<!-- OPTIONAL - Preserves request parameters received as part of an portal ActionRequest -->
+ <init-param>
+ <name>javax.portlet.faces.preserveActionParams</name>
+ <value>true</value>
+ </init-param>
+<!-- OPTIONAL - explicitly set GenericFacesPortlet to override bridge event dispatch -->
+ <init-param>
+ <name>javax.portlet.faces.autoDispatchEvents</name>
+ <value>true</value>
+ </init-param>
+<!-- OPTIONAL - Receive Event - specifies whether the portlet can receive bridge events. In this case, a BookingEventHandler event -->
+ <init-param>
+ <name>javax.portlet.faces.bridgeEventHandler</name>
+ <value>org.jboss.example.booking.BookingEventHandler</value>
+ </init-param>
+
+<!-- OPTIONAL -->
+ <supported-publishing-event>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">[namespace]:[Event_name]</qname>
+ </supported-publishing-event>
+<!-- OPTIONAL -->
+ <event-definition>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">[namespace]:[event_name]</qname>
+ <value-type>[the appropriate class to map the application type to]</value-type>
+ </event-definition>
+<!-- OPTIONAL - Receive Event -->
+ <supported-processing-event>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">[namespace]:[event_name]</qname>
+ </supported-processing-event>
+</portlet>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default200.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default200.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default200.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -3,8 +3,11 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
...
- <!-- This is optional parameters for a facelets based application -->
- <context-param>
- <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
- <param-value>org.jboss.portletbridge.application.FaceletPortletViewHandler</param-value>
- </context-param>
+ <context-param>
+ <param-name>
+ javax.portlet.faces.RENDER_POLICY
+ </param-name>
+ <param-value>
+ ALWAYS_DELEGATE
+ </param-value>
+ </context-param>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default202.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default202.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Configuration/default202.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -2,12 +2,12 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
-
- <context-param>
- <param-name>javax.portlet.faces.RENDER_POLICY </param-name>
- <param-value>
- NEVER_DELEGATE
- </param-value>
- </context-param>
- ...
+<!-- Other configuration information removed for clarity -->
+ <context-param>
+ <param-name>javax.portlet.faces.RENDER_POLICY </param-name>
+ <param-value>
+ NEVER_DELEGATE
+ </param-value>
+ </context-param>
+<!-- Other configuration information removed for clarity -->
</web-app>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default218.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default218.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default218.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1 +1 @@
-<security:portal-identity authenticate-method="#{authenticator.authenticate}"/>
+<security:portal-identity authenticate-method="#{authenticator.authenticate}"/>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default219.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default219.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_GettingStarted/default219.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1,4 +1,4 @@
- <context-param>
- <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
- <param-value>true</param-value>
- </context-param>
+<context-param>
+ <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
+ <param-value>true</param-value>
+</context-param>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default224.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default224.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default224.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1,7 +1,7 @@
<navigation-rule>
- <from-view-id>/register.jspx</from-view-id>
- <navigation-case>
- <from-outcome>edit</from-outcome>
- <to-view-id>/edit.jspx?javax.portlet.faces.PortletMode=edit</to-view-id>
- </navigation-case>
-</navigation-rule>
\ No newline at end of file
+ <from-view-id>/register.xhtml</from-view-id>
+ <navigation-case>
+ <from-outcome>edit</from-outcome>
+ <to-view-id>/edit.xhtml?javax.portlet.faces.PortletMode=edit</to-view-id>
+ </navigation-case>
+</navigation-rule>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default225.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default225.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/extras/PortletBridge_Portlet_Development/default225.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1,7 +1,7 @@
<navigation-rule>
- <from-view-id>/edit.jspx*</from-view-id>
- <navigation-case>
- <from-outcome>view</from-outcome>
- <to-view-id>#{sessionScope['javax.portlet.faces.viewIdHistory.view']}</to-view-id>
- </navigation-case>
-</navigation-rule>
\ No newline at end of file
+ <from-view-id>/edit.xhtml*</from-view-id>
+ <navigation-case>
+ <from-outcome>view</from-outcome>
+ <to-view-id>#{sessionScope['javax.portlet.faces.viewIdHistory.view']}</to-view-id>
+ </navigation-case>
+</navigation-rule>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -40,11 +40,8 @@
</portlet-app>
</programlisting>
<para>
- The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default The file path is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/portlet.xml</filename>
+ The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default, the file path is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/portlet.xml</filename>
</para>
- <para>
- <emphasis role="bold">For JBoss</emphasis>: The file path is <filename><replaceable>EPP_DIST</replaceable>/jboss-as/server/default/conf/gatein/portlet.xml</filename>.
- </para>
<section id="sect-Reference_Guide-Shared_portlet.xml-Global_Metadata_Elements">
<title>Global Metadata Elements</title>
<para>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -5,663 +5,58 @@
]>
<section id="sect-Reference_Guide-Bridge_Configuration">
<title>Bridge Configuration</title>
- <para>
- The 329 specification is aimed at making the developer's life as easy as possible with JSF+Portlet development. You will see below that there are minimal settings to getting any JSF web application up and running in the Portal environment.
- </para>
-<!-- Commented as Maven Archetypes section removed from gettingstarted.xml
- <para>
- If you are new to these concepts, we highly recommend you refer to <xref linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes" />.
- </para> --> <section id="sect-Reference_Guide-Bridge_Configuration-Core_Setup_and_Configuration">
- <title>Core Setup and Configuration</title>
- <section id="sect-Reference_Guide-Core_Setup_and_Configuration-portlet.xml">
- <title>portlet.xml</title>
- <para>
- The basic JSR-329 portlet configuration.
+ <section id="sect-Reference_Guide-Core_Setup_and_Configuration-portlet.xml">
+ <title>portlet.xml</title>
+ <para>To have access to all portlet 2 specification features, you must declare the portlet schema definition as prescribed in the <filename>portlet.xml</filename> file. The <init-param> directives are explained in more detail if required below the portlet.xml code.</para>
+ <para>The XML below describes the basic directives required for a JSF2 portlet.
+Some directives are optional, and are called-out in the file. </para>
+ <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default197.xml" parse="text"/></programlisting>
+ <variablelist>
+ <title><init-param> directives</title>
+ <varlistentry>
+ <term>preserveActionParams</term>
+ <listitem>
+ <para>Specifies how request parameters are maintained during a portal action request. </para>
+ <important>
+ <para>When the entire portlet is written in JSF, this parameter must be set to <parameter>true</parameter>. If your portlet uses a mix of view technologies, set this parameter to <parameter>false</parameter>, or do not specify it.</para>
+ </important>
+ <para>
+ When set to <parameter>true</parameter>, the bridge must maintain any request parameters assigned during the portlet's <emphasis>bridge request scope</emphasis> action request.
+When set to <parameter>false</parameter>, or not defined, the action's request parameters are only maintained for the duration of the <emphasis>portlet request scope</emphasis>.
</para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default197.xml" parse="text"/></programlisting>
- <para>
- When <parameter>preserveActionParams</parameter> is set to <parameter>TRUE</parameter>, the bridge must maintain any request parameters assigned during the portlet's action request.
- </para>
- <para>
- The request parameters are maintained in the <emphasis>"bridge request scope"</emphasis>. When this attribute is not present or is <parameter>FALSE</parameter> the action's request parameters are only maintained for the duration of the <emphasis>portlet request scope</emphasis>.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default198.xml" parse="text"/></programlisting>
- </section>
- <section id="sect-Reference_Guide-Core_Setup_and_Configuration-faces_config.xml">
- <title>faces-config.xml</title>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>autoDispatchEvents</term>
+ <listitem>
+ <para>Explicitly specifies that GenericFacesPortlet overrides event handling to dispatch all events to the Bridge. </para>
+ <para>GenericFacesPortlet overrides event handling by default, without supplying this directive. However, this parameter can be set to <parameter>true</parameter> so the behavior is explicitly stated in the configuration file.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <title>Other directives</title>
+ <varlistentry>
+ <term><supported-publishing-event></term>
+ <listitem>
+ <para>Specifies that the portlet can publish an event to the portal. </para>
+ <para>The value of the <qname> parameter specifies a namespace (for example, jbp:), and the name to use when publishing the event (for example, BookingEvent).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><event-definition></term>
+ <listitem>
+ <para>Specifies how the event namespace and publishing name link to an actual type within a portlet application.</para>
+ <para>The directive requires a <qname> element, and a <value-type> element.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="sect-Reference_Guide-Core_Setup_and_Configuration-faces_config.xml">
+ <title>faces-config.xml</title>
+ <para>
The <parameter>PortletViewHandler</parameter> ensures that each JSF portlet instance is properly namespaced.
</para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default199.xml" parse="text"/></programlisting>
- </section>
- <section id="sect-Reference_Guide-Core_Setup_and_Configuration-Facelets_Configuration">
- <title>Facelets Configuration</title>
- <para>
- The following <filename>web.xml</filename> setting is only for <literal>Facelets</literal> based applications
- </para>
- <section id="sect-Reference_Guide-Facelets_Configuration-web.xml">
- <title>web.xml</title>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default200.xml" parse="text"/></programlisting>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default201.xml" parse="text"/></programlisting>
- <variablelist id="vari-Reference_Guide-web.xml-RenderPolicy_Options">
- <title>RenderPolicy Options</title>
- <varlistentry>
- <term>ALWAYS_DELEGATE</term>
- <listitem>
- <para>
- Indicates the bridge should not render the view itself but rather always delegate the rendering.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>NEVER_DELEGATE</term>
- <listitem>
- <para>
- Indicates the bridge should always render the view itself and never delegate.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DEFAULT</term>
- <listitem>
- <para>
- Directs the bridge to first delegate the render. If an exception is thrown, the bridge renders the view based on its own logic. If the configuration parameter is not present or has an invalid value the bridge renders using default behavior as it would if DEFAULT was set.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- </section>
- <section id="sect-Reference_Guide-Core_Setup_and_Configuration-JSP_Only_Configuration">
- <title>JSP Only Configuration</title>
- <para>
- The following <filename>web.xml</filename> setting is only for JSP based applications. Download the demonstration application <ulink url="http://anonsvn.jboss.org/repos/portletbridge/trunk/examples/jsf-ri/1.2-basic/">here</ulink>.
- </para>
- <section id="sect-Reference_Guide-JSP_Only_Configuration-web.xml">
- <title>web.xml</title>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default202.xml" parse="text"/></programlisting>
- </section>
- </section>
-<!-- Section removed as per feedback from Prabhat Jha
-<section id="sect-Reference_Guide-Core_Setup_and_Configuration-JSR_329">
- <title>JSR-329</title>
- <para>
- The JBoss Portlet Bridge can be used with any compatible implementation (for example, <literal>MyFaces</literal> implementation). Simply put the following into <filename>web.xml</filename>:
- </para>
-
-<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Configuration/default203.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- </section> --> </section>
-<!-- End 301 core setup --> <section id="sect-Reference_Guide-Bridge_Configuration-RichFaces_Setup_and_Configuration_Options">
- <title>RichFaces Setup and Configuration Options</title>
- <section id="sect-Reference_Guide-RichFaces_Setup_and_Configuration_Options-web.xml">
- <title>web.xml</title>
- <para>
- The following configuration is designated for portlets using the <application>RichFaces</application> library. These settings will vary based on your individual needs.
- </para>
- <para>
- See <ulink url="http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/devguide/en/html/ArchitectureOverview.html#ScriptsandStylesLoadStrategy"> this section</ulink> of the <application>RichFaces</application> documentation for more details.
- </para>
- <para>
- Sometimes it is better to use the "<parameter>ALL</parameter>" load strategy in portlets so you do not need to worry about loading the "framework.pack.js" and "ui.pack.js" files manually in your portlet header.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default204.xml" parse="text"/></programlisting>
- <note>
- <para>
- If you use the "<parameter>NONE</parameter>" strategy, you must include the following scripts in your portlet or portal page header. If you are using <application>JBoss Portal</application>, you can add this to the <filename>jboss-portlet.xml</filename> file.
- </para>
- </note>
- <para>
- The <literal>org.ajax4jsf.RESOURCE_URI_PREFIX</literal> configuration cross-references the path to your scripts below. These settings are required for <application>RichFaces</application> using the "<parameter>NONE</parameter>" strategy. Replace all <replaceable>richFacesPortlet</replaceable> text in the example with the actual name of the portlet resource. </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default205.xml" parse="text"/></programlisting>
- <para>
- <application>Seam</application> automatically configures your Ajax4JSF Filter, so if you are running a <application>Seam</application> portlet, you do not need the following Filter configuration (however, you do need the <literal>RESOURCE_URI_PREFIX</literal> no matter what).
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default206.xml" parse="text"/></programlisting>
- </section>
- <section id="sect-Reference_Guide-RichFaces_Setup_and_Configuration_Options-Configuration_needed_for_Richfaces_to_work_with_WSRP_and_PortletBridge">
-<!-- Content added from JBEPP-708 and JBQA-3999 --> <title>Configure RichFaces to work with WSRP and PortletBridge</title>
- <para>
- Use the following settings in <filename>web.xml</filename> when running WSRP portlets:
- </para>
- <programlisting language="XML" role="XML"><context-param>
- <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
- <param-value>false</param-value>
- </context-param>
-....
- <context-param>
- <param-name>org.richfaces.LoadStyleStrategy</param-name>
- <param-value>ALL</param-value>
- </context-param>
- <context-param>
- <param-name>org.richfaces.LoadScriptStrategy</param-name>
- <param-value>DEFAULT</param-value>
- </context-param>
-</programlisting>
- <para>
- The styles below must also be manually added to the facelets template header in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/portletbridge/examples/richFacesPortlet-<replaceable>VERSION</replaceable>.war:richFacesPortlet.war/templates/main.xhtml</filename> file.
- </para>
- <programlisting language="XML" role="XML"><link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/basic_both.xcss"/>
-<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/extended_both.xcss"/>
-<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>
-</programlisting>
- <para>
- The table below outlines the current status of RichFaces features when used in both local and remote portlets.
- </para>
- <table id="tabl-Reference_Guide-Configuration_needed_for_Richfaces_to_work_with_WSRP_and_PortletBridge-RichFaces_Feature_Status">
- <title>RichFaces Feature Status</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry> Richfaces Component </entry>
- <entry> Supported as Local Portlet </entry>
- <entry> Supported as Remote Portlet using WSRP </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>a4j:commandButton</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:commandLink</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:jsFunction</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:push</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:poll</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:queue</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:status</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:keepAlive</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:include</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:loadStyle</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:loadScript</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:ajaxValidator</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:beanValidator</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:graphValidator</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:mediaOutput</literal>
- </entry>
- <entry> No </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:outputPanel</literal>
- </entry>
- <entry> Yes (except Firefox 3.5) </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:log</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:dataTable</literal>
- </entry>
- <entry> Yes (except Firefox 3.6 and IE8) </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>a4j:dataFilterSlider</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:dataGrid</literal>
- </entry>
- <entry> Yes </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:dataList</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:datascroller</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:extendedDataTable</literal>
- </entry>
- <entry> Yes (except IE7) </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:repeat</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:scrollableDataTable</literal>
- </entry>
- <entry> Yes (except Firefox 3.6) </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>drag-drop support</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:contextMenu</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:dropDownMenu</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:tree</literal>
- </entry>
- <entry> Yes (except Firefox 3.5) </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:modalPanel</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:paint2d</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:panel</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:panelBar</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:panelMenu</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:progressBar</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:separator</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:simpleTogglePanel</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:spacer</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:tabPanel</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes (except tab deletion) </entry>
- </row>
- <row>
- <entry>
- <literal>rich:togglePanel</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:toolBar</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:toolTip</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:calendar</literal>
- </entry>
- <entry> Yes </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:colorPicker</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:comboBox</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:editor</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:fileUpload</literal>
- </entry>
- <entry> No </entry>
- <entry> No </entry>
- </row>
- <row>
- <entry>
- <literal>rich:inplaceSelect</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:inplaceInput</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:inputNumberSpinner</literal>
- </entry>
- <entry> Yes (except IE7) </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:inputNumberSlider</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:suggestionBox</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:listShuttle</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:orderingList</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- <row>
- <entry>
- <literal>rich:pickList</literal>
- </entry>
- <entry> Yes </entry>
- <entry> Yes </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-<!-- DO NOT UNCOMMENT <section>
-<title>jboss-portlet.xml</title>
-<para>
-To avoid scripts loading more than once from different portlet windows you can define additional scripts in
-jboss-portlet.xml. *Note the "rfRes" URI prefix that is mapped in the web.xml.</para>
-<programlisting role="XML"><![CDATA[
-<portlet>
-<portlet-name>ajaxPortlet</portlet-name>
-<header-content>
-<script src="/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script>
-<script src="/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script>
-<link rel="stylesheet" type="text/css" href="/faces/rfRes/org/richfaces/skin.xcss"/>
-</header-content>
-</portlet>
-]]></programlisting>
-</section> --> </section>
- <section id="sect-Reference_Guide-Bridge_Configuration-Seam_Setup_and_Configuration_Options">
- <title>Seam Setup and Configuration Options</title>
- <section id="sect-Reference_Guide-Seam_Setup_and_Configuration_Options-Configuration">
- <title>Configuration</title>
- <para>
- The <literal>ExceptionHandler</literal> is used to clean <application>Seam</application> contexts and transactions after errors.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default207.xml" parse="text"/></programlisting>
-<!-- Section removed as per feedback from Prabhat Jha
- <para>
- If you are using this bridge version from <literal>2.0.0.BETA</literal> through <literal>2.0.0.CR1</literal>, you must define the following <filename>web.xml</filename> parameter to use the JBoss Portlet Bridge provided Seam Phase Listener. This is done by the bridge automatically (if needed) in <literal>2.0.0.FINAL</literal>.
- </para>
-
-<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Configuration/default208.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --> </section>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default199.xml" parse="text"/></programlisting>
</section>
- <section id="sect-Reference_Guide-Bridge_Configuration-Portlet_2.0_Coordination">
- <title>Portlet 2.0 Coordination</title>
- <note>
- <title>Schema and XSD Definitions</title>
- <para>
- It is important to ensure, before using either of the following mechanisms, that the proper 2.0 schema and xsd are defined at the top of your <filename>portlet.xml</filename>.
- </para>
- </note>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default209.xml" parse="text"/></programlisting>
- <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events">
- <title>Sending and Receiving Events</title>
- <section id="sect-Reference_Guide-Sending_and_Receiving_Events-Configuration">
- <title>Configuration</title>
- <para>
- Just like with any portlet 2.0 event consumer and receiver, you must define them in the <filename>portlet.xml</filename>.
- </para>
-<!-- Unsure if community reference is appropriate enterprise doc. As per QE concern (anross
-<para>
-To see a working example, checkout the Seam Booking Demo portlet. <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.FINAL/examples/seam/booking/" />
-</para> --> <para>
- You must also define the following <emphasis>init params</emphasis> in your <filename>portlet.xml</filename>.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default210.xml" parse="text"/></programlisting>
- <para>
- While future versions of the 2.0 bridge will automate the dispatching and consuming of events, at the moment you must dispatch the event in the JSF or Seam backing bean.
- </para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default211.java" parse="text"/></programlisting>
- <para>
- You must also create the event handler class by implementing the <literal>BridgeEventHandler</literal> interface to process the event payload.
- </para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/BookingEventHandler.java" parse="text"/></programlisting>
- </section>
- </section>
- <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters">
- <title>Public Render Parameters</title>
- <section id="sect-Reference_Guide-Public_Render_Parameters-Configuration">
- <title>Configuration</title>
- <para>
- Public Render Parameters (or PRPs) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or otherwise) can share the same render parameters. This feature can be used to present a cohesive UI to the user across all portlets on the page. An example would be using an employee ID to display relative data.
- </para>
- <para>
- The bridge maps a render parameter to a backing bean using settings in your <filename>faces-config.xml</filename> and <filename>portlet.xml</filename>.
- </para>
- <para>
- A clear and working example can be found in the Seam Booking Demo portlet. <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/examples/seam/booking/"/>
- </para>
- <para>
- You must define the following <emphasis>init params</emphasis> in your <filename>portlet.xml</filename>.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default212.xml" parse="text"/></programlisting>
- <para>
- Create a managed bean and <literal>public-parameter-mappings</literal> in your <filename>faces-config.xml</filename>. This should be a basic bean that you can bind the passed parameter to a string with <emphasis>getter</emphasis> and <emphasis>setter</emphasis>.
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default213.xml" parse="text"/></programlisting>
- <para>
- You must set the parameter in the JSF or Seam backing bean, if you are providing one from your portlet.
- </para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default214.java" parse="text"/></programlisting>
- <para>
- Then you must also implement the <literal>BridgePublicRenderParameterHandler</literal> interface to process any updates from the received parameter.
- </para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default215.java" parse="text"/></programlisting>
- </section>
- </section>
- <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet">
- <title>Serving Your JSF Resources in a Portlet</title>
- <section id="sect-Reference_Guide-Serving_Your_JSF_Resources_in_a_Portlet-Configuration">
- <title>Configuration</title>
- <para>
- We have setup a few examples to show you how to use <literal>EL</literal> and a simple bean that will allow you to use the portlet resource serving mechanism within a JSF portlet.
- </para>
- <para>
- In <ulink url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.3.0.CP01.EPP521/examples/richfaces/richfaces-demo/src/main/java/org/richfaces/demo/common/ResourceBean.java">ResourceBean.java</ulink>, you can see a very simple implementation of a Map object that uses the bridge to get and encode a resource URL served from the portlet application.
- </para>
- <para>
- So, when you have the normal "<filename>/images</filename>", "<filename>/styles</filename>" and other resource folders in your web application, you can use the following <literal>EL</literal> expression to serve them in your JSF application.
- </para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default216.java" parse="text"/></programlisting>
- <para>
- Just copy the <literal>ResourceBean.java</literal> code above, and add an entry to your <filename>faces-config.xml</filename> for the bean:
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default217.xml" parse="text"/></programlisting>
- </section>
- </section>
- </section>
</section>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -8,6 +8,48 @@
<para>
This chapter demonstrates common development tasks described by the 329 specification.
</para>
+ <section>
+ <title>Portlet tags</title>
+ <para>Portlet Bridge supports the following tags from section PLT.26 of the Portlet 2.0 Spec (JSR 286):</para>
+ <itemizedlist>
+ <listitem>
+ <para>actionURL</para>
+ </listitem>
+ <listitem>
+ <para>renderURL</para>
+ </listitem>
+ <listitem>
+ <para>resourceURL</para>
+ </listitem>
+ <listitem>
+ <para>namespace</para>
+ </listitem>
+ <listitem>
+ <para>param</para>
+ </listitem>
+ <listitem>
+ <para>property</para>
+ </listitem>
+ </itemizedlist>
+ <para>When using the tag library, the following namespace needs to be added to the facelet page of the application.</para>
+ <programlisting>xmlns:pbr="http://jboss.org/portletbridge"</programlisting>
+ <example>
+ <title>renderURL example</title>
+ <para>Generate a Portlet Render URL that enables switching between Portlet modes.</para>
+ <programlisting language="XML"><pbr:renderURL var="renderUrl" portletMode="edit">
+</pbr:renderURL>
+<h:outputLink value="#{renderUrl}">Edit Mode</h:outputLink></programlisting>
+ </example>
+ <example>
+ <title>namespace example</title>
+ <para>This portlet tag is particularly useful for prefixing JavaScript functions within a given portlet. This ensures that the JavaScript function name does not clash with a name from another portlet, or from the same portlet displayed on the same page multiple times. </para>
+ <para>An example for defining a JavaScript method is:</para>
+ <programlisting language="XML"><script type='text/javascript'>
+ function <pbr:namespace />DoSomething() {
+ }
+</script></programlisting>
+ </example>
+ </section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Excluding_Attributes_from_the_Bridge_Request_Scope">
<title>Excluding Attributes from the Bridge Request Scope</title>
<para>
@@ -18,18 +60,56 @@
</para>
<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default223.xml" parse="text"/></programlisting>
</section>
+ <section id="JSF_Facelet_View">
+ <title>JSF facelet view</title>
+ <para>When creating a JSF Facelet view document, it is common to see content wrapped with the following code.</para>
+ <programlisting language="HTML"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"
+ xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:a4j="http://richfaces.org/a4j">
+<!-- Unnecessary content removed for clarity -->
+</html></programlisting>
+ <para>Because a single portlet only reflects a potentially small portion of the HTML markup for a page, a JSF portlet returning the above markup for each portlet can be distracting, and potentially problematic.</para>
+ <para>The recommended way to wrap the content of a JSF Facelet view document for a portlet is to use the <f:view> element. Using <f:view> means that only the relevant content of the portlet mark-up is returned to the page.</para>
+ <programlisting language="HTML"><f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"
+ xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:a4j="http://richfaces.org/a4j">
+<!-- Unnecessary content removed for clarity -->
+</f:view></programlisting>
+ <note>
+ <para>While not specifically relevant to portlet, it is important to include <h:head> and <h:body> elements to allow JSF to process the facelet correctly.</para>
+ </note>
+ </section>
+ <section id="JSF_Facelet_Error_Handling">
+ <title>Error handling</title>
+ <para>To display error pages for specific exceptions in a JSF portlet, the following code is required in the web.xml file.</para>
+ <programlisting language="XML"><error-page>
+ <exception-type>javax.servlet.ServletException</exception-type>
+ <location>/faces/error.xhtml</location>
+</error-page>
+<error-page>
+ <exception-type>javax.faces.application.ViewExpiredException</exception-type>
+ <location>/faces/error.xhtml</location>
+</error-page></programlisting>
+ <para>The above error page definitions are appropriate for a JSF portlet that has a FacesServlet mapping such as /faces/. </para>
+ <para>If the FacesServlet mapping was **.jsf, the location would be error, error.jsf or error.xhtml.</para>
+ <para>There is no requirement when using FacesServlet suffix mapping to append an extension, the name of the view is all that is required for the page to be found</para>
+ <note>
+ <para>Remember to add a link from any error page to the normal flow of the JSF application, otherwise the same error page will be constantly displayed.</para>
+ </note>
+ </section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Supporting_PortletMode_Changes">
- <title>Supporting PortletMode Changes</title>
+ <title>Switching Portlet Modes</title>
<para>
A <literal>PortletMode</literal> represents a distinct render path within an application. There are three standard modes: <emphasis>view</emphasis>, <emphasis>edit</emphasis>, and <emphasis>help</emphasis>.
</para>
<para>
The bridge's <literal>ExternalContext.encodeActionURL</literal> recognizes the query string parameter <literal>javax.portlet.faces.PortletMode</literal> and uses this parameter's value to set the portlet mode on the underlying portlet <literal>actionURL</literal> or response.
- </para>
- <para>
- Once processed it then removes this parameter from the query string. This means the following navigation rule causes one to render the <filename>/edit.jspx</filename> viewId in the portlet edit mode:
- </para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default224.xml" parse="text"/></programlisting>
+
+ Once processed it then removes this parameter from the query string. </para>
+ <example>
+ <title>/edit.xhtml navigation rule</title>
+ <para>This navigation rule causes one to render the <filename>/edit.xhtml</filename> viewId in the portlet edit mode. </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default224.xml" parse="text"/></programlisting>
+ </example>
</section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Navigating_to_a_modes_last_viewId">
<title>Navigating to a mode's last viewId</title>
@@ -45,7 +125,11 @@
<para>
This is most easily expressed via an <literal>EL</literal> expression. For example:
</para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default225.xml" parse="text"/></programlisting>
+ <example>
+ <title>/register.xhtml viewId navigation rule</title>
+ <para><remark>BZ#856417 - added from "Portlet Mode's last viewId" Confluence section</remark>This navigation rule causes one to render the <filename>/edit.xhtml</filename> viewId in the portlet edit mode. </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default225.xml" parse="text"/></programlisting>
+ </example>
<section id="sect-Reference_Guide-Navigating_to_a_modes_last_viewId-Note_to_Portlet_Developers">
<title>Note to Portlet Developers</title>
<para>
@@ -131,7 +215,7 @@
However, if these do not meet your use case or you have a different strategy, you can use one of the following methods.
</para>
<section id="sect-Reference_Guide-Communication_Between_Your_Portlets-Storing_Components_in_PortletSession.APPLICATION_SCOPE">
- <title>Storing Components in <parameter>PortletSession.APPLICATION_SCOPE</parameter></title>
+ <title>Storing Components in PortletSession.APPLICATION_SCOPE</title>
<para>
Sometimes it is beneficial to store your <application>Seam</application> components in the portlet <parameter>APPLICATION_SCOPE</parameter>.
</para>
@@ -171,33 +255,156 @@
</section>
</section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Linking_to_PortletJSF_Pages_Using_houtputlink">
- <title>Linking to Portlet/JSF Pages Using h:outputlink</title>
- <para>
- For linking to any JSF/Facelets page within your portlet web application, you can use the following.
+ <title>Linking to a Facelets page within the same portlet</title>
+ <para>To link any JSF/Facelets page within a portlet web application, use the following code.
</para>
+ <remark>BZ#856417 - This code sample is the same in the Confluence docs.</remark>
<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default238.xml" parse="text"/></programlisting>
</section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Redirecting_to_an_External_Page_or_Resource">
- <title>Redirecting to an External Page or Resource</title>
+ <title>Redirecting to an external page or resource</title>
<para>
- To link to a non JSF view, <emphasis>jboss.org</emphasis> for example, you can use the following parameter.
+ To link to a non JSF view, <emphasis>jboss.org</emphasis> for example, you can use the following code.
</para>
<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default239.xml" parse="text"/></programlisting>
- <para>
- Then in your backing bean, you must call a <parameter>redirect()</parameter>.
+ <para>In the backing bean, a <parameter>redirect()</parameter> must be called.
</para>
- <programlisting language="Java" role="JAVA">FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org");
-</programlisting>
+ <programlisting language="Java">public class YourBean {
+ public void yourListener() {
+ FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org");
+ }
+}</programlisting>
</section>
<section id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Using_Provided_EL_Variables">
<title>Using Provided EL Variables</title>
+ <remark>BZ#856417 - Added the table from Confluence</remark>
<para>
- All <literal>EL</literal> variables found in the JSR-329 (Portlet 2.0) specification are available in the JBoss Portlet Bridge. For example, you can use the following to edit the portlet preferences on the UI:
+ All <literal>EL</literal> variables found in the JSR-329 (Portlet 2.0) specification are available in the JBoss Portlet Bridge. </para>
+ <table frame="all" pgwide="1">
+ <title/>
+ <tgroup cols="2">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <tbody>
+ <row>
+ <entry>portalConfig</entry>
+ <entry>
+ <para>Object of type javax.portlet.PortletConfig
+</para>
+ </entry>
+ </row>
+ <row>
+ <entry>actionRequest</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.ActionRequest</para>
+ <para>(only accessible when processing an ActionRequest)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>actionResponse</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.ActionResponse</para>
+ <para>(only accessible when processing an ActionResponse)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>eventRequest</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.EventRequest</para>
+ <para>(only accessible when processing an EventRequest)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>eventResponse</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.EventResponse</para>
+ <para>(only accessible when processing an EventRequest)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>renderRequest</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.RenderRequest</para>
+ <para>(only accessible when processing an RenderResponse)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>renderResponse</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.RenderResponse</para>
+ <para>(only accessible when processing an RenderResponse)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>resourceRequest</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.ResourceRequest</para>
+ <para>(only accessible when processing an ResourceRequest)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>resourceResponse</entry>
+ <entry>
+ <para>Object of type</para>
+ <para>javax.portlet.ResourceResponse</para>
+ <para>(only accessible when processing an ResourceResponse)</para>
+ </entry>
+ </row>
+ <row>
+ <entry>portletSession</entry>
+ <entry>
+ <para>Current PortletSession object
+</para>
+ </entry>
+ </row>
+ <row>
+ <entry>portletSessionScope</entry>
+ <entry>
+ <para>Map of PortletSession attributes in PORTLET_SCOPE. JSP Expression returns immutable Map, but Faces Expression returns mutable Map.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>httpSessionScope</entry>
+ <entry>
+ <para>Mutable Map of PortletSession attributes in APPLICATION_SCOPE</para>
+ </entry>
+ </row>
+ <row>
+ <entry>portletPreferences</entry>
+ <entry>
+ <para>Current PortletPreferences object</para>
+ </entry>
+ </row>
+ <row>
+ <entry>portletPreferencesValues</entry>
+ <entry>
+ <para>Immutable Map containing entries equivalent to PortletPreferences.getMap()</para>
+ </entry>
+ </row>
+ <row>
+ <entry>mutablePortletPreferencesValues</entry>
+ <entry>
+ <para>Mutable Map of type Map<String, javax.portlet.faces.preference.Preference>. This EL variable provides read/write access to each portlet preference.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <example>
+ <title/>
+ <para>This code allows you to edit the portlet preferences on the UI
</para>
- <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default241.xml" parse="text"/></programlisting>
- <para>
- Then in your backing bean, you must call the PortletPreferences.store() method.
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default241.xml" parse="text"/></programlisting>
+ <para>In the backing bean, call the PortletPreferences.store() method.
</para>
- <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default242.java" parse="text"/></programlisting>
+ <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Portlet_Development/default242.java" parse="text"/></programlisting>
+ </example>
</section>
</section>
Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml
===================================================================
--- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2012-09-17 03:31:58 UTC (rev 8848)
+++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2012-09-19 06:42:19 UTC (rev 8849)
@@ -1,13 +1,877 @@
-<?xml version='1.0' encoding='utf-8' ?>
+<?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" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Reference_Guide-Building_JSF_Portlets">
- <title>Building JSF Portlets</title>
- <xi:include href="PortletBridge/overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="PortletBridge/gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="PortletBridge/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="PortletBridge/portlet_development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <title>JBoss Portlet Bridge</title>
+ <section>
+ <title>Portlet Bridge</title>
+ <para>A portlet bridge is a mediator that allows non-native application frameworks to run in a portal environment, independent to the underlying portlet API, or portlet concept. This functionality provides a developer flexibility to continue writing applications in a preferred language, and allows a controlled transition to new technologies. </para>
+ </section>
+ <section>
+ <title>JBoss Portlet Bridge</title>
+ <para>The JBoss Portlet Bridge is a non-final draft implementation of the JSR-329 specification. It supports the JSF 1.2 and 2.0 runtime within a JSR 168 or 286 portlet.
+The project follows the spec from JSR-301 to JSR-329, with version 3.0 of the bridge compatible with JSF 2.0 and RichFaces 4.0.</para>
+ <para>
+ JBoss Portlet Bridge allows JSF applications to run using supported JBoss frameworks such as <application>Seam</application> and <application>RichFaces</application>.
+ </para>
+ <para>
+ The bridge is used to execute <literal>Faces</literal> requests on behalf of the portlet. During each request, the <literal>Faces</literal> environment is setup and handled by the bridge.
+ </para>
+ <para>
+ Part of this implementation acts as a <literal>Faces</literal> controller, much like the FacesServlet does in the direct client request environment.
+ </para>
+ <para>
+ The other part of this implementation is provided by implementing a variety of (standard) <literal>Faces</literal> extensions.
+ </para>
+ </section>
+ <section>
+ <title>File Locations</title>
+ <remark>BZ#856417 - NEEDINFO - will we be packaging the portletbridge binaries in this folder for EPP 6? </remark>
+ <para>The binaries required for Portlet Bridge applications, and example applications that can be used to learn and understand JSF applications are located in in <filename>EPP_HOME/portletbridge</filename>. </para>
+ <para>Configuration files for Portlet Bridge are located in the following locations: </para>
+ <remark>BZ#856417 - NEEDINFO - basing these file paths on what I understand the structure will be using EAP 6. DOMAIN in this case refers to /managed or /standalone</remark>
+ <itemizedlist>
+ <listitem>
+ <para><replaceable>EPP_DIST</replaceable>/<replaceable>DOMAIN</replaceable>/conf/gatein/portlet.xml</para>
+ </listitem>
+ <listitem>
+ <para><replaceable>EPP_HOME</replaceable>/<replaceable>DOMAIN</replaceable>/<replaceable>portlet_name</replaceable>.war/WEB-INF/faces-config.xml</para>
+ </listitem>
+ <listitem>
+ <para><replaceable>EPP_HOME</replaceable>/<replaceable>DOMAIN</replaceable>/<replaceable>portlet_name</replaceable>.war/WEB-INF/web.xml</para>
+ </listitem>
+ </itemizedlist>
+ <para><variablelist>
+ <varlistentry>
+ <term>
+ <filename>portlet.xml</filename>
+ </term>
+ <listitem>
+ <para>Contains the primary configuration information for the portlet. Information such as the GenericFacesPortlet location, and which Java Server Faces (JSF) pages to render are stored in this file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>faces-config.xml</filename>
+ </term>
+ <listitem>
+ <para>Contains configuration directives that are specific to JSF applications. The specific directives will be covered as needed throughout this guide.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>web.xml</filename>
+ </term>
+ <listitem>
+ <para>Contains configuration directives that apply to the web application in general.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+ <section id="What_is_a_portlet_application">
+ <title>Portlet application</title>
+ <para>A portlet application is defined as a single web archive (WAR). </para>
+ <para>All portlets that are part of the same WAR are considered to form part of the same portlet application.</para>
+ </section>
+ <section>
+ <title>Bridgelets</title>
+ <para>Bridgelets are extensions that sit on top of the portlet bridge framework. They extend the functionality of other JBoss portlet applications, and are critical in JSF portlet development. </para>
+ <para>Bridglets are made available in the impl development binary, located in <filename><replaceable>EPP_HOME</replaceable>/portletbridge</filename>. </para>
+ </section>
+ <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-Seam_Bridgelets">
+ <title>Seam Bridgelet</title>
+ <para><literal>PortalIdentity</literal> <application>Seam</application> bridgelet allows you to implement Single Sign-On (SSO) between <application>Seam</application> and <application>JBoss Enterprise Portal Platform</application>.
+ </para>
+ <para>
+ This bridgelet is configured in the application's <filename>components.xml</filename> file, by specifying the following directive: </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_GettingStarted/default218.xml" parse="text"/></programlisting>
+ </section>
+ <section id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-RichFaces_Bridgelets">
+ <title>RichFaces Bridgelet</title>
+ <para>
+ <application>Richfaces</application> does not account for multiple components on the same portal page by default. This following <filename>web.xml</filename> bridgelet renders all <application>RichFaces</application> component javascript portal-friendly.
+ </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_GettingStarted/default219.xml" parse="text"/></programlisting>
+ </section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortletBridge/configuration.xml"/>
+ <section>
+ <title>Render Policy Parameters</title>
+ <para>Different JSF View Declaration Languages require different behavior from the JBoss Portlet Bridge when it comes to rendering views. Instructing the Bridge on which policy to use is done using the javax.portlet.faces.RENDER_POLICY <context-param> directive in <filename>web.xml</filename>.</para>
+ <variablelist id="vari-Reference_Guide-web.xml-RenderPolicy_Options">
+ <title>RenderPolicy Options</title>
+ <varlistentry>
+ <term>ALWAYS_DELEGATE</term>
+ <listitem>
+ <para>
+ Indicates the bridge should not render the view itself, but rather always delegate the rendering.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>NEVER_DELEGATE</term>
+ <listitem>
+ <para>
+ Indicates the bridge should always render the view itself and never delegate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DEFAULT</term>
+ <listitem>
+ <para>
+ Directs the bridge to first delegate the render. If an exception is thrown, the bridge renders the view based on its own logic. If the configuration parameter is not present or has an invalid value the bridge renders using default behavior as it would if DEFAULT was set.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="sect-Reference_Guide-Core_Setup_and_Configuration-Facelets_Configuration">
+ <title>Facelets Configuration</title>
+ <para>
+ The following <filename>web.xml</filename> setting is only for <literal>Facelets</literal> based applications. </para>
+ <section id="sect-Reference_Guide-Facelets_Configuration-web.xml">
+ <title>web.xml</title>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default201.xml" parse="text"/></programlisting>
+ </section>
+ </section>
+ <section id="sect-Reference_Guide-Core_Setup_and_Configuration-JSP_Only_Configuration">
+ <title>JSP Only Configuration</title>
+ <para>
+ The following <filename>web.xml</filename> setting is only for JSP based applications. Download the demonstration application <ulink url="http://anonsvn.jboss.org/repos/portletbridge/trunk/examples/jsf-ri/1.2-basic/">here</ulink>.
+ </para>
+ <section id="sect-Reference_Guide-JSP_Only_Configuration-web.xml">
+ <title>web.xml</title>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default202.xml" parse="text"/></programlisting>
+ </section>
+ </section>
+ <section id="sect-Reference_Guide-Bridge_Configuration-RichFaces_Setup_and_Configuration_Options">
+ <title>RichFaces Setup and Configuration Options</title>
+ <remark>BZ#856417 - NEEDINFO - these sections remain untouched in the EPP 6 work to date. Should they be reviewed?</remark>
+ <section id="sect-Reference_Guide-RichFaces_Setup_and_Configuration_Options-web.xml">
+ <title>Richfaces web.xml settings</title>
+ <para><remark>BZ#856417 - NEEDINFO - Is this Richfaces configuration still relevant for PBR v3.0?</remark>
+ The following configuration is designated for portlets using the <application>RichFaces</application> library. These settings will vary based on your individual needs.
+ </para>
+ <para>
+ See <ulink url="http://docs.jboss.org/richfaces/latest_3_3_X/en/devguide/html/ArchitectureOverview.html#ScriptsandStylesLoadStrategy"> this section</ulink> of the <application>RichFaces</application> documentation for more details.
+ </para>
+ <para>
+ Sometimes it is better to use the "<parameter>ALL</parameter>" load strategy in portlets so you do not need to worry about loading the "framework.pack.js" and "ui.pack.js" files manually in your portlet header.
+ </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default204.xml" parse="text"/></programlisting>
+ <note>
+ <para>
+ If you use the "<parameter>NONE</parameter>" strategy, you must include the following scripts in your portlet or portal page header. If you are using <application>JBoss Portal</application>, you can add this to the <filename>jboss-portlet.xml</filename> file.
+ </para>
+ </note>
+ <para>
+ The <literal>org.ajax4jsf.RESOURCE_URI_PREFIX</literal> configuration cross-references the path to your scripts below. These settings are required for <application>RichFaces</application> using the "<parameter>NONE</parameter>" strategy. Replace all <replaceable>richFacesPortlet</replaceable> text in the example with the actual name of the portlet resource. </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default205.xml" parse="text"/></programlisting>
+ <para>
+ <application>Seam</application> automatically configures your Ajax4JSF Filter, so if you are running a <application>Seam</application> portlet, you do not need the following Filter configuration (however, you do need the <literal>RESOURCE_URI_PREFIX</literal> no matter what).
+ </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default206.xml" parse="text"/></programlisting>
+ </section>
+ <section id="sect-Reference_Guide-RichFaces_Setup_and_Configuration_Options-Configuration_needed_for_Richfaces_to_work_with_WSRP_and_PortletBridge">
+<!-- Content added from JBEPP-708 and JBQA-3999 --> <title>Configure RichFaces to work with WSRP and PortletBridge</title>
+ <remark>BZ#856417 - NEEDINFO - Are we supporting this in EPP 6?</remark>
+ <para>
+ Use the following settings in <filename>web.xml</filename> when running WSRP portlets:
+ </para>
+ <programlisting language="XML" role="XML"><context-param>
+ <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
+ <param-value>false</param-value>
+ </context-param>
+....
+ <context-param>
+ <param-name>org.richfaces.LoadStyleStrategy</param-name>
+ <param-value>ALL</param-value>
+ </context-param>
+ <context-param>
+ <param-name>org.richfaces.LoadScriptStrategy</param-name>
+ <param-value>DEFAULT</param-value>
+ </context-param>
+</programlisting>
+ <para>
+ The styles below must also be manually added to the facelets template header in the <filename><replaceable>EPP_DIST</replaceable>/jboss-as/portletbridge/examples/richFacesPortlet-<replaceable>VERSION</replaceable>.war:richFacesPortlet.war/templates/main.xhtml</filename> file.
+ </para>
+ <programlisting language="XML" role="XML"><link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/basic_both.xcss"/>
+<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/renderkit/html/css/extended_both.xcss"/>
+<link rel="stylesheet" type="text/css" href="/richFacesPortlet/faces/rfRes/org/richfaces/skin.xcss"/>
+</programlisting>
+ <para>
+ The table below outlines the current status of RichFaces features when used in both local and remote portlets.
+ </para>
+ <table id="tabl-Reference_Guide-Configuration_needed_for_Richfaces_to_work_with_WSRP_and_PortletBridge-RichFaces_Feature_Status">
+ <title>RichFaces Feature Status</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry> Richfaces Component </entry>
+ <entry> Supported as Local Portlet </entry>
+ <entry> Supported as Remote Portlet using WSRP </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>a4j:commandButton</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:commandLink</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:jsFunction</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:push</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:poll</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:queue</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:status</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:keepAlive</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:include</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:loadStyle</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:loadScript</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:ajaxValidator</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:beanValidator</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:graphValidator</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:mediaOutput</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:outputPanel</literal>
+ </entry>
+ <entry> Yes (except Firefox 3.5) </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:log</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:dataTable</literal>
+ </entry>
+ <entry> Yes (except Firefox 3.6 and IE8) </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>a4j:dataFilterSlider</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:dataGrid</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:dataList</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:datascroller</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:extendedDataTable</literal>
+ </entry>
+ <entry> Yes (except IE7) </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:repeat</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:scrollableDataTable</literal>
+ </entry>
+ <entry> Yes (except Firefox 3.6) </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>drag-drop support</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:contextMenu</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:dropDownMenu</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:tree</literal>
+ </entry>
+ <entry> Yes (except Firefox 3.5) </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:modalPanel</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:paint2d</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:panel</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:panelBar</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:panelMenu</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:progressBar</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:separator</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:simpleTogglePanel</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:spacer</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:tabPanel</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes (except tab deletion) </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:togglePanel</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:toolBar</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:toolTip</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:calendar</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:colorPicker</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:comboBox</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:editor</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:fileUpload</literal>
+ </entry>
+ <entry> No </entry>
+ <entry> No </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:inplaceSelect</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:inplaceInput</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:inputNumberSpinner</literal>
+ </entry>
+ <entry> Yes (except IE7) </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:inputNumberSlider</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:suggestionBox</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:listShuttle</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:orderingList</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>rich:pickList</literal>
+ </entry>
+ <entry> Yes </entry>
+ <entry> Yes </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+<!-- DO NOT UNCOMMENT <section>
+<title>jboss-portlet.xml</title>
+<para>
+To avoid scripts loading more than once from different portlet windows you can define additional scripts in
+jboss-portlet.xml. *Note the "rfRes" URI prefix that is mapped in the web.xml.</para>
+<programlisting role="XML"><![CDATA[
+<portlet>
+<portlet-name>ajaxPortlet</portlet-name>
+<header-content>
+<script src="/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script>
+<script src="/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script>
+<link rel="stylesheet" type="text/css" href="/faces/rfRes/org/richfaces/skin.xcss"/>
+</header-content>
+</portlet>
+]]></programlisting>
+</section> --> </section>
+ <section id="sect-Reference_Guide-Bridge_Configuration-Seam_Setup_and_Configuration_Options">
+ <title>Seam Setup and Configuration Options</title>
+ <remark>BZ#856417 - NEEDINFO - these sections remain untouched in the EPP 6 work to date. Should they be reviewed?</remark>
+ <section id="sect-Reference_Guide-Seam_Setup_and_Configuration_Options-Configuration">
+ <title>Configuration</title>
+ <para>
+ The <literal>ExceptionHandler</literal> is used to clean <application>Seam</application> contexts and transactions after errors.
+ </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default207.xml" parse="text"/></programlisting>
+<!-- Section removed as per feedback from Prabhat Jha
+ <para>
+ If you are using this bridge version from <literal>2.0.0.BETA</literal> through <literal>2.0.0.CR1</literal>, you must define the following <filename>web.xml</filename> parameter to use the JBoss Portlet Bridge provided Seam Phase Listener. This is done by the bridge automatically (if needed) in <literal>2.0.0.FINAL</literal>.
+ </para>
+
+<programlisting language="XML" role="XML"><xi:include href="../../../extras/PortletBridge_Configuration/default208.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --> </section>
+ </section>
+ <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events">
+ <title>Sending and Receiving Events</title>
+ <para>
+ The bridge considers a portlet event a model event, which means the event is targeted to the applications data model, not its view.
+ </para>
+ <para>Because JSF events primarily concern its view, the bridge processes the portlet events manually. Provisions are made to ensure that any model changes resulting from processing the event are updated in the view.
+ </para>
+ <para>Because event payloads are arbitrarily complex however, the manual data processing is left primarily to the portlet application to support. </para>
+ <section>
+ <title>Sending Events</title>
+ <para>The following event configuration references the eventing implemented in the Seam Booking Demo, available for exploration in <filename><replaceable>EPP_HOME</replaceable>/portletbridge/examples/seamEAR.ear</filename>. The concepts described are the same for sending events using other event handlers. </para>
+ <para>Explicitly specify that the GenericFacesPortlet should override event handling and dispatch all events to the bridge by defining the autoDispatchEvents <init-param> in <filename>portlet.xml</filename>.</para>
+ <para>If the application is written entirely in JSF (as opposed to a mix of view technologies), this <init-param> must be set to <parameter>true</parameter>.</para>
+ <programlisting language="XML"><init-param>
+ <name>javax.portlet.faces.autoDispatchEvents</name>
+ <value>true</value>
+</init-param></programlisting>
+ <para>Enable the portlet to publish an event to the portal, by defining the <supported-publishing-event> in <filename>portlet.xml</filename>. </para>
+ <programlisting language="XML"><supported-publishing-event>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
+</supported-publishing-event></programlisting>
+ <para>Define how the event namespace (<qname>) is linked to an actual type within the application by defining the <event-definition> directive in <filename>portlet.xml</filename>.</para>
+ <programlisting language="XML"><event-definition>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
+ <value-type>org.jboss.example.booking.BookingEvent</value-type>
+</event-definition></programlisting>
+ <para>To publish an event, define an event type that represents the actual object that will be attached to the event.</para>
+ <example>
+ <title>Event type example</title>
+ <para>The type requires the @XmlRootElement annotation to allow the event to be serialized into a JAXB object for publishing.</para>
+ <programlisting language="Java">
+ at XmlRootElement
+public class BookingEvent implements Serializable {
+
+ private String id;
+ public static final QName QNAME = new QName("urn:jboss:portal:samples:event", "BookingEvent");
+
+ public BookingEvent(String id) {
+ this.id = id;
+ }
+
+ public String getId() {
+ return id;
+ }
+}</programlisting>
+ </example>
+ <para>To dispatch an event to other portlets within the portal, one approach is to use a bean method triggered by an action.</para>
+ <example>
+ <title>Dispatch event example</title>
+ <programlisting language="Java">Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
+ if (response instanceof StateAwareResponse) {
+ String id = "an id";
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setEvent(BookingEvent.QNAME, new BookingEvent(id));
+ }</programlisting>
+ </example>
+ </section>
+ <section>
+ <title>Receiving Events</title>
+ <para>The following event configuration references the eventing implemented in the Seam Booking Demo, available for exploration in <filename><replaceable>EPP_HOME</replaceable>/portletbridge/examples/seamEAR.ear</filename>. The concepts described are the same for receiving events using other event handlers.</para>
+ <para>Define that the portlet can receive an event, by specifying bridgeEventHandler as a parameter of an <init-param> directive in <filename>portlet.xml</filename>.</para>
+ <programlisting language="XML"><init-param>
+ <name>javax.portlet.faces.bridgeEventHandler</name>
+ <value>org.jboss.example.booking.BookingEventHandler</value>
+</init-param></programlisting>
+ <para>Define that the portlet can also receive an event from the portal, by specifying a <supported-processing-event> directive in <filename>portal.xml</filename></para>
+ <programlisting language="XML"><supported-processing-event>
+ <qname xmlns:jbp="urn:jboss:portal:samples:event">jbp:BookingEvent</qname>
+</supported-processing-event></programlisting>
+ <para>To process a received event within a portlet, specify in the portlet code that the event handler implements the BridgeEventHandler.</para>
+ <programlisting>public class BookingEventHandler implements BridgeEventHandler {
+ public EventNavigationResult handleEvent(FacesContext context, Event event) {
+ // Process event payload as appropriate
+ }
+}</programlisting>
+ </section>
+ <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters">
+ <title>Public Render Parameters</title>
+ <para>
+ Public Render Parameters (or PRPs) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or otherwise) can share the same PRPs. This feature can be used to present a cohesive UI to the user across all portlets on the page. An example would be using an employee ID to display relative data.
+ </para>
+ <para>
+ The bridge automates public render parameter processing.
+ </para>
+ <para>
+ A public render parameter can be mapped to an object's accessor (<literal>get</literal>/<literal>set</literal> method) designed to handle a String representation of the value through a <application>Faces</application> <literal>ValueExpression</literal>.
+ </para>
+ <para>Unlike Events, PRPs can only be used to set/get a string value, and not an object.</para>
+ <para>
+ When a new public render parameter value is received in a request, the bridge sets the value by calling the <literal>ValueExpression</literal>'s <parameter>setValue()</parameter>.
+ </para>
+ <para>
+ The bridge maps a render parameter to a backing bean using settings in the <filename>faces-config.xml</filename> and <filename>portlet.xml</filename> files.
+ </para>
+ <para>
+ At the end of a request, if the current value of any mapped public render parameter does not match the current incoming value, the bridge sets the new value in an outgoing public render parameter (if feasible in the given phase).
+ </para>
+ <section>
+ <title>PRP portlet configuration</title>
+ <para>The following PRP portlet configuration references the Seam Booking Demo, available for exploration in <filename><replaceable>EPP_HOME</replaceable>/portletbridge/examples/seamEAR.ear</filename>. The concepts described are the same for receiving PRP events in other implementations.</para>
+ <para>PRPs must be configured in both the portlet that sends (sets) the PRP, and the portlet that retrieves (gets) the PRP. </para>
+ <programlisting language="XML"><portlet>
+<!-- Unnecessary configuration information removed for clarity -->
+ <supported-public-render-parameter>hotelName</supported-public-render-parameter>
+</portlet>
+
+<public-render-parameter>
+ <identifier>hotelName</identifier>
+ <qname xmlns:j="http://jboss.org/params">j:hotelName</qname>
+</public-render-parameter></programlisting>
+ <para>In the portlet that retrieves the PRP, a PRP handler must be specified as an <init-param> directive.</para>
+ <programlisting language="XML"><init-param>
+
+<name>javax.portlet.faces.bridgePublicRenderParameterHandler</name>
+ <value>org.jboss.example.booking.BookingPRPHandler</value>
+</init-param></programlisting>
+ </section>
+ <section id="sect-Reference_Guide-Public_Render_Parameters-Configuration">
+ <title>Application configuration</title>
+ <para> A public render parameter example is implemented in the Seam Booking Demo portlet, which is located in <filename><filename>EPP_HOME</filename>/portletbridge/SeamEAR.ear</filename>. Continue reading the configuration procedures to understand the configuration steps behind the SeamEAR.ear example. </para>
+ <section>
+ <title>Set Parameter</title>
+ <para>To set the PRP, create a Bean method for the portlet setting the parameter that is triggered from a UI action, and sets the PRP onto the response.</para>
+ <programlisting language="Java">Object response = FacesContext.getCurrentInstance().getExternalContext().getResponse();
+if (response instanceof StateAwareResponse) {
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setRenderParameter("hotelName", "Name of Hotel");
+}</programlisting>
+ </section>
+ <section>
+ <title>Retrieve parameter</title>
+ <para>The retrieving portlet requires a Bean with a getter/setter for the parameter, to enable Portlet Bridge to set the parameter.</para>
+ <programlisting language="Java">public class BookingPRP {
+ private String hotelName;
+
+ public String getHotelName() {
+ return hotelName;
+ }
+
+ public void setHotelName(String hotelName) {
+ this.hotelName = hotelName;
+ }
+}</programlisting>
+ <para>To set the value on the bean, the Bridge needs to be informed which PRP to retrieve and which Bean to set it on. </para>
+ <para>If the getter/setter Bean is defined with a EL name of bookingPRP, the following configuration is required in <filename>faces-config.xml</filename>.</para>
+ <programlisting><application>
+ <application-extension>
+ <bridge:public-parameter-mappings>
+ <bridge:public-parameter-mapping>
+ <parameter>[bookingMapPortlet]:[hotelName]</parameter>
+ <model-el>#{bookingPRP.hotelName}</model-el>
+ </bridge:public-parameter-mapping>
+ </bridge:public-parameter-mappings>
+ </application-extension>
+</application></programlisting>
+ <important>
+ <para>Specifying the portlet name restricts model updates to the specified portlet only. If the portlet name is omitted and only the render parameter specified, every portlet within the web application that supports that render parameter will have its model updated. </para>
+ </important>
+ <variablelist>
+ <varlistentry>
+ <term>[bookingMapPortlet]</term>
+ <listitem>
+ <para>The arbitrary name of the portlet, as set in <filename>portlet.xml</filename></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>[hotelName]</term>
+ <listitem>
+ <para>The arbitrary name of the render parameter.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>The handler specified in the <filename>portlet.xml</filename> requires a bean to process the updates to the model, as a result of the Public Render Parameter.</para>
+ <programlisting language="Java">public class BookingPRPHandler implements BridgePublicRenderParameterHandler {
+ public void processUpdates(FacesContext context) {
+ ELContext elContext = context.getELContext();
+ BookingPRPBean bean = (BookingPRPBean) elContext.getELResolver().getValue(elContext, null, "bookingPRP");
+
+ if(null != bean) {
+ System.out.println("******processUpdates from BookingPRPHandler: " + bean.getHotelName());
+ }
+ }
+}</programlisting>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Portlet Session</title>
+ <para>To share data with other portlets within the same portlet application, use name/value pairs within the PortletSession.</para>
+ <programlisting language="Java">
+Object objSession = FacesContext.getCurrentInstance().getExternalContext().getSession(false);
+ try {
+ if (objSession instanceof PortletSession) {
+ PortletSession portalSession = (PortletSession)objSession;
+ portalSession.setAttribute("your parameter name", "parameter value", PortletSession.APPLICATION_SCOPE);
+ }
+ }</programlisting>
+ <para>In the JSP or Facelets page, the value string can be retrieved using the following code.</para>
+ <programlisting>
+#{httpSessionScope['your parameter name']}</programlisting>
+ </section>
+ </section>
+ <section>
+ <title>Resource serving</title>
+ <para>When using resources from a JSF portlet, it is important to ensure that they are accessed in a way that allows JBoss Portlet Bridge to construct an appropriate Portal URL to the resource being requested.</para>
+ <para>The correct way to reference a resource is to locate it within the web application, in the <filename>/ resources</filename> directory. This placement allows the resource to be retrieved using JSF2 resource handling.</para>
+ <programlisting>#{resource['/stylesheet.css']}</programlisting>
+ <para>In this instance, stylesheet.css would be present in the root of the <filename>/resources</filename> directory, because it does not specify a resource library. For resources that do specify a library, these must be placed in the library sub-directory.</para>
+ <section id="sect-Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet">
+ <title>Serving Your JSF Resources in a Portlet</title>
+ <para>
+ The bridge deals with portlet served resources in one of two ways:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If the request is for a non-JSF resource, the bridge handles the request by acquiring a request dispatcher and forwarding the request to the named resource.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the request is for a JSF resource, the bridge runs the full JSF life-cycle ensuring that data is processed and the resource (markup) is rendered.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="sect-Reference_Guide-Serving_Your_JSF_Resources_in_a_Portlet-Configuration">
+ <title>Configuration</title>
+ <para>Some examples demonstrating how to use <literal>EL</literal> and a simple bean are provided in <filename>EPP_HOME/portletbridge/examples/richFacesPortlet.war//WEB-INF/src/org/richfaces/demo/common/ResourceBean.java</filename> </para>
+ <para>When you have the normal "<filename>/images</filename>", "<filename>/styles</filename>" and other resource folders in your web application, you can use the following <literal>EL</literal> expression to serve them in your JSF application.
+ </para>
+ <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default216.java" parse="text"/></programlisting>
+ <para>Copy the <literal>ResourceBean.java</literal> code above, and add an entry to the <filename>faces-config.xml</filename> for the bean.
+ </para>
+ <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortletBridge_Configuration/default217.xml" parse="text"/></programlisting>
+ </section>
+ </section>
+ </section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="PortletBridge/portlet_development.xml"/>
</chapter>
-
More information about the gatein-commits
mailing list