Author: thomas.heute(a)jboss.com
Date: 2010-07-15 16:28:08 -0400 (Thu, 15 Jul 2010)
New Revision: 13964
Added:
docs/enterprise/trunk/PortletBridge/en-US/configuration.xml
docs/enterprise/trunk/PortletBridge/en-US/gettingstarted.xml
docs/enterprise/trunk/PortletBridge/en-US/overview.xml
docs/enterprise/trunk/PortletBridge/en-US/portlet_development.xml
Removed:
docs/enterprise/trunk/PortletBridge/en-US/Configuration.xml
docs/enterprise/trunk/PortletBridge/en-US/Getting_Started.xml
docs/enterprise/trunk/PortletBridge/en-US/Overview.xml
docs/enterprise/trunk/PortletBridge/en-US/Portlet_Development.xml
Modified:
docs/enterprise/trunk/PortletBridge/en-US/JBoss_Portlet_Bridge_Overview.xml
Log:
JBEPP-376: EPP 4.3.CP05 Documentation
Upgrade to Portlet Bridge 2.0
Deleted: docs/enterprise/trunk/PortletBridge/en-US/Configuration.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/Configuration.xml 2010-07-15 19:52:49 UTC
(rev 13963)
+++ docs/enterprise/trunk/PortletBridge/en-US/Configuration.xml 2010-07-15 20:28:08 UTC
(rev 13964)
@@ -1,296 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-Overview-Bridge_Configuration">
- <title>Bridge Configuration</title>
- <para>
- The 301 specification is aimed at making the developer's life as easy as
possible when developing with JSF+Portlet. You will see below that there are minimal
settings to getting any JSF web application up and running in the Portal environment.
- </para>
- <section
id="sect-Overview-Bridge_Configuration-Core_Setup_and_Configuration">
- <title>Core Setup and Configuration</title>
- <section id="sect-Overview-Core_Setup_and_Configuration-portlet.xml">
- <title>portlet.xml</title>
- <para>
- The basic JSR-301 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 is not 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-Overview-Core_Setup_and_Configuration-faces_config.xml">
- <title>faces-config.xml</title>
- <para>
- The PortletViewHandler ensures that each JSF portlet instance is porperly
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-Overview-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-Overview-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>
-
-<programlisting role="XML">
- <context-param>
-
<param-name>javax.portlet.faces.renderPolicy</param-name>
- <param-value>
- ALWAYS_DELEGATE
- </param-value>
- </context-param>
- ...
- </web-app>
-</programlisting>
- <note>
- <title>RenderPolicy Options</title>
- <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 to render the view based on its
own logic. If the configuration parameter is not present or has an invalid value the
bridge renders using the default behavior i.e. as though DEFAULT were set.
- </para>
-
- </listitem>
-
- </itemizedlist>
-
- </note>
-
- </section>
-
-
- </section>
-
- <section
id="sect-Overview-Core_Setup_and_Configuration-JSP_Only_Configuration">
- <title>JSP Only Configuration</title>
- <para>
- The following web.xml setting is only for JSP based applications
- </para>
- <section id="sect-Overview-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-Overview-Core_Setup_and_Configuration-JSR_301">
- <title>JSR-301</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-Overview-Bridge_Configuration-RichFaces_Setup_and_Configuration_Options">
- <title>RichFaces Setup and Configuration Options</title>
- <note>
- <para>
- Please be aware that RichFaces integration is a technology preview and hence is
currently unsupported.
- </para>
-
- </note>
- <section
id="sect-Overview-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>
-
-<programlisting role="XML">
- <context-param>
-
<param-name>org.richfaces.LoadStyleStrategy</param-name>
- <param-value>NONE</param-value>
- </context-param>
- <context-param>
-
<param-name>org.richfaces.LoadScriptStrategy</param-name>
- <param-value>NONE</param-value>
- </context-param>
-</programlisting>
- <para>
- The <literal>org.ajax4jsf.RESOURCE_URI_PREFIX</literal> configuration
cross references a setting in your <filename>jboss-portlet.xml</filename> file
(see below). These settings are required for RichFaces.
- </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
id="sect-Overview-RichFaces_Setup_and_Configuration_Options-jboss_portlet.xml">
- <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">
- <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-Overview-Bridge_Configuration-Seam_Setup_and_Configuration_Options">
- <title>Seam Setup and Configuration Options</title>
- <note>
- <para>
- Please be aware that Seam integration is a technology preview and hence is currently
unsupported.
- </para>
-
- </note>
- <section
id="sect-Overview-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>
- Earlier 2.0.x versions of Seam portlets must have the LIFECYCLE_ID set to
SEAM_PORTLET in the web.xml file. This setting allows the bridge to replace the original
Seam phase listener during the faces life-cycle addPhaseListeners. This setting is not
needed for Seam portlets version 2.1.x and up.
- </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>
-
-
-</chapter>
-
Deleted: docs/enterprise/trunk/PortletBridge/en-US/Getting_Started.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/Getting_Started.xml 2010-07-15 19:52:49 UTC
(rev 13963)
+++ docs/enterprise/trunk/PortletBridge/en-US/Getting_Started.xml 2010-07-15 20:28:08 UTC
(rev 13964)
@@ -1,233 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-Overview-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-Overview-Getting_started_with_JBoss_Portlet_Bridge-Bridge_Frameworks_and_Extensions">
- <title>Bridge Frameworks and Extensions</title>
- <para>
- The JBoss Portlet Bridge project is also actively developing extensions, or
Bridgelets, that enhance or bring together features of JBoss Portal, Seam, and Richfaces.
For example, the PortalIdentity seam component allows you to drop the jar in your
classpath and you instantly have SSO between Seam and Portal. This extension can also be
configured with additional attributes in your Seam application's components.xml
file.
- <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 participate
on the <ulink
url="http://www.jboss.com/index.html?module=bb&op=viewforum&...
forum</ulink> and bring issues/enhancements to our attention.
- </para>
-
- </note>
-
- </para>
- <para>
- <table frame="all"
id="tabl-Overview-Bridge_Frameworks_and_Extensions-Available_Bridgelets">
- <title>Available Bridgelets</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">
- Bridgelet
- </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">
- Single Sign On
- </entry>
- <entry align="left" nameend="c5"
namest="c2">
- <para>
- By including the following dependency in your web pom, you will automatically
enable SSO between JBoss Portal and your Seam 2.1.1.GA application.
-<programlisting>
-<dependency>
-
<groupId>org.jboss.portletbridge.extensions.seam</groupId>
- <artifactId>PortalIdentity</artifactId>
- <version>1.0.0.CR2</version>
-</dependency>
-</programlisting>
-
- </para>
-
- </entry>
-
- </row>
-
- </tbody>
-
- </tgroup>
-
- </table>
-
- </para>
-
- </section>
-
- <section
id="sect-Overview-Getting_started_with_JBoss_Portlet_Bridge-Before_you_start">
- <title>Before you start</title>
- <para>
- Current version and compatibility information can be easily located on the <ulink
url="http://www.jboss.org/wiki/JBossPortletBridge">JBoss Portlet Bridge
wiki</ulink>. Ensure you are using compatible versions of all integrated frameworks
before you begin.
- </para>
- <para>
- JBoss Portal provides its latest distribution with the JBoss Application Server. All
of the guesswork has been eliminated so that you can unzip and run Portal with a few
clicks. <ulink
url="http://www.jboss.org/jbossportal/download/index.html">Get the latest
version here</ulink> (ensure you choose the JBoss 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 configure your portlet to use the bridge. Or, you can run a
provided archetype <xref
linkend="sect-Overview-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-Overview-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes">
- <title>Maven Archetypes</title>
- <para>
- The JBPB 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-Overview-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=1.0.0.CR2
- -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=1.0.0.CR2
- -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=1.0.0.CR2
- -DgroupId=org.whatever.project
- -DartifactId=seamproject
- -DarchetypeRepository=http://repository.jboss.org/maven2/
-</programlisting>
-
- </entry>
-
- </row>
-
- </tbody>
-
- </tgroup>
-
- </table>
-
- </para>
- <section id="sect-Overview-Maven_Archetypes-Running_the_Examples">
- <title>Running the Examples</title>
- <para>
- <emphasis role="bold">JSF 1.2 Basic, RichFaces Basic, Seam Basic, and
other demos</emphasis>
- </para>
- <para>
- Each example application is configured to download the latest version of JBoss Portal
bundled with JBoss Application Server. After running the archetype <xref
linkend="sect-Overview-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes"
/> or <ulink
url="http://www.jboss.org/portletbridge/download/">downloading the source
code</ulink> for the example application that you are interested in, you can run one
of the following Maven profiles to save time and get everything up and running with only 2
commands.
- </para>
- <para>
- <emphasis role="bold">JBoss Portal 2.7.2.GA + JBoss AS 4.2.3
(Bundled)</emphasis>
- </para>
-
-<programlisting role="XML">
-mvn install -Plocal-portal cargo:start
-mvn cargo:deploy -Plocal-portal
-visit
http://localhost:8080/portal
-</programlisting>
- <!--
- <para>
- <emphasis role="bold">JBoss Portlet Container 2.0 + JBoss AS 4.2.3
(Bundled)</emphasis>
- </para>
-
-<programlisting role="XML">
-mvn install cargo:start -Premote-portal -Dpc20
-mvn cargo:deploy -Premote-portal -Dpc20
-</programlisting>
- --> <para>
- <emphasis>Time Saving Tips</emphasis>
- </para>
- <para>
- <emphasis role="normal">If you plan on using the cargo profiles to do
active development, you can save a lot of time by not downloading the bundle each time you
do a clean install. To use a locally configured server bundled with portal, use the
following command line parameters. The variable for JBOSS_HOME_DIR is related to how you
zip the server directory. If you zip the files under JBOSS_HOME/* then it will only be the
name of your archive. But if you zip the actual folder JBOSS_HOME then JBOSS_HOME_DIR must
be defined as 'zip file name/JBOSS_HOME folder name'.</emphasis>
- </para>
- <!--
- <para>
- <emphasis role="bold">JBoss Portal 2.7.0.B1</emphasis>
- </para>
-
-<programlisting role="XML">
-mvn install cargo:start -Plocal-portal
-DJBOSS_ZIP_HOME=/path_to_bundle_zip/jboss-portal-2.7.0.B1-bundled.zip
-DJBOSS_HOME_DIR=jboss-portal-2.7.0.B1-bundled/jboss-portal-2.7.0.B1
-mvn cargo:deploy -Plocal-portal
-DJBOSS_ZIP_HOME=/path_to_bundle_zip/jboss-portal-2.7.0.B1-bundled.zip
-DJBOSS_HOME_DIR=jboss-portal-2.7.0.B1-bundled/jboss-portal-2.7.0.B1
-</programlisting>
- <para>
- <emphasis role="bold">PortletContainer 2.0</emphasis>
- </para>
-
-<programlisting role="XML">
-mvn install cargo:start -Plocal-portal
-DJBOSS_ZIP_HOME=/path_to_bundle_zip/Jboss-4.2.2-PC20.zip
-DJBOSS_HOME_DIR=Jboss-4.2.2-PC20
-mvn cargo:deploy -Plocal-portal -DJBOSS_ZIP_HOME=/path_to_bundle_zip/Jboss-4.2.2-PC20.zip
-DJBOSS_HOME_DIR=Jboss-4.2.2-PC20
-</programlisting>
- -->
- </section>
-
-
- </section>
-
-
-</chapter>
-
Modified: docs/enterprise/trunk/PortletBridge/en-US/JBoss_Portlet_Bridge_Overview.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/JBoss_Portlet_Bridge_Overview.xml 2010-07-15
19:52:49 UTC (rev 13963)
+++ docs/enterprise/trunk/PortletBridge/en-US/JBoss_Portlet_Bridge_Overview.xml 2010-07-15
20:28:08 UTC (rev 13964)
@@ -4,10 +4,10 @@
<book>
<xi:include href="Book_Info.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preface.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Overview.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Getting_Started.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Portlet_Development.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="overview.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="gettingstarted.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="configuration.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="portlet_development.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Deleted: docs/enterprise/trunk/PortletBridge/en-US/Overview.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/Overview.xml 2010-07-15 19:52:49 UTC (rev
13963)
+++ docs/enterprise/trunk/PortletBridge/en-US/Overview.xml 2010-07-15 20:28:08 UTC (rev
13964)
@@ -1,86 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-Overview-JBoss_Portlet_Bridge_Overview">
- <title>JBoss Portlet Bridge Overview</title>
- <warning>
- <para>
- As part of the support contract, only JSF applications are supported and should be
used in production. Seam and RichFaces portlets are provided here as technology preview,
at this stage it is recommended to <emphasis role="bold">not use those in
production</emphasis>. Work is being done to support those two technologies. In the
meantime it is encouraged to try those during development to report any issue in our
community forums to help mature the integration.
- </para>
-
- </warning>
- <note>
- <para>
- This project is marked as 'Beta' since the JSR-301 specification is
not final at the time of release and because support for RichFaces and Seam need to
mature. As part of the professional support the API will not change for JSF portlets
during the lifetime of the Enterprise Portal Platform to guarantee that no issue will
arise during an upgrade. Again JSF applications are fully supported and can be used in
production. Also note that the Maven archetypes may download binaries that are not
supported by the support contract.
- </para>
-
- </note>
- <para>
- To get an idea of the JBoss Portlet Bridge community, the developers, and for wiki
resources, check out <ulink
url="http://www.jboss.org/portletbridge/">the
project page</ulink>.
- </para>
- <para>
- <emphasis role="bold">What is the JBoss Portlet
Bridge?</emphasis>
- </para>
- <para>
- The JBoss Portlet Bridge (or JBPB for short) is an implementation of the <ulink
url="http://jcp.org/en/jsr/detail?id=301">JSR-301</ulink> specification
which supports JSF within a portlet and with added enhancements, offers support of other
web frameworks (such as <ulink
url="http://www.seamframework.org/">Seam</ulink> and <ulink
url="http://www.jboss.org/jbossrichfaces/">RichFaces</ulink>). It
basically 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>
- <para>
- <emphasis role="bold">Understanding how JSF works with
Portal</emphasis>
- </para>
- <para>
- It is important to understand that the portlet bridge is not a portlet. Rather, it is
the mediator between the two environments and allows JSF and Portal to be completely
unaware of each other and live in their own seperate worlds. The bridge is used to execute
Faces requests on behalf of the portlet. During each request, the Faces environment is set
up and handled by the bridge. Part of this implementation acts as a Faces controller much
like how the FacesServlet does for direct client requests. The other part of this
implementation is provided by incorporating a variety of (standard) Faces extensions.
- </para>
- <!-- <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> -->
-</chapter>
-
Deleted: docs/enterprise/trunk/PortletBridge/en-US/Portlet_Development.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/Portlet_Development.xml 2010-07-15 19:52:49
UTC (rev 13963)
+++ docs/enterprise/trunk/PortletBridge/en-US/Portlet_Development.xml 2010-07-15 20:28:08
UTC (rev 13964)
@@ -1,108 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-Overview-Developing_Portlets_with_the_Bridge">
- <title>Developing Portlets with the Bridge</title>
- <para>
- This chapter demonstrates common development tasks described by the 301 specification.
- </para>
- <section
id="sect-Overview-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 file. 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-Overview-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-Overview-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>
- <para>
- <emphasis>Note to Portlet Developers</emphasis> 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
-<programlisting><to-view-id>
-</programlisting>
- expression returns a viewId of the form
-<programlisting>/viewId?javax.portlet.faces.PortletMode=view&....
-</programlisting>
- 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
-<programlisting><from-view-id>
-</programlisting>
- is wildcarded because there are navigation rules that target it that use a query
string (
-<programlisting><to-view-id>
/edit.jspx?javax.portlet.faces.PortletMode=edit </to-view-id>
-</programlisting>
- ). Developers are encouraged to use such wildcards to ensure they execute properly
in the broadest set of bridge implementations.
- </para>
-
- </note>
-
- </section>
-
- <section
id="sect-Overview-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>
-
- </section>
-
-
-</chapter>
-
Added: docs/enterprise/trunk/PortletBridge/en-US/configuration.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/configuration.xml
(rev 0)
+++ docs/enterprise/trunk/PortletBridge/en-US/configuration.xml 2010-07-15 20:28:08 UTC
(rev 13964)
@@ -0,0 +1,483 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBoss_Portlet_Bridge_Overview.ent">
+%BOOK_ENTITIES;
+]>
+<chapter 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>
+ <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.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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 <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"><![CDATA[
+ <init-param>
+ <name>javax.portlet.faces.preserveActionParams</name>
+ <value>true</value>
+ </init-param>
+]]></programlisting>
+ </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"><![CDATA[
+ <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-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"><![CDATA[
+ <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>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <context-param>
+ <param-name>javax.portlet.faces.RENDER_POLICY</param-name>
+ <param-value>
+ ALWAYS_DELEGATE
+ </param-value>
+ </context-param>
+ ...
+ </web-app>
+]]></programlisting>
+
+ <variablelist>
+ <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 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>
+ </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"><![CDATA[
+ <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-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, <literal>MyFaces</literal> implementation). Simply put the following
into <filename>web.xml</filename>:
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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-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"><![CDATA[
+ <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 "<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.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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>
+ <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"><![CDATA[
+ <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>
+
+ <!-- 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"><![CDATA[
+ <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 <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"><![CDATA[
+ <context-param>
+ <param-name>javax.faces.LIFECYCLE_ID</param-name>
+ <param-value>SEAM_PORTLET</param-value>
+ </context-param>
+]]></programlisting>
+ </section>
+
+ </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"><![CDATA[
+ <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-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"><![CDATA[ <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>
+ While future versions on the 2.0 bridge will automate the dispatching and consuming
of events, at the moments you must dispatch the event in the JSF or Seam backing bean.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[ if
(response instanceof StateAwareResponse) {
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setEvent(Foo.QNAME, new Bar());
+ }
+]]></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="XML" role="XML"><![CDATA[
+ public class BookingEventHandler implements BridgeEventHandler
+ {
+ public EventNavigationResult handleEvent(FacesContext context, Event event)
+ {
+ //process event payload here
+ }
+
+ }
+]]></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 use 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.0.0.FINAL/e...
/>
+ </para>
+ <para>
+ You must define the following <emphasis>init params</emphasis> in your
<filename>portlet.xml</filename>.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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 <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"><![CDATA[
+ <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 language="XML" role="XML"><![CDATA[
+ if (response instanceof StateAwareResponse) {
+ StateAwareResponse stateResponse = (StateAwareResponse) response;
+ stateResponse.setRenderParameter("hotelName",selectedHotel.getName());
+ }
+]]></programlisting>
+ <para>
+ Then you must also implement the
<literal>BridgePublicRenderParameterHandler</literal> interface to process any
updates from the received parameter.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ 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-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.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 "<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="XML" role="XML">
+ #{resource['/img/the-path-to-my-image.png']}
+</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"><![CDATA[
+ <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>
+
+</chapter>
+
+
Added: docs/enterprise/trunk/PortletBridge/en-US/gettingstarted.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/gettingstarted.xml
(rev 0)
+++ docs/enterprise/trunk/PortletBridge/en-US/gettingstarted.xml 2010-07-15 20:28:08 UTC
(rev 13964)
@@ -0,0 +1,235 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBoss_Portlet_Bridge_Overview.ent">
+%BOOK_ENTITIES;
+]>
+<chapter
id="sect-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
<application>Seam</application> and
<application>RichFaces</application>.
+ </para>
+ <section
id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Whats_New_in_2.0">
+ <title>What's New in 2.0?</title>
+ <section id="sect-Reference_Guide-Whats_New_in_2.0-Eventing">
+ <title>Eventing</title>
+ <para>
+ The bridge considers a portlet event a model event. The event is targeted to the
applications data model, not its view.
+ </para>
+ <para>
+ As JSF events primarily concern its view, the bridge processes the portlet events
manually, however provisions are made to ensure that any model changes resulting from
processing the event are updated in the view.
+ </para>
+ <para>
+ 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-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"
/> for details and examples.
+ </para>
+ </section>
+
+ <section
id="sect-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:
+ </para>
+ <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>
+ <para>
+ 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-Reference_Guide-Portlet_2.0_Coordination-Serving_Your_JSF_Resources_in_a_Portlet"
/> for details and examples.
+ </para>
+ </section>
+
+ <section
id="sect-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.
+ </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 via a
<application>Faces</application>
<literal>ValueExpression</literal>.
+ </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>
+ 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-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"
/> for details and examples.
+ </para>
+ </section>
+
+ </section>
+
+ <section
id="sect-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 &PRODUCT;,
<application>GateIn</application>, <application>JSF
1.2</application>, <application>JBoss Seam</application>, and
<application>JBoss Richfaces</application>. There are configurations that
apply to supporting each framework. See section <xref
linkend="sect-Reference_Guide-Bridge_Configuration" /> for instructions.
+ </para>
+ <para>
+ The JBoss Portlet Bridge project is also actively developing extensions called
"<emphasis role="bold">Bridgelets</emphasis>".
+ </para>
+ <para>
+ In this release it was decided to bring all available bridgelets into the impl code
base since they are critical in most JSF portlet applications. A single line of
configuration utilizes these features.
+ </para>
+ <section
id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-Seam_Bridgelets">
+ <title>Seam Bridgelets</title>
+ <para>
+ For example, the <literal>PortalIdentity</literal>
<application>Seam</application> component allows you to instantly have Single
Sign-On (SSO) between <application>Seam</application> and
<application>GateIn</application> or
<application>&PRODUCT;</application>.
+ </para>
+ <para>
+ This extension is configured in your <application>Seam</application>
application's <filename>components.xml</filename> file as follows.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+<security:portal-identity
authenticate-method="#{authenticator.authenticate}"/>
+]]></programlisting>
+ </section>
+
+ <section
id="sect-Reference_Guide-Bridge_Frameworks_and_Extensions-RichFaces_Bridgelets">
+ <title>RichFaces Bridgelets</title>
+ <para>
+ <application>Richfaces</application> does not account for multiple
components on the same portal page by default. This following
<filename>web.xml</filename> renders all
<application>RichFaces</application> component javascript portal-friendly.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <context-param>
+ <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
+ <param-value>true</param-value>
+ </context-param>
+]]></programlisting>
+ </section>
+
+ </section>
+
+ <section
id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Before_you_start">
+ <title>Before You Start</title>
+ <para>
+ The embedded version in the &PRODUCT; is made to be compatible with the JSF
implementation, portal and application server that compose the product. You will find the
binaries embedded in <filename>jboss-epp-5.0/portletbridge</filename>
+ </para>
+ <para>
+ You can run a provided archetype (See <xref
linkend="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes"
/>) and deploy the generated <literal>war</literal> in a few easy steps.
+ </para>
+ </section>
+
+ <section
id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Maven_Archetypes">
+ <title>Maven Archetypes</title>
+ <para>
+ This product 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-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.FINAL
+ -DgroupId=org.whatever.project
+ -DartifactId=myprojectname
+ -DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/
+</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.FINAL
+ -DgroupId=org.whatever.project
+ -DartifactId=myprojectname
+ -DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/
+</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.FINAL
+ -DgroupId=org.whatever.project
+ -DartifactId=seamproject
+ -DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/
+</programlisting>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section
id="sect-Reference_Guide-Getting_started_with_JBoss_Portlet_Bridge-Video_Tutorials">
+ <title>Video Tutorials</title>
+
+ <para>
+ The following links provide tutorial videos created by the Portlet Bridge developer:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/3977469">Episode 1: Getting Started
With The Bridge</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/4521877">Episode 2: Portlet 1.0
Advanced Seam and RichFaces</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/5847864">Episode 3: Seam and
Portlet 2.0 Eventing</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/7255033">Episode 4: Running the 2.0
bridge on GateIn and deploy using JBoss Tools</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/8752541">Episode 5: GateIn JMX
Metrics and Dashboard Demo</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink
url="http://www.vimeo.com/wesleyhales/videos">Check here for
the latest videos.</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+</chapter>
+
+
Added: docs/enterprise/trunk/PortletBridge/en-US/overview.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/overview.xml (rev
0)
+++ docs/enterprise/trunk/PortletBridge/en-US/overview.xml 2010-07-15 20:28:08 UTC (rev
13964)
@@ -0,0 +1,111 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBoss_Portlet_Bridge_Overview.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="sect-Reference_Guide-JBoss_Portlet_Bridge_Overview">
+ <title>JBoss Portlet Bridge Overview</title>
+ <formalpara
id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-What_is_the_JBoss_Portlet_Bridge">
+ <title>What is the JBoss Portlet Bridge?</title>
+ <para>
+ The JBoss Portlet Bridge (or <literal>JBPB</literal> for short) is a
non-final implementation of the <ulink
url="http://jcp.org/en/jsr/detail?id=329">JSR-329</ulink>
specification.
+ </para>
+ </formalpara>
+ <para>
+ It 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>).
+ </para>
+
+ <para>
+ It allows any Java developer to quickly get started 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>
+
+ <para>
+ Find more information about the JBoss Portlet Bridge, the developers, the community at
<ulink
url="http://www.jboss.org/portletbridge/">the project
page</ulink>.
+ </para>
+
+ <formalpara
id="form-Reference_Guide-JBoss_Portlet_Bridge_Overview-Understanding_how_JSF_works_with_Portal">
+ <title>Understanding how JSF works with Portal</title>
+ <para>
+ The portlet bridge is not a portlet. It is the mediator between the two environments
and allows JSF and Portal to be completely unaware of each other.
+ </para>
+ </formalpara>
+ <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 as the FacesServlet does in the direct client request environment.
+ </para>
+ <para>
+ The other part of this implementation is provided by implementating a variety of
(standard) <literal>Faces</literal> extensions.
+ </para>
+ <important>
+ <title>Disclaimer</title>
+ <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.
+ </para>
+ <para>
+ Publication of this draft specification is not intended to provide the basis for
implementations of the specification. This draft specification is provided AS IS.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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>
+ </important>
+ <!-- <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> -->
+</chapter>
+
+
Added: docs/enterprise/trunk/PortletBridge/en-US/portlet_development.xml
===================================================================
--- docs/enterprise/trunk/PortletBridge/en-US/portlet_development.xml
(rev 0)
+++ docs/enterprise/trunk/PortletBridge/en-US/portlet_development.xml 2010-07-15 20:28:08
UTC (rev 13964)
@@ -0,0 +1,337 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBoss_Portlet_Bridge_Overview.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="sect-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-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
<filename>faces-config.xml</filename>.
+ </para>
+ <para>
+ In the code sample below you can see that any attribute namespaced as
<literal>foo.bar</literal> or any attribute beginning with
<literal>foo.baz(wildcard)</literal> will be excluded from the bridge request
scope and only be used per that application's request.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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-Reference_Guide-Developing_Portlets_with_the_Bridge-Supporting_PortletMode_Changes">
+ <title>Supporting PortletMode Changes</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 \edit.jspx viewId in the portlet edit
mode:
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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-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 a mode left after entering
another mode (e.g.. view -> edit -> view) is to return to the last view (and
state) of this origin mode.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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
<parameter>X</parameter> return to the last view of mode
<parameter>Y</parameter>".
+ </para>
+ <para>
+ This is most easily expressed via an <literal>EL</literal> expression. For
example:
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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>
+ <section>
+ <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. In the above, for example, the
+ </para>
+
+<programlisting language="XML"
role="XML"><![CDATA[<to-view-id>
+]]></programlisting>
+ <para>
+ expression returns a <parameter>viewId</parameter> of the form
+ </para>
+
+<programlisting language="XML"
role="XML"><![CDATA[/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 <literal>edit.jspx</literal>
+ </para>
+
+<programlisting language="XML"
role="XML"><![CDATA[<from-view-id>
+]]></programlisting>
+ <para>
+ is wildcarded because there are navigation rules that target it that use a query
string:
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+<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>
+
+ <section
id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Clearing_The_View_History_When_Changing_Portlet_Modes">
+ <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 <filename>portlet.xml</filename> to use the default viewId
each time you switch modes.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <init-param>
+ <name>javax.portlet.faces.extension.resetModeViewId</name>
+ <value>true</value>
+ </init-param>
+]]></programlisting>
+ </section>
+
+ <section
id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-General_Error_Handling">
+ <title>General Error Handling</title>
+ <note>
+ <para>
+ If you are developing a <application>Seam</application> portlet you can
now use <filename>pages.xml</filename> 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 <literal>ViewExpiredExceptions</literal>.
+ </para>
+ <note>
+ <title>The Location Element</title>
+ <para>
+ The location element must contain the <filename>/faces/</filename>
mapping to work properly.
+ </para>
+ </note>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <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-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 language="XML" role="XML"><![CDATA[
+ <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 <filename>web.xml</filename>.
+ </para>
+
+<programlisting language="XML" role="XML"><![CDATA[
+ <context-param>
+ <param-name>org.ajax4jsf.handleViewExpiredOnClient</param-name>
+ <param-value>true</param-value>
+ </context-param>
+]]></programlisting>
+ <para>
+ 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>
+ </section>
+
+ <section
id="sect-Reference_Guide-Developing_Portlets_with_the_Bridge-Communication_Between_Your_Portlets">
+ <title>Communication Between Your Portlets</title>
+ <para>
+ There are four different ways to send messages, events, and parameters between
portlets which are contained in different <literal>ears/wars</literal> or
contained in the same <literal>war</literal>.
+ </para>
+ <para>
+ Having two portlets in the same <literal>war</literal> or having them
separated does not affect the Portlet Container because each portlet has a different
<parameter>HttpSession</parameter>.
+ </para>
+ <para>
+ The recommended way to share a parameter or event payload between two or more portlets
with the Portlet 2.0 specification are the <xref
linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Public_Render_Parameters"
/> and <xref
linkend="sect-Reference_Guide-Portlet_2.0_Coordination-Sending_and_Receiving_Events"
/> mechanisms.
+ </para>
+ <para>
+ This allows you to decouple your application from surgically managing objects in the
<parameter>PortletSession.APPLICATION_SCOPE.</parameter>
+ </para>
+ <para>
+ 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>
+ <para>
+ Sometimes it is beneficial to store your <application>Seam</application>
components in the portlet <parameter>APPLICATION_SCOPE</parameter>.
+ </para>
+ <para>
+ By default, these objects are stored in the
<parameter>PORTLET_SCOPE</parameter> but with the annotation below, this class
can be pulled out of the <literal>PortletSession</literal> and its values used
in other portlets across different <application>Seam</application>
applications.
+ </para>
+
+<programlisting language="XML" role="XML">
+ @PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE)
+</programlisting>
+ <para>
+ Then you would pull the statefull object from the session:
+ </para>
+
+<programlisting language="Java" role="JAVA"><![CDATA[
+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-Reference_Guide-Communication_Between_Your_Portlets-Using_the_PortletSession">
+ <title>Using the PortletSession</title>
+ <para>
+ If you need to access the <literal>PortletSession</literal> to simply
share a parameter or value across multiple portlets, you can use the following:
+ </para>
+
+<programlisting language="Java" role="JAVA"><![CDATA[
+ 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 language="XML" role="XML"><![CDATA[
+ #{httpSessionScope['your parameter name']}
+]]></programlisting>
+ <para>
+ <note>
+ <title>Note to Portlet Developers</title>
+ <para>
+ <literal>#{httpSessionScope}</literal> was implemented after
<literal>2.0.0.BETA</literal>. If you are using the
<literal>1.0</literal> bridge or pre
<literal>2.0.0.BETA</literal>, you must use the
<literal>EL</literal> variable
<literal>#{sessionApplicationScope}</literal>.
+ </para>
+ </note>
+ For more information about which <literal>EL</literal> 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-Reference_Guide-Developing_Portlets_with_the_Bridge-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 can use
the following.
+ </para>
+
+<programlisting language="Java" role="JAVA"><![CDATA[
+ <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-Reference_Guide-Developing_Portlets_with_the_Bridge-Redirecting_to_an_External_Page_or_Resource">
+ <title>Redirecting to an External Page or Resource</title>
+ <para>
+ To link to a non JSF view (that is,
jboss.org) you can use the following parameter.
+ </para>
+
+<programlisting language="Java" role="JAVA"><![CDATA[
+ <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
<parameter>redirect()</parameter>.
+ </para>
+
+<programlisting language="Java" role="JAVA"><![CDATA[
+
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>
+ <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:
+ </para>
+
+<programlisting language="XML" 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 language="Java" 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>
+
+ <!-- DO NOT UNCOMMENT!! 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> -->
+</chapter>