[gatein-commits] gatein SVN: r979 - in portal/trunk/docs/reference-guide/en: images/tutorials and 5 other directories.

Author: thomas.heute(a)jboss.com Date: 2009-12-09 07:27:57 -0500 (Wed, 09 Dec 2009) New Revision: 979 Added: portal/trunk/docs/reference-guide/en/images/tutorials/ portal/trunk/docs/reference-guide/en/images/tutorials/SpecPortalDef.png portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/ portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/deployed.png portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/output.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/ portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/exploded.gif portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_deploy.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_explode.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_deploy.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_explode.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/output.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_42x.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces42.png portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_sunri.png portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/ portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/output.png portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/process.png portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml Modified: portal/trunk/docs/reference-guide/en/modules/Portlets.xml Log: Adding the tutorial chapter form JBoss Portal (Will require new screenshots) Added: portal/trunk/docs/reference-guide/en/images/tutorials/SpecPortalDef.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/SpecPortalDef.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/deployed.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/deployed.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/output.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/first_portlet/output.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/exploded.gif =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/exploded.gif ___________________________________________________________________ Name: svn:executable + * Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_deploy.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_deploy.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_explode.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/jsf_ant_explode.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_deploy.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_deploy.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_explode.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/myfaces_ant_explode.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/output.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/output.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_42x.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_42x.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces42.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_myfaces42.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_sunri.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsf_portlet/package_sunri.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/output.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/output.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/process.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/tutorials/jsp_portlet/process.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: portal/trunk/docs/reference-guide/en/modules/Portlets.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Portlets.xml 2009-12-09 11:43:22 UTC (rev 978) +++ portal/trunk/docs/reference-guide/en/modules/Portlets.xml 2009-12-09 12:27:57 UTC (rev 979) @@ -6,7 +6,8 @@ <xi:include href="portlets/WebUI.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portlets/AJAX_in_GateIn_Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portlets/Groovy_Templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="portlets/Create_a_WebUI_Portlet.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portlets/Portlet_Lifecycle.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="portlets/Standard.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="portlets/Create_a_WebUI_Portlet.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Added: portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml (rev 0) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml 2009-12-09 12:27:57 UTC (rev 979) @@ -0,0 +1,1036 @@ +<?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"> +<section id="tutorials"> + <title>Portlet Primer</title> + <section id="portlet_primer"> + <title>JSR-168 and JSR-286 overview</title> + <para> + The Portlet Specifications aims at defining portlets that can + be used by any + <ulink url="http://www.jcp.org/en/jsr/detail?id=168"> + JSR-168 (Portlet 1.0) + </ulink> + or + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 (Portlet 2.0) + </ulink> + portlet container. Most Java EE portals include one, it is + obviously the case for + GateIn Portal which includes the GateIn + Portlet Container supporting the two + versions. This chapter + gives a brief overview of the Portlet Specifications but + portlet developers are strongly encouraged to read the + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 Portlet Specification + </ulink> + . + </para> + <para> + GateIn Portal is fully JSR-286 compliant, which means any + JSR-168 or JSR-286 + portlet behaves as it is mandated by the + respective specifications inside the + portal. + </para> + <section> + <title>Portal Pages</title> + <para> + A portal can be seen as pages with different areas, and + inside areas, + different windows, and each window having one + portlet: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/SpecPortalDef.png" + format="PNG" scalefit="1" /> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Rendering Modes</title> + <para> + A portlet can have different view modes. Three modes are + defined by the + JSR-286 specification: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>view</emphasis> + - generates markup reflecting the current state of + the portlet. + </para> + </listitem> + <listitem> + <para> + <emphasis>edit</emphasis> + - allows a user to customize the behavior of the + portlet. + </para> + </listitem> + <listitem> + <para> + <emphasis>help</emphasis> + - provides information to the user as to how to use + the portlet. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section> + <title>Window States</title> + <para> + Window states are an indicator of how much page + real-estate a portlet consumes + on any given page. The three + states defined by the JSR-168 specification are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>normal</emphasis> + - a portlet shares this page with other portlets. + </para> + </listitem> + <listitem> + <para> + <emphasis>minimized</emphasis> + -a portlet may show very little information, or + none at all. + </para> + </listitem> + <listitem> + <para> + <emphasis>maximized</emphasis> + - a portlet may be the only portlet displayed on + this page. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section id="tutorials_tutorials"> + <title>Tutorials</title> + <para> + The tutorials contained in this chapter are targeted toward + portlet developers. + Although they are a good starting and + reference point, it is highly recommend + that portlet developers + read and understand the + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 Portlet Specification + </ulink> + . + </para> + <section> + <title>Deploying your first Portlet</title> + <section> + <title>Introduction</title> + <para> + This section describes how to deploy a portlet in GateIn + Portal. You will + find the + <emphasis>SimplestHelloWorld</emphasis> + portlet in the + <literal>examples</literal> + directory at the root of your GateIn Portal binary + package. + </para> + </section> + <section> + <title>Compiling</title> + <para> + This example is using Maven to compile and build the web + archive. If you + don't have Maven already installed, you + will find a version for your + operating system + <ulink url="http://maven.apache.org/download.html">here</ulink> + </para> + <para> + To compile and package the application, go to the + SimplestHelloWorld + directory and type + <literal>mvn package</literal> + . + </para> + <para> + Once successfully packaged, the result should be + available in: + <literal>SimplestHelloWorld/target/SimplestHelloWorld-0.0.1.war + </literal> + . Simply copy that file into + <literal>JBOSS_HOME/server/default/deploy</literal> + , then start JBoss Application Server if it was not + already started. + </para> + <para> + Now you will need to create a new page and add that portlet on it. + </para> + <para> + <mediaobject> + <imageobject> + <objectinfo> + <title>SimplestHelloWorldPortlet deployed on a + new page</title> + </objectinfo> + <imagedata + fileref="images/tutorials/first_portlet/deployed.png" /> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title>Package Structure</title> + <bridgehead> + Now that we have seen how to deploy an existing + web application, let's have + a look inside. + </bridgehead> + <para> + Like other Java Platform, Enterprise Edition (Java EE) + applications, + portlets are packaged in WAR files. A + typical portlet WAR file can include + servlets, resource + bundles, images, HTML, + <trademark class="trade">JavaServer</trademark> + Pages ( + <trademark class="trade">JSP</trademark> + ), and other static or dynamic files. The following is an + example of the + directory structure of the + HelloWorldPortlet portlet: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.javaclass" coords='9' /> + <area id="tutorials.simplest.portlet" coords='10' /> + <area id="tutorials.simplest.web" coords='11' /> + </areaspec> + <programlisting><![CDATA[|-- SimplestHelloWorld-0.0.1.war +| `-- WEB-INF +| |-- classes +| | `-- org +| | `-- gatein +| | `-- portal +| | `-- examples +| | `-- portlets +| | `-- SimplestHelloWorldPortlet.class +| |-- portlet.xml +| `-- web.xml]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.javaclass"> + <para> + The compiled Java class implementing + <emphasis>javax.portlet.Portlet</emphasis> + (through + <emphasis>javax.portlet.GenericPortlet + </emphasis> + ) + </para> + </callout> + <callout arearefs="tutorials.simplest.portlet"> + <para> + This is the mandatory descriptor files for + portlets. It is used + during deployment.. + </para> + </callout> + <callout arearefs="tutorials.simplest.web"> + <para>This is the mandatory descriptor for web + applications.</para> + </callout> + </calloutlist> + </programlistingco> + </section> + + <section> + <title>Portlet Class</title> + <bridgehead>Let's study the Java class in detail. + </bridgehead> + <para> + The following file is the + <filename> + SimplestHelloWorldPortlet/src/main/java/org/gatein/portal/examples/portlets/SimplestHelloWorldPortlet.java + </filename> + Java source. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.extends" coords='10' /> + <area id="tutorials.simplest.doview" coords='13' /> + <area id="tutorials.simplest.writer" coords='15' /> + <area id="tutorials.simplest.write" coords='16' /> + <area id="tutorials.simplest.close" coords='17' /> + </areaspec> + <programlisting role="JAVA"><![CDATA[package org.gatein.portal.examples.portlets; + +import java.io.IOException; +import java.io.PrintWriter; + +import javax.portlet.GenericPortlet; +import javax.portlet.RenderRequest; +import javax.portlet.RenderResponse; + +public class SimplestHelloWorldPortlet extends GenericPortlet +{ + public void doView(RenderRequest request, + RenderResponse response) throws IOException + { + PrintWriter writer = response.getWriter(); + writer.write("Hello World !"); + writer.close(); + } +}]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.extends"> + <para> + All portlets must implement the + <literal>javax.portlet.Portlet</literal> + interface. The portlet API provides a convenient + implementation of + this interface, in the form of + the + <literal>javax.portlet.GenericPortlet</literal> + class, which among other things, implements the + <literal>Portlet render</literal> + method to dispatch to abstract mode-specific + methods to make it + easier to support the standard + portlet modes. As well, it provides + a default + implementation for the + <literal>processAction</literal> + , + <literal>init</literal> + and + <literal>destroy</literal> + methods. It is recommended to extend + <literal>GenericPortlet</literal> + for most cases. + </para> + </callout> + <callout arearefs="tutorials.simplest.doview"> + <para> + As we extend from + <literal>GenericPortlet</literal> + , and are only interested in supporting the + <literal>view</literal> + mode, only the + <literal>doView</literal> + method needs to be implemented, and the + <literal>GenericPortlet</literal> + <literal>render</literal> + implemention calls our implementation when the + <literal>view</literal> + mode is requested. + </para> + </callout> + <callout arearefs="tutorials.simplest.writer"> + <para> + Use the + <emphasis>RenderResponse</emphasis> + to obtain a writer to be used to produce + content. + </para> + </callout> + <callout arearefs="tutorials.simplest.write"> + <para>Write the markup to display.</para> + </callout> + <callout arearefs="tutorials.simplest.close"> + <para>Closing the writer.</para> + </callout> + </calloutlist> + </programlistingco> + <para> + <note> + <title>Markup Fragments</title> + <para> + Portlets are responsible for generating markup + fragments, as they are + included on a page and are + surrounded by other portlets. In + particular, this + means that a portlet outputting HTML must not + output + any markup that cannot be found in a + <literal>&lt;body&gt;</literal> + element. + </para> + </note> + </para> + </section> + <section id="first_portlet_descriptors"> + <title>Application Descriptors</title> + <para> + GateIn Portal requires certain descriptors to be + included in a portlet WAR + file. Thise descriptors are + defined by the Jave EE (web.xml) and Portlet + Specification (portlet.xml). + </para> + <para> + The following is an example of the + <filename>SimplestHelloWorldPortlet/WEB-INF/portlet.xml + </filename> + file. This file must adhere to its definition in the + JSR-286 Portlet + Specification. You may define more than + one portlet application in this + file: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.portletname" coords='8' /> + <area id="tutorials.simplest.portletclass" + coords='9' /> + <area id="tutorials.simplest.supports" coords='12' /> + <area id="tutorials.simplest.portletinfo" coords='15' /> + </areaspec> + <programlisting><![CDATA[ +<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... + http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> + <portlet> + <portlet-name>SimplestHelloWorldPortlet</portlet-name> + <portlet-class> + org.gatein.portal.examples.portlets.SimplestHelloWorldPortlet + </portlet-class> + <supports> + <mime-type>text/html</mime-type> + </supports> + <portlet-info> + <title>Simplest Hello World Portlet</title> + </portlet-info> + </portlet> +</portlet-app>]]> + </programlisting> + <calloutlist> + <callout arearefs="tutorials.simplest.portletname"> + <para> + Define the portlet name. It does not have to + be the class name. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletclass"> + <para> + The Fully Qualified Name (FQN) of your + portlet class must be + declared here. + </para> + </callout> + <callout arearefs="tutorials.simplest.supports"> + <para> + The + <computeroutput>&lt;supports&gt; + </computeroutput> + element declares all of the markup types that a + portlet supports + in the + <literal>render</literal> + method. This is accomplished via the + <computeroutput>&lt;mime-type&gt; + </computeroutput> + element, which is required for every portlet. + The declared MIME + types must match the capability + of the portlet. As well, it allows + you to pair + which modes and window states are supported for + each + markup type. All portlets must support the + <computeroutput>view</computeroutput> + portlet mode, so this does not have to be + declared. Use the + <computeroutput>&lt;mime-type&gt; + </computeroutput> + element to define which markup type your portlet + supports, which + in this example, is + <computeroutput>text/html</computeroutput> + . This section tells the portal that it only + outputs HTML. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletinfo"> + <para> + When rendered, the portlet's title is displayed + as the header in + the portlet window, unless it is + overridden programmatically. In + this example, the + title would be + <computeroutput>Simplest Hello World Portlet + </computeroutput> + . + </para> + </callout> + </calloutlist> + </programlistingco> + </section> + </section> + <section> + <title> + <trademark class="trade">JavaServer</trademark> + Pages Portlet Example + </title> + <section> + <title>Introduction</title> + <para> + Now we will add more features to the previous example and + also use a JSP + page to render the markup. We will use the + portlet tag library to generate + links to our portlet in + different ways and use the other standard portlet + modes. + This example can be found in the directory + <literal>JSPHelloUser</literal> + . + Use + <literal>mvn package</literal> + then copy + <filename>JSPHelloUser/target/JSPHelloUser-0.0.1.war + </filename> + in the + <literal>deploy</literal> + directory of JBoss Application Server. + Point your brwoser + to + <literal></literal> + , you should see the following: + <mediaobject> + <imageobject> + <imagedata + fileref="images/tutorials/jsp_portlet/output.png" + align="center" scalefit="1" /> + </imageobject> + </mediaobject> + <note> + <para> + The + <literal>EDIT</literal> + button only appears with logged-in users, which is + not the case + on the screenshot + </para> + </note> + </para> + </section> + <section> + <title>Package Structure</title> + <para> + The structure doesn't change much at the exception of + adding some JSP files + detailed later. + </para> + <para> + The JSPHelloUser portlet contains the mandatory + portlet application descriptors. + The following is an example of the + directory structure of + the JSPHelloUser portlet: + </para> + <programlisting><![CDATA[JSPHelloUser-0.0.1.war + |-- META-INF + | |-- MANIFEST.MF + |-- WEB-INF + | |-- classes + | | `-- org + | | `-- gatein + | | `-- portal + | | `-- examples + | | `-- portlets + | | `-- JSPHelloUserPortlet.class + | |-- portlet.xml + | `-- web.xml + `-- jsp + |-- edit.jsp + |-- hello.jsp + |-- help.jsp + `-- welcome.jsp]]> + </programlisting> + </section> + <section> + <title>Portlet Class</title> + <bridgehead>Let's study the Java class in detail. + </bridgehead> + <para> + The following file is the + <filename> + JSPHelloUser/src/main/java/org/gatein/portal/examples/portlets/JSPHelloUserPortlet.java + </filename> + Java source. It is split in different pieces. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.doView" coords='18' /> + <area id="tutorials.jsphello.renderParameter" + coords='21' /> + <area id="tutorials.jsphello.requestDispatcher" + coords='25' /> + <area id="tutorials.jsphello.include" coords='26' /> + </areaspec> + <programlisting role="JAVA"><![CDATA[package org.gatein.portal.examples.portlets; + +import java.io.IOException; + +import javax.portlet.ActionRequest; +import javax.portlet.ActionResponse; +import javax.portlet.GenericPortlet; +import javax.portlet.PortletException; +import javax.portlet.PortletRequestDispatcher; +import javax.portlet.RenderRequest; +import javax.portlet.RenderResponse; +import javax.portlet.UnavailableException; + +public class JSPHelloUserPortlet extends GenericPortlet +{ + + public void doView(RenderRequest request, RenderResponse response) + throws PortletException, IOException + { + String sYourName = (String) request.getParameter("yourname"); + if (sYourName != null) + { + request.setAttribute("yourname", sYourName); + PortletRequestDispatcher prd = + getPortletContext().getRequestDispatcher("/jsp/hello.jsp"); + prd.include(request, response); + } + else + { + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/welcome.jsp"); + prd.include(request, response); + } + } +...]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.doView"> + <para> + As in the first portlet, we override the + <emphasis>doView</emphasis> + method. + </para> + </callout> + <callout arearefs="tutorials.jsphello.renderParameter"> + <para> + Here we try to obtain the value of the render + parameter names + <literal>yourname</literal> + . If defined we want to redirect to the + <filename>hello.jsp</filename> + JSP page, otherwise to the + <filename>welcome.jsp</filename> + JSP page. + </para> + </callout> + <callout arearefs="tutorials.jsphello.requestDispatcher"> + <para> + Very similar to the Servlet way, we get a + request dispatcher on a + file located within the + web archive. + </para> + </callout> + <callout arearefs="tutorials.jsphello.include"> + <para> + The last step is to perform the inclusion of + the markup obtained + from the JSP. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + We have seen the + <literal>VIEW</literal> + portlet mode, the spec defines two other modes that can + be used called + <literal>EDIT</literal> + and + <literal>HELP</literal> + . In order to enable those modes, they will need to be + defined in the + <filename>portlet.xml</filename> + descriptor as we will see later. Having those modes + defined will enable the + corresponding buttons on the + portlet's window. + </para> + <para> + The generic portlet that is inherited dispatches the + different views to + methods named: + <literal>doView</literal> + , + <literal>doHelp</literal> + and + <literal>doEdit</literal> + . Let's watch the code for those two last portlet modes. + </para> + <programlisting role="JAVA"><![CDATA[... + protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, + UnavailableException + { + rResponse.setContentType("text/html"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/help.jsp"); + prd.include(rRequest, rResponse); + } + + protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, + UnavailableException + { + rResponse.setContentType("text/html"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/edit.jsp"); + prd.include(rRequest, rResponse); + } +...]]></programlisting> + + <para> + If you have read the portlet specification carefully + you should have notice + that portlet calls happen in one or + two phases. One when the portlet is + just rendered, two + when the portlet is actionned then rendered. An action + phase is a phase where some state change. The render + phase will have access + to render parameters that will be + passed each time the portlet is refreshed + (with the + exception of caching capabilities). + </para> + <para> + The code to be executed during an action has to be + implemented in the + <emphasis>processAction</emphasis> + method of the portlet. + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.processAction" + coords='2' /> + <area id="tutorials.jsphello.getActionParameter" + coords='5' /> + <area id="tutorials.jsphello.setRenderParameter" + coords='6' /> + </areaspec> + <programlisting role="JAVA"><![CDATA[... + public void processAction(ActionRequest aRequest, ActionResponse aResponse) throws PortletException, IOException, + UnavailableException + { + String sYourname = (String) aRequest.getParameter("yourname"); + aResponse.setRenderParameter("yourname", sYourname); + } +...]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.processAction"> + <para> + <literal>processAction</literal> + is the method from GernericPorlet to override + for the + <emphasis>action</emphasis> + phase. + </para> + </callout> + <callout arearefs="tutorials.jsphello.getActionParameter"> + <para> + Here we retrieve the parameter obtained through + an + <emphasis>action URL</emphasis> + . + </para> + </callout> + <callout arearefs="tutorials.jsphello.setRenderParameter"> + <para> + Here we need to keep the value of + <literal>yourname</literal> + to make it available in the rendering phase. + With the previous + line, we are simply copying an + action parameter to a render + parameter for the + sake of this example. + </para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section> + <title> + <trademark class="trade">JSP</trademark> + files and the Portlet Tag Library + </title> + <bridgehead>Let's have a look inside the JSP pages. + </bridgehead> + <para> + The + <filename>help.jsp</filename> + and + <filename>edit.jsp</filename> + files are very simple, they simply display some text. + Note that we used CSS + styles as defined in the portlet + specification. It ensures that the portlet + will look + "good" within the theme and accross portal vendors. + </para> + <programlisting role="XHTML"><![CDATA[<div class="portlet-section-header">Help mode</div> +<div class="portlet-section-body">This is the help mode, a convenient place to give the user some help information.</div>]]></programlisting> + <programlisting role="XHTML"><![CDATA[<div class="portlet-section-header">Edit mode</div> +<div class="portlet-section-body">This is the edit mode, a convenient place to let the user change his portlet preferences.</div>]]></programlisting> + <para> + Now let's have a look at the landing page, it contains + the links and form + to call our portlet: + </para> + <programlistingco> + <areaspec> + <area id="tutorials.jsphello.taglib" coords='1' /> + <area id="tutorials.jsphello.method1" coords='13' /> + <area id="tutorials.jsphello.method2.1" coords='20' /> + <area id="tutorials.jsphello.method2.2" coords='24' /> + <area id="tutorials.jsphello.method3.1" coords='30' /> + <area id="tutorials.jsphello.method3.2" coords='31' /> + </areaspec> + + <programlisting><![CDATA[<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> + +<div class="portlet-section-header">Welcome !</div> + +<br/> + +<div class="portlet-font">Welcome on the JSP Hello User portlet, +my name is GateIn Portal. What's yours ?</div> + +<br/> + +<div class="portlet-font">Method 1: We simply pass the parameter to the render phase:<br/> +<a href="<portlet:renderURL><portlet:param name="yourname" value="John Doe"/> + </portlet:renderURL>">John Doe</a></div> + +<br/> + +<div class="portlet-font">Method 2: We pass the parameter to the render phase, using valid XML: +Please check the source code to see the difference with Method 1. +<portlet:renderURL var="myRenderURL"> + <portlet:param name="yourname" value='John Doe'/> +</portlet:renderURL> +<br/> +<a href="<%= myRenderURL %>">John Doe</a></div> + +<br/> + +<div class="portlet-font">Method 3: We use a form:<br/> + +<portlet:actionURL var="myActionURL"/> +<form action="<%= myActionURL %>" method="POST"> + <span class="portlet-form-field-label">Name:</span> + <input class="portlet-form-input-field" type="text" name="yourname"/> + <input class="portlet-form-button" type="Submit"/> +</form> +</div>]]></programlisting> + <calloutlist> + <callout arearefs="tutorials.jsphello.taglib"> + <para> + Since we will use the portlet taglib, we + first need to declare it. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method1"> + <para> + The first method showed here is the simplest + one, + <literal>portlet:renderURL</literal> + will create a URL that will call the render + phase of the current + portlet and append the + result at the place of the markup (Here + within a + tag...). We also added a parameter directly on + the URL. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method2.1"> + <para> + In this method instead of having a tag within + another tag, which + is not XML valid, we use the + <literal>var</literal> + attribute. Instead of printing the url the + <literal>portlet:renderURL</literal> + tag will store the result in the referenced + variable ( + <literal>myRenderURL</literal> + in our case). + </para> + </callout> + <callout arearefs="tutorials.jsphello.method2.2"> + <para> + The variable + <literal>myRenderURL</literal> + is used like any other JSP variable. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method3.1"> + <para> + The third method mixes form submission and + action request. Like in + the second method, we + used a temporary variable to put the created + URL + into. + </para> + </callout> + <callout arearefs="tutorials.jsphello.method3.2"> + <para>The action URL is used in the HTML form. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + On the third method, first the action phase is triggered + then later in the request, the render + phase is triggered, + which output some content back to the web browser based + on the + available render parameters. + <mediaobject> + <imageobject> + <imagedata format="PNG" + fileref="images/tutorials/jsp_portlet/process.png" + scalefit="1" /> + </imageobject> + </mediaobject> + </para> + </section> + <section> + <title> + <trademark class="trade">JSF</trademark> + example using the JBoss Portlet Bridge + </title> + <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: + </para> + <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> + <para> + 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. + </para> + <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><![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... + 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> + </section> + </section> + </section> +</section>