[gatein-commits] gatein SVN: r979 - in portal/trunk/docs/reference-guide/en: images/tutorials and 5 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Dec 9 07:27:57 EST 2009
Author: thomas.heute at 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><body></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_0.xsd
+ 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><supports>
+ </computeroutput>
+ element declares all of the markup types that a
+ portlet supports
+ in the
+ <literal>render</literal>
+ method. This is accomplished via the
+ <computeroutput><mime-type>
+ </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><mime-type>
+ </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_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>
+ </section>
+ </section>
+ </section>
+</section>
More information about the gatein-commits
mailing list