10:59 a.m.
Author: thomas.heute(a)jboss.com
Date: 2010-04-28 11:59:53 -0400 (Wed, 28 Apr 2010)
New Revision: 2880
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml
Modified:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment.xml
Log:
JBEPP-276: Reference Guide
Merging the PortletBridge reference guide
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml
(rev 0)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -0,0 +1,464 @@
+<?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;
+]>
+<section
id="chap-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration">
+ <title>Bridge Configuration</title>
+ <para>
+ The 329 specification is aimed at making the developers 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>
+ <para>
+ If you are starting from scratch, we highly recommend you use the <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes"
/>.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration-Core_Setup_and_Configuration">
+ <title>Core Setup and Configuration</title>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Core_Setup_and_Configuration-portlet.xml">
+ <title>portlet.xml</title>
+ <para>
+ The basic JSR-329 portlet configuration.
+ </para>
+
+<programlisting role="XML">
+ <portlet>
+ <portlet-name>yourPortletName</portlet-name>
+ <portlet-class>
+ javax.portlet.faces.GenericFacesPortlet
+ </portlet-class>
+
+ <init-param>
+
<name>javax.portlet.faces.defaultViewId.view</name>
+ <value>/welcome.xhtml</value>
+ </init-param>
+
+ <init-param>
+
<name>javax.portlet.faces.defaultViewId.edit</name>
+ <value>/jsf/edit.xhtml</value>
+ </init-param>
+
+ <init-param>
+
<name>javax.portlet.faces.defaultViewId.help</name>
+ <value>/jsf/help.xhtml</value>
+ </init-param>
+</programlisting>
+ <para>
+ When preserveActionParams is set to TRUE, the bridge must maintain any request
parameters assigned during the portlet's action request. The request parameters are
maintained in the<emphasis role="italics">"bridge request
scope"</emphasis>. When this attribute isn't present or is FALSE the
action's request parameters are only maintained for the duration of the <emphasis
role="italics">portlet request scope</emphasis>.
+ </para>
+
+<programlisting role="XML">
+ <init-param>
+
<name>javax.portlet.faces.preserveActionParams</name>
+ <value>true</value>
+ </init-param>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Core_Setup_and_Configuration-faces_config.xml">
+ <title>faces-config.xml</title>
+ <para>
+ The PortletViewHandler ensures that each JSF portlet instance is properly
namespaced.
+ </para>
+
+<programlisting role="XML">
+ <faces-config>
+ <application>
+ <view-handler>
+ org.jboss.portletbridge.application.PortletViewHandler
+ </view-handler>
+
<state-manager>org.jboss.portletbridge.application.PortletStateManager</state-manager>
+ </application>
+ ...
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Core_Setup_and_Configuration-Facelets_Configuration">
+ <title>Facelets Configuration</title>
+ <para>
+ The following web.xml setting is only for Facelets based applications
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Facelets_Configuration-web.xml">
+ <title>web.xml</title>
+
+<programlisting role="XML">
+ <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ 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">
+ ...
+ <!-- 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>
+</programlisting>
+ <para>
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+
<param-name>javax.portlet.faces.RENDER_POLICY</param-name>
+ <param-value>
+ ALWAYS_DELEGATE
+ </param-value>
+ </context-param>
+ ...
+ </web-app>
+</programlisting>
+ <note>
+ <title>RenderPolicy Options</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>ALWAYS_DELEGATE</literal> Indicates the bridge should not
render the view itself but rather always delegate the rendering.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>NEVER_DELEGATE</literal> Indicates the bridge should always
render the view itself and never delegate.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>DEFAULT</literal> Directs the bridge to first delegate the
render and if and only if an Exception is thrown then render 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. I.e. as if DEFAULT is set.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </note>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Core_Setup_and_Configuration-JSP_Only_Configuration">
+ <title>JSP Only Configuration</title>
+ <para>
+ The following web.xml setting is only for JSP based applications. Download the demo
application <ulink
url="http://anonsvn.jboss.org/repos/portletbridge/trunk/examples/jsf...;.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-JSP_Only_Configuration-web.xml">
+ <title>web.xml</title>
+
+<programlisting role="XML">
+ <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ 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.renderPolicy</param-name>
+ <param-value>
+ NEVER_DELEGATE
+ </param-value>
+ </context-param>
+ ...
+ </web-app>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Core_Setup_and_Configuration-JSR_329">
+ <title>JSR-329</title>
+ <para>
+ The Jboss Portlet Bridge can be used with a any compatible implementation ( for
example, MyFaces implementation). Simply put the following into web.xml :
+ </para>
+
+<programlisting role="XML">
+
+ <context-param>
+
<param-name>javax.portlet.faces.BridgeImplClass</param-name>
+
<param-value>org.apache.myfaces.portlet.faces.bridge.BridgeImpl</param-value>
+ </context-param>
+</programlisting>
+ </section>
+
+ </section>
+
+ <!-- End 301 core setup -->
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration-RichFaces_Setup_and_Configuration_Options">
+ <title>RichFaces Setup and Configuration Options</title>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-RichFaces_Setup_and_Configuration_Options-web.xml">
+ <title>web.xml</title>
+ <para>
+ The following configuration is designated for portlets using the RichFaces library.
These settings will vary based on your individual needs. See <ulink
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...
this section</ulink> of the RichFaces documentation for more details.
+ </para>
+ <para>
+ Sometimes it is better to use the "ALL" 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 role="XML">
+ <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>ALL</param-value>
+ </context-param>
+</programlisting>
+ <note>
+ <para>
+ If you use the "NONE" strategy, you must include the following scripts in
your portlet or portal page header. If you are using JBoss Portal, you can add this to the
jboss-portlet.xml 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 RichFaces
using the "NONE" strategy.
+ </para>
+
+<programlisting role="XML">
+ <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"/>
+</programlisting>
+ <para>
+ Seam automatically configures your Ajax4JSF Filter, so if you are running a Seam
portlet, you do not need the following Filter config. (But you do need the
RESOURCE_URI_PREFIX no matter what)
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+
<param-name>org.ajax4jsf.RESOURCE_URI_PREFIX</param-name>
+ <param-value>rfRes</param-value>
+ </context-param>
+
+ <filter>
+ <display-name>Ajax4jsf Filter</display-name>
+ <filter-name>ajax4jsf</filter-name>
+
<filter-class>org.ajax4jsf.Filter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>ajax4jsf</filter-name>
+ <servlet-name>FacesServlet</servlet-name>
+ <dispatcher>FORWARD</dispatcher>
+ <dispatcher>REQUEST</dispatcher>
+ <dispatcher>INCLUDE</dispatcher>
+ </filter-mapping>
+ ...
+ </web-app>
+</programlisting>
+ </section>
+
+ <!-- <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-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration-Seam_Setup_and_Configuration_Options">
+ <title>Seam Setup and Configuration Options</title>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Seam_Setup_and_Configuration_Options-Configuration">
+ <title>Configuration</title>
+ <para>
+ The ExceptionHandler is used to clean Seam contexts and transactions after errors.
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+
<param-name>org.jboss.portletbridge.ExceptionHandler</param-name>
+ <param-value>
+ org.jboss.portletbridge.SeamExceptionHandlerImpl
+ </param-value>
+ </context-param>
+</programlisting>
+ <para>
+ If you are using this bridge version from 2.0.0.BETA through 2.0.0.CR1, you must
define the following web.xml parameter to use the JBoss Portlet Bridge provided Seam Phase
Listener.
+ This is done by the bridge automatically (if needed) in 2.0.0.FINAL.
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+ <param-name>javax.faces.LIFECYCLE_ID</param-name>
+ <param-value>SEAM_PORTLET</param-value>
+ </context-param>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration-Portlet_2.0_Coordination">
+ <title>Portlet 2.0 Coordination</title>
+ <para>
+ One very important thing to note before using either of the following mechanisms, is
that you must have the proper 2.0 schema and xsd definition at the top of your
portlet.xml.
+ </para>
+
+<programlisting role="XML">
+ <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">
+</programlisting>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events">
+ <title>Sending and Receiving Events</title>
+ <section
id="sect-JBoss_Portlet_Bridge_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 portlet.xml. To see a working example, checkout the Seam Booking Demo portlet.
<ulink
url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.CR1/exa...
/>
+ </para>
+ <para>
+ You must also define the following init params in your portlet.xml.
+ </para>
+
+<programlisting role="XML">
+ </init-param>
+ <init-param>
+ <name>javax.portlet.faces.autoDispatchEvents</name>
+ <value>true</value>
+ </init-param>
+ <init-param>
+ <name>javax.portlet.faces.bridgeEventHandler</name>
+ <value>org.foo.eventhandler</value>
+ </init-param>
+</programlisting>
+ <para>
+ For now, you must dipatch the event in the JSF or Seam backing bean. Future versions
on the 2.0 bridge will automate the dispatching and consuming of events.
+ </para>
+
+<programlisting role="XML">
+ if (response instanceof StateAwareResponse) {
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setEvent(Foo.QNAME, new Bar());
+ }
+</programlisting>
+ <para>
+ Then you must also create the event handler class by implementing the
BridgeEventHandler interface to process the event payload.
+ </para>
+
+<programlisting role="XML">
+ public class BookingEventHandler implements BridgeEventHandler
+ {
+ public EventNavigationResult handleEvent(FacesContext context, Event event)
+ {
+ //process event payload here
+ }
+
+ }
+</programlisting>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters">
+ <title>Public Render Parameters</title>
+ <section
id="sect-JBoss_Portlet_Bridge_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 not) can share the same render parameters. This
feature can be use to present a cohesive UI to the user across all portlets on the page
(i.e. using an employee ID to display relative data).
+ </para>
+ <para>
+ The bridge maps a render parameter to a backing bean using settings in your
faces-config.xml and portlet.xml. A clear and working example can be found in the Seam
Booking Demo portlet. <ulink
url="http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.CR1/exa...
/>
+ </para>
+ <para>
+ You must define the following init params in your portlet.xml.
+ </para>
+
+<programlisting role="XML">
+ <init-param>
+
<name>javax.portlet.faces.bridgePublicRenderParameterHandler</name>
+ <value>org.foo.PRPHandler</value>
+ </init-param>
+ ...
+
<supported-public-render-parameter>myCoolPRP</supported-public-render-parameter>
+</programlisting>
+ <para>
+ Create a managed bean and public-parameter-mappings in your faces-config.xml. This
should be a basic bean that you can bind the passed parameter to a string with getter and
setter.
+ </para>
+
+<programlisting role="XML">
+ <managed-bean>
+ <managed-bean-name>bookingPRP</managed-bean-name>
+
<managed-bean-class>your.class.Name</managed-bean-class>
+ <managed-bean-scope>session</managed-bean-scope>
+ </managed-bean>
+
+ <application>
+ <application-extension>
+ <bridge:public-parameter-mappings>
+ <bridge:public-parameter-mapping>
+ <parameter>"the name of your
portlet":hotelName</parameter>
+ <model-el>#{bookingPRP.hotelName}</model-el>
+ </bridge:public-parameter-mapping>
+ </bridge:public-parameter-mappings>
+ </application-extension>
+ </application>
+</programlisting>
+ <para>
+ You must set the parameter in the JSF or Seam backing bean, if you are providing one
from your portlet.
+ </para>
+
+<programlisting role="XML">
+ if (response instanceof StateAwareResponse) {
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setRenderParameter("hotelName",selectedHotel.getName());
+ }
+</programlisting>
+ <para>
+ Then you must also implement the BridgePublicRenderParameterHandler interface to
process any updates from the received parameter.
+ </para>
+
+<programlisting role="XML">
+ public void processUpdates(FacesContext context)
+ {
+ ELContext elContext = context.getELContext();
+ BookingPRPBean bean = (BookingPRPBean)
elContext.getELResolver().getValue(elContext, null, "bookingPRP");
+
+ if(null != bean){
+ //Do something with bean.getHotelName());
+ } else {
+
+ }
+ }
+</programlisting>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_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-JBoss_Portlet_Bridge_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 EL 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.0.0.CR1/exa...;,
you can see a very simple implementations of a Map object that uses the bridge to get and
encode a resource url served from the portlets web application.
+ </para>
+ <para>
+ So, when you have the normal "/images", "/styles" and other
resource folders in your web app, you can use the following EL expression to serve them in
your JSF application.
+ </para>
+
+<programlisting role="XML">
+ #{resource['/img/the-path-to-my-image.png']}
+</programlisting>
+ <para>
+ Just copy the ResourceBean.java code above, and add an entry to you faces-config.xml
for the bean:
+ </para>
+
+<programlisting role="XML">
+ <managed-bean>
+ <managed-bean-name>resource</managed-bean-name>
+
<managed-bean-class>org.richfaces.demo.common.ResourceBean</managed-bean-class>
+ <managed-bean-scope>application</managed-bean-scope>
+ </managed-bean>
+</programlisting>
+ </section>
+
+ </section>
+
+ </section>
+
+</section>
+
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml
(rev 0)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -0,0 +1,249 @@
+<?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;
+]>
+<section
id="chap-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge">
+ <title>Getting started with JBoss Portlet Bridge</title>
+ <para>
+ JBoss Portlet Bridge not only gives you the ability to run JSF web applications in a
portlet, but also gives you the benefit of running supported JBoss frameworks like Seam
and RichFaces.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Whats_New_in_2.0">
+ <title>What's New in 2.0?</title>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Whats_New_in_2.0-Eventing">
+ <title>Eventing</title>
+ <para>
+ The bridge considers a portlet event a model event. I.e. the event is targeted to the
applications data model not its view. As JSF events primarily concern its view, the bridge
processes the portlet events manually, however provisions are made to make sure that any
model changes that result from processing the event are updated in the view. Since event
payloads are arbitrarily complex, the manual processing of the data, though managed by the
bridge, is left to the (portlet) application to support.
+ </para>
+ <para>
+ See <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"
/> for details and examples.
+ </para>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Whats_New_in_2.0-Portlet_Served_Resources">
+ <title>Portlet Served Resources</title>
+ <para>
+ The bridge deals with portlet served resources in one of two ways. 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. If the request is for a JSF resource,
the bridge runs the full JSF lifecycle ensuring that data is processed and the resource
(markup) is rendered.
+ </para>
+ <para>
+ See <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet"
/> for details and examples.
+ </para>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Whats_New_in_2.0-Public_Render_Parameters">
+ <title>Public Render Parameters</title>
+ <para>
+ The bridge automates the processing of public render parameters. A public render
parameter can be mapped to an object's accessor (get/set method) designed to handle a
String representation of the value via a Faces ValueExpression. When a new public render
parameter value is received in a request, the bridge sets the value by calling the
ValueExpression's setValue(). At the end of a request, if the current value of any
mapped public render parameter doesn't match the current incoming value, the bridge
sets the new value in an outgoing public render parameter (if feasible in the given
phase).
+ </para>
+ <para>
+ See <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"
/> for details and examples.
+ </para>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Bridge_Frameworks_and_Extensions">
+ <title>Bridge Frameworks and Extensions</title>
+ <para>
+ The JBoss Portlet Bridge currently supports JBoss Portal, GateIn, JSF 1.2, JBoss Seam,
and JBoss Richfaces. There are configurations that apply to supporting each framework. See
section <xref
linkend="chap-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Configuration" />
for instructions.
+ </para>
+ <para>
+ The JBoss Portlet Bridge project is also actively developing extensions, and to
differentiate from just another "project" that has boring ol'
"extensions" we coined the term "Bridgelets" - because what would a
project with Java and JSF be without having "*let" on the end of it? Not very
cool in my opinion ;) With that said, in this current release we decided to bring all of
our bridgelets into the impl code base since they are critical in most JSF portlet
applications. Now it only takes a single line of configuration to utilize these features.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Frameworks_and_Extensions-Seam_Bridgelets">
+ <title>Seam Bridgelets</title>
+ <para>
+ For example, the PortalIdentity seam component allows you to instantly have SSO
between Seam and GateIn or JBoss Portal. This extension is configured in your Seam
application's components.xml file as follows.
+ </para>
+
+<programlisting role="XML">
+ <security:portal-identity
authenticate-method="#{authenticator.authenticate}"/>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Bridge_Frameworks_and_Extensions-RichFaces_Bridgelets">
+ <title>RichFaces Bridgelets</title>
+ <para>
+ Richfaces does not account for multiple components on the same portal page by
default. This following web.xml renders all RichFaces component javascript to be portal
friendly.
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+
<param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
+ <param-value>true</param-value>
+ </context-param>
+</programlisting>
+ <para>
+ <!-- <table frame='all'>
+ <title>Available Bridgelets</title>
+ <tgroup cols='5' align='left' colsep='1'
rowsep='1'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colnum='5' colname='c5'/>
+ <thead>
+ <row>
+ <entry align="center">Bridgelet</entry>
+ <entry namest="c2" nameend="c5"
align="center">Command</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row class="table-odd"
style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;">
+ <entry align="left">Single Sign On</entry>
+ <entry namest="c2" nameend="c5"
align="left">
+ <para>By inlcuding the following dependency in your web pom,
you will automatically have SSO
+ between Jboss Portal and your Seam application.
+ <programlisting><![CDATA[
+<dependency>
+ <groupId>org.jboss.portletbridge.extensions.seam</groupId>
+ <artifactId>PortalIdentity</artifactId>
+ <version>2.0.0.BETA</version>
+</dependency>]]>
+ </programlisting></para>
+ </entry>
+ </row>
+ <row class="table-even"
style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;">
+ <entry align="left">RichFaces Javascript
Compatibility</entry>
+ <entry namest="c2" nameend="c5"
align="left">
+ <para>Richfaces does not account for multiple components on
the same portal page by default. This bridgelet
+ renders all RichFaces component javascript to be portal
friendly.
+ <programlisting><![CDATA[
+<dependency>
+ <groupId>org.jboss.portletbridge.extensions.richfaces</groupId>
+ <artifactId>PortalResourceBuilder</artifactId>
+ <version>2.0.0.BETA</version>
+</dependency>]]>
+ </programlisting> </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table> -->
+ <note>
+ <para>
+ Don't forget that the bridge is still in Beta and so are any extensions. If you
would like to contribute to any part of this project, we encourage you to be active on the
<ulink
url="http://www.jboss.com/index.html?module=bb&op=viewforum&...
forum</ulink> and bring issues/enhancements to attention.
+ </para>
+ </note>
+ </para>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Before_you_start">
+ <title>Before you start</title>
+ <para>
+ Current version and compatibilty information can be easily located on the <ulink
url="http://www.jboss.org/community/wiki/JBossPortletBridge">...
wiki</ulink>. Ensure you are using compatible versions of all integrated frameworks
before you begin.
+ </para>
+ <para>
+ JBoss Portal and GateIn provides it's latest distribution included in JBoss
Application Server. All of the guesswork has been eliminated so that you can unzip and run
the Portal with a few clicks. <ulink
url="http://jboss.org/gatein/downloads.html">Get the latest
here</ulink> (ensure you choose the Portal + JBoss AS link)
+ </para>
+ <para>
+ Next, all that's left is to download the <ulink
url="http://www.jboss.org/portletbridge/download/">JBoss Portlet Bridge
distribution</ulink> and cofigure your portlet to use the bridge. Or, you can run a
provided archetype <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes"
/> and deploy the generated war in a few easy steps. This will also give you an empty
project to play around with or start from scratch.
+ </para>
+ <!-- <para>
+ For system requirements and setting up your JBoss Portal environment see the
+ <ulink
url="http://docs.jboss.com/jbportal/v2.6.4/referenceGuide/html_singl...
guide</ulink>.
+ </para> -->
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes">
+ <title>Maven Archetypes</title>
+ <para>
+ This project utilizes <ulink
url="http://maven.apache.org/guides/introduction/introduction-to-arc...
archetypes</ulink> which allow you get up and running with different flavors of the
bridge quickly.
+ <table frame="all"
id="tabl-JBoss_Portlet_Bridge_Reference_Guide-Maven_Archetypes-Available_Archetypes">
+ <title>Available Archetypes</title>
+ <tgroup align="left" cols="5" colsep="1"
rowsep="1">
+ <colspec colname="c1"></colspec>
+ <colspec colname="c2"></colspec>
+ <colspec colname="c3"></colspec>
+ <colspec colname="c5" colnum="5"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ Archetype
+ </entry>
+ <entry align="center" nameend="c5"
namest="c2">
+ Command
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row class="table-odd" style="background-color:#D6DEE0;border:1px
solid #E1E9EB;color:#334558;">
+ <entry align="left">
+ JSF 1.2 Basic
+ </entry>
+ <entry align="left" nameend="c5" namest="c2">
+
+<programlisting>mvn archetype:generate
+ -DarchetypeGroupId=org.jboss.portletbridge.archetypes
+ -DarchetypeArtifactId=1.2-basic
+ -DarchetypeVersion=2.0.0.CR1
+ -DgroupId=org.whatever.project
+ -DartifactId=myprojectname
+ -DarchetypeRepository=http://repository.jboss.org/maven2/
+</programlisting>
+ </entry>
+ </row>
+ <row class="table-even"
style="background-color:#D6DEE0;border:1px solid #E1E9EB;color:#334558;">
+ <entry align="left">
+ RichFaces Basic
+ </entry>
+ <entry align="left" nameend="c5" namest="c2">
+
+<programlisting>mvn archetype:generate
+ -DarchetypeGroupId=org.jboss.portletbridge.archetypes
+ -DarchetypeArtifactId=richfaces-basic
+ -DarchetypeVersion=2.0.0.CR1
+ -DgroupId=org.whatever.project
+ -DartifactId=myprojectname
+ -DarchetypeRepository=http://repository.jboss.org/maven2/
+</programlisting>
+ </entry>
+ </row>
+ <row class="table-odd" style="background-color:#D6DEE0;border:1px
solid #E1E9EB;color:#334558;">
+ <entry align="left">
+ Seam Basic (Modular EAR)
+ </entry>
+ <entry align="left" nameend="c5" namest="c2">
+
+<programlisting>mvn archetype:generate
+ -DarchetypeGroupId=org.jboss.portletbridge.archetypes
+ -DarchetypeArtifactId=seam-basic
+ -DarchetypeVersion=2.0.0.CR1
+ -DgroupId=org.whatever.project
+ -DartifactId=seamproject
+ -DarchetypeRepository=http://repository.jboss.org/maven2/
+</programlisting>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Video_Tutorials">
+ <title>Video Tutorials</title>
+ <para>
+ <ulink url="http://www.vimeo.com/3977469">Episode 1: Getting Started
With The Bridge</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.vimeo.com/4521877">Episode 2: Portlet 1.0
Advanced Seam and RichFaces</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.vimeo.com/5847864">Episode 3: Seam and Portlet
2.0 Eventing</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.vimeo.com/7255033">Episode 4: Running the 2.0
bridge on GateIn and deploy using JBoss Tools</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.vimeo.com/7255033">Episode 5: GateIn JMX
Metrics and Dashboard Demo</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.vimeo.com/wesleyhales/videos">Check here for
the latest videos.</ulink>
+ </para>
+
+ </section>
+
+</section>
+
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml
(rev 0)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -0,0 +1,82 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE preface 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;
+]>
+<section
id="chap-JBoss_Portlet_Bridge_Reference_Guide-JBoss_Portlet_Bridge_Overview">
+ <title>JBoss Portlet Bridge Overview</title>
+ <para>
+ To get an idea of the JBoss Portlet Bridge community, the developers, and for wiki
information, checkout <ulink url="http://www.jboss.org/portletbridge/">the
project page</ulink>.
+ </para>
+ <formalpara>
+ <title>What is the JBoss Portlet Bridge?</title>
+ <para>
+ The JBoss Portlet Bridge (or JBPB for short) is a non-final draft implementation of
the <ulink url="http://jcp.org/en/jsr/detail?id=329">JSR-329</ulink>
specification which supports the JSF 1.2 runtime within a JSR 286 portlet and with added
enhancements to support other web frameworks (such as <ulink
url="http://www.seamframework.org/">Seam</ulink> and <ulink
url="http://www.jboss.org/jbossrichfaces/">RichFaces</ulink>). It
allows any Java developer to get started quickly with their JSF web application running in
a portal environment. The developer no longer needs to worry about the underlying portlet
development, portlet concepts, or the API.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Understanding how JSF works with Portal</title>
+ <para>
+ The portlet bridge isn't a portlet. It's the mediator between the two
environments and allows JSF and Portal to be completely unaware of each other. The bridge
is used to execute Faces requests on behalf of the portlet. During each request, the Faces
environment is setup and handled by the bridge. Part of this implementation acts as a
Faces controller much as the FacesServlet does in the direct client request world. The
other part of this implementation is provided by implementating a variety of (standard)
Faces extensions.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ This draft specification for the JSR 329 specification is not final. Any final
specification that may be published will likely contain differences, some of which may be
substantial. Publication of this draft specification is not intended to provide the basis
for implementations of the specification. This draft specification is provided AS IS, with
all faults. THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF CONDITION
OF TITLE OR NONINFRINGEMENT. You may copy and display this draft specification provided
that you include this notice and any existing copyright notice. Except for the limited
copyright license granted above, there are no other licenses granted to any intellectual
property owned or controlled by any of the authors or developers of this material. No
other rights are granted by implication, estoppel or otherwise.
+ </para>
+ </note>
+ <!-- <figure id="build.fig">
+ <title>Faces in Portlet Environment</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/portletbridge-basic.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <imageobject>
+ <imagedata fileref="images/frontpage.png" format="png"
align="center"
+ valign="middle"/>
+ </imageobject>
+ </para> --><!-- <para>
+ <emphasis role="bold">JBoss Portal Resources:</emphasis>
+ <orderedlist>
+ <listitem>
+ <para>
+ <ulink url="http://labs.jboss.com/jbossportal">JBoss
Portal Home Page</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Forums:
+ <ulink
+
url="http://www.jboss.org/index.html?module=bb&op=viewforum&...
+ >User</ulink>
+ |
+ <ulink
+
url="http://www.jboss.org/index.html?module=bb&op=viewforum&...
+ >Design</ulink>
+ |
+ <ulink
url="http://jboss.org/index.html?module=bb&op=viewforum&...
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.jboss.com/wiki/Wiki.jsp?page=JBossPortal">Wi...
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.portletswap.com">PortletSwap.com
portlet exchange</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
+
url="http://jira.jboss.com/jira/browse/JBPORTAL?report=com.atlassian...
+ >Our Roadmap</ulink>
+ </para>
+ </listitem>
+ </orderedlist>
+ </para> -->
+</section>
+
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml
(rev 0)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -0,0 +1,311 @@
+<?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;
+]>
+<section
id="chap-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge">
+ <title>Developing Portlets with the Bridge</title>
+ <para>
+ This chapter demonstrates common development tasks described by the 329 specification.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Excluding_Attributes_from_the_Bridge_Request_Scope">
+ <title>Excluding Attributes from the Bridge Request Scope</title>
+ <para>
+ When your application uses request attributes on a per request basis and you do not
want that particular attribute to be managed in the extended bridge request scope, you
must use the following configuration in your faces-config.xml. Below you will see that any
attribute namespaced as foo.bar or any attribute beginning with foo.baz(wildcard) will be
excluded from the bridge request scope and only be used per that application's
request.
+ </para>
+
+<programlisting role="XML">
+ <application>
+ <application-extension>
+ <bridge:excluded-attributes>
+
<bridge:excluded-attribute>foo.bar</bridge:excluded-attribute>
+
<bridge:excluded-attribute>foo.baz.*</bridge:excluded-attribute>
+ </bridge:excluded-attributes>
+ </application-extension>
+ </application>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Supporting_PortletMode_Changes">
+ <title>Supporting PortletMode Changes</title>
+ <para>
+ A PortletMode represents a distinct render path within an application. There are three
standard modes: view, edit, and help. The bridge's ExternalContext.encodeActionURL
recognizes the query string parameter javax.portlet.faces.PortletMode and uses this
parameter's value to set the portlet mode on the underlying portlet actionURL or
response. Once processed it then removes this parameter from the query string. This means
the following navigation rule causes one to render the \edit.jspx viewId in the portlet
edit mode:
+ </para>
+
+<programlisting role="XML">
+ <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>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Navigating_to_a_modes_last_viewId">
+ <title>Navigating to a mode's last viewId</title>
+ <para>
+ By default a mode change will start in the mode's default view without any (prior)
existing state. One common portlet pattern when returning to the mode one left after
entering another mode (e.g.. view -> edit -> view) is to return to the last
view (and state) of this origin mode. The bridge will explicitly encode the necessary
information so that when returning to a prior mode it can target the appropriate view and
restore the appropriate state. The session attributes maintained by the bridge are
intended to be used by developers to navigate back from a mode to the last location and
state of a prior mode. As such a developer needs to describe a dynamic navigation:
"from view X return to the last view of mode y". This is most easily expressed
via an EL expression. E.g.
+ </para>
+
+<programlisting role="XML">
+ <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>
+</programlisting>
+ <note>
+ <title>Note to Portlet Developers</title>
+ <para>
+ Depending on the bridge implementation, when using values from these session scoped
attributes or any viewIds which may contain query string parameters it may be necessary to
use the wildcard syntax when identifying the rule target. For example, the above
+ </para>
+ </note>
+<programlisting><to-view-id>
+</programlisting>
+ <para>
+ expression returns a viewId of the form
+ </para>
+<programlisting>/viewId?javax.portlet.faces.PortletMode=view&....
+</programlisting>
+ <para>
+ Without wildcarding, when a subsequent navigation occurs from this new view, the
navigation rules wouldn't resolve because there wouldn't be an exact match.
Likewise, the above edit.jspx
+ </para>
+<programlisting><from-view-id>
+</programlisting>
+ <para>
+ is wildcarded because there are navigation rules that target it that use a query
string:
+ </para>
+<programlisting><to-view-id>
/edit.jspx?javax.portlet.faces.PortletMode=edit </to-view-id>
+</programlisting>
+ <para>
+ Developers are encouraged to use such wildcarding to ensure they execute properly in
the broadest set of bridge implementations.
+ </para>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Clear-View-History">
+ <title>Clearing The View History When Changing Portlet Modes</title>
+ <para>
+ By default the bridge remembers the view history when you switch to a different
portlet mode (like "Help" or "Edit"). You
+ can use the following parameter in your portlet.xml to use the default viewId
each time you switch modes.
+ </para>
+
+ <programlisting role="XML"><![CDATA[
+ <init-param>
+ <name>javax.portlet.faces.extension.resetModeViewId</name>
+ <value>true</value>
+ </init-param>
+ ]]></programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-General_Error_Handling">
+ <title>General Error Handling</title>
+ <note>
+ <para>
+ If you're developing a Seam portlet you can now use pages.xml for all error
handling.
+ </para>
+ </note>
+ <para>
+ The following configuration may be used to handle exceptions. This is also useful for
handling session timeout and ViewExpiredExceptions.
+ </para>
+ <para>
+ Pay attention to the location element. It must contain the /faces/ mapping to work
properly.
+ </para>
+
+<programlisting role="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>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Custom_Ajax_Error_Handling">
+ <title>Custom Ajax Error Handling</title>
+ <para>
+ By default, error handling is sent to a standard servlet page for Ajax requests. To
handle the error inside the portlet, use the following javascript:
+ </para>
+
+<programlisting role="XML">
+ <script type="text/javascript">
+ A4J.AJAX.onError = function(req,status,message){
+ window.alert("Custom onError handler "+message);
+ }
+
+ A4J.AJAX.onExpired = function(loc,expiredMsg){
+ if(window.confirm("Custom onExpired handler "+expiredMsg+"
for a location: "+loc)){
+ return loc;
+ } else {
+ return false;
+ }
+ }
+ </script>
+</programlisting>
+ <para>
+ Also, add the following to web.xml. Read more about these settings here <ulink
url="http://docs.jboss.org/richfaces/3.3.3.BETA1/en/devguide/html/Ar...
Errors and Session Expiration Handling</ulink>
+ </para>
+
+<programlisting role="XML">
+ <context-param>
+
<param-name>org.ajax4jsf.handleViewExpiredOnClient</param-name>
+ <param-value>true</param-value>
+ </context-param>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Communication_Between_Your_Portlets">
+ <title>Communication Between Your Portlets</title>
+ <para>
+ There are roughly 4 different ways to send messages, events, and parameters between
portlets which are contained in different ears/wars or contained in the same war. The
Portlet Container does not care if you have 2 portlets in the same war or if they are
separated, because each portlet has a different HttpSession.
+ </para>
+ <para>
+ Of course, with the Portlet 2.0 spec, the recommended way to share a parameter or
event payload between 2 or more portlets are the <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"/>
and <xref
linkend="sect-JBoss_Portlet_Bridge_Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"
/> mechanisms. This allows you to decouple your application from surgically managing
objects in the PortletSession.APPLICATION_SCOPE.
+ </para>
+ <para>
+ But, if these do not meet your usecase or you have a different strategy, you can use
one of the following methods.
+ </para>
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Communication_Between_Your_Portlets-Storing_Components_in_PortletSession.APPLICATION_SCOPE">
+ <title>Storing Components in PortletSession.APPLICATION_SCOPE</title>
+ <para>
+ Sometimes it makes sense to store your Seam components in the portlet
APPLICATION_SCOPE. By default, these objects are stored in the PORTLET_SCOPE but with the
annotation below, you can fish this class out of the PortletSession and use its values in
other portlets across different Seam applications.
+ </para>
+
+<programlisting role="XML">
+ @PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE)
+</programlisting>
+ <para>
+ Then you would pull the statefull object from the session:
+ </para>
+
+<programlisting role="java">
+ YourSessionClass yourSessionClass =
(YourSessionClass)getRenderRequest().getAttribute("javax.portlet.p./default/seamproject/seamprojectPortletWindow?textHolder");
+</programlisting>
+ <para>
+ This method is demonstrated in this video: <ulink
url="http://www.vimeo.com/4521877">Lesson 2: Portlet 1.0 Advanced Seam and
RichFaces</ulink>
+ </para>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Communication_Between_Your_Portlets-Using_the_PortletSession">
+ <title>Using the PortletSession</title>
+ <para>
+ If you need to access the PortletSession to simply share a parameter/value across
multiple portlets, you can use the following to do so.
+ </para>
+
+<programlisting role="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>
+ Then, in your JSP or Facelets page, you can use:
+ </para>
+
+<programlisting role="XML">
+ #{httpSessionScope['your parameter name']}
+</programlisting>
+ <para>
+ <note>
+ <title>Note to Portlet Developers</title>
+ <para>
+ #{httpSessionScope} was implemented after 2.0.0.BETA. If you are using the 1.0
bridge or pre 2.0.0.BETA, you must use the el variable #{sessionApplicationScope}
+ </para>
+ </note>
+ For more information about which EL variables are provided by the bridge, read
<ulink
url="http://jcp.org/aboutJava/communityprocess/edr/jsr329/index2.htm...
6.5.1 of the JSR-329 specification</ulink>.
+ </para>
+ </section>
+
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-View_Linking_to_PortletJSF_Pages_Using_houtputink">
+ <title>Linking to Portlet/JSF Pages Using h:outputink</title>
+ <para>
+ For linking to any JSF/Facelets page within your portlet web application, you may use
the following.
+ </para>
+
+<programlisting role="java">
+ <h:outputLink
value="#{facesContext.externalContext.requestContextPath}/home.xhtml">
+ <f:param name="javax.portlet.faces.ViewLink"
value="true"/>
+ navigate to the test page
+ </h:outputLink>
+</programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Direct_Linking_to_PortletJSF_Pages_Using_houtputink">
+ <title>Redirecting to an External Page or Resource</title>
+ <para>
+ To link to a non JSF view (i.e. jboss.org) you can use the following parameter.
+ </para>
+
+<programlisting role="java">
+ <h:commandLink actionListener="#{yourBean.yourListenr}">
+ <f:param name="javax.portlet.faces.DirectLink"
value="true"/>
+ navigate to the test page
+ </h:commandLink>
+</programlisting>
+ <para>
+ Then in your backing bean, you must call a redirect().
+ </para>
+<programlisting role="java"><![CDATA[
+
FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.jboss.org");
+]]></programlisting>
+ </section>
+
+ <section
id="sect-JBoss_Portlet_Bridge_Reference_Guide-Developing_Portlets_with_the_Bridge-Available-EL">
+ <title>Using Provided EL Variables</title>
+ <para>
+ All EL 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.
+ </para>
+
+<programlisting role="xml"><![CDATA[
+ <h:form>
+ <h:inputText id="pref" required="true"
value="#{mutablePortletPreferencesValues['userName'].value}" />
+ <h:commandButton actionListener="#{myBean.savePref}"
value="Save Preferences" />
+ </h:form>
+]]></programlisting>
+ <para>
+ Then in your backing bean, you must call the PortletPreferences.store() method.
+ </para>
+<programlisting role="java"><![CDATA[
+ Object request =
FacesContext.getCurrentInstance().getExternalContext().getRequest();
+ PortletRequest portletRequest = (PortletRequest)request;
+ if (request instanceof PortletRequest) {
+ try {
+ PortletPreferences portletPreferences = portletRequest.getPreferences();
+ portletPreferences.store();
+]]></programlisting>
+ </section>
+
+ <!--EL variables-->
+
+
+ <!--using sendRedirect-->
+
<!--FacesContext.getCurrentInstance().getExternalContext().redirect("http://www.google.com");-->
+<!--and adding the <f:param name="javax.portlet.faces.DirectLink"
value="true"/> to the commandButton, all seems fine. -->
+
+
+ <!-- <section>
+ <title>Integrations with JBoss Tools IDE</title>
+ <para>
+
+ </para>
+ <programlisting role="XML"><![CDATA[
+
+ ]]></programlisting>
+
+ </section> -->
+</section>
+
Added:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml
(rev 0)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -0,0 +1,13 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<section>
+ <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" />
+</section>
+
Modified:
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment.xml
===================================================================
---
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment.xml 2010-04-28
15:51:00 UTC (rev 2879)
+++
portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules/PortletDevelopment.xml 2010-04-28
15:59:53 UTC (rev 2880)
@@ -7,6 +7,6 @@
<title>Portlet development</title>
<xi:include href="PortletDevelopment/Standard.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
+ <xi:include href="PortletDevelopment/PortletBridge.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>