Author: thomas.heute(a)jboss.com Date: 2008-07-10 08:03:40 -0400 (Thu, 10 Jul 2008) New Revision: 11407 Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml Log: Sorry Murray, i use my version, it's just impossible to merge... Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml 2008-07-10 11:59:26 UTC (rev 11406) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml 2008-07-10 12:03:40 UTC (rev 11407) @@ -24,10 +24,10 @@ <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> JSR-286 (Portlet 2.0) </ulink> - portlet container. Most Java EE portals include a portlet container, it is - obvously the case for JBoss Portal which includes the JBoss Portlet container - supporting the two versions. This chapter gives a brief overview of the Portlet - Specifications. Portlet developers are strongly encouraged to read the + portlet container. Most Java EE portals include one, it is obviously the case for + JBoss Portal which includes the JBoss 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> @@ -47,7 +47,8 @@ <para> <mediaobject> <imageobject> - <imagedata fileref="images/tutorials/SpecPortalDef.png" scalefit="1" /> + <imagedata fileref="images/tutorials/SpecPortalDef.png" format="PNG" + scalefit="1" /> </imageobject> </mediaobject> </para> @@ -110,26 +111,17 @@ </itemizedlist> </para> </sect2> - <sect2> - <title>Section Status</title> - <para> - This overview of the JSR-168 Portlet Specification is a work in progress. - Check back for more in-depth analsis of the specification. The sections - following here after contain real-world cases for how to leverage the - specification. - </para> - </sect2> </sect1> <sect1 id="tutorials_tutorials"> <title>Tutorials</title> <para> - The tutorials contained in this chapter are targetted toward portlet developers. + 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> - . Use the + . Feel free to use the <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... JBoss Portal User Forums </ulink> @@ -140,19 +132,58 @@ <sect3> <title>Introduction</title> <para> - This section describes how to deploy a portlet in JBoss Portal. Before - proceeding, download the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles... - HelloWorldPortlet - </ulink> - from - <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink> + This section describes how to deploy a portlet in JBoss Portal. You will + find the + <emphasis>SimplestHelloWorld</emphasis> + portlet in the + <literal>examples</literal> + directory at the root of your JBoss Portal binary package. + </para> + </sect3> + <sect3> + <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> + You should now see a new page called + <literal>SimplestHelloWorld</literal> + , with a window inside containing the portlet instance we have created, as + seen below. + </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> </sect3> <sect3> <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 @@ -163,15 +194,15 @@ ), and other static or dynamic files. The following is an example of the directory structure of the HelloWorldPortlet portlet: </para> -<programlistingco> - <areaspec> - <area id="javaclass" coords='9' /> - <area id="defaultobject" coords='10' /> - <area id="portletinstances" coords='11' /> - <area id="portlet" coords='12' /> - <area id="web" coords='13' /> - </areaspec> - <programlisting><![CDATA[|-- SimplestHelloWorld-0.0.1.war + <programlistingco> + <areaspec> + <area id="tutorials.simplest.javaclass" coords='9' /> + <area id="tutorials.simplest.defaultobject" coords='10' /> + <area id="tutorials.simplest.portletinstances" coords='11' /> + <area id="tutorials.simplest.portlet" coords='12' /> + <area id="tutorials.simplest.web" coords='13' /> + </areaspec> + <programlisting><![CDATA[|-- SimplestHelloWorld-0.0.1.war | `-- WEB-INF | |-- classes | | `-- org @@ -184,54 +215,75 @@ | |-- portlet-instances.xml | |-- portlet.xml | `-- web.xml]]> - </programlisting> - <calloutlist> - <callout arearefs="javaclass"> - <para> - The compiled Java class implementing <emphasis>javax.portlet.Portlet</emphasis> (through <emphasis>javax.portlet.GenericPortlet</emphasis>) - </para> - </callout> - <callout arearefs="defaultobject"> - <para> - <emphasis>default-object.xml</emphasis> is an optional file, it is used to define the layout of the portal. It can be used to define the different portals, pages and windows. - The same result can be obtained through the administration portal. Note that the definition of the layout is stored in database, this file is then used to populate the database - during deployment which can be very useful during development. - </para> - </callout> - <callout arearefs="portletinstances"> - <para> - <emphasis>portlet-instances.xml</emphasis> is also optional, it allows to create a portlet instance from the SimpleHelloWorld portlet definition. Creating - instances can also be done through the administration portal. Note that the definition of instances is stored in database, this file is then used to populate the database - during deployment which can be very useful during development. - </para> - </callout> - <callout arearefs="portlet"> - <para>This is the mandatory descriptor files for portlets. It is used during deployment..</para> - </callout> - <callout arearefs="web"> - <para>This is the mandatory descriptor for web applications.</para> - </callout> - </calloutlist> - </programlistingco> - </sect3> + </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.defaultobject"> + <para> + <emphasis>default-object.xml</emphasis> + is an optional file, it is used to define the layout of the + portal. It can be used to define the different portals, pages and + windows. The same result can be obtained through the + administration portal. Note that the definition of the layout is + stored in database, this file is then used to populate the + database during deployment which can be very useful during + development. + </para> + </callout> + <callout arearefs="tutorials.simplest.portletinstances"> + <para> + <emphasis>portlet-instances.xml</emphasis> + is also optional, it allows to create a portlet instance from the + SimpleHelloWorld portlet definition. Creating instances can also + be done through the administration portal. Note that the + definition of instances is stored in database, this file is then + used to populate the database during deployment which can be very + useful during development. Having portlet-instances.xml and + default-object.xml included in this package ensures that the + portlet will appear directly on the portal by just deploying the + web application. + </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> + </sect3> + <sect3> - <title>Portlet Classes</title> + <title>Portlet Class</title> + <bridgehead>Let's study the Java class in detail.</bridgehead> <para> - The following is the + The following file is the <filename> SimplestHelloWorldPortlet/src/main/java/org/jboss/portal/portlet/samples/SimplestHelloWorldPortlet.java </filename> - Java source file, which comes bundled with your JBoss Portal download: + Java source. </para> - <programlistingco> - <areaspec> - <area id="extends" coords='10' /> - <area id="doview" coords='13' /> - <area id="writer" coords='15' /> - <area id="write" coords='16' /> - <area id="close" coords='17' /> - </areaspec> - <programlisting role="JAVA"><![CDATA[package org.jboss.portal.portlet.samples; + <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.jboss.portal.portlet.samples; import java.io.IOException; import java.io.PrintWriter; @@ -250,61 +302,61 @@ writer.close(); } }]]> - </programlisting> - <calloutlist> - <callout arearefs="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="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="writer"> - <para> - Use the - <emphasis>RenderResponse</emphasis> - to obtain a writer to be used to produce content. - </para> - </callout> - <callout arearefs="write"> - <para>Write the markup to display.</para> - </callout> - <callout arearefs="close"> - <para>Closing the writer.</para> - </callout> - </calloutlist> - </programlistingco> + </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> @@ -323,24 +375,24 @@ <title>Application Descriptors</title> <para> JBoss Portal requires certain descriptors to be included in a portlet WAR - file. Some of these descriptors are defined by the Portlet - Specification, and others are specific to JBoss Portal. + file. Some of these descriptors are defined by the Portlet Specification, + and others are specific to JBoss Portal. </para> - <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="portletname" coords='8' /> - <area id="portletclass" coords='9' /> - <area id="supports" coords='12' /> - <area id="portletinfo" coords='15' /> - </areaspec> - <programlisting><![CDATA[ + <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... @@ -361,58 +413,62 @@ </portlet-app>]]> </programlisting> <calloutlist> - <callout arearefs="portletname"> - <para>Define the portlet name. It does not have to be the class name.</para> - </callout> - <callout arearefs="portletclass"> - <para> - The Fully Qualified Name (FQN) of your portlet class must be - declared here. - </para> - </callout> - <callout arearefs="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="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>HelloWorld Portlet</computeroutput> - . - </para> - </callout> + <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> + </programlistingco> <para> The - <filename>HelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> + <filename> + SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> file is a JBoss Portal specific descriptor, that allows you to create instances of portlets. The <computeroutput>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</computeroutput> value given in the - <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> + <filename>SimplestHelloWorldPortlet/WEB-INF/portlet.xml</filename> file. The <computeroutput>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the @@ -425,10 +481,12 @@ </para> <para> The following is an example of the - <filename>SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> + <filename> + SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> file: </para> - <programlisting role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> + <programlisting role="XML"><![CDATA[<?xml version="1.0" standalone="yes"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portlet Instances 2.6//EN" "http://www.jboss.org/portlet/dtd/portlet-instances_2_6.dtd"> @@ -440,7 +498,7 @@ </instance> </deployment> </deployments>]]> - </programlisting> + </programlisting> <para> The <filename>*-object.xml</filename> @@ -456,14 +514,14 @@ <listitem> <para> specifies that the window displays the markup generated by the - <computeroutput>HelloWorldPortletInstance</computeroutput> + <computeroutput>SimplestHelloWorldInstance</computeroutput> portlet instance. </para> </listitem> <listitem> <para> - the window is assigned to the - <computeroutput>default.default</computeroutput> + the window is assigned to the page that we are creating and called + <computeroutput>SimplestHelloWorld</computeroutput> page. </para> </listitem> @@ -481,17 +539,17 @@ <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> file: </para> - <programlistingco> - <areaspec> - <area id="parentref" coords='7' /> - <area id="ifexists" coords='8' /> - <area id="windowname" coords='12' /> - <area id="instanceref" coords='13' /> - <area id="region" coords='14' /> - <area id="height" coords='15' /> - </areaspec> - <programlisting><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> + <programlistingco> + <areaspec> + <area id="tutorials.simplest.parentref" coords='7' /> + <area id="tutorials.simplest.ifexists" coords='8' /> + <area id="tutorials.simplest.pagename" coords='12' /> + <area id="tutorials.simplest.windowname" coords='12' /> + <area id="tutorials.simplest.instanceref" coords='13' /> + <area id="tutorials.simplest.region" coords='14' /> + <area id="tutorials.simplest.height" coords='15' /> + </areaspec> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> @@ -512,63 +570,70 @@ </deployments>]]> </programlisting> <calloutlist> - <callout arearefs="parentref"> - <para> - Tells the portal where this portlet appears. In this case, - <computeroutput>default.default</computeroutput> - specifies that the portlet appears in the portal instance named - <computeroutput>default</computeroutput> - , and on the page named - <computeroutput>default</computeroutput> - . - </para> + <callout arearefs="tutorials.simplest.parentref"> + <para> + Tells the portal where this portlet appears. In this case, + <computeroutput>default.default</computeroutput> + specifies that the portlet appears in the portal instance named + <computeroutput>default</computeroutput> + , and on the page named + <computeroutput>default</computeroutput> + . + </para> </callout> - <callout arearefs="ifexists"> - <para> - Instructs the portal to overwrite or keep this object if it - already exists. Accepted values are - <computeroutput>overwrite</computeroutput> - and - <computeroutput>keep</computeroutput> - . The - <computeroutput>overwrite</computeroutput> - option destroys the existing object, and creates a new one - based on the content of the deployment. The - <computeroutput>keep</computeroutput> - option maintains the existing object deployment, or creates a - new one if it does not exist. - </para> + <callout arearefs="tutorials.simplest.ifexists"> + <para> + Instructs the portal to overwrite or keep this object if it + already exists. Accepted values are + <computeroutput>overwrite</computeroutput> + and + <computeroutput>keep</computeroutput> + . The + <computeroutput>overwrite</computeroutput> + option destroys the existing object, and creates a new one based + on the content of the deployment. The + <computeroutput>keep</computeroutput> + option maintains the existing object deployment, or creates a new + one if it does not exist. + </para> </callout> - <callout arearefs="windowname"> - <para> - A - <emphasis role="bold">unique name</emphasis> - given to the portlet window. This can be named anything. - </para> + <callout arearefs="tutorials.simplest.pagename"> + <para> + Here we are creating a new page to put the new window on. We give + that new page a name that will be by default used on the tab of + the default theme. + </para> </callout> - <callout arearefs="instanceref"> - <para> - The value of - <computeroutput>&lt;instance-ref&gt;</computeroutput> - must match the value of one of the - <computeroutput>&lt;instance-id&gt;</computeroutput> - elements found in the - <filename> - HelloWorldPortlet/WEB-INF/portlet-instances.xml - </filename> - file. - </para> + <callout arearefs="tutorials.simplest.windowname"> + <para> + A + <emphasis role="bold">unique name</emphasis> + given to the portlet window. This can be named anything. + </para> </callout> - <callout arearefs="region"> - <para> - Specifies where the window appears within the page layout. - </para> + <callout arearefs="tutorials.simplest.instanceref"> + <para> + The value of + <computeroutput>&lt;instance-ref&gt;</computeroutput> + must match the value of one of the + <computeroutput>&lt;instance-id&gt;</computeroutput> + elements found in the + <filename> + HelloWorldPortlet/WEB-INF/portlet-instances.xml + </filename> + file. + </para> </callout> - <callout arearefs="height"> - <para> - Specifies where the window appears within the page layout. - </para> + <callout arearefs="tutorials.simplest.region"> + <para> + Specifies where the window appears within the page layout. + </para> </callout> + <callout arearefs="tutorials.simplest.height"> + <para> + Specifies where the window appears within the page layout. + </para> + </callout> </calloutlist> </programlistingco> <para> @@ -577,15 +642,15 @@ , <filename>portlet-instances.xml</filename> , and - <filename>helloworld-object.xml</filename> + <filename>default-object.xml</filename> descriptors: </para> <para> <mediaobject> <imageobject> - <imagedata align="center" - fileref="images/tutorials/first_portlet/desc_relationship.gif" - valign="middle" /> + <imagedata + fileref="images/tutorials/first_portlet/desc_relationship.png" + align="center" scalefit="1" /> </imageobject> </mediaobject> </para> @@ -602,8 +667,7 @@ following is an example deployment descriptor that uses the new content framework: </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> @@ -622,7 +686,7 @@ </window> </deployment> </deployments>]]> - </programlisting> + </programlisting> <para> This declaration is equivalent to the previous @@ -637,14 +701,14 @@ . The <computeroutput>&lt;content-uri&gt;</computeroutput> element specifies which content to display, which in this example, is the - <computeroutput>HelloWorldPortletInstance</computeroutput> + <computeroutput>SimplestHelloWorldInstance</computeroutput> : </para> - <programlisting role="XML"><![CDATA[<content> + <programlisting role="XML"><![CDATA[<content> <content-type>portlet</content-type> - <content-uri>HelloWorldPortletInstance</content-uri> + <content-uri>SimplestHelloWorldInstance</content-uri> </content>]]> - </programlisting> + </programlisting> <para> To display certain content or a file, use the <computeroutput>cms</computeroutput> @@ -653,285 +717,115 @@ element being the path to the file in the CMS. This behavior is pluggable: you can plug in almost any type of content. </para> + <note> + <title>Beware of context-path change</title> + <para> + If the context-path change the portal may not be able to find a + reference on your portlets anymore. For that reason it's recommended to + add the following descriptor + <literal>WEB-INF/jboss-portlet.xml</literal> + which is not mandatory: + </para> + <programlisting><![CDATA[<!DOCTYPE portlet-app PUBLIC + "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd"> + +<portlet-app> + <app-id>SimplestHelloWorld</app-id> +</portlet-app>]]></programlisting> + </note> </sect3> - <sect3 id="first_portlet_build"> - <title>Building your Portlet</title> - <para> - The - <filename>HelloWorldPortlet.zip</filename> - file contains a pre-compiled - <filename>helloworldportlet.war</filename> - file; however, to manually build the - <filename>helloworldportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> - <para> - Change into the - <filename>HelloWorldPortlet/</filename> - directory, and remove the existing - <filename>helloworldportlet.war</filename> - file. - </para> - </listitem> - <listitem> - <para> - If required, edit the - <filename> - HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java - </filename> - file, and the application descriptors in the - <filename> - HelloWorldPortlet/src/resources/helloworldportlet-war/WEB-INF/ - </filename> - directory. - </para> - </listitem> - <listitem> - <para> - Change into - <filename>HelloWorldPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. On Windows, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/first_portlet/building.gif" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - Expanding the - <filename>helloworldportlet.war</filename> - file allows you to deploy the portlet as an expanded directory, which makes - development easier. As well, it gives you access to the application - descriptors, resource files, JSF, and JSP pages. To expand the - <filename>helloworldportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> - <para> - If you do not have the - <filename>HelloWorldPortlet/helloworldportlet.war</filename> - file, change into the - <filename>HelloWorldPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. This creates the - <filename>helloworldportlet.war</filename> - file. - </para> - </listitem> - <listitem> - <para> - To expand the WAR file, change into the - <filename>HelloWorldPortlet/</filename> - directory, and run the - <command>ant explode</command> - command. On Windows, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/first_portlet/buildexplode.gif" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - The - <command>ant explode</command> - command creates a directory structure such as the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/first_portlet/exploded.gif" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - The expanded WAR file and the application descriptors are located in the - <filename> - HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/WEB-INF/ - </filename> - directory. - </para> - </sect3> - <sect3> - <title>Deploying your Portlet</title> - <para> - If you did not expand the - <filename>helloworldportlet.war</filename> - file, copy the - <filename>HelloWorldPortlet/helloworldportlet.war</filename> - file into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. If you expanded the - <filename>helloworldportlet.war</filename> - file, copy the - <filename> - HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/ - </filename> - directory into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. For example, if you are using the - <computeroutput>default</computeroutput> - JBoss AS profile, copy the WAR file or the expanded directory into the - <filename>$JBOSS_HOME/server/default/deploy/</filename> - directory. - </para> - <para> - Performing this step on a running instance of JBoss AS or JBoss EAP, and - JBoss Portal, triggers a hot-deploy of the portlet: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldportlet, -warUrl=.../tmp/deploy/tmp35219helloworldportlet-exp.war/]]></screen> - </para> - <para> - To see the HelloWorldPortlet, navigate to - <ulink url="http://localhost:8080/portal/"> - http://localhost:8080/portal/ - </ulink> - , or, if the default JBoss Portal page is already open, refresh the page. - The HelloWorldPortlet is added to the bottom of the default JBoss Portal - page: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/first_portlet/output.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To re-deploy the portlet, for example, if you have made changes to any of - the application descriptors, touch the - <filename> - $JBOSS_HOME/server/ - <replaceable>configuration</replaceable> - /deploy/helloworldportlet.war/WEB-INF/web.xml - </filename> - file. This only works if you copied the - <filename> - HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/ - </filename> - directory into the JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. On Linux, run the <command>touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldportlet.war/WEB-INF/web.xml</command> command to re-deploy the HelloWorldPortlet. - </para> - <para> - Re-deploying the HelloWorldPortlet produces output to the JBoss AS or JBoss - EAP console, similar to the following: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] undeploy, ctxPath=/helloworldportlet, -warUrl=.../deploy/helloworldportlet.war/ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldportlet, -warUrl=.../deploy/helloworldportlet.war/]]> - </screen> - </para> - </sect3> </sect2> <sect2> <title> - An example - <trademark class="trade">JavaServer</trademark> - Pages ( - <trademark class="trade">JSP</trademark> - ) portlet + <trademark class="trade">JavaServer</trademark> + Pages Portlet Example </title> <sect3> <title>Introduction</title> <para> - This section describes how to deploy a - <trademark class="trade">JSP</trademark> - portlet in JBoss Portal. Before proceeding, download the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - HelloWorldJSPPortlet - </ulink> - from - <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink> - . The HelloWorldJSPPortlet demonstrates how to use JSP pages for view - rendering, and the portlet tag library (taglib) for generating links. + 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> </sect3> <sect3> <title>Package Structure</title> <para> - The application descriptors for the HelloWorldJSPPortlet portlet are - similar to those from the HelloWorldPortlet ( - <xref linkend="first_portlet_descriptors" /> - ). Refer to - <xref linkend="descriptors_portlet" /> - for further information about application descriptors. + The structure doesn't change much at the exception of adding some JSP files + detailed later. </para> <para> - The HelloWorldJSPPortlet portlet contains the traditional portlet and JBoss - Portal specific application descriptors. The following is an example of the - directory structure of the HelloWorldJSPPortlet portlet: + The JSPHelloUser portlet contains the traditional portlet and JBoss Portal + specific application descriptors. The following is an example of the + directory structure of the JSPHelloUser portlet: </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/package.gif" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To create the - <filename>WEB-INF/</filename> - and - <filename>META-INF/</filename> - directories, extract the - <filename>helloworldjspportlet.war</filename> - file. - </para> + <programlisting><![CDATA[JSPHelloUser-0.0.1.war + |-- META-INF + | |-- MANIFEST.MF + | `-- maven + | `-- org.jboss.portal.example + | `-- JSPHelloUser + | |-- pom.properties + | `-- pom.xml + |-- WEB-INF + | |-- classes + | | `-- org + | | `-- jboss + | | `-- portal + | | `-- portlet + | | `-- samples + | | `-- JSPHelloUserPortlet.class + | |-- default-object.xml + | |-- jboss-portlet.xml + | |-- portlet-instances.xml + | |-- portlet.xml + | `-- web.xml + `-- jsp + |-- edit.jsp + |-- hello.jsp + |-- help.jsp + `-- welcome.jsp]]> + </programlisting> </sect3> <sect3> - <title>Portlet Classes</title> + <title>Portlet Class</title> + <bridgehead>Let's study the Java class in detail.</bridgehead> <para> - The - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - HelloWorldJSPPortlet - </ulink> - contains the + The following file is the <filename> - HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/HelloWorldJSPPortlet.java + JSPHelloUser/src/main/java/org/jboss/portal/portlet/samples/JSPHelloUserPortlet.java </filename> - file: + Java source. It is split in different pieces. </para> - <programlisting role="JAVA"><![CDATA[ -package org.jboss.portlet.hello; + <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.jboss.portal.portlet.samples; +package org.jboss.portal.portlet.samples; +import java.io.IOException; + import javax.portlet.ActionRequest; import javax.portlet.ActionResponse; import javax.portlet.GenericPortlet; @@ -940,1615 +834,284 @@ import javax.portlet.RenderRequest; import javax.portlet.RenderResponse; import javax.portlet.UnavailableException; -import java.io.IOException; -public class HelloWorldJSPPortlet extends GenericPortlet +public class JSPHelloUserPortlet extends GenericPortlet { - protected void doView(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException + + public void doView(RenderRequest request, RenderResponse response) + throws PortletException, IOException { - rResponse.setContentType("text/html"); - - String sYourName = (String) rRequest.getParameter("yourname"); - - if(sYourName != null) + String sYourName = (String) request.getParameter("yourname"); + if (sYourName != null) { - rRequest.setAttribute("yourname", sYourName); - PortletRequestDispatcher prd = getPortletContext() - .getRequestDispatcher("/WEB-INF/jsp/view2.jsp"); - prd.include(rRequest, rResponse); + request.setAttribute("yourname", sYourName); + PortletRequestDispatcher prd = + getPortletContext().getRequestDispatcher("/jsp/hello.jsp"); + prd.include(request, response); } else { - PortletRequestDispatcher prd = getPortletContext() - .getRequestDispatcher("/WEB-INF/jsp/view.jsp"); - prd.include(rRequest, rResponse); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/welcome.jsp"); + prd.include(request, response); } } - - public void processAction(ActionRequest aRequest, ActionResponse aResponse) - throws PortletException, IOException, UnavailableException +...]]></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 { - String sYourname = (String) aRequest.getParameter("yourname"); - - // do something - - aResponse.setRenderParameter("yourname", sYourname); - } - - protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException - { rResponse.setContentType("text/html"); - PortletRequestDispatcher prd = getPortletContext() - .getRequestDispatcher("/WEB-INF/jsp/help.jsp"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/help.jsp"); prd.include(rRequest, rResponse); } - protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException + protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, + UnavailableException { rResponse.setContentType("text/html"); - PortletRequestDispatcher prd = getPortletContext() - .getRequestDispatcher("/WEB-INF/jsp/edit.jsp"); + PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/edit.jsp"); prd.include(rRequest, rResponse); } -}]]> - </programlisting> - <para> - <variablelist> - <varlistentry> - <term> - <programlisting><![CDATA[ -protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException]]> - </programlisting> - <programlisting><![CDATA[ -protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException]]> - </programlisting> - </term> - <listitem> - <para> - Support for these modes must be declared in the - <filename>HelloWorldJSPPortlet/WEB-INF/portlet.xml</filename> - file. They are triggered when a user clicks on the respective - icons in the portlet window titlebar, or through generated - links within the portlet. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -public void processAction(ActionRequest aRequest, ActionResponse aResponse) - throws PortletException, IOException, UnavailableException -{ - String sYourname = (String) aRequest.getParameter("yourname"); +...]]></programlisting> - // do something - - aResponse.setRenderParameter("yourname", sYourname); -}]]></programlisting> - </term> - <listitem> - <para> - This method is triggered when a user clicks on an - <computeroutput>actionURL</computeroutput> - , which is defined in the - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> - file. This retrieves - <computeroutput>yourname</computeroutput> - from the HTML form, and passes it as a - <computeroutput>aResponse.setRenderParameter</computeroutput> - to the - <literal>doView()</literal> - method. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -rResponse.setContentType("text/html");]]> - </programlisting> - </term> - <listitem> - <para> - As in the servlet world, you must declare what content-type the - portlet will be responding in. Do this before starting to write - content, or the portlet throws an exception. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -protected void doView(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException]]> - </programlisting> - </term> - <listitem> - <para> - The - <literal>doView</literal> - implementation is responsible for dispatching to the - appropriate JSP, - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> - or - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp</filename> - , depending on the existence of the - <literal>yourname</literal> - parameter passed in from - <literal>processAction</literal> - . - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect3> - <sect3> - <title> - <trademark class="trade">JSP</trademark> - files and the Portlet Tag Library - </title> <para> - The - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> - and - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp</filename> - <trademark class="trade">JSP</trademark> - files are included in the HelloWorldJSPPortlet portlet. The - <filename>view.jsp</filename> - file allows a user to input their name. This is then posted to the - <computeroutput>processAction</computeroutput> - method in the portlet class, which is set as a - <computeroutput>aResponse.setRenderParameter</computeroutput> - . The - <computeroutput>doView</computeroutput> - <literal>render</literal> - method is invoked, which dispatches to the - <filename>view2.jsp</filename> - JSP: + 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> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/process.gif" - valign="middle" /> - </imageobject> - </mediaobject> + The code to be executed during an action has to be implemented in the + <emphasis>processAction</emphasis> + method of the portlet. </para> - <para> - The following is an example of the - <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> - file: - </para> - <programlisting><![CDATA[ -<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> - -<portlet:defineObjects/> - -<div align="center"> - This is a simple HelloWorld JSP Portlet. Type in a name and it will dispatch - to the view2.jsp to print out your name. - <br/> - - <form action="<portlet:actionURL><portlet:param name="page" value="mainview"/> - </portlet:actionURL>" method="POST"> - Name:<br/> - <input type="text" name="yourname"/> - </form> - <br/> - You can also link to other pages, using a renderURL, like <a - href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo"> - </portlet:param></portlet:renderURL>">this</a>. -</div>]]></programlisting> - <para> - <variablelist> - <varlistentry> - <term> - <programlisting><![CDATA[ -<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>]]> -</programlisting> - </term> - <listitem> - <para> - Define the portlet taglib. You do not need to bundle the - portlet taglib - JBoss Portal handles this for you. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> -<programlisting><![CDATA[ -<portlet:defineObjects/>]]> -</programlisting> - </term> - <listitem> - <para> - Calling - <literal>defineObjects</literal> - makes available implicit objects in the JSP, such as - <literal>renderRequest</literal> - , - <literal>actionRequest</literal> - , and - <literal>portletConfig</literal> - . - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<form action="<portlet:actionURL><portlet:param name="page" value="mainview"/> - </portlet:actionURL>" method="POST">]]> -</programlisting> - </term> - <listitem> - <para> - A HTML form is created. This form posts to the URL defined by - the portlet taglib. In this example, an - <computeroutput>actionURL</computeroutput> - is created, that activates the - <literal>processAction</literal> - method, which passes the input parameters from the form. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<a href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo"> -</portlet:param></portlet:renderURL>">]]> -</programlisting> - </term> - <listitem> - <para> - You can create a link to the - <computeroutput>doView</computeroutput> - method by creating a - <computeroutput>renderURL</computeroutput> - , which passes the - <computeroutput>yourname</computeroutput> - parameter. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect3> - <sect3> - <title> - Building your - <trademark class="trade">JSP</trademark> - portlet - </title> - <para> - The - <filename>HelloWorldJSPPortlet.zip</filename> - file contains a pre-compiled - <filename>helloworldjspportlet.war</filename> - file; however, to manually build the - <filename>helloworldjspportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> + <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> - Change into the - <filename>HelloWorldJSPPortlet/</filename> - directory, and remove the existing - <filename>helloworldjspportlet.war</filename> - file. + <literal>processAction</literal> + is the method from GernericPorlet to override for the + <emphasis>action</emphasis> + phase. </para> - </listitem> - <listitem> + </callout> + <callout arearefs="tutorials.jsphello.getActionParameter"> <para> - If required, edit the - <filename> - HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/HelloWorldJSPPortlet.java - </filename> - file, and the application descriptors in the - <filename> - HelloWorldJSPPortlet/src/resources/helloworldjspportlet-war/WEB-INF/ - </filename> - directory. + Here we retrieve the parameter obtained through an + <emphasis>action URL</emphasis> + . </para> - </listitem> - <listitem> + </callout> + <callout arearefs="tutorials.jsphello.setRenderParameter"> <para> - Change into - <filename>HelloWorldJSPPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. On Linux, the output will be similar to the following: + 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> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/jsp_ant_deploy.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - Expanding the - <filename>helloworldjspportlet.war</filename> - file allows you to deploy the portlet as an expanded directory, which makes - development easier. As well, it gives you access to the application - descriptors, resource files, JSF, and - <trademark class="trade">JSP</trademark> - pages. To expand the - <filename>helloworldjspportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> - <para> - If you do not have the - <filename>HelloWorldJSPPortlet/helloworldjspportlet.war</filename> - file, change into the - <filename>HelloWorldJSPPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. This creates the - <filename>helloworldjspportlet.war</filename> - file. - </para> - </listitem> - <listitem> - <para> - To expand the WAR file, change into the - <filename>HelloWorldJSPPortlet/</filename> - directory, and run the - <command>ant explode</command> - command. On Linux, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/jsp_ant_explode.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - The - <command>ant explode</command> - command creates a directory structure such as the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/exploded.gif" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - The expanded WAR file and the application descriptors are located in the - <filename> - HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/WEB-INF/ - </filename> - directory. - </para> + </callout> + </calloutlist> + </programlistingco> </sect3> <sect3> <title> - Deploying your <trademark class="trade">JSP</trademark> - portlet + files and the Portlet Tag Library </title> + <bridgehead>Let's have a look inside the JSP pages.</bridgehead> <para> - If you did not expand the - <filename>helloworldjspportlet.war</filename> - file, copy the - <filename>HelloWorldJSPPortlet/helloworldjspportlet.war</filename> - file into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. If you expanded the - <filename>helloworldjspportlet.war</filename> - file, copy the - <filename> - HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/ - </filename> - directory into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. For example, if you are using the - <computeroutput>default</computeroutput> - JBoss AS profile, copy the WAR file or the expanded directory into the - <filename>$JBOSS_HOME/server/default/deploy/</filename> - directory. - </para> - <para> - Performing this step on a running instance of JBoss AS or JBoss EAP, and - JBoss Portal, triggers a hot-deploy of the portlet: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet, -warUrl=.../deploy/helloworldjspportlet.war/]]> - </screen> - </para> - <para> - To see the HelloWorldJSPPortlet, navigate to - <ulink url="http://localhost:8080/portal/"></ulink> - , or, if the default JBoss Portal page is already open, refresh the page. - The HelloWorldJSPPortlet is added to the bottom of the default JBoss Portal - page: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsp_portlet/output.png" valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To re-deploy the portlet, for example, if you have made changes to any of - the application descriptors, touch the - <filename> - $JBOSS_HOME/server/ - <replaceable>configuration</replaceable> - /deploy/helloworldjspportlet.war/WEB-INF/web.xml - </filename> - file. This only works if you copied the - <filename> - HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/ - </filename> - directory into the JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. On Linux, run the <command>touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjspportlet.war/WEB-INF/web.xml</command> command to re-deploy the HelloWorldJSPPortlet. - </para> - <para> - Re-deploying the HelloWorldJSPPortlet produces output to the JBoss AS or - JBoss EAP console, similar to the following: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] undeploy, ctxPath=/helloworldjspportlet, -warUrl=.../deploy/helloworldjspportlet.war/ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet, -warUrl=.../deploy/helloworldjspportlet.war/]]> - </screen> - </para> - </sect3> - </sect2> - <sect2 id="sunri_42x"> - <title> - An example - <trademark class="trade">Sun</trademark> - JSF Reference Implementation (RI) portlet - </title> - <sect3> - <title>Introduction</title> - <para> - This section describes how to deploy a JSF portlet in JBoss Portal, using - the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Before - proceeding, download the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles... - HelloWorldJSFSunRIPortlet - </ulink> - from - <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink> - . - </para> - </sect3> - <sect3> - <title>Package Structure</title> - <para> - JBoss Portal requires certain descriptors to be included in a portlet WAR - file. Some of these descriptors are defined by the JSR-168 Portlet - Specification, and others are specific to JBoss Portal. Like a typical JSF - application, the HelloWorldJSFSunRIPortlet package contains a - <filename>faces-config.xml</filename> - file that defines managed-beans, converters, validators, navigation rules, - and so on. The following is an example of the directory structure of the - HelloWorldJSFSunRIPortlet portlet: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/package_sunri.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To create the - <filename>WEB-INF/</filename> + The + <filename>help.jsp</filename> and - <filename>META-INF/</filename> - directories, extract the - <filename>helloworldjsfsunriportlet.war</filename> - file. + <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> - <note> - <title> - Bundled - <trademark class="trade">Sun</trademark> - JSF RI - </title> - <para> - JBoss AS version 4.2. - <replaceable>x</replaceable> - and JBoss EAP bundle the - <trademark class="trade">Sun</trademark> - JSF RI libraries in the - <filename> - $JBOSS_HOME/server/default/deploy/jboss-web.deployer/jsf-libs/ - </filename> - directory. Therefore, you do not need to package the Sun JSF RI - libraries with your portlet application. - </para> - </note> + Now let's have a look at the landing page, it contains the links and form + to call our portlet. </para> - </sect3> - <sect3> - <title>Application Descriptors</title> - <para> - Only the - <filename>portlet.xml</filename> - , - <filename>faces-config.xml</filename> - , and - <filename>web.xml</filename> - descriptors are described here. For more information about application - descriptors, refer to - <xref linkend="first_portlet_descriptors" /> - and - <xref linkend="descriptors_portlet" /> - . - </para> - <para> - The following is an example of the - <filename>HelloWorldJSFSunRIPortlet/WEB-INF/portlet.xml</filename> - file. This file must adhere to its definition in the JSR-168 Portlet - Specification. You may define more than one portlet application in this - file: - </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... - http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - version="1.0"> - <portlet> - <portlet-name>HelloWorldJSFPortlet</portlet-name> - <portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class> - <init-param> - <name>com.sun.faces.portlet.INIT_VIEW</name> - <value>/WEB-INF/jsp/index.jsp</value> - </init-param> - <supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> - </supports> - <portlet-info> - <title>HelloWorld JSF Portlet</title> - </portlet-info> - </portlet> -</portlet-app>]]> - </programlisting> - <para> - <variablelist> - <varlistentry> - <term> - <programlisting><![CDATA[ -<portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class>]]> -</programlisting> - </term> - <listitem> - <para> - This specifies that the - <computeroutput> - com.sun.faces.portlet.FacesPortlet - </computeroutput> - handles all requests and responses from the users. This class - is part of the - <filename> - HelloWorldJSFSunRIPortlet/WEB-INF/lib/jsf-portlet.jar - </filename> - file. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<init-param> - <name>com.sun.faces.portlet.INIT_VIEW</name> - <value>/WEB-INF/jsp/index.jsp</value> -</init-param>]]> -</programlisting> - </term> - <listitem> - <para> - You must initialize the portlet with a default page to render, - similar to a welcome page. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> -</supports>]]></programlisting> - </term> - <listitem> - <para> - The - <computeroutput>&lt;supports&gt;</computeroutput> - element allows you to declare 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 text and - HTML, and that it only supports the - <computeroutput>view</computeroutput> - mode. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - The following is an example - <filename>HelloWorldJSFSunRIPortlet/WEB-INF/faces-config.xml</filename> - file: - </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0"?> -<!DOCTYPE faces-config PUBLIC - "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" - "http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> -<faces-config> - <managed-bean> - <description>Basic UserBean</description> - <managed-bean-name>user</managed-bean-name> - <managed-bean-class>org.jboss.portlet.hello.bean.User</managed-bean-class> - <managed-bean-scope>session</managed-bean-scope> - </managed-bean> - - <navigation-rule> - <navigation-case> - <from-outcome>done</from-outcome> - <to-view-id>/WEB-INF/jsp/result.jsp</to-view-id> - </navigation-case> - </navigation-rule> -</faces-config>]]> - </programlisting> - <para> - Without the - <filename>faces-config.xml</filename> - file, the application would work the same outside of the portlet as it - would inside a portlet container. In this example, a basic user bean, - <computeroutput> - &lt;managed-bean-name&gt;user&lt;/managed-bean-name&gt; - </computeroutput> - , and a navigation rule are defined, which handle the submission of the - original form in the - <filename>HelloWorldJSFSunRIPortlet/WEB-INF/jsp/index.jsp</filename> - file. - </para> - <para> - The following is an example of the - <computeroutput>Faces Servlet</computeroutput> - and - <computeroutput>Faces Servlet Mapping</computeroutput> - sections from the - <filename>HelloWorldJSFSunRIPortlet/WEB-INF/web.xml</filename> - file: - </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0"?> -<!DOCTYPE web-app PUBLIC - "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" - "http://java.sun.com/dtd/web-app_2_3.dtd"> -<web-app> + <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> - <!-- Faces Servlet --> - <servlet> - <servlet-name>Faces Servlet</servlet-name> - <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> - <load-on-startup>1</load-on-startup> - </servlet> + <programlisting role="JSP"><![CDATA[<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> +<div class="portlet-section-header">Welcome !</div> - <!-- Faces Servlet Mapping --> - <servlet-mapping> - <servlet-name>Faces Servlet</servlet-name> - <url-pattern>*.jsf</url-pattern> - </servlet-mapping> +<br/> -</web-app>]]> - </programlisting> - <para> - For Sun JSF RI portlets, the - <computeroutput>Faces Servlet</computeroutput> - and - <computeroutput>Faces Servlet Mapping</computeroutput> - sections are required to associate files with the - <filename>.jsf</filename> - extension to the Apache MyFaces servlet. - </para> - <para> - <warning> - <title>Classes for the JSF-Portlet bridge are not included</title> - <para> - Unlike Apache MyFaces, the classes for the JSF-Portlet bridge are not - included in the JSF implementation, JBoss AS, or JBoss EAP. This - library must be available in your application package. Navigate to - the - <ulink - url="https://jsfportletbridge.dev.java.net/servlets/ProjectDocumentL... - JSF-Portlet bridge webpage - </ulink> - to download the JSF-Portlet bridge library. - </para> - </warning> - </para> - </sect3> - <sect3> - <title>Building your JSF portlet</title> - <para> - The - <filename>HelloWorldJSFSunRIPortlet.zip</filename> - file contains a pre-compiled - <filename>helloworldjsfsunriportlet.war</filename> - file; however, to manually build the - <filename>helloworldjsfsunriportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> +<div class="portlet-font">Welcome on the JSP Hello User portlet, +my name is JBoss 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> - Change into the - <filename>HelloWorldJSFSunRIPortlet/</filename> - directory, and remove the existing - <filename>helloworldjsfsunriportlet.war</filename> - file. + Since we will use the portlet taglib, we first need to declare it. </para> - </listitem> - <listitem> + </callout> + <callout arearefs="tutorials.jsphello.method1"> <para> - If required, edit the - <filename> - HelloWorldJSFSunRIPortlet/src/main/org/jboss/portlet/hello/bean/User.java - </filename> - file, and the application descriptors in the - <filename> - HelloWorldJSFSunRIPortlet/src/resources/helloworldjsfsunriportlet-war/WEB-INF/ - </filename> - directory. + 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> - </listitem> - <listitem> + </callout> + <callout arearefs="tutorials.jsphello.method2.1"> <para> - Change into - <filename>HelloWorldJSFSunRIPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. On Linux, the output will be similar to the following: + 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> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/jsf_ant_deploy.png" - valign="middle" /> - </imageobject> - </mediaobject> + The variable + <literal>myRenderURL</literal> + is used like any other JSP variable. </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - Expanding the - <filename>helloworldjsfsunriportlet.war</filename> - file allows you to deploy the portlet as an expanded directory, which makes - development easier. As well, it gives you access to the application - descriptors, resource files, JSF, and JSP pages. To expand the - <filename>helloworldjsfsunriportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> + </callout> + <callout arearefs="tutorials.jsphello.method3.1"> <para> - If you do not have the - <filename> - HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war - </filename> - file, change into the - <filename>HelloWorldJSFSunRIPortlet/</filename> - directory, and run the - <command>ant deploy</command> - command. This creates the - <filename>helloworldjsfsunriportlet.war</filename> - file. + 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> - </listitem> - <listitem> - <para> - To expand the WAR file, change into the - <filename>HelloWorldJSFSunRIPortlet/</filename> - directory, and run the - <command>ant explode</command> - command. On Linux, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/jsf_ant_explode.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> + </callout> + <callout arearefs="tutorials.jsphello.method3.2"> + <para>The action URL is used in the HTML form.</para> + </callout> + </calloutlist> + </programlistingco> + <para> - The expanded WAR file and the application descriptors are located in the - <filename> - HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/WEB-INF/ - </filename> - directory. - </para> - </sect3> - <sect3> - <title>Deploying your JSF portlet</title> - <para> - If you did not expand the - <filename>helloworldjsfsunriportlet.war</filename> - file, copy the - <filename> - HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war - </filename> - file into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. If you expanded the - <filename>helloworldjsfsunriportlet.war</filename> - file, copy the - <filename> - HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/ - </filename> - directory into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. For example, if you are using - <computeroutput>default</computeroutput> - JBoss AS profile, copy the WAR file or the expanded directory into the - <filename>$JBOSS_HOME/server/default/deploy/</filename> - directory. - </para> - <para> - Performing this step on a running instance of JBoss AS or JBoss EAP, and - JBoss Portal, triggers a hot-deploy of the portlet: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldjsfsunriportlet, -warUrl=.../tmp/deploy/tmp9138helloworldjsfsunriportlet-exp.war/]]> - </screen> - </para> - <para> - To see the HelloWorldJSFSunRIPortlet, navigate to - <ulink url="http://localhost:8080/portal/"> - http://localhost:8080/portal/ - </ulink> - , or, if the default JBoss Portal page is already open, refresh the page. - The HelloWorldJSFSunRIPortlet is added to the bottom of the default JBoss - Portal page: - </para> - <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 align="center" - fileref="images/tutorials/jsf_portlet/output.png" valign="middle" /> + <imagedata format="PNG" + fileref="images/tutorials/jsp_portlet/process.png" scalefit="1" /> </imageobject> </mediaobject> </para> - <para> - To re-deploy the portlet, for example, if you have made changes to any of - the application descriptors, touch the - <filename> - $JBOSS_HOME/server/ - <replaceable>configuration</replaceable> - /deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml - </filename> - file. This only works if you copied the - <filename> - HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/ - </filename> - directory into the JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. On Linux, run the <command>touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml</command> command to re-deploy the HelloWorldJSFSunRIPortlet. - </para> - <para> - Re-deploying the HelloWorldJSFSunRIPortlet produces output to the JBoss AS - or JBoss EAP console, similar to the following: - </para> - <para> - <screen><![CDATA[ -INFO [TomcatDeployer] undeploy, ctxPath=/helloworldjsfsunriportlet, -warUrl=.../deploy/helloworldjsfsunriportlet.war/ -INFO [TomcatDeployer] deploy, ctxPath=/helloworldjsfsunriportlet, -warUrl=.../deploy/helloworldjsfsunriportlet.war/]]> - </screen> - </para> </sect3> </sect2> - <!--<sect2 id="sunri_42x_301"> - <title>Portal and JSF RI: A basic demonstration using common components</title> - <sect3> - <para>JSF portlets are now possible using the MyFaces 301 implementation of the JSR-301 specification. - This does NOT mean that you are using the MyFaces implementation of JSF, it only means that you are - using the 301 bridge implementation (which was initially donated by Oracle). The 301 spec or bridge is - a subsystem that allows a JavaServer Faces resource to execute and satisfy a portlet request. You can - read more about the specification details <ulink url="http://jcp.org/en/jsr/detail?id=301">here</ulink>;. - </para> - </sect3> - <sect3> - <title>Downloading The Project Source</title> - <para> - You have 2 options for getting started. - <sbr/> - 1) Download the binary distribution in a zip file. This will - include all the source files along with a deployable war file. - <sbr/> - 2) Use subversion to checkout the source - code. If you plan on making changes to the source or possibly using it as a template for future development, - it is recommended that you checkout the project and use maven to build the war. - <para> - For instructions on setting up Subversion and/or Maven 2 see <xref linkend="first_portlet_descriptors"/> - </para> - <itemizedlist> - <listitem> - <para> - You can download all the project files in one zip file here: - <sbr/> - <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;. - <sbr/> - Once you extract the zip archive, the deployable war file is located in the target/ directory. - </para> - </listitem> - <listitem> - <para> - The source code: - <sbr/> - <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/src/framewo...;. - </para> - </listitem> - </itemizedlist> - </para> - </sect3> - </sect2>--> - <sect2 id="myfaces_42x"> - <title>An example Apache MyFaces JSF portlet</title> - <sect3> - <title>Introduction</title> - <para> - This section describes how to deploy a JSF portlet in JBoss Portal, using - the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Before - proceeding, download the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles... - HelloWorldJSFMyFaces42Portlet - </ulink> - from - <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink> - . - </para> - <para> - Apache MyFaces can be used globally for the entire server, replacing the - Sun JSF RI libraries, but the HelloWorldJSFMyFaces42Portlet uses its own - libraries, but does not affect the application server. - </para> - </sect3> - <sect3> - <title>Package Structure</title> - <para> - JBoss Portal requires certain descriptors to be included in a portlet WAR - file. Some of these descriptors are defined by the JSR-168 Portlet - Specification, and others are specific to JBoss Portal. Like a typical JSF - application, the HelloWorldJSFMyFaces42Portlet package contains a - <filename>faces-config.xml</filename> - file that defines managed-beans, converters, validators, navigation rules, - and so on. The following is an example of the directory structure of the - HelloWorldJSFMyFaces42Portlet portlet: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/package_myfaces42.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To create the - <filename>WEB-INF/</filename> - and - <filename>META-INF/</filename> - directories, extract the - <filename>helloworldjsfmyfacesportlet.war</filename> - file. The - <filename>WEB-INF/lib/</filename> - directory must contain the Apache MyFaces libraries, along with the - dependent libraries. - </para> - </sect3> - <sect3> - <title>Application Descriptors</title> - <para> - Only the - <filename>portlet.xml</filename> - , - <filename>faces-config.xml</filename> - , and - <filename>web.xml</filename> - descriptors are described here. For more information about application - descriptors, refer to - <xref linkend="first_portlet_descriptors" /> - and - <xref linkend="descriptors_portlet" /> - . - </para> - <para> - The following is an example of the - <filename>HelloWorldJSFMyFaces42Portlet/WEB-INF/portlet.xml</filename> - file. This file must adhere to its definition in the JSR-168 Portlet - Specification. You may define more than one portlet application in this - file: - </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... - http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - version="1.0"> - <portlet> - <portlet-name>HelloWorldJSFPortlet</portlet-name> - <portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class> - <init-param> - <name>default-view</name> - <value>/WEB-INF/jsp/index.jsp</value> - </init-param> - <supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> - </supports> - <portlet-info> - <title>HelloWorld JSF Portlet</title> - </portlet-info> - </portlet> -</portlet-app>]]> - </programlisting> - <para> - <variablelist> - <varlistentry> - <term> - <programlisting><![CDATA[ -<portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class>]]> -</programlisting> - </term> - <listitem> - <para> - This specifies that the - <computeroutput> - org.apache.myfaces.portlet.MyFacesGenericPortlet - </computeroutput> - handles all requests and responses from the users. Therefore, - there is no need to develop a specific portlet class, as Apache - MyFaces provides a generic implementation which bridges the JSF - and portlet worlds. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<init-param> - <name>default-view</name> - <value>/WEB-INF/jsp/index.jsp</value> -</init-param>]]> -</programlisting> - </term> - <listitem> - <para> - You must initialize the portlet with a default page to render, - similar to a welcome page. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <programlisting><![CDATA[ -<supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> -</supports>]]></programlisting> - </term> - <listitem> - <para> - The - <computeroutput>&lt;supports&gt;</computeroutput> - element allows you to declare 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 text and - HTML, and that it only supports the - <computeroutput>view</computeroutput> - mode. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - <note> - <title>Adding Functionality to an Apache MyFaces JSF portlet</title> - <para> - To add functionality to an Apache MyFaces JSF portlet, sub-class it - and create your own class. - </para> - </note> - </para> - <para> - The following is an example - <filename>HelloWorldJSFMyFaces42Portlet/WEB-INF/faces-config.xml</filename> - file: - </para> - <programlisting role="XML"><![CDATA[ -<?xml version="1.0"?> -<!DOCTYPE faces-config PUBLIC - "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" - "http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> -<faces-config> - <managed-bean> - <description>Basic UserBean</description> - <managed-bean-name>user</managed-bean-name> - <managed-bean-class>org.jboss.portlet.hello.bean.User</managed-bean-class> - <managed-bean-scope>session</managed-bean-scope> - </managed-bean> - - <navigation-rule> - <navigation-case> - <from-outcome>done</from-outcome> - <to-view-id>/WEB-INF/jsp/result.jsp</to-view-id> - </navigation-case> - </navigation-rule> -</faces-config>]]> - </programlisting> - <para> - Without the - <filename>faces-config.xml</filename> - file, the application would work the same outside of the portlet as it - would inside a portlet container. In this example, a basic user bean, - <computeroutput> - &lt;managed-bean-name&gt;user&lt;/managed-bean-name&gt; - </computeroutput> - , and a navigation rule are defined, which handle the submission of the - original form in the - <filename>HelloWorldJSFMyFaces42Portlet/WEB-INF/jsp/index.jsp</filename> - file. - </para> - <para> - The following is an example of the - <computeroutput>&lt;context-parm&gt;</computeroutput> - element from the - <filename>HelloWorldJSFMyFaces42Portlet/WEB-INF/web.xml</filename> - file: - </para> - <programlisting role="XML"><![CDATA[ -<context-param> - <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> - <param-value>true</param-value> -</context-param>]]> - </programlisting> - <para> - These extra parameters let the application server know that the portlet - embeds its own libraries. This avoids collision with the Sun JSF RI - libraries bundled with JBoss AS and JBoss EAP. For more information, refer - to the - <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossFaces"> - JBossFaces page on the JBoss Wiki - </ulink> - . - </para> - </sect3> - <sect3> - <title>Building your Apache MyFaces JSF portlet</title> - <para> - The - <filename>HelloWorldJSFMyFaces42Portlet.zip</filename> - file contains a pre-compiled - <filename>helloworldjsfmyfacesportlet.war</filename> - file; however, to manually build the - <filename>helloworldjsfmyfacesportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> - <para> - Change into the - <filename>HelloWorldJSFMyFaces42Portlet/</filename> - directory, and remove the existing - <filename>helloworldjsfmyfacesportlet.war</filename> - file. - </para> - </listitem> - <listitem> - <para> - If required, edit the - <filename> - HelloWorldJSFMyFaces42Portlet/src/main/org/jboss/portlet/hello/bean/User.java - </filename> - file, and the application descriptors in the - <filename> - HelloWorldJSFMyFaces42Portlet/src/resources/helloworldjsfmyfacesportlet-war/WEB-INF/ - </filename> - directory. - </para> - </listitem> - <listitem> - <para> - Change into - <filename>HelloWorldJSFMyFaces42Portlet/</filename> - directory, and run the - <command>ant deploy</command> - command. On Linux, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/myfaces_ant_deploy.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - Expanding the - <filename>helloworldjsfmyfacesportlet.war</filename> - file allows you to deploy the portlet as an expanded directory, which makes - development easier. As well, it gives you access to the application - descriptors, resource files, JSF, and JSP pages. To expand the - <filename>helloworldjsfmyfacesportlet.war</filename> - file: - </para> - <para> - <orderedlist> - <listitem> - <para> - If you do not have the - <filename> - HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportlet.war - </filename> - file, change into the - <filename>HelloWorldJSFMyFaces42Portlet/</filename> - directory, and run the - <command>ant deploy</command> - command. This creates the - <filename>helloworldjsfmyfacesportlet.war</filename> - file. - </para> - </listitem> - <listitem> - <para> - To expand the WAR file, change into the - <filename>HelloWorldJSFMyFaces42Portlet/</filename> - directory, and run the - <command>ant explode</command> - command. On Linux, the output will be similar to the following: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/myfaces_ant_explode.png" - valign="middle" /> - </imageobject> - </mediaobject> - </para> - </listitem> - </orderedlist> - </para> - <para>Note: the directory names will be different for your system.</para> - <para> - The expanded WAR file and the application descriptors are located in the - <filename> - HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/WEB-INF/ - </filename> - directory. - </para> - </sect3> - <sect3> - <title>Deploying your Apache MyFaces JSF portlet</title> - <para> - If you did not expand the - <filename>helloworldjsfmyfacesportlet.war</filename> - file, copy the - <filename> - HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportlet.war - </filename> - file into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. If you expanded the - <filename>helloworldjsfmyfacesportlet.war</filename> - file, copy the - <filename> - HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/ - </filename> - directory into the correct JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. For example, if you are using the - <computeroutput>default</computeroutput> - JBoss AS profile, copy the WAR file or the expanded directory into the - <filename>$JBOSS_HOME/server/default/deploy/</filename> - directory. - </para> - <para> - Performing this step on a running instance of JBoss AS or JBoss EAP, and - JBoss Portal, triggers a hot-deploy of the portlet. - </para> - <para> - To see the HelloWorldJSFMyFaces42Portlet, navigate to - <ulink url="http://localhost:8080/portal/"></ulink> - , or, if the default JBoss Portal page is already open, refresh the page. - The HelloWorldJSFMyFaces42Portlet is added to the bottom of the default - JBoss Portal page: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="images/tutorials/jsf_portlet/output.png" valign="middle" /> - </imageobject> - </mediaobject> - </para> - <para> - To re-deploy the portlet, for example, if you have made changes to any of - the application descriptors, touch the - <filename> - $JBOSS_HOME/server/ - <replaceable>configuration</replaceable> - /deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml - </filename> - file. This only works if you copied the - <filename> - HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/ - </filename> - directory into the JBoss AS or JBoss EAP - <filename>deploy/</filename> - directory. On Linux, run the <command>touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml</command> command to re-deploy the - HelloWorldJSFMyFaces42Portlet. - </para> - </sect3> - </sect2> - <!-- sect2> - <title>Adapting MyFaces JSF Portlet to work on JBoss AS 4.2.x</title> - <para>We saw in <xref linkend="myfaces_40x"/> how to create a JSF-based portlet using Apache's MyFaces - JSF implementation on JBoss Application Server 4.0.x. Starting with version 4.2.0 of JBoss Application - Server, the default bundled JSF implementation is Sun's Reference Implementation (RI). We thus need to - adapt our MyFaces portlet sightly so that it works in this new environment. - </para> - <para>The first step is to provide access to MyFaces as it's not bundled anymore in JBoss AS. This is - accomplished by adding <literal>myfaces-api.jar</literal> and <literal>myfaces-impl.jar</literal> in - our portlet <literal>WEB-INF/lib</literal> directory. This can be done automatically via a modification of - the ant script and is left as an exercise to the reader. - </para> - <para> - We also need to need to tell JBoss AS not to use its bundled JSF implementation for our portlet. This - is accomplished by adding the following to our portlet's <literal>web.xml</literal>: - <programlisting><![CDATA[<context-param> - <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> - <param-value>true</param-value> - </context-param>]]></programlisting> - More details on this procedure can be found at <ulink - url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossFaces">ht...;. - </para> - <para> - We should get the following package content for our portlet: - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_42x.png" valign="middle"/> - </imageobject> - </mediaobject> - </para> - </sect2--> - <!-- sect2 id="richfaces"> - <title>Portal and RichFaces: A basic demonstration using Ajax4JSF and RichFaces components</title> - <sect3> - <para> - RichFaces is currently in technology preview mode and not fully supported in Jboss Portal. - </para> - </sect3> - <sect3> - <title>Downloading The Binaries or Project Source</title> - <para> - You have 2 options for getting started. - <-<para> - For instructions on setting up Subversion and/or Maven 2 see <xref linkend="build_instructions"/> - </para>-> - <itemizedlist> - <listitem> - <para> - 1) Download the binary distribution in a zip file. This will - include all the source files along with a deployable war file. - <sbr/> - <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;. - <sbr/> - Once you extract the zip archive, the deployable war file is located in the target/ directory. - </para> - </listitem> - <listitem> - <para> - 2) Use subversion to checkout the source code. - If you plan on making changes to the source or possibly using it as a template for future development, - it is recommended that you checkout the project and use maven to build the war. - <sbr/> - <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/src/framewo...;. - </para> - </listitem> - </itemizedlist> - </para> - </sect3> - <sect3> - <title>Project Configuration</title> - <para> - The following configurations must be made to use RichFaces in your portlet. - </para> - <para> - Here we use javax.portlet.faces.GenericFacesPortlet which is part of the JSR-301 specification. We also - must declare the view, edit, and help modes as shown below. - <itemizedlist> - <listitem> - <literal>portlet.xml</literal> - <programlisting> - <![CDATA[<portlet-app version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/portlet" - xmlns="http://java.sun.com/xml/ns/portlet"> - <portlet> - <portlet-name>ajaxPortlet</portlet-name> - <portlet-class> - javax.portlet.faces.GenericFacesPortlet - </portlet-class> - - <init-param> - <name>javax.portlet.faces.defaultViewId.view</name> - <value>/jsf/start.xhtml</value> - </init-param> - - <init-param> - <name>javax.portlet.faces.defaultViewId.edit</name> - <value>/jsf/edit.xhtml</value> - </init-param> - - <init-param> - <name>javax.portlet.faces.defaultViewId.help</name> - <value>/jsf/help.xhtml</value> - </init-param> - - <expiration-cache>-0</expiration-cache> - <portlet-info> - <title>Ajax Portlet</title> - </portlet-info> - <supports> - <mime-type>text/html</mime-type> - <portlet-mode>VIEW</portlet-mode> - <portlet-mode>EDIT</portlet-mode> - <portlet-mode>HELP</portlet-mode> - </supports> - </portlet> - </portlet-app>]]> - </programlisting> - </listitem> - <listitem> - <literal>faces-config.xml</literal> - <programlisting> - <![CDATA[... - <application> - <view-handler> - org.ajax4jsf.portlet.application.PortletViewHandler - </view-handler> - <state-manager> - org.ajax4jsf.portlet.application.PortalStateManager - </state-manager> - </application> - <factory> - <faces-context-factory> - org.ajax4jsf.portlet.context.FacesContextFactoryImpl - </faces-context-factory> - </factory> - ...]]> - </programlisting> - </listitem> - <listitem> - <literal>web.xml</literal> - <programlisting> - <![CDATA[... - <context-param> - <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name> - <param-value>org.ajax4jsf.portlet.application.FaceletPortletViewHandler</param-value> - </context-param> - <filter> - <display-name>Ajax4jsf Filter</display-name> - <filter-name>ajax4jsf</filter-name> - <filter-class>org.ajax4jsf.Filter</filter-class> - </filter> - - <filter-mapping> - <filter-name>ajax4jsf</filter-name> - <servlet-name>FacesServlet</servlet-name> - <dispatcher>FORWARD</dispatcher> - <dispatcher>REQUEST</dispatcher> - <dispatcher>INCLUDE</dispatcher> - </filter-mapping> - ...]]> - </programlisting> - </listitem> - </itemizedlist> - </para> - </sect3> - </sect2--> </sect1> </chapter> \ No newline at end of file