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>chris.laprun(a)jboss.com</email>
</author>
+ <author>
+ <firstname>Thomas</firstname>
+ <surname>Heute</surname>
+ <email>thomas.heute(a)jboss.com</email>
+ </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