Author: thomas.heute(a)jboss.com Date: 2008-07-09 02:24:42 -0400 (Wed, 09 Jul 2008) New Revision: 11361 Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml Log: Just started 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-09 06:22:14 UTC (rev 11360) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml 2008-07-09 06:24:42 UTC (rev 11361) @@ -1,10 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="tutorials"> <chapterinfo> <author> - <firstname>Roy</firstname> - <surname>Russo</surname> - </author> - <author> <firstname>Chris</firstname> <surname>Laprun</surname> </author> @@ -15,470 +14,594 @@ </chapterinfo> <title>Portlet Primer</title> <sect1 id="portlet_primer"> - <title>JSR-168 Overview</title> - <para>The <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink> aims at defining portlets that can be used by any JSR-168 portlet container, also known as a portal. There are different portals with commercial and non-commercial licenses. This chapter gives a brief overview of the JSR-168 Portlet Specification. Portlet developers are strongly encouraged to read the <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink>. + <title>JSR-168 and JSR-286 overview</title> + <para> + The Portlet Specifications aims at defining portlets that can be used by any + <ulink url="http://www.jcp.org/en/jsr/detail?id=168"> + JSR-168 (Portlet 1.0) + </ulink> + or + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 (Portlet 2.0) + </ulink> + portlet container. Most Java EE portals include 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 + <ulink url="http://www.jcp.org/en/jsr/detail?id=286"> + JSR-286 Portlet Specification + </ulink> + . </para> <para> - JBoss Portal is fully JSR-168 compliant, which means any JSR-168 portlet behaves as it should inside the portal. + JBoss Portal is fully JSR-286 compliant, which means any JSR-168 or JSR-286 + portlet behaves as it is mandated by the respective specifications inside the + portal. </para> <sect2> <title>Portal Pages</title> <para> - A portal can be seen as pages with different areas, and inside areas, different windows, and each window - having one portlet: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/SpecPortalDef.png" valign="middle"/> - </imageobject> - </mediaobject> - </para> + A portal can be seen as pages with different areas, and inside areas, + different windows, and each window having one portlet: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata fileref="images/tutorials/SpecPortalDef.png" scalefit="1" /> + </imageobject> + </mediaobject> + </para> </sect2> <sect2> <title>Rendering Modes</title> - <para>A portlet can have different view modes. Three modes are defined by the JSR-168 specification, but a portal can - extend those modes. The three modes are: - </para> - <para> + <para> + A portlet can have different view modes. Three modes are defined by the + JSR-288 specification: + </para> + <para> <itemizedlist> <listitem> - <para> - <computeroutput>view</computeroutput> - generates markup reflecting the current state of the portlet. - </para> - </listitem> + <para> + <emphasis>view</emphasis> + - generates markup reflecting the current state of the portlet. + </para> + </listitem> <listitem> - <para> - <computeroutput>edit</computeroutput> - allows a user to customize the behavior of the portlet. - </para> - </listitem> + <para> + <emphasis>edit</emphasis> + - allows a user to customize the behavior of the portlet. + </para> + </listitem> <listitem> - <para> - <computeroutput>help</computeroutput> - provides information to the user as to how to use the portlet. - </para> - </listitem> + <para> + <emphasis>help</emphasis> + - provides information to the user as to how to use the portlet. + </para> + </listitem> </itemizedlist> </para> </sect2> <sect2> <title>Window States</title> <para> - Window states are an indicator of how much page real-estate a portlet consumes on any given page. - The three states defined by the JSR-168 specification are: + Window states are an indicator of how much page real-estate a portlet consumes + on any given page. The three states defined by the JSR-168 specification are: </para> - <para> + <para> <itemizedlist> <listitem> - <para> - <computeroutput>normal</computeroutput> - a portlet shares this page with other portlets. - </para> - </listitem> + <para> + <emphasis>normal</emphasis> + - a portlet shares this page with other portlets. + </para> + </listitem> <listitem> - <para> - <computeroutput>minimized</computeroutput> -a portlet may show very little information, or none at all. - </para> - </listitem> + <para> + <emphasis>minimized</emphasis> + -a portlet may show very little information, or none at all. + </para> + </listitem> <listitem> - <para> - <computeroutput>maximized</computeroutput> - a portlet may be the only portlet displayed on this page. - </para> - </listitem> + <para> + <emphasis>maximized</emphasis> + - a portlet may be the only portlet displayed on this page. + </para> + </listitem> </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> + <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. 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=168">JSR-168 Portlet Specification</ulink>. Use the <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... Portal User Forums</ulink> for user-to-user help. + The tutorials contained in this chapter are targetted 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 + <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... + JBoss Portal User Forums + </ulink> + for user-to-user help. </para> - <!--<sect2 id="build_instructions"> - <title> - Building and deploying the tutorials - </title> - <sect3> - <title id="ant_build">Ant based tutorials</title> - <para> - For projects that are Ant based you can execute the build.xml with ant or inside your IDE. - Executing <literal>ant</literal> will compile all source files and produce a - artifact file auch as a .war. - <sbr/> - Before you run your first tutorial build, you must download <ulink url="http://ant.apache.org/bindownload.cgi">Apache Ant</ulink> - and add it to your classpath. - </para> - <para> - The <literal>explode</literal> target will produce the following: - - </para> - <para> - Deploying the portlet is as easy as copying/moving the <literal>helloworldjspportlet.war</literal> file - to the server <literal>deploy</literal> directory. We can then see our portlet on the Portal default - page (<ulink url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>): - - </para> - </sect3> - <sect3> - <title id="maven_build">Maven based tutorials</title> - <para> - - </para> - </sect3> - </sect2>--> - <sect2> <title>Deploying your first Portlet</title> <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... from <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink>. - </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> + . + </para> </sect3> <sect3> <title>Package Structure</title> <para> - Like other Java Platform, Enterprise Edition (Java EE) applications, portlets are packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles, images, HTML, <trademark class="trade">JavaServer</trademark> Pages (<trademark class="trade">JSP</trademark>), and other static or dynamic files. The following is an example of the directory structure of the HelloWorldPortlet portlet: + Like other Java Platform, Enterprise Edition (Java EE) applications, + portlets are packaged in WAR files. A typical portlet WAR file can include + servlets, resource bundles, images, HTML, + <trademark class="trade">JavaServer</trademark> + Pages ( + <trademark class="trade">JSP</trademark> + ), and other static or dynamic files. The following is an example of the + directory structure of the HelloWorldPortlet portlet: </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/first_portlet/package.gif" valign="middle"/> - </imageobject> - </mediaobject> - </para> - </sect3> +<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 +| `-- WEB-INF +| |-- classes +| | `-- org +| | `-- jboss +| | `-- portal +| | `-- portlet +| | `-- samples +| | `-- SimplestHelloWorldPortlet.class +| |-- default-object.xml +| |-- 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> <sect3> <title>Portlet Classes</title> <para> - The following is the <filename>HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java</filename> Java source file, which comes bundled with the <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;: - </para> - <para> -<screen><![CDATA[ + The following 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: + </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; -package org.jboss.portlet.hello; +import java.io.IOException; +import java.io.PrintWriter; import javax.portlet.GenericPortlet; -import javax.portlet.PortletException; import javax.portlet.RenderRequest; import javax.portlet.RenderResponse; -import javax.portlet.UnavailableException; -import java.io.IOException; -import java.io.PrintWriter; -public class HelloWorldPortlet extends GenericPortlet - +public class SimplestHelloWorldPortlet extends GenericPortlet { - protected void doView(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException - - { - rResponse.setContentType("text/html"); - PrintWriter writer = rResponse.getWriter(); - writer.write("Hello World!"); - writer.close(); - } - -} ]]> -</screen> - </para> - <para> - <variablelist> - <varlistentry><term><screen> -public class HelloWorldPortlet extends GenericPortlet</screen></term> - <listitem> - <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> - </listitem> - </varlistentry> - <varlistentry><term><screen> -protected void doView(RenderRequest rRequest, RenderResponse rResponse) -throws PortletException, IOException, UnavailableException</screen></term> - <listitem> - <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> - </listitem> - </varlistentry> - <varlistentry><term><screen> -rResponse.setContentType("text/html");</screen></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 will throw an exception. - </para> - </listitem> - </varlistentry> - <varlistentry><term><screen> -PrintWriter writer = rResponse.getWriter(); -writer.write("Hello World!"); -writer.close();</screen></term> - <listitem> - <para> - This produces the <literal>Hello World!</literal> text in our portlet window. - </para> - </listitem> - </varlistentry> - </variablelist> -</para> -<para> - <note> - <title>Markup Fragments</title> - <para> - Portlets are responsible for generating markup fragments, as they are included on a page and are - surrounded by other portlets. In particular, this means that a portlet outputting HTML must - not output any markup that cannot be found in a <literal>&lt;body&gt;</literal> element. - </para> - </note> -</para> + public void doView(RenderRequest request, + RenderResponse response) throws IOException + { + PrintWriter writer = response.getWriter(); + writer.write("Hello World !"); + 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> + <para> + <note> + <title>Markup Fragments</title> + <para> + Portlets are responsible for generating markup fragments, as they are + included on a page and are surrounded by other portlets. In + particular, this means that a portlet outputting HTML must not output + any markup that cannot be found in a + <literal>&lt;body&gt;</literal> + element. + </para> + </note> + </para> </sect3> <sect3 id="first_portlet_descriptors"> <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 JSR-168 Portlet Specification, and others are specific to JBoss Portal. The following is an example of the directory structure of the HelloWorldPortlet portlet: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/first_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>helloworldportlet.war</filename> file. - </para> - <para> - The following is an example of the <filename>HelloWorldPortlet/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> - <para> -<screen><![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"> + 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. + </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[ +<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... + http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + version="2.0"> <portlet> - <portlet-name>HelloWorldPortlet</portlet-name> - <portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class> + <portlet-name>SimplestHelloWorldPortlet</portlet-name> + <portlet-class> + org.jboss.portal.portlet.samples.SimplestHelloWorldPortlet + </portlet-class> <supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> + <mime-type>text/html</mime-type> </supports> <portlet-info> - <title>HelloWorld Portlet</title> + <title>Simplest Hello World Portlet</title> </portlet-info> </portlet> </portlet-app>]]> -</screen> - </para> - <para> - <variablelist> - <varlistentry><term><screen><![CDATA[ -<portlet-name>HelloWorldPortlet</portlet-name>]]></screen></term> -<listitem> - <para> - Define the portlet name. It does not have to be the class name. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></screen></term> -<listitem> - <para> - The Fully Qualified Name (FQN) of your portlet class must be declared here. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<supports> - <mime-type>text/html</mime-type> - <portlet-mode>view</portlet-mode> -</supports>]]></screen></term> -<listitem> - <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 text and HTML, and that it only supports the <computeroutput>view</computeroutput> mode. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<portlet-info> - <title>HelloWorld Portlet</title> -</portlet-info>]]></screen></term> -<listitem> - <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> -</listitem> -</varlistentry> -</variablelist> -</para> - <para> - The <filename>HelloWorldPortlet/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> file. The <computeroutput>&lt;instance-id&gt;</computeroutput> - value can be named anything, but it must match the <computeroutput>&lt;instance-ref&gt;</computeroutput> value given - in the <filename>*-object.xml</filename> file, which in this example, would be the <filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename> file. - </para> -<para> - The following is an example of the <filename>HelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> file: -</para> -<para> -<screen><![CDATA[ -<?xml version="1.0" standalone="yes"?> + </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> + </calloutlist> + </programlistingco> + <para> + The + <filename>HelloWorldPortlet/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> + file. The + <computeroutput>&lt;instance-id&gt;</computeroutput> + value can be named anything, but it must match the + <computeroutput>&lt;instance-ref&gt;</computeroutput> + value given in the + <filename>*-object.xml</filename> + file, which in this example, would be the + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + file. + </para> + <para> + The following is an example of the + <filename>SimplestHelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> + file: + </para> + <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/portal/dtd/portlet-instances_2_6.dtd"> + "http://www.jboss.org/portlet/dtd/portlet-instances_2_6.dtd"> <deployments> <deployment> <instance> - <instance-id>HelloWorldPortletInstance</instance-id> - <portlet-ref>HelloWorldPortlet</portlet-ref> + <instance-id>SimplestHelloWorldInstance</instance-id> + <portlet-ref>SimplestHelloWorldPortlet</portlet-ref> </instance> </deployment> </deployments>]]> -</screen> -</para> -<para> - The <filename>*-object.xml</filename> file is a JBoss Portal specific descriptor that allow users to - define the structure of their portal instances, and create and configure their windows and - pages. In the following example: -</para> -<para> - <itemizedlist> - <listitem> - <para> - a portlet window is created. - </para> - </listitem> - <listitem> - <para> - specifies that the window displays the markup generated by the <computeroutput>HelloWorldPortletInstance</computeroutput> portlet instance. - </para> - </listitem> - <listitem> - <para> - the window is assigned to the <computeroutput>default.default</computeroutput> page. - </para> - </listitem> - <listitem> - <para> - the <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. - </para> - </listitem> - </itemizedlist> -</para> -<para> - The following is an example <filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename> file: -</para> -<para> -<screen><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + </programlisting> + <para> + The + <filename>*-object.xml</filename> + file is a JBoss Portal specific descriptor that allow users to define the + structure of their portal instances, and create and configure their windows + and pages. In the following example: + </para> + <para> + <itemizedlist> + <listitem> + <para>a portlet window is created.</para> + </listitem> + <listitem> + <para> + specifies that the window displays the markup generated by the + <computeroutput>HelloWorldPortletInstance</computeroutput> + portlet instance. + </para> + </listitem> + <listitem> + <para> + the window is assigned to the + <computeroutput>default.default</computeroutput> + page. + </para> + </listitem> + <listitem> + <para> + the + <computeroutput>&lt;region&gt;</computeroutput> + element specifies where the window appears on the page. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following is an example + <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"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> <deployments> <deployment> - <parent-ref>default.default</parent-ref> + <parent-ref>default</parent-ref> <if-exists>overwrite</if-exists> - <window> - <window-name>HelloWorldPortletWindow</window-name> - <instance-ref>HelloWorldPortletInstance</instance-ref> - <region>center</region> - <height>1</height> - </window> + <page> + <page-name>SimplestHelloWorld</page-name> + <window> + <window-name>SimplestHelloWorldWindow</window-name> + <instance-ref>SimplestHelloWorldInstance</instance-ref> + <region>center</region> + <height>0</height> + </window> + </page> </deployment> </deployments>]]> -</screen> -</para> - -<para> - <variablelist> - <varlistentry><term><screen><![CDATA[ -<parent-ref>default.default</parent-ref>]]> -</screen></term> -<listitem> - <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> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<if-exists>overwrite</if-exists>]]> -</screen></term> -<listitem> - <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> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<window-name>HelloWorldPortletWindow</window-name>]]> -</screen></term> -<listitem> - <para> - A <emphasis role="bold">unique name</emphasis> given to the portlet window. This can be named anything. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<instance-ref>HelloWorldPortletInstance</instance-ref>]]> -</screen></term> -<listitem> - <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> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ -<region>center</region> -<height>1</height>]]> -</screen></term> -<listitem> - <para> - Specifies where the window appears within the page layout. - </para> -</listitem> -</varlistentry> -</variablelist> -</para> -<para> - The following diagram illustrates the relationship between the <filename>portlet.xml</filename>, <filename>portlet-instances.xml</filename>, and <filename>helloworld-object.xml</filename> descriptors: -</para> -<para> + </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> + <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> + <callout arearefs="windowname"> + <para> + A + <emphasis role="bold">unique name</emphasis> + given to the portlet window. This can be named anything. + </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> + <callout arearefs="region"> + <para> + Specifies where the window appears within the page layout. + </para> + </callout> + <callout arearefs="height"> + <para> + Specifies where the window appears within the page layout. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + The following diagram illustrates the relationship between the + <filename>portlet.xml</filename> + , + <filename>portlet-instances.xml</filename> + , and + <filename>helloworld-object.xml</filename> + descriptors: + </para> + <para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/first_portlet/desc_relationship.gif" - valign="middle"/> + <imagedata align="center" + fileref="images/tutorials/first_portlet/desc_relationship.gif" + valign="middle" /> </imageobject> </mediaobject> -</para> + </para> <para> - JBoss Portal 2.6 introduces the notion of <emphasis>content-type</emphasis>, which is a generic mechanism to - specify what content displayed by a given portlet window. The <computeroutput>window</computeroutput> section - of the previous example, <filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename>, can be re-written to take advantage of the new content framework. The following is an example deployment descriptor that uses the new content framework: + JBoss Portal 2.6 introduced the notion of + <emphasis>content-type</emphasis> + , which is a generic mechanism to specify what content displayed by a given + portlet window. The + <computeroutput>window</computeroutput> + section of the previous example, + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + , can be re-written to take advantage of the new content framework. The + following is an example deployment descriptor that uses the new content + framework: </para> - <para> -<screen><![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" @@ -488,188 +611,334 @@ <parent-ref>default.default</parent-ref> <if-exists>overwrite</if-exists> <window> - <window-name>HelloWorldPortletWindow</window-name> + <window-name>SimplestHelloWorldWindow</window-name> <content> <content-type>portlet</content-type> - <content-uri>HelloWorldPortletInstance</content-uri> + <content-uri>SimplestHelloWorldInstance</content-uri> </content> <region>center</region> <height>1</height> </window> </deployment> </deployments>]]> -</screen> - </para> - <para> + </programlisting> + <para> - This declaration is equivalent to the previous <filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename> example. Use <computeroutput>&lt;content-type&gt;</computeroutput> to specify the content to display. In this example, the content being displayed by the <computeroutput>HelloWorldPortletWindow</computeroutput> is a <computeroutput>portlet</computeroutput>. The <computeroutput>&lt;content-uri&gt;</computeroutput> element specifies which content to display, which in this example, is the <computeroutput>HelloWorldPortletInstance</computeroutput>: - </para> - <para> -<screen><![CDATA[ -<content> + This declaration is equivalent to the previous + <filename>SimplestHelloWorldPortlet/WEB-INF/default-object.xml</filename> + example. Use + <computeroutput>&lt;content-type&gt;</computeroutput> + to specify the content to display. In this example, the content being + displayed by the + <computeroutput>SimplestHelloWorldWindow</computeroutput> + is a + <computeroutput>portlet</computeroutput> + . The + <computeroutput>&lt;content-uri&gt;</computeroutput> + element specifies which content to display, which in this example, is the + <computeroutput>HelloWorldPortletInstance</computeroutput> + : + </para> + <programlisting role="XML"><![CDATA[<content> <content-type>portlet</content-type> <content-uri>HelloWorldPortletInstance</content-uri> </content>]]> -</screen> - </para> - <para> - To display certain content or a file, use the <computeroutput>cms</computeroutput> content-type, with the <computeroutput>&lt;content-uri&gt;</computeroutput> element being the path to the file in the CMS. This behavior is pluggable: you can plug in almost any type of content. - </para> + </programlisting> + <para> + To display certain content or a file, use the + <computeroutput>cms</computeroutput> + content-type, with the + <computeroutput>&lt;content-uri&gt;</computeroutput> + element being the path to the file in the CMS. This behavior is pluggable: + you can plug in almost any type of content. + </para> </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> + 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> - 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> + <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"/> + <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> + <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[ + 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> + </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"/> + <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 following command to re-deploy the HelloWorldPortlet: - </para> - <para> -<screen> -touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldportlet.war/WEB-INF/web.xml -</screen> - </para> - <para> - Re-deploying the HelloWorldPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following: - </para> - <para> -<screen><![CDATA[ + <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 following command to re-deploy the + HelloWorldPortlet: + </para> + <para> + <screen> + touch $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/helloworldportlet.war/WEB-INF/web.xml + </screen> + </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> + </screen> + </para> + </sect3> </sect2> <sect2> - <title>An example <trademark class="trade">JavaServer</trademark> Pages (<trademark class="trade">JSP</trademark>) portlet</title> + <title> + An example + <trademark class="trade">JavaServer</trademark> + Pages ( + <trademark class="trade">JSP</trademark> + ) portlet + </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... 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. + <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. </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. - </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: - </para> - <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. + </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: + </para> + <para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsp_portlet/package.gif" valign="middle"/> + <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> + <para> + To create the + <filename>WEB-INF/</filename> + and + <filename>META-INF/</filename> + directories, extract the + <filename>helloworldjspportlet.war</filename> + file. + </para> </sect3> <sect3> <title>Portlet Classes</title> <para> - The <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... contains the <filename>HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/HelloWorldJSPPortlet.java</filename> file: - </para> - <para> -<screen><![CDATA[ + The + <ulink + url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... + HelloWorldJSPPortlet + </ulink> + contains the + <filename> + HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/HelloWorldJSPPortlet.java + </filename> + file: + </para> + <para> + <screen><![CDATA[ package org.jboss.portlet.hello; import javax.portlet.ActionRequest; @@ -734,24 +1003,34 @@ prd.include(rRequest, rResponse); } }]]> -</screen> -</para> -<para> - <variablelist> - <varlistentry><term><screen><![CDATA[ + </screen> + </para> + <para> + <variablelist> + <varlistentry> + <term> + <screen><![CDATA[ protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException]]> -</screen><screen><![CDATA[ + </screen> + <screen><![CDATA[ protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ public void processAction(ActionRequest aRequest, ActionResponse aResponse) throws PortletException, IOException, UnavailableException { @@ -761,52 +1040,105 @@ aResponse.setRenderParameter("yourname", sYourname); }]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ rResponse.setContentType("text/html");]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException]]> -</screen></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> + </screen> + </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> + <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: - </para> - <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: + </para> + <para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsp_portlet/process.gif" valign="middle"/> + <imagedata align="center" + fileref="images/tutorials/jsp_portlet/process.gif" + valign="middle" /> </imageobject> </mediaobject> </para> - <para> - The following is an example of the <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> file: + <para> + The following is an example of the + <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> + file: </para> <para> -<screen><![CDATA[ + <screen><![CDATA[ <%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> <portlet:defineObjects/> @@ -826,215 +1158,400 @@ href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo"> </portlet:param></portlet:renderURL>">this</a>. </div>]]> -</screen> -</para> -<para> -<variablelist> - <varlistentry><term><screen><![CDATA[ + </screen> + </para> + <para> + <variablelist> + <varlistentry> + <term> + <screen><![CDATA[ <%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ <portlet:defineObjects/>]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ <form action="<portlet:actionURL><portlet:param name="page" value="mainview"/> </portlet:actionURL>" method="POST">]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ <a href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo"> </portlet:param></portlet:renderURL>">]]> -</screen></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> + </screen> + </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> - <para> - Change into the <filename>HelloWorldJSPPortlet/</filename> directory, and remove the existing <filename>helloworldjspportlet.war</filename> file. - </para> - </listitem> - <listitem> - <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. - </para> - </listitem> - <listitem> - <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: - </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> - </sect3> - <sect3> - <title>Deploying your <trademark class="trade">JSP</trademark> portlet</title> - <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[ + <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> + <para> + Change into the + <filename>HelloWorldJSPPortlet/</filename> + directory, and remove the existing + <filename>helloworldjspportlet.war</filename> + file. + </para> + </listitem> + <listitem> + <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. + </para> + </listitem> + <listitem> + <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: + </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> + </sect3> + <sect3> + <title> + Deploying your + <trademark class="trade">JSP</trademark> + portlet + </title> + <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 following command to re-deploy the HelloWorldJSPPortlet: -</para> -<para> -<screen> -touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjspportlet.war/WEB-INF/web.xml -</screen> -</para> -<para> - Re-deploying the HelloWorldJSPPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following: -</para> -<para> -<screen><![CDATA[ + </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 following command to re-deploy the + HelloWorldJSPPortlet: + </para> + <para> + <screen> + touch $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/helloworldjspportlet.war/WEB-INF/web.xml + </screen> + </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> + </screen> + </para> + </sect3> + </sect2> <sect2 id="sunri_42x"> - <title>An example <trademark class="trade">Sun</trademark> JSF Reference Implementation (RI) portlet</title> + <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... from <ulink url="http://labs.jboss.com/portletswap/">JBoss PortletSwap</ulink>. + 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> <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> + 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"/> + <imagedata align="center" + fileref="images/tutorials/jsf_portlet/package_sunri.png" + valign="middle" /> </imageobject> </mediaobject> - </para> - <para> - To create the <filename>WEB-INF/</filename> and <filename>META-INF/</filename> directories, extract the <filename>helloworldjsfsunriportlet.war</filename> file. - </para> - <para> + </para> + <para> + To create the + <filename>WEB-INF/</filename> + and + <filename>META-INF/</filename> + directories, extract the + <filename>helloworldjsfsunriportlet.war</filename> + file. + </para> + <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> + <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> </para> - </sect3> - <sect3> - <title>Application Descriptors</title> + </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> - <para> -<screen><![CDATA[ + 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> + <para> + <screen><![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" @@ -1057,50 +1574,90 @@ </portlet-info> </portlet> </portlet-app>]]> -</screen> - </para> - <para> - <variablelist> - <varlistentry><term><screen><![CDATA[ + </screen> + </para> + <para> + <variablelist> + <varlistentry> + <term> + <screen><![CDATA[ <portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class>]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ <init-param> <name>com.sun.faces.portlet.INIT_VIEW</name> <value>/WEB-INF/jsp/index.jsp</value> </init-param>]]> -</screen></term> -<listitem> - <para> - You must initialize the portlet with a default page to render, similar to a welcome page. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ + </screen> + </term> + <listitem> + <para> + You must initialize the portlet with a default page to render, + similar to a welcome page. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <screen><![CDATA[ <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> -</supports>]]></screen></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> -<para> -<screen><![CDATA[ +</supports>]]></screen> + </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> + <para> + <screen><![CDATA[ <?xml version="1.0"?> <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" @@ -1120,16 +1677,32 @@ </navigation-case> </navigation-rule> </faces-config>]]> -</screen> -</para> -<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> -<para> -<screen><![CDATA[ + </screen> + </para> + <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> + <para> + <screen><![CDATA[ <?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" @@ -1151,212 +1724,361 @@ </servlet-mapping> </web-app>]]> -</screen> -</para> -<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... bridge webpage</ulink> to download the JSF-Portlet bridge library. - </para> - </warning> -</para> + </screen> + </para> + <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> - <para> - Change into the <filename>HelloWorldJSFSunRIPortlet/</filename> directory, and remove the existing <filename>helloworldjsfsunriportlet.war</filename> file. - </para> - </listitem> - <listitem> - <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. - </para> - </listitem> - <listitem> - <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: - </para> - <para> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/jsf_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>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> - <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. - </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> - <para> - The expanded WAR file and the application descriptors are located in the <filename>HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/WEB-INF/</filename> directory. + <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> - </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[ + <para> + <orderedlist> + <listitem> + <para> + Change into the + <filename>HelloWorldJSFSunRIPortlet/</filename> + directory, and remove the existing + <filename>helloworldjsfsunriportlet.war</filename> + file. + </para> + </listitem> + <listitem> + <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. + </para> + </listitem> + <listitem> + <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: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" + fileref="images/tutorials/jsf_portlet/jsf_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>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> + <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. + </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> + <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> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/output.png" valign="middle"/> - </imageobject> + </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> + <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/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 following command to re-deploy the HelloWorldJSFSunRIPortlet: - </para> - <para> -<screen> -touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml -</screen> - </para> - <para> - Re-deploying the HelloWorldJSFSunRIPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following: - </para> - <para> -<screen><![CDATA[ + <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 following command to re-deploy the + HelloWorldJSFSunRIPortlet: + </para> + <para> + <screen> + touch $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml + </screen> + </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> + </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> + <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> + <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>--> <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... 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> + <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> + 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"/> + <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> - <para> -<screen><![CDATA[ + <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> + <para> + <screen><![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" @@ -1379,58 +2101,97 @@ </portlet-info> </portlet> </portlet-app>]]> -</screen> -</para> -<para> - <variablelist> - <varlistentry><term><screen><![CDATA[ + </screen> + </para> + <para> + <variablelist> + <varlistentry> + <term> + <screen><![CDATA[ <portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class>]]> -</screen></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><screen><![CDATA[ + </screen> + </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> + <screen><![CDATA[ <init-param> <name>default-view</name> <value>/WEB-INF/jsp/index.jsp</value> </init-param>]]> -</screen></term> -<listitem> - <para> - You must initialize the portlet with a default page to render, similar to a welcome page. - </para> -</listitem> -</varlistentry> -<varlistentry><term><screen><![CDATA[ + </screen> + </term> + <listitem> + <para> + You must initialize the portlet with a default page to render, + similar to a welcome page. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <screen><![CDATA[ <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> -</supports>]]></screen></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> -<para> -<screen><![CDATA[ +</supports>]]></screen> + </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> + <para> + <screen><![CDATA[ <?xml version="1.0"?> <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" @@ -1450,283 +2211,393 @@ </navigation-case> </navigation-rule> </faces-config>]]> -</screen> -</para> - <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> -<para> -<screen><![CDATA[ + </screen> + </para> + <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> + <para> + <screen><![CDATA[ <context-param> <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> <param-value>true</param-value> </context-param>]]> -</screen> -</para> -<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">JB... page on the JBoss Wiki</ulink>. -</para> -</sect3> + </screen> + </para> + <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 following command to re-deploy the HelloWorldJSFMyFaces42Portlet: - </para> - <para> -<screen> -touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml -</screen> - </para> + <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 following command to re-deploy the + HelloWorldJSFMyFaces42Portlet: + </para> + <para> + <screen> + touch $JBOSS_HOME/server/ + <replaceable>configuration</replaceable> + /deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml + </screen> + </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. + 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. + 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...;. + 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> + 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--> <!-- 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> + <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> + <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> + <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[... + </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> + <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> + <faces-context-factory> + org.ajax4jsf.portlet.context.FacesContextFactoryImpl + </faces-context-factory> </factory> ...]]> -</programlisting> - </listitem> - <listitem> - <literal>web.xml</literal> -<programlisting> - <![CDATA[... + </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> + <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> + <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-name>ajax4jsf</filter-name> + <servlet-name>FacesServlet</servlet-name> + <dispatcher>FORWARD</dispatcher> + <dispatcher>REQUEST</dispatcher> + <dispatcher>INCLUDE</dispatcher> </filter-mapping> ...]]> -</programlisting> - </listitem> - </itemizedlist> - </para> + </programlisting> + </listitem> + </itemizedlist> + </para> </sect3> - </sect2--> + </sect2--> </sect1> </chapter> \ No newline at end of file