Author: smumford Date: 2010-02-04 01:36:37 -0500 (Thu, 04 Feb 2010) New Revision: 1527 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml Log: further edits to Chapter 4 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml 2010-02-04 02:19:23 UTC (rev 1526) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml 2010-02-04 06:36:37 UTC (rev 1527) @@ -8,17 +8,29 @@ <section id="sect-Reference_Guide-Portlet_Primer-JSR_168_and_JSR_286_overview"> <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> . + The Java Community Process (<literal>JCP</literal>) uses Java Specification Requests (<literal>JSR</literal>s) to define proposed specifications and technologies designed for the Java platform. </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. + The Portlet Specifications aim 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. </para> + <para> + Most Java EE (Enterprise Edition) portals include at least one compliant portlet container, and &PRODUCT; is no exception. In fact, &PRODUCT; includes a container that supports both versions. + </para> + <para> + 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> + &PRODUCT; is fully JSR-286 compliant. Any JSR-168 or JSR-286 portlet operates as it is mandated by the respective specifications inside the portal. + </para> <section id="sect-Reference_Guide-JSR_168_and_JSR_286_overview-Portal_Pages"> <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: + A portal can be considered as a series of web pages with different <emphasis>areas</emphasis> within them. Those areas contain different <emphasis>windows</emphasis> and each <emphasis>window</emphasis> contains portlet: </para> <para> + The diagram below visually represents this nesting: + </para> + <para> <mediaobject> <imageobject> <imagedata fileref="images/tutorials/SpecPortalDef.png" format="PNG" scalefit="1" width="444" /> @@ -32,51 +44,65 @@ <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> + <variablelist> + <varlistentry> + <term>View</term> + <listitem> + <para> + Generates markup reflecting the current state of the portlet. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Edit</term> + <listitem> + <para> + Allows a user to customize the behavior of the portlet. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Help</term> + <listitem> + <para> + Provides information to the user as to how to use the portlet. + </para> + </listitem> + </varlistentry> + </variablelist> </section> <section id="sect-Reference_Guide-JSR_168_and_JSR_286_overview-Window_States"> <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: + Window states are an indicator of how much page space 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> + <variablelist> + <varlistentry> + <term>Normal</term> + <listitem> + <para> + A portlet shares this page with other portlets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Minimized</term> + <listitem> + <para> + A portlet may show very little information, or none at all. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Maximized</term> + <listitem> + <para> + A portlet may be the only portlet displayed on this page. + </para> + </listitem> + </varlistentry> + </variablelist> </section> </section> @@ -84,46 +110,71 @@ <section id="sect-Reference_Guide-Portlet_Primer-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> . + The tutorials contained in this chapter are targeted toward portlet developers. It is also recommend that developers read and understand the <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> JSR-286 Portlet Specification </ulink> . </para> + <note> + <title>Maven</title> + <para> + This example is using Maven to compile and build the web archive. Maven versions can be downloaded from <ulink url="http://maven.apache.org/download.html">maven.apache.org... + </para> + </note> + <section id="sect-Reference_Guide-Tutorials-Deploying_your_first_Portlet"> <title>Deploying your first Portlet</title> - <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Introduction"> - <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. + This section describes how to deploy a portlet in &PRODUCT;. A sample portlet called <filename>SimplestHelloWorld</filename> is located in the <literal>examples</literal> directory at the root of your &PRODUCT; binary package. This sample is used in the following examples. </para> - </section> - + <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Compiling"> <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> + To compile and package the application: </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 id="obje-Reference_Guide-Compiling-SimplestHelloWorldPortlet_deployed_on_a_new_page"><title>SimplestHelloWorldPortlet deployed on a new page</title> - </objectinfo><imagedata fileref="images/tutorials/first_portlet/deployed.png" format="PNG" width="444" /> - </imageobject> - </mediaobject> - </para> + <procedure> + <step> + <para> + Navigate to the <filename>SimplestHelloWorld</filename> directory and execute: + </para> +<programlisting>mvn package +</programlisting> + </step> + <step> + <para> + If the compile is successfully packaged the result will be available in: <filename>SimplestHelloWorld/target/SimplestHelloWorld-0.0.1.war </filename>. + </para> + </step> + <step> + <para> + Copy the package file into <literal>JBOSS_HOME/server/default/deploy</literal>. + </para> + </step> + <step> + <para> + Start JBoss Application Server (if it is not already running). + </para> + </step> + <step> + <para> + Create a new portal page and add the portlet to it. + </para> + <mediaobject> + <imageobject> + <objectinfo id="obje-Reference_Guide-Compiling-SimplestHelloWorldPortlet_deployed_on_a_new_page"><title>SimplestHelloWorldPortlet deployed on a new page</title> + </objectinfo><imagedata fileref="images/tutorials/first_portlet/deployed.png" format="PNG" width="444" /> + </imageobject> + </mediaobject> + </step> + </procedure> </section> <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Package_Structure"> <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: + Like other Java EE applications, &PRODUCT; portlets are packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles, images, HTML, JavaServer Pages (JSP), and other static or dynamic files. + </para> + <para> + The following is an example of the directory structure of the <filename>SimplestHelloWorld</filename> portlet: </para> <programlistingco> <areaspec> @@ -167,9 +218,8 @@ <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Portlet_Class"> <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. + Below is the <filename>SimplestHelloWorldPortlet/src/main/java/org/gatein/portal/examples/portlets/SimplestHelloWorldPortlet.java </filename> Java source: </para> <programlistingco> <areaspec> @@ -203,12 +253,18 @@ <calloutlist> <callout arearefs="area-Reference_Guide-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. + All portlets must implement the <literal>javax.portlet.Portlet</literal> interface. The portlet API provides a convenient implementation of this interface. </para> + <para> + The <literal>javax.portlet.Portlet</literal> interface uses the <literal>javax.portlet.GenericPortlet</literal> class which implements the <literal>Portlet render</literal> method to dispatch to abstract mode-specific methods. This makes it easier to support the standard portlet modes. + </para> + <para> + <literal>Portlet render</literal> also 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="area-Reference_Guide-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. + If only the <literal>view</literal> mode is required, then only the <literal>doView</literal> method needs to be implemented. The <literal>GenericPortlet</literal><literal>render</literal> implementation calls our implementation when the <literal>view</literal> mode is requested. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.simplest.writer"> @@ -233,7 +289,7 @@ <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. + Portlets are responsible for generating markup fragments, as they are included on a page and are surrounded by other portlets. 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> @@ -242,10 +298,10 @@ <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Application_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). + &PRODUCT; requires certain descriptors to be included in a portlet WAR file. These descriptors are defined by the Jave EE (<filename>web.xml</filename>) and Portlet Specification (<filename>portlet.xml</filename>). </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: + Below 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. More than one portlet application may be defined in this file: </para> <programlistingco> <areaspec> @@ -283,17 +339,26 @@ </callout> <callout arearefs="area-Reference_Guide-tutorials.simplest.portletclass"> <para> - The Fully Qualified Name (FQN) of your portlet class must be declared here. + The Fully Qualified Name (<literal>FQN</literal>) of your portlet class must be declared here. </para> </callout> <callout arearefs="area-Reference_Guide-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. + The <literal>&lt;supports&gt; </literal> element declares all of the markup types that a portlet supports in the <literal>render</literal> method. This is accomplished via the <literal>&lt;mime-type&gt; </literal> element, which is required for every portlet. </para> + <para> + The declared MIME types must match the capability of the portlet. It allows administrators to pair which modes and window states are supported for each markup type. + </para> + <para> + This does not have to be declared as all portlets must support the <literal>view</literal> portlet mode. + </para> + <para> + Use the <literal>&lt;mime-type&gt; </literal> element to define which markup type the portlet supports. In the example above this is <literal>text/html</literal>. This section tells the portal to only output HTML. + </para> </callout> <callout arearefs="area-Reference_Guide-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> . + When rendered, the portlet's title is displayed as the header in the portlet window, unless it is overridden programmatically. In the example above the title would be <literal>Simplest Hello World Portlet</literal> . </para> </callout> </calloutlist> @@ -304,11 +369,54 @@ </section> <section id="sect-Reference_Guide-Tutorials-_JavaServer_Pages_Portlet_Example_"> - <title><trademark class="trade">JavaServer</trademark> Pages Portlet Example </title> - <section id="sect-Reference_Guide-_JavaServer_Pages_Portlet_Example_-Introduction"> - <title>Introduction</title> + <title>JavaServer Pages Portlet Example</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: + This section discusses: + </para> + <orderedlist> + <listitem> + <para> + Adding more features to the previous example. + </para> + </listitem> + <listitem> + <para> + Using a JSP page to render the markup. + </para> + </listitem> + <listitem> + <para> + Using the portlet tag library to generate links to the portlet in different ways. + </para> + </listitem> + <listitem> + <para> + Using the other standard portlet modes. + </para> + </listitem> + </orderedlist> + <procedure> + <step> + <para> + The example used in this section can be found in the <literal>JSPHelloUser</literal> directory. + </para> + </step> + <step> + <para> + Execute <command>mvn package</command> in this directory. + </para> + </step> + <step> + <para> + Copy <filename>JSPHelloUser/target/JSPHelloUser-0.0.1.war </filename> to the <literal>deploy</literal> directory of JBoss Application Server. + </para> + </step> + <step> + <para> + Select the new <literal>JSPHelloUser</literal> tab in your portal. + </para> + </step> + </procedure> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsp_portlet/output.png" format="PNG" scalefit="1" width="444" /> @@ -316,16 +424,14 @@ </mediaobject> <note> <para> - The <literal>EDIT</literal> button only appears with logged-in users, which is not the case on the screenshot + The <literal>EDIT</literal> button only appears with logged-in users, which is not the case in the screenshot. </para> </note> - </para> - </section> <section id="sect-Reference_Guide-_JavaServer_Pages_Portlet_Example_-Package_Structure"> <title>Package Structure</title> <para> - The structure doesn't change much at the exception of adding some JSP files detailed later. + The package structure in this tutorial does not differ greatly from the previous example, with 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: @@ -354,9 +460,8 @@ <section id="sect-Reference_Guide-_JavaServer_Pages_Portlet_Example_-Portlet_Class"> <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. + The code below is from 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> @@ -404,31 +509,34 @@ <calloutlist> <callout arearefs="area-Reference_Guide-tutorials.jsphello.doView"> <para> - As in the first portlet, we override the <emphasis>doView</emphasis> method. + Override the <emphasis>doView</emphasis> method (as in the first tutorial). </para> </callout> <callout arearefs="area-Reference_Guide-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. + This entry attempts to obtain the value of the render parameter named <literal>yourname</literal>. If defined it should redirect to the <filename>hello.jsp</filename> JSP page, otherwise to the <filename>welcome.jsp</filename> JSP page. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.requestDispatcher"> <para> - Very similar to the Servlet way, we get a request dispatcher on a file located within the web archive. + Get a request dispatcher on a file located within the web archive. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.include"> <para> - The last step is to perform the inclusion of the markup obtained from the JSP. + 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. + As well as the <literal>VIEW</literal> portlet mode, the spec defines two other modes; <literal>EDIT</literal> and <literal>HELP</literal>. </para> <para> + These modes need to be defined in the <filename>portlet.xml</filename> descriptor. 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>