Author: chris.laprun(a)jboss.com Date: 2007-08-08 12:35:23 -0400 (Wed, 08 Aug 2007) New Revision: 7877 Added: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png Removed: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/building.gif docs/trunk/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif docs/trunk/referenceGuide/en/images/tutorials/jsp_portlet/building.gif Modified: docs/trunk/referenceGuide/en/modules/tutorials.xml Log: - More tutorial improvements in particular with respect to JSF portlets. Deleted: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif =================================================================== (Binary files differ) Deleted: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/building.gif =================================================================== (Binary files differ) Added: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: docs/trunk/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif =================================================================== (Binary files differ) Deleted: docs/trunk/referenceGuide/en/images/tutorials/jsp_portlet/building.gif =================================================================== (Binary files differ) Modified: docs/trunk/referenceGuide/en/modules/tutorials.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-08-08 16:11:13 UTC (rev 7876) +++ docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-08-08 16:35:23 UTC (rev 7877) @@ -5,6 +5,11 @@ <surname>Russo</surname> <email&gt;roy(a)jboss.org&lt;/email&gt; </author> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + <email&gt;chris.laprun(a)jboss.com&lt;/email&gt; + </author> </chapterinfo> <title>Portlet Primer</title> <sect1 id="portlet_primer"> @@ -68,11 +73,9 @@ <para> The tutorials contained in this chapter are targetted toward portlet developers. Although they are a good starting and reference point, we do heavily recommend that portlet developers read and understand the - <ulink url="http://www.jcp.org/en/jsr/detail?id=168">Portlet - Specification (JSR-168)</ulink> - . We also recommend, using our - <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... Portal User Forums</ulink> - for user-to-user help, when needed. + <ulink url="http://www.jcp.org/en/jsr/detail?id=168">Portlet Specification (JSR-168)</ulink>. We also recommend + using our <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... Portal User + Forums</ulink> for user-to-user help, when needed. </para> <sect2> <title>Deploying your first portlet</title> @@ -81,18 +84,15 @@ <para>This section will introduce the reader to deploying his first portlet in JBoss Portal. It requires you download the HelloWorldPortlet from PortletSwap.com, using this <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - link</ulink> - . + url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...;. </para> </sect3> <sect3> <title>Package Structure</title> <para> - Portlets are packaged in war files, just like other JEE applications. A typical portlet war file can also - include servlets, resource bundles, images, html, jsps, and other static or dynamic files you would - commonly - include. + Portlets are packaged in WAR files, just like other JEE applications. A typical portlet WAR file can also + include servlets, resource bundles, images, HTML, JSPs, and other static or dynamic files you would + commonly include. </para> <para> <mediaobject> @@ -103,15 +103,13 @@ </para> </sect3> <sect3> - <title>The Portlet Class</title> + <title>Portlet Class</title> <para> Included in the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - download bundle</ulink> - you should have one java source file: - <emphasis>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java</emphasis> - , and it should contain the following: + <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... + download bundle</ulink> you should have one java source file: + <literal>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java</literal>, and it + should contain the following: <programlisting><![CDATA[package org.jboss.portlet.hello; import javax.portlet.GenericPortlet; @@ -134,7 +132,7 @@ } }]]> </programlisting> - Now lets dissect our simplest of portlets: + Now let's dissect our simplest of portlets: <itemizedlist> <listitem> <para> @@ -154,9 +152,9 @@ <programlisting>protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException</programlisting> As we extend from <literal>GenericPortlet</literal> and we are only interested in supported the - <emphasis>VIEW</emphasis> mode, we only need to implement the <literal>doView</literal> method, + <literal>VIEW</literal> mode, we only need to implement the <literal>doView</literal> method, and <literal>GenericPortlet</literal>'s <literal>render</literal> implementation will call our - implementation when the <emphasis>VIEW</emphasis> mode is requested. + implementation when the <literal>VIEW</literal> mode is requested. </para> </listitem> <listitem> @@ -174,7 +172,7 @@ writer.write("Hello World!"); writer.close();]]></programlisting> Here we output the text - <emphasis>Hello World!</emphasis> + <literal>Hello World!</literal> in our portlet window. <note> Portlets are responsible for generating markup fragments, as they are included on a page and @@ -187,21 +185,20 @@ </para> </sect3> <sect3 id="first_portlet_descriptors"> - <title>The Application Descriptors</title> + <title>Application Descriptors</title> <para> - JBoss Portal requires certain descriptors be included in your portlet war, for different reasons. Some of - these descriptors are defined by the Portlet Specification, and some are specific to JBoss Portal. + JBoss Portal requires certain descriptors be included in your portlet WAR, for different reasons. Some of + these descriptors are defined by the Portlet Specification, some are specific to JBoss Portal. <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/first_portlet/package.gif" valign="middle"/> </imageobject> </mediaobject> - Now lets explain what each of these does: + Now let's explain what each of these does: <itemizedlist> <listitem> - <para> - portlet.xml - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + <para><literal>portlet.xml</literal> +<programlisting><![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... @@ -231,7 +228,7 @@ <listitem> <para> <programlisting><![CDATA[<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></programlisting> - The FQN of your portlet class must be declared here. + The Fully Qualified Name (FQN) of your portlet class must be declared here. </para> </listitem> <listitem> @@ -267,8 +264,8 @@ </para> </listitem> <listitem> - <para>portlet-instances.xml - <programlisting><![CDATA[<?xml version="1.0" standalone="yes"?> + <para><literal>portlet-instances.xml</literal> +<programlisting><![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"> @@ -288,8 +285,8 @@ </para> </listitem> <listitem> - <para>helloworld-object.xml - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + <para><literal>helloworld-object.xml</literal> +<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"> @@ -317,30 +314,19 @@ <para> <programlisting><![CDATA[<parent-ref>default.default</parent-ref>]]></programlisting> Tells the portal where this portlet should appear. In this case, - <emphasis>default.default</emphasis> - specifies that this portlet should appear in the portal instance named - <emphasis>default</emphasis> - and the - page named - <emphasis>default</emphasis> - . + <literal>default.default</literal> specifies that this portlet should appear in the + portal instance named <literal>default</literal> and the page named + <literal>default</literal>. </para> </listitem> <listitem> <para> <programlisting><![CDATA[<if-exists>overwrite</if-exists>]]></programlisting> Instructs the portal to overwrite or keep this object if it already exists. - Possible values are - <emphasis>overwrite</emphasis> - or - <emphasis>keep</emphasis> - . - <emphasis>Overwrite</emphasis> - will destroy the existing object and create a new one - based on the content of the deployment. - <emphasis>Keep</emphasis> - will maintain the - existing objct deployment or create a new one if it does not yet exist. + Possible values are <literal>overwrite</literal> or <literal>keep</literal>. + <literal>overwrite</literal> will destroy the existing object and create a new one + based on the content of the deployment. <literal>keep</literal> will maintain the + existing object deployment or create a new one if it does not yet exist. </para> </listitem> <listitem> @@ -352,13 +338,8 @@ <listitem> <para> <programlisting><![CDATA[<instance-ref>HelloWorldPortletInstance</instance-ref>]]></programlisting> - The value of - <emphasis>instance-ref</emphasis> - must match the value of - <emphasis>instance-id</emphasis> - found in the - <emphasis>portlet-instances.xml</emphasis> - . + The value of <literal>instance-ref</literal> must match the value of + <literal>instance-id</literal> found in the <literal>portlet-instances.xml</literal>. </para> </listitem> <listitem> @@ -374,8 +355,7 @@ </itemizedlist> </para> <para> - To illustrate the relationship between the descriptors - , we have provided this simple diagram + To illustrate the relationship between the descriptors, we have provided this simple diagram <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/first_portlet/desc_relationship.gif" @@ -387,7 +367,8 @@ <para> Portal 2.6 introduces the notion of <emphasis>content type</emphasis>, which is a generic mechanism to specify which content will be displayed by a given portlet window. The <literal>window</literal> section - of the previous example can be re-written as follows to take advantage of the new content framework: + of the previous example can be re-written to take advantage of the new content framework, resulting in + the following deployment descriptor: <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portal Object 2.6//EN" @@ -416,15 +397,12 @@ pluggable and it is possible to plug virtually any kind of content. </para> </sect3> - <sect3> + <sect3 id="first_portlet_build"> <title>Building your portlet</title> - <para>If you have downloaded the sample, you can execute the build.xml with ANT or inside your IDE. - Executing the - <emphasis>deploy</emphasis> - target - will compile all src files and produce a helloworldportlet.war under - <emphasis>HelloWorldPortlet\helloworldportlet.war.</emphasis> - + <para>If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. + Executing the <literal>deploy</literal> target will compile all the source files and produce a + <literal>helloworldportlet.war</literal> file under + <literal>HelloWorldPortlet\helloworldportlet.war.</literal> </para> <para> <mediaobject> @@ -434,10 +412,8 @@ </mediaobject> </para> <para> - If you want to create an expanded war directory, after executing the above deploy target, you should - execute the - <emphasis>explode</emphasis> - target. + If you want to create an expanded WAR directory, after executing the above deploy target, you should + execute the <literal>explode</literal> target. <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/first_portlet/buildexplode.gif" @@ -452,33 +428,25 @@ <imagedata align="center" fileref="images/tutorials/first_portlet/exploded.gif" valign="middle"/> </imageobject> </mediaobject> - This will deflate the helloworldportlet.war, and allow you to deploy it as an expanded directory. It will - work just the same, with some additional benefits noted below: - </para> - <para> - The advantage to expanded war deployments is that you can modify xml descriptors, resource files - jsp/jsf pages easily during development. Simply - <emphasis>touch</emphasis> - the web.xml to have JBoss Application Server hot-deploy the web appllication on a live-running server - instance - </para> + This will deflate <literal>helloworldportlet.war</literal>, and allow you to deploy it as an + expanded directory. It will work just the same but is easier to work with during development as you can + easily modify the XML descriptors, resources files, JSF/JSP pages. A simple <literal>touch</literal> + operation (or equivalent) on the <literal>web.xml</literal> file will let any live JBoss Application + Server instance know that it needs to hot-redeploy your web application. + </para> </sect3> <sect3> <title>Deploying your portlet</title> <para> - Deploying a portlet is as simple as copying/moving the - <emphasis>helloworldportlet.war</emphasis> - in to the server deploy directory. Doing this on a running instance of the portal and application server, - will trigger a - <emphasis>hot-deploy</emphasis> - : + Deploying a portlet is as simple as copying/moving <literal>helloworldportlet.war</literal> + to your server <literal>deploy</literal> directory. Doing this on a running instance of JBoss Portal and + application server, will trigger a <emphasis>hot-deploy</emphasis> of your portlet: <programlisting><![CDATA[18:25:56,366 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: CVSTag=JBoss_4_0_5_GA date=2006000000)] Started in 1m:3s:688ms 18:26:21,147 INFO [TomcatDeployer] deploy, ctxPath=/helloworldportlet, warUrl=.../tmp/deploy/tmp35219helloworldportlet-exp.war/]]></programlisting> - Pointing your browser to - <ulink url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink> - , should yield a view of our HelloWorldPortlet: + Pointing your browser to <ulink url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>, + should yield a view of our HelloWorldPortlet, added to the default page of Portal: <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/first_portlet/output.png" valign="middle"/> @@ -492,12 +460,9 @@ <sect3> <title>Introduction</title> <para>This section will introduce the reader to deploying a simple JSP portlet in JBoss Portal. It requires - you - download the HelloWorldJSPPortlet from PortletSwap.com, using this - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - link</ulink> - . + you download the HelloWorldJSPPortlet from PortletSwap.com, using this + <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... + link</ulink>. </para> <para> This portlet will introduce you to using JSPs for view rendering and the portlet taglib for generating @@ -505,31 +470,28 @@ </para> </sect3> <sect3> - <title>Package Structure</title> + <title>Package content</title> <para> - Portlets are packaged in war files, just like other JEE applications. A typical portlet war file can also - include servlets, resource bundles, images, html, jsps, and other static or dynamic files you would - commonly - include. - </para> - <para> + The application descriptors for this portlet are similar to the ones we saw in + <xref linkend="first_portlet_descriptors"/>. See the <xref linkend="descriptors_portlet"/> chapter on + descriptors for more details. <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsp_portlet/package.gif" valign="middle"/> </imageobject> </mediaobject> + As you can see in the figure above, the package content is what you'd expect from a traditional web + application augmented with the portlet- and JBoss Portal-specific application descriptors. </para> </sect3> <sect3> - <title>The Portlet Class</title> + <title>Portlet Class</title> <para> - Included in the - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - download bundle</ulink> - you should have one java source file: - <emphasis>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java</emphasis> - , and it should contain the following: + Included in the <ulink + url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... + download bundle</ulink> you should have one java source file: + <literal>HelloWorldJSPPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java</literal>, + containing the following: <programlisting><![CDATA[package org.jboss.portlet.hello; import javax.portlet.ActionRequest; @@ -594,7 +556,7 @@ prd.include(rRequest, rResponse); } }]]></programlisting> - Now lets look at some of our methods: + Now let's look at some of our methods: <itemizedlist> <listitem> <para> @@ -619,16 +581,17 @@ aResponse.setRenderParameter("yourname", sYourname); }]]></programlisting> - This method will be triggered upon clicking on an ActionURL from our view.jsp. It will retrieve - <emphasis>yourname</emphasis> - from the HTML form, and pass it along as a renderParameter to the doView(). + This method will be triggered upon clicking on an <literal>ActionURL</literal> from our + <literal>view.jsp</literal>. It will retrieve <literal>yourname</literal> from the HTML form, + and pass it along as a <literal>renderParameter</literal> to the <literal>doView()</literal> + method. </para> </listitem> <listitem> <para> <programlisting>rResponse.setContentType("text/html");</programlisting> - Just like in the servlet-world, you must declare what content-type the portlet will be - responding in. + Just like in the servlet world, you must declare which kind of MIME type of the content the + portlet will be generating. </para> </listitem> <listitem> @@ -636,100 +599,29 @@ <programlisting><![CDATA[protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException ]]></programlisting> - In this case, our doView, is responsible for dispatching to the appropriate jsp - <emphasis>view.jsp</emphasis> - or - <emphasis>view2.jsp</emphasis> - , depending on the existence of the - <emphasis>yourname</emphasis> - parameter passed in from the - <emphasis>processAction</emphasis> - . + In this case, our <literal>doView</literal> implementation is responsible for dispatching to + the appropriate JSP <literal>view.jsp</literal> or <literal>view2.jsp</literal>, depending on + the existence of the <literal>yourname</literal> parameter passed in from + <literal>processAction</literal>. </para> </listitem> </itemizedlist> </para> - </sect3> + </sect3> <sect3> - <title>The Application Descriptors</title> - <para> - JBoss Portal requires certain descriptors be included in your portlet war, for different reasons. Some of - these descriptors are defined by the Portlet Specification, and some are specific to JBoss Portal. For - brevity, we only discuss the - <emphasis>portlet.xml</emphasis> - descriptor here. For discussion on the other descriptors, please view - <xref linkend="first_portlet_descriptors"/> - or the - chapter on descriptors: - <xref linkend="descriptors_portlet"/> - . - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsp_portlet/package.gif" valign="middle"/> - </imageobject> - </mediaobject> - <itemizedlist> - <listitem> - <para> - portlet.xml - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> -<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... - http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" - version="1.0"> - <portlet> - <portlet-name>HelloWorldJSPPortlet</portlet-name> - <portlet-class>org.jboss.portlet.hello.HelloWorldJSPPortlet</portlet-class> - <supports> - <mime-type>text/html</mime-type> - <portlet-mode>VIEW</portlet-mode> - <portlet-mode>EDIT</portlet-mode> - <portlet-mode>HELP</portlet-mode> - </supports> - <portlet-info> - <title>HelloWorld JSP Portlet</title> - </portlet-info> - </portlet> -</portlet-app>]]></programlisting> - This file must adhere to its definition in the Portlet Specification. You may define more than - one portlet application in this file. - <note> - This sample portlet supports 3 view modes: VIEW, EDIT, and HELP. The supported modes must be - declared in the - <emphasis>portlet.xml</emphasis> - using the - <emphasis>portlet-mode</emphasis> - tag. - . - </note> - </para> - </listitem> - </itemizedlist> - </para> - </sect3> - <sect3> <title>JSP files and the portlet taglib</title> <para> - Of importance in this tutorial are the two view jsps. The first, allows the user to input his name, which - is then posted to the - <emphasis>processAction</emphasis> - method in our portlet class, set as a - <emphasis>renderParameter</emphasis> - , then the render method is invoked (in our case its the - <emphasis>doView</emphasis> - , which then dispatches to our - <emphasis>view2.jsp</emphasis> - . + Of importance in this tutorial are the two view JSPs. The first, <literal>view.jsp</literal>, allows the + user to input his name, which is then posted to the <literal>processAction</literal> method in our + portlet class, set as a <literal>renderParameter</literal>, then the <literal>render</literal> method is + invoked (in our case, <literal>doView</literal>, which then dispatches to our + <literal>view2.jsp</literal>). <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> - Now lets have a look at our - <emphasis>view.jsp</emphasis> - : + Now let's have a look at our <literal>view.jsp</literal>: </para> <para> <programlisting><![CDATA[<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> @@ -755,42 +647,32 @@ <listitem> <para> <programlisting><![CDATA[<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>]]></programlisting> - Define the portlet taglib. You do not need to bundle the portlet taglib, JBoss Portal will - handle that for you. + Define the portlet taglib. You do <emphasis>NOT</emphasis> need to bundle the portlet taglib, + JBoss Portal will handle that for you. </para> </listitem> <listitem> <para> <programlisting><![CDATA[<portlet:defineObjects/>]]></programlisting> - Calling - <emphasis>defineObjects</emphasis> - creates implicit objects in this jsp, that you can access, like: - <emphasis>renderRequest, actionRequest, portletConfig</emphasis> - . + Calling <literal>defineObjects</literal> makes available implicit objects, such as + <literal>renderRequest, actionRequest, portletConfig</literal>, in this JSP. </para> </listitem> <listitem> <para> <programlisting><![CDATA[<form action="<portlet:actionURL><portlet:param name="page" value="mainview"/> </portlet:actionURL>" method="POST">]]></programlisting> - We create an HTML form, but generate the URL it will post to, using the portlet tag library. In - this case, notice how we are creating an - <emphasis>actionURL</emphasis> - , which will activate out - <emphasis>processAction</emphasis> - method, passing in any input parameters in the form. + We create an HTML form, but generate the URL it will post to using the portlet tag library. In + this case, notice how we are creating an <literal>actionURL</literal>, which will activate our + <literal>processAction</literal> method, passing in any input parameters in the form. </para> </listitem> <listitem> <para> <programlisting><![CDATA[<a href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo"> </portlet:param></portlet:renderURL>">]]></programlisting> - Likewise, we are able to create a link to our - <emphasis>doView</emphasis> - , by simply creating it with a - <emphasis>renderURL</emphasis> - , that passes in our - <emphasis>yourname</emphasis> + Likewise, we are able to create a link to our <literal>doView</literal> method, by simply + creating it with a <literal>renderURL</literal>, that passes in our <literal>yourname</literal> parameter. </para> </listitem> @@ -798,103 +680,45 @@ </para> </sect3> <sect3> - <title>Building your portlet</title> - <para>If you have downloaded the sample, you can execute the build.xml with ANT or inside your IDE. - Executing the - <emphasis>deploy</emphasis> - target - will compile all src files and produce a helloworldportlet.war under - <emphasis>HelloWorldPortlet\helloworldjspportlet.war.</emphasis> - + <title>Building and deploying your portlet</title> + <para>If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. + Executing the <literal>deploy</literal> target will compile all source files and produce a + <literal>helloworldjspportlet.war</literal> file in a way similar to what we saw in + <xref linkend="first_portlet_build"/>. </para> <para> + The <literal>explode</literal> target will produce the following: <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsp_portlet/building.gif" valign="middle"/> - </imageobject> - </mediaobject> - </para> - <para> - If you want to create an expanded war directory, after executing the above deploy target, you should - execute the - <emphasis>explode</emphasis> - target. - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsp_portlet/buildexplode.gif" - valign="middle"/> - </imageobject> - </mediaobject> - </para> - <para> - The above target will produce the following: - <mediaobject> - <imageobject> <imagedata align="center" fileref="images/tutorials/jsp_portlet/exploded.gif" valign="middle"/> </imageobject> </mediaobject> - This will deflate the helloworldjspportlet.war, and allow you to deploy it as an expanded directory. It - will - work just the same, with some additional benefits noted below: </para> <para> - The advantage to expanded war deployments is that you can modify xml descriptors, resource files - jsp/jsf pages easily during development. Simply - <emphasis>touch</emphasis> - the web.xml to have JBoss Application Server hot-deploy the web appllication on a live-running server - instance - </para> - </sect3> - <sect3> - <title>Deploying your portlet</title> - <para> - Deploying a portlet is as simple as copying/moving the - <emphasis>helloworldjspportlet.war</emphasis> - in to the server deploy directory. Doing this on a running instance of the portal and application server, - will trigger a - <emphasis>hot-deploy</emphasis> - : - <programlisting><![CDATA[15:54:34,234 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: - CVSTag=JBoss_4_0_5_GA date=2006000000)] - Started in 1m:9s:766ms -15:55:04,062 INFO [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet, - warUrl=.../tmp/deploy/tmp57782helloworldjspportlet-exp.war/]]></programlisting> - Pointing your browser to - <ulink url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink> - , should yield a view of our HelloWorldPortlet: + 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>): <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsp_portlet/output.png" valign="middle"/> </imageobject> </mediaobject> </para> - </sect3> + </sect3> </sect2> - <sect2> - <title>A Simple JSF Portlet</title> + <sect2 id="myfaces_40x"> + <title>A Simple MyFaces JSF Portlet on JBoss AS 4.0.x</title> <sect3> <title>Introduction</title> - <para>This section will introduce the reader to deploying a simple JSF portlet in JBoss Portal. It requires - you - download the HelloWorldJSFPortlet from PortletSwap.com, using this - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - link</ulink> - . + <para>This section will introduce the reader to deploying a simple JSF portlet in JBoss Portal, using + Apache's MyFaces JSF implementation on JBoss AS 4.0.x. It requires you download the HelloWorldJSFPortlet + from PortletSwap.com, using this + <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...;. </para> - <para> - This portlet will introduce you to leveraging the JSF framework in portlet development. - </para> - </sect3> + </sect3> <sect3> - <title>Package Structure</title> + <title>Package Content</title> <para> - Portlets are packaged in war files, just like other JEE applications. A typical portlet war file can also - include servlets, resource bundles, images, html, jsps, and other static or dynamic files you would - commonly - include. - </para> - <para> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/package.gif" valign="middle"/> @@ -902,29 +726,15 @@ </mediaobject> Like a typical JSF application, we also package our faces-config.xml that defines our managed-beans, converters, validators, navigation rules, etc... - </para> - <para> - <note>When deploying on JBoss Application Seever, you do not need to package the myfaces libraries with - your portlet application. JBoss AS already bundles these libraries by default under - <emphasis>JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/jsf-libs/</emphasis> + <note>JBoss Application Server version 4.0.x bundles Apache's MyFaces JSF implementation in + <literal>JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/jsf-libs/</literal>. As a result, + you do not need to package MyFaces' libraries with your portlet application. </note> </para> - </sect3> - <sect3> - <title>The Application Descriptors</title> - <para> - JBoss Portal requires certain descriptors be included in your portlet war, for different reasons. Some of - these descriptors are defined by the Portlet Specification, and some are specific to JBoss Portal. For - brevity, we only discuss the - <emphasis>portlet.xml</emphasis> - and - <emphasis>faces-config.xml</emphasis> - descriptors here. For discussion on the other descriptors, please view - <xref linkend="first_portlet_descriptors"/> - or the - chapter on descriptors: - <xref linkend="descriptors_portlet"/> - . + <para>For the sake of brevity, we only discuss the <literal>portlet.xml</literal> and + <literal>faces-config.xml</literal> descriptors here. For discussion on the other descriptors, please + view <xref linkend="first_portlet_descriptors"/> or the chapter on descriptors: + <xref linkend="descriptors_portlet"/>. <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/package.gif" valign="middle"/> @@ -932,9 +742,8 @@ </mediaobject> <itemizedlist> <listitem> - <para> - portlet.xml - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + <para><literal>portlet.xml</literal> +<programlisting><![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... @@ -957,15 +766,15 @@ </portlet> </portlet-app>]]></programlisting> This file must adhere to its definition in the Portlet Specification. You may define more than - one portlet application in this file. Now lets look at the portions that deal with our use of + one portlet application in this file. Now let's look at the portions that deal with our use of JSF: <itemizedlist> <listitem> <para> - Here we define our portlet class, as we normally would. However, note the use of the - MyFacesGenericPortlet. In this case, we will allow the MyFacesGenericPortlet to handle - all requests/responses from our users: <programlisting><![CDATA[<portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class>]]></programlisting> + Here we specify that MyFacesGenericPortlet will handle all requests/responses from our + users. There is therefore no need to develop a specific portlet class, MyFaces + providing a generic implementation bridging the JSF and portlet worlds. <note>If you wanted to add more functionality to your JSF portlet, not included in the MyFacesGenericPortlet, you could sublass it and create your own Class.</note> </para> @@ -984,8 +793,8 @@ </para> </listitem> <listitem> - <para>faces-config.xml - <programlisting><![CDATA[<?xml version="1.0"?> + <para><literal>faces-config.xml</literal> +<programlisting><![CDATA[<?xml version="1.0"?> <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN" "http://java.sun.com/dtd/web-facesconfig_1_0.dtd"> @@ -1003,101 +812,80 @@ </navigation-case> </navigation-rule> </faces-config>]]></programlisting> - There is nothing special about the faces-config.xml included here. This application would work - just as well outside of a portlet as it would inside a portlet container. In the above lines, we - define a basic User Bean and a navigation rule to handle the submittal of the original form on - the index.jsp. + There is nothing special about the <literal>faces-config.xml</literal> file included here. This + application would work just as well outside of a portlet as it would inside a portlet container. + In the above lines, we define a basic <literal>User</literal> Bean and a navigation rule to + handle the submittal of the original form on <literal>index.jsp</literal>. </para> </listitem> </itemizedlist> </para> </sect3> <sect3> - <title>The JSP files</title> + <title>JSP files</title> + <para>TODO!!</para> </sect3> <sect3> - <title>Building your portlet</title> - <para>If you have downloaded the sample, you can execute the build.xml with ANT or inside your IDE. - Executing the - <emphasis>deploy</emphasis> - target - will compile all src files and produce a helloworldjsfportlet.war under - <emphasis>HelloWorldJSFPortlet\helloworldjsfportlet.war.</emphasis> - + <title>Building and deploying your portlet</title> + <para>If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. + Executing the <literal>deploy</literal> target will compile all source files and produce a + <literal>helloworldjspportlet.war</literal> file in a way similar to what we saw in + <xref linkend="first_portlet_build"/>. </para> <para> + The <literal>explode</literal> target will produce the following: <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/building.gif" valign="middle"/> - </imageobject> - </mediaobject> - </para> - <para> - If you want to create an expanded war directory, after executing the above deploy target, you should - execute the - <emphasis>explode</emphasis> - target. - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/buildexplode.gif" - valign="middle"/> - </imageobject> - </mediaobject> - </para> - <para> - The above target will produce the following: - <mediaobject> - <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/exploded.gif" valign="middle"/> </imageobject> </mediaobject> - This will deflate the helloworldjsfportlet.war, and allow you to deploy it as an expanded directory. It - will - work just the same, with some additional benefits noted below: </para> <para> - The advantage to expanded war deployments is that you can modify xml descriptors, resource files - jsp/jsf pages easily during development. Simply - <emphasis>touch</emphasis> - the web.xml to have JBoss Application Server hot-deploy the web application on a live-running server - instance - </para> - </sect3> - <sect3> - <title>Deploying your portlet</title> - <para> - Deploying a portlet is as simple as copying/moving the - <emphasis>helloworldjsfportlet.war</emphasis> - in to the server deploy directory. Doing this on a running instance of the portal and application server, - will trigger a - <emphasis>hot-deploy</emphasis> - : - <programlisting><![CDATA[22:30:03,093 INFO [TomcatDeployer] deploy, ctxPath=/helloworldjsfportlet, - warUrl=.../tmp/deploy/tmp5571helloworldjsfportlet-exp.war/ -22:30:03,312 INFO [FacesConfigurator] Reading standard config - org/apache/myfaces/resource/standard-faces-config.xml -22:30:03,390 INFO [FacesConfigurator] Reading config - jar:file:/C:/jboss-4.0.5.GA/server/default/tmp/deploy/ - tmp5504jboss-portal.sar-contents/lib/jsf-facelets.jar!/ - META-INF/faces-config.xml -22:30:03,406 INFO [FacesConfigurator] Reading config jar:file:/C:/jboss-4.0.5.GA/ - server/default/tmp/deploy/tmp5504jboss-portal.sar-contents/ - lib/tomahawk.jar!/META-INF/faces-config.xml -22:30:03,468 INFO [FacesConfigurator] Reading config /WEB-INF/faces-config.xml -22:30:03,484 ERROR [LocaleUtils] Locale name null or empty, ignoring -22:30:03,640 INFO [MyFacesGenericPortlet] PortletContext 'C:\jboss-4.0.5.GA\server\ - default\.\tmp\deploy\tmp5571helloworldjsfportlet-exp.war\' - initialized.]]></programlisting> - Pointing your browser to - <ulink url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink> - , should yield a view of our HelloWorldJSFPortlet: + 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>): <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/output.png" valign="middle"/> </imageobject> </mediaobject> </para> - </sect3> + </sect3> </sect2> + <sect2> + <title>Adapting MyFaces JSF Portlet to work on JBoss AS 4.2.x</title> + <para>We saw in <xref linkend="myfaces_40x"/> how to create a JSF-based portlet using Apache's MyFaces + JSF implementation on JBoss Application Server 4.0.x. Starting with version 4.2.0 of JBoss Application + Server, the default bundled JSF implementation is Sun's Reference Implementation (RI). We thus need to + adapt our MyFaces portlet sightly so that it works in this new environment. + </para> + <para>The first step is to provide access to MyFaces as it's not bundled anymore in JBoss AS. This is + accomplished by adding <literal>myfaces-api.jar</literal> and <literal>myfaces-impl.jar</literal> in + our portlet <literal>WEB-INF/lib</literal> directory. This can be done automatically via a modification of + the ant script and is left as an exercise to the reader. + </para> + <para> + We also need to need to tell JBoss AS not to use its bundled JSF implementation for our portlet. This + is accomplished by adding the following to our portlet's <literal>web.xml</literal>: + <programlisting><![CDATA[<context-param> + <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name> + <param-value>true</param-value> +</context-param>]]></programlisting> + More details on this procedure can be found at <ulink + url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossFaces">ht...;. + </para> + <para> + We should get the following package content for our portlet: + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_42x.png" valign="middle"/> + </imageobject> + </mediaobject> + </para> + </sect2> + <sect2> + <title>JSF Portlet using Sun's JSF Reference Implementation (RI)</title> + <para>TODO</para> + </sect2> </sect1> </chapter> \ No newline at end of file