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...
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...;.
- </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...
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/e...
/>
-</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.EP...
- </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.EP...;,
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&...
+ <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...;.
+ </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/A...
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">
+@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&am...
+</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>
-