[portal-commits] JBoss Portal SVN: r11832 - docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules.

[portal-commits at lists.jboss.org]

Author: thomas.heute at jboss.com
Date: 2008-09-08 10:08:37 -0400 (Mon, 08 Sep 2008)
New Revision: 11832

Modified:
   docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml
Log:
Added some documentation

Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml	2008-09-08 13:04:48 UTC (rev 11831)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml	2008-09-08 14:08:37 UTC (rev 11832)
@@ -1118,7 +1118,78 @@
                <trademark class="trade">JSF</trademark>
                example using the JBoss Portlet Bridge
             </title>
-            <bridgehead>TODO.</bridgehead>
+            <bridgehead>In order to write a portlet using JSF we need a piece of software called 'bridge' that
+            lets us write a portlet application as if it was a JSF application, the bridge takes care of the
+            interactions between the two layers.</bridgehead>
+            <para>Such an example is available in examples/JSFHelloUser, it uses the JBoss Portlet Bridge.
+            The configuration is slightly different from a JSP application, since it is a bit tricky it is usally a good
+            idea to copy an existing application that starting from scratch.</para>
+            <para>First, as any JSF application, the file <literal>faces-config.xml</literal> is required. It includes
+            the following required information in it:
+            <programlisting 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>
+...
+</faces-config> ]]></programlisting>
+            The portlet bridge libraries must be available and are usually bundled with the <literal>WEB-INF/lib</literal>
+            directory of the web archive.</para>
+            <para>The other difference compare to a regular portlet application, can be found in the portlet
+            descriptor. All details about it can be found in the JSR-301 specification that the JBoss Portlet Bridge
+            implements.
+            <programlistingco>
+            <areaspec>
+               <area id="tutorials.jsf.portlet" coords="9"/>
+               <area id="tutorials.jsf.view" coords="21"/>
+               <area id="tutorials.jsf.edit" coords="26"/>
+               <area id="tutorials.jsf.help" coords="31"/>
+            </areaspec>
+            <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+   xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd 
+                                         http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
+   version="2.0">
+   <portlet>
+      <portlet-name>JSFHelloUserPortlet</portlet-name>
+      <portlet-class>javax.portlet.faces.GenericFacesPortlet</portlet-class>
+      <supports>
+         <mime-type>text/html</mime-type>
+         <portlet-mode>view</portlet-mode>
+         <portlet-mode>edit</portlet-mode>
+         <portlet-mode>help</portlet-mode>
+      </supports>
+      <portlet-info>
+         <title>JSF Hello User Portlet</title>
+      </portlet-info>
+      
+      <init-param>
+         <name>javax.portlet.faces.defaultViewId.view</name>
+         <value>/jsf/welcome.jsp</value>
+      </init-param>
+
+      <init-param>
+         <name>javax.portlet.faces.defaultViewId.edit</name>
+         <value>/jsf/edit.jsp</value>
+      </init-param>
+
+      <init-param>
+         <name>javax.portlet.faces.defaultViewId.help</name>
+         <value>/jsf/help.jsp</value>
+      </init-param>
+
+   </portlet>
+</portlet-app>]]></programlisting>
+            <calloutlist>
+               <callout arearefs="tutorials.jsf.portlet"><para>All JSF portlets define <literal>javax.portlet.faces.GenericFacesPortlet</literal>
+               as portlet class. This class is part of the JBoss Portlet Bridge</para></callout>
+               <callout arearefs="tutorials.jsf.view"><para>This is a mandatory parameter to define what's the default page to display.</para></callout>
+               <callout arearefs="tutorials.jsf.edit"><para>This parameter defines which page to display on the 'edit' mode.</para></callout>
+               <callout arearefs="tutorials.jsf.help"><para>This parameter defines which page to display on the 'help' mode.</para></callout>
+            </calloutlist>
+            </programlistingco>
          </sect3>
       </sect2>
    </sect1>