[portal-commits] JBoss Portal SVN: r9997 - docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules.

Author: mmcallis Date: 2008-02-15 21:54:58 -0500 (Fri, 15 Feb 2008) New Revision: 9997 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml Log: revising 5.2.3. An example Sun JSF Reference Implementation (RI) Portle *** this will break the book until later commits *** Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2008-02-15 21:44:13 UTC (rev 9996) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2008-02-16 02:54:58 UTC (rev 9997) @@ -141,7 +141,7 @@ <sect3> <title>Introduction</title> <para> - This section describes how to deploy a portlet for JBoss Portal. Before proceeding, download the <ulink + 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> </sect3> @@ -264,7 +264,10 @@ </mediaobject> </para> <para> - The following is an example of the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> file. In order to create the <filename>WEB-INF/</filename> and <filename>META-INF/</filename> directories, extract the <filename>helloworldportlet.war</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: + 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[ @@ -640,16 +643,16 @@ <sect3> <title>Introduction</title> <para> - This section describes how to deploy a JSP portlet for 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 JSPs for view rendering, and the portlet taglib for generating links. + This section describes how to deploy a JSP 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 JSPs for view rendering, and the portlet tag library (taglib) for generating links. </para> </sect3> <sect3> - <title>Package Content</title> + <title>Package Structure</title> <para> The application descriptors for the HelloWorldJSPPortlet portlet are similar to those from the HelloWorldPortlet (<xref linkend="first_portlet_descriptors"/>). See <xref linkend="descriptors_portlet"/> for further information about application descriptors. </para> <para> - The following is an example of the directory structure of the HelloWorldJSPPortlet portlet. The HelloWorldJSPPortlet portlet contains the traditional portlet and JBoss Portal specific application descriptors. In order to create the <filename>WEB-INF/</filename> and <filename>META-INF/</filename> directories, extract the <filename>helloworldjspportlet.war</filename> file. + 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> @@ -658,9 +661,12 @@ </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> </sect3> <sect3> - <title>Portlet Class</title> + <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> @@ -789,7 +795,7 @@ <sect3> <title>JSP 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> JSP 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 <literal>render</literal> method, <computeroutput>doView</computeroutput>, is invoked, which dispatches to the <filename>view2.jsp</filename> JSP: + The <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> and <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp</filename> JSP 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> @@ -831,7 +837,7 @@ </screen></term> <listitem> <para> - Define the portlet tag library (taglib). You do not need to bundle the portlet taglib - JBoss Portal handles this for you. + Define the portlet taglib. You do not need to bundle the portlet taglib - JBoss Portal handles this for you. </para> </listitem> </varlistentry> @@ -861,7 +867,7 @@ </screen></term> <listitem> <para> - You can create a link to the <computeroutput>doView</computeroutput> method by creating a <computeroutput>renderURL</computeroutput>, that passes the <computeroutput>yourname</computeroutput> parameter. + 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> @@ -972,7 +978,7 @@ </para> <para> <screen> -touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy//helloworldjspportlet.war/WEB-INF/web.xml +touch $JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjspportlet.war/WEB-INF/web.xml </screen> </para> <para> @@ -989,43 +995,59 @@ </sect3> </sect2> <sect2 id="sunri_42x"> - <title>A Sun JSF Reference Implementation (RI) portlet</title> + <title>An example Sun JSF Reference Implementation (RI) Portlet</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> + This section describes how to deploy a JSF portlet in JBoss Portal, using the Apache MyFaces JSF implementation on JBoss AS or 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> </sect3> <sect3> - <title>Package Content</title> + <title>Package Structure</title> + <para> + JBoss Portal requires certain descriptors to be included in a portlet WAR file. Some of these descriptors are defined by the JSR-168 Portlet Specification, and others are specific to JBoss Portal. Like a typical JSF application, the HelloWorldJSFSunRIPortlet package contains a <filename>faces-config.xml</filename> file, that defines managed-beans, converters, validators, navigation rules, and so on. The following is an example of the directory structure of the HelloWorldJSFSunRIPortlet portlet: + </para> <para> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_sunri.png" valign="middle"/> </imageobject> </mediaobject> - 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. + </para> + <para> + To create the <filename>WEB-INF/</filename> and <filename>META-INF/</filename> directories, extract the helloworldjsfsunriportlet.war file. + </para> + <para> + <note> + <title>Bundled Sun JSF RI</title> + <para> + JBoss AS version 4.2.<replaceable>x</replaceable> and JBoss EAP bundle Sun's JSF RI 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> - <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"/>. + </sect3> + <sect3> + <title>Application Descriptors</title> + <para> + For brevity, only the <filename>portlet.xml</filename>, <filename>faces-config.xml</filename>, and <filename>web.xml</filename> descriptors are defined. For more information on other discriptors, refer to <xref linkend="first_portlet_descriptors"/> and <xref linkend="descriptors_portlet"/>. + </para> + <para> + The following is an example of the directory structure of the HelloWorldJSFSunRIPortlet portlet: + </para> + <para> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/jsf_portlet/package_sunri.png" valign="middle"/> </imageobject> </mediaobject> - <itemizedlist> - <listitem> - <para><literal>portlet.xml</literal> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + </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" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... @@ -1046,31 +1068,34 @@ <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> +</portlet-app>]]> +</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 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>]]></programlisting> - </para> - </listitem> - </itemizedlist> - </para> - </listitem> +</init-param>]]> +</screen></term> +<listitem> + <para> + You must initializes the portlet with a default view page to render, similar to the default JBoss Portal page. + </para> +</listitem> +</variabelist> +</para> + <listitem> <para><literal>faces-config.xml</literal> <programlisting><![CDATA[<?xml version="1.0"?>