[portal-commits] JBoss Portal SVN: r8092 - in docs/trunk/referenceGuide/en: modules and 1 other directory.

Author: thomas.heute(a)jboss.com Date: 2007-08-29 06:18:40 -0400 (Wed, 29 Aug 2007) New Revision: 8092 Removed: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/package.gif Modified: docs/trunk/referenceGuide/en/modules/tutorials.xml Log: Updated reference documentation about JSF tutorials Deleted: docs/trunk/referenceGuide/en/images/tutorials/jsf_portlet/package.gif =================================================================== (Binary files differ) Modified: docs/trunk/referenceGuide/en/modules/tutorials.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-08-29 08:41:42 UTC (rev 8091) +++ docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-08-29 10:18:40 UTC (rev 8092) @@ -10,6 +10,11 @@ <surname>Laprun</surname> <email&gt;chris.laprun(a)jboss.com&lt;/email&gt; </author> + <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + <email&gt;thomas.heute(a)jboss.com&lt;/email&gt; + </author> </chapterinfo> <title>Portlet Primer</title> <sect1 id="portlet_primer"> @@ -706,14 +711,193 @@ </para> </sect3> </sect2> + <sect2 id="sunri_42x"> + <title>A simple Sun's JSF Reference Implementation (RI) portlet on JBoss AS 4.2.x</title> + <sect3> + <title>Introduction</title> + <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.2.x. It requires you download the HelloWorldJSFSunRIPortlet + from PortletSwap.com, using this link: + <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;. + </para> + </sect3> + <sect3> + <title>Package Content</title> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_sunri.png" valign="middle"/> + </imageobject> + </mediaobject> + Like a typical JSF application, we also package our faces-config.xml that defines our + managed-beans, converters, validators, navigation rules, etc... + <note>JBoss Application Server version 4.2.x bundles Sun's JSF Reference Implementation (RI) in + <literal>JBOSS_HOME/server/default/deploy/jboss-web.deployer/jsf-libs/</literal>. As a result, + you do not need to package Sun RI's libraries with your portlet application. + </note> + </para> + <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_sunri.png" valign="middle"/> + </imageobject> + </mediaobject> + <itemizedlist> + <listitem> + <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... + http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" + version="1.0"> + <portlet> + <portlet-name>HelloWorldJSFPortlet</portlet-name> + <portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class> + <init-param> + <name>com.sun.faces.portlet.INIT_VIEW</name> + <value>/WEB-INF/jsp/index.jsp</value> + </init-param> + <supports> + <mime-type>text/html</mime-type> + <portlet-mode>VIEW</portlet-mode> + </supports> + <portlet-info> + <title>HelloWorld JSF Portlet</title> + </portlet-info> + </portlet> +</portlet-app>]]></programlisting> + This file must adhere to its definition in the Portlet Specification. You may define more than + one portlet application in this file. Now let's look at the portions that deal with our use of + JSF: + <itemizedlist> + <listitem> + <para> + <programlisting><![CDATA[<portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class>]]></programlisting> + Here we specify that com.sun.faces.portlet.FacesPortlet will handle all requests/responses from our + users. This class is part of jsf-portlet.jar as explained later. + </para> + </listitem> + <listitem> + <para> + We need to initialize the portlet with a default view page for it to render, much like + a welcome page: + <programlisting><![CDATA[<init-param> + <name>com.sun.faces.portlet.INIT_VIEW</name> + <value>/WEB-INF/jsp/index.jsp</value> +</init-param>]]></programlisting> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <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"> +<faces-config> + <managed-bean> + <description>Basic UserBean</description> + <managed-bean-name>user</managed-bean-name> + <managed-bean-class>org.jboss.portlet.hello.bean.User</managed-bean-class> + <managed-bean-scope>session</managed-bean-scope> + </managed-bean> + <navigation-rule> + <navigation-case> + <from-outcome>done</from-outcome> + <to-view-id>/WEB-INF/jsp/result.jsp</to-view-id> + </navigation-case> + </navigation-rule> +</faces-config>]]></programlisting> + 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> + <listitem> + <para><literal>web.xml</literal> +<programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE web-app PUBLIC + "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" + "http://java.sun.com/dtd/web-app_2_3.dtd"> +<web-app> + + <!-- Faces Servlet --> + <servlet> + <servlet-name>Faces Servlet</servlet-name> + <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> + <load-on-startup>1</load-on-startup> + </servlet> + + + <!-- Faces Servlet Mapping --> + <servlet-mapping> + <servlet-name>Faces Servlet</servlet-name> + <url-pattern>*.jsf</url-pattern> + </servlet-mapping> + +</web-app>]]></programlisting> + For the Sun RI, this definition is mandatory to associate jsf extension with the faces servlet. + </para> + </listitem> + <listitem> + <para><literal>jsf-portlet.jar</literal> This library that can be downloaded here: <ulink url="https://jsfportletbridge.dev.java.net/servlets/ProjectDocumentL... + contains the classes for the JSF-Portlet bridge. Since they are not included with the JSF + implementation (unlike myfaces) neither in JBoss AS, it is required to have this library available + in the package.</para> + </listitem> + </itemizedlist> + </para> + </sect3> + <!-- + <sect3> + <title>JSP files</title> + <para>TODO!!</para> + </sect3> + --> + <sect3> + <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 <literal>ant</literal> 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/exploded.gif" valign="middle"/> + </imageobject> + </mediaobject> + </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>): + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/tutorials/jsf_portlet/output.png" valign="middle"/> + </imageobject> + </mediaobject> + </para> + </sect3> + </sect2> <sect2 id="myfaces_40x"> - <title>A Simple MyFaces JSF Portlet on JBoss AS 4.0.x</title> + <title>A simple MyFaces JSF Portlet on JBoss AS 4.0.5+</title> <sect3> <title>Introduction</title> <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...;. + Apache's MyFaces JSF implementation on JBoss AS 4.0.5+. It requires you download the HelloWorldJSFMyFacesPortlet + from PortletSwap.com, using this link: + <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;. </para> </sect3> <sect3> @@ -721,7 +905,7 @@ <para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/package.gif" valign="middle"/> + <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_myfaces.png" valign="middle"/> </imageobject> </mediaobject> Like a typical JSF application, we also package our faces-config.xml that defines our @@ -737,7 +921,7 @@ <xref linkend="descriptors_portlet"/>. <mediaobject> <imageobject> - <imagedata align="center" fileref="images/tutorials/jsf_portlet/package.gif" valign="middle"/> + <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_myfaces.png" valign="middle"/> </imageobject> </mediaobject> <itemizedlist> @@ -821,17 +1005,20 @@ </itemizedlist> </para> </sect3> + <!-- <sect3> <title>JSP files</title> <para>TODO!!</para> </sect3> + --> <sect3> <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 + Executing <literal>ant</literal> will compile all source files and produce a + <literal>helloworldjsfportlet.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> @@ -840,6 +1027,7 @@ </imageobject> </mediaobject> </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 @@ -883,9 +1071,5 @@ </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