[portal-commits] JBoss Portal SVN: r8091 - in docs: branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet and 4 other directories.

Author: thomas.heute(a)jboss.com Date: 2007-08-29 04:41:42 -0400 (Wed, 29 Aug 2007) New Revision: 8091 Added: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png Removed: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/building.gif docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/building.gif Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml docs/trunk/referenceGuide/en/master.xml docs/trunk/referenceGuide/en/modules/installation.xml docs/trunk/referenceGuide/en/modules/migration.xml docs/trunk/referenceGuide/en/modules/portalapi.xml Log: Merge docs in trunk and 2_6 branch Deleted: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif =================================================================== (Binary files differ) Deleted: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/building.gif =================================================================== (Binary files differ) Added: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif =================================================================== (Binary files differ) Deleted: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/building.gif =================================================================== (Binary files differ) Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -32,10 +32,10 @@ ]> <book lang="en"> <bookinfo> - <title>JBoss Portal 2.6.1-CR1</title> + <title>JBoss Portal 2.6.2</title> <subtitle>Reference Guide</subtitle> - <releaseinfo>Release 2.6.1-CR1 "Ninja"</releaseinfo> - <releaseinfo>June 2007</releaseinfo> + <releaseinfo>Release 2.6.2 "Ninja"</releaseinfo> + <releaseinfo>October 2007</releaseinfo> <author> <firstname>Thomas</firstname> <surname>Heute</surname> 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 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -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,28 +132,37 @@ } }]]> </programlisting> - Now lets dissect our simplest of portlets: + Now let's dissect our simplest of portlets: <itemizedlist> <listitem> <para> <programlisting>public class HelloWorldPortlet extends GenericPortlet</programlisting> - All Portlets MUST implement the javax.portlet.GenericPortlet Interface. + All Portlets MUST implement the <literal>javax.portlet.Portlet</literal> interface. The Portlet + API also provides a convenience 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. It also provides + a default implementation for <literal>processAction</literal>, <literal>init</literal> and + <literal>destory</literal> methods. It is recommended to extend <literal>GenericPortlet</literal> + for most cases. </para> </listitem> <listitem> <para> <programlisting>protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException, UnavailableException</programlisting> - In this case, our - <emphasis>doView</emphasis> - will be called when the portlet is asked to render output in VIEW Mode. + As we extend from <literal>GenericPortlet</literal> and we are only interested in supported the + <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 <literal>VIEW</literal> mode is requested. </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. + responding in. You need to do this before starting to write content or the portlet will throw + an exception. </para> </listitem> <listitem> @@ -165,11 +172,12 @@ 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 - surrounded by other portlets. + 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>body</literal> element. </note> </para> </listitem> @@ -177,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... @@ -221,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> @@ -230,15 +237,17 @@ <mime-type>text/html</mime-type> <portlet-mode>VIEW</portlet-mode> </supports>]]></programlisting> - The supports attributes allow you to declare extra vital information about the portlet. - In this case, we are letting the portal know that it will be outputting text/html and + The <literal>supports</literal> element allows you to declare all the markup types your + portlet supports in the <literal>render</literal> method. This is accomplish via the + <literal>mime-type</literal> element, which is <emphasis>required</emphasis> for every + portlet. Of course, the declared MIME types must match the capability of the portlet. + + It also allows you to pair + which modes and window states are supported for each markup type. In out case, as all + portlets must support the VIEW portlet mode, we didn't have to declare it. We did need + to declare that our portlet supports the <literal>text/html</literal> markup type. + Hence, we are letting the portal know that it will be outputting text/html and only support a VIEW mode. - <note> - A content-type must be declared here for every portlet, and it must match with how - the portlet is programmatically responding. Likewise, a portlet mode must be - declared here and have a corresponding method in its class. In our case, the VIEW - mode will map to the doView() in our class. - </note> </para> </listitem> <listitem> @@ -255,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"> @@ -269,23 +278,15 @@ </deployment> </deployments>]]></programlisting> This is a JBoss Portal specific descriptor that allows you create an instance of a portlet. The - <emphasis>portlet-ref</emphasis> - value must match the - <emphasis>portlet-name</emphasis> - value given in the packaged - <emphasis>portlet.xml</emphasis> - . The - <emphasis>instance-id</emphasis> - value can be named anything, but it must match the - <emphasis>instance-ref</emphasis> - value given in the - <emphasis>*-object.xml</emphasis> - file we will explore below. + <literal>portlet-ref</literal> value must match the <literal>portlet-name</literal> value + given in the packaged <literal>portlet.xml</literal>. The <literal>instance-id</literal> + value can be named anything, but it must match the <literal>instance-ref</literal> value given + in the <literal>*-object.xml</literal> file we will explore below. </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"> @@ -302,56 +303,30 @@ </deployment> </deployments>]]></programlisting> - The *-object.xml is responsible for creating/configuring windows, pages, and even portal - objects. In our example, we are creating a portlet window, assigning it to a page, and - specifying where it should appear on that page. This is a specific descriptor to JBoss Portal. - Since 2.6 we can replace also the window section by the following which will do exactly the same. - - <programlisting><![CDATA[<window> - <window-name>HelloWorldPortletWindow</window-name> - <content> - <content-type>portlet</content-type> - <content-uri>HelloWorldPortletInstance</content-uri> - </content> - <region>center</region> - <height>1</height> -</window> -]]></programlisting> - The kind of declaration allows to declare for a window different kind of content types. You can see - that as a generic way to declare content for a window. In our case the type of content is portlet - and the content uri declares the HelloWorldPortletInstance. The content uri value is the identifier of - the content. It is possible to declare windows with content type cms and use directly the path - to the file in the CMS to make the window show cms content. That behavior is pluggable and it - is virtually possible to plug in any kind of content. + <literal>*-object.xml</literal> files are JBoss Portal specific descriptors and allow users to + define the structure of their portal instances as well as create/configure thier windows and + pages. In our example, we create a portlet window, specify that it will display the markup + generated by the <literal>HelloWorldPortletInstance</literal> portlet instance, assign it to the + <literal>default.default</literal> page, and specify where it should appear on that page. + <itemizedlist> <listitem> <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> @@ -363,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> @@ -385,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" @@ -394,16 +363,46 @@ </imageobject> </mediaobject> </para> + + <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 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" + "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd"> +<deployments> + <deployment> + <parent-ref>default.default</parent-ref> + <if-exists>overwrite</if-exists> + <window> + <window-name>HelloWorldPortletWindow</window-name> + <content> + <content-type>portlet</content-type> + <content-uri>HelloWorldPortletInstance</content-uri> + </content> + <region>center</region> + <height>1</height> + </window> + </deployment> +</deployments>]]></programlisting> + + This declaration is equivalent to the previous example. We specify that the content being displayed by + the <literal>HelloWorldPortletWindow</literal> is a <literal>portlet</literal> content. The content URI + identifies which content to be displayed, in this case, the <literal>HelloWorldPortletInstance</literal>. + It is possible to declare windows with a <literal>cms</literal> content type and use directly the path to + the file in the CMS to make the window show the content of the associated file. That behavior is + 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> @@ -413,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" @@ -431,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"/> @@ -471,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 @@ -484,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; @@ -573,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> @@ -598,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> @@ -615,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" %> @@ -734,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> @@ -777,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"/> @@ -881,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"/> @@ -911,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... @@ -936,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> @@ -963,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"> @@ -982,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 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -53,26 +53,27 @@ HTML markup (as Portal itself doesn't handle other markup types). We do support explicit portlet cloning and we fully support the PortletManagement interface.</para> - <para>As far as caching goes, we have Level 1 Producer and Consumer. We support Cookie handling properly on the - Consumer and our Producer requires initialization of cookies (as we have found that it improved - interoperabilty with some consumers). We don't support custom window states or modes, as Portal doesn't either. - We do, however, support CSS on both the Producer (though it's more a function of the portlets than - inherent Producer capability) and Consumer.</para> + <para>As far as caching goes, we have Level 1 Producer and Consumer. We support Cookie handling properly on the + Consumer and our Producer requires initialization of cookies (as we have found that it improved interoperabilty + with some consumers). We don't support custom window states or modes, as Portal doesn't either. We do, however, + support CSS on both the Producer (though it's more a function of the portlets than inherent Producer + capability) and Consumer.</para> - <para>While we provide a complete implementation of WSRP 1.0, we do need to go through the - <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> and - perform more interoperability testing (an area that needs to be better supported by the WSRP Technical - Committee and Community at large).</para> + <para>While we provide a complete implementation of WSRP 1.0, we do need to go through the + <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> and + perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + Committee and Community at large).</para> </sect1> <sect1> <title>Deploying JBoss Portal's WSRP services</title> - <para>JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and offers - both consumer and producer services. WSRP support is provided by the <emphasis>portal-wsrp.sar</emphasis> - service archive, included in the main <emphasis>jboss-portal.sar</emphasis> service archive, if - you've obtained JBoss Portal from a binary distribution. If you don't intend on using WSRP, we - recommend that you remove the <emphasis>portal-wspr.sar</emphasis> from the main - <emphasis>jboss-portal.sar</emphasis> service archive.</para> + <para> + JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and offers + both consumer and producer services. WSRP support is provided by the <emphasis>portal-wsrp.sar</emphasis> + service archive, included in the main <emphasis>jboss-portal.sar</emphasis> service archive, if you've + obtained JBoss Portal from a binary distribution. If you don't intend on using WSRP, we recommend that you + remove the <emphasis>portal-wspr.sar</emphasis> from the main <emphasis>jboss-portal.sar</emphasis> service + archive.</para> <para>If you've obtained the source distribution of JBoss Portal, you need to build and deploy the WSRP service separately. Please follow the instructions on how to install <ulink url="http://docs.jboss.com/jbportal/v2.6/reference-guide/en/html/ins... Portal @@ -186,7 +187,7 @@ refer to <xref linkend="consumer_configuration"/>. </para> <para> - JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. + JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. You can access the WSDL file at <literal>http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl</literal>. You can access the endpoint URLs at: <itemizedlist> @@ -491,7 +492,7 @@ <deployment> <wsrp-producer id="self" expiration-cache="300"> <!-- - we need to use the individual endpoint configuration because the configuration via + we need to use the individual endpoint configuration because the configuration via wsdl forces an immediate attempt to access the web service description which is not available yet at this point of deployment --> @@ -582,7 +583,7 @@ <title>Default configuration</title> <para> Let's look at the default configuration: - <programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC + <programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN" "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd"> <?xml version="1.0" encoding="UTF-8"?> @@ -648,7 +649,7 @@ </para> <para>Please refer to the Javadoc for <literal>org.jboss.portal.registration.RegistrationPolicy</literal> and <literal>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</literal> for more details - on what is expected of each method. + on what is expected of each method. </para> <para>Defining a registration policy is required for the producer to be correctly configured. This is accomplished by specifying the qualified class name of the registration policy via the @@ -688,11 +689,11 @@ complete service description until they are correctly registered and requires consumers to provide acceptable values for two String registration properties named "name1" and "name2" respectively. The registration service will use the <literal>com.example.portal.SomeCustomRegistrationPolicy</literal> class for its - registration policy. + registration policy. <programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN" "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd"> -<?xml version="1.0" encoding="UTF-8"?> +<?xml version="1.0" encoding="UTF-8"?> <producer-configuration> <registration-configuration fullServiceDescriptionRequiresRegistration="true"> <registration-policy>com.example.portal.SomeCustomRegistrationPolicy</registration-policy> Modified: docs/trunk/referenceGuide/en/master.xml =================================================================== --- docs/trunk/referenceGuide/en/master.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/trunk/referenceGuide/en/master.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -32,9 +32,9 @@ ]> <book lang="en"> <bookinfo> - <title>JBoss Portal 2.6.0-GA</title> + <title>JBoss Portal 2.8.0</title> <subtitle>Reference Guide</subtitle> - <releaseinfo>Release 2.6.0-GA "Ninja"</releaseinfo> + <releaseinfo>Release 2.8.0</releaseinfo> <releaseinfo>June 2007</releaseinfo> <author> <firstname>Thomas</firstname> Modified: docs/trunk/referenceGuide/en/modules/installation.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/installation.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/trunk/referenceGuide/en/modules/installation.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -110,7 +110,8 @@ <sect3> <title>Application Server Setup</title> <para>Of course you will need to install JBoss Application Server prior to installing JBoss - portal, if you didn't do so yet, please install JBoss 4.0.5+ from + portal, if you didn't do so yet, please install JBoss EAP 4.2, JBoss AS 4.2.1 or JBoss AS 4.0.5 if + you have to. You can have access to the EAP version from the support portal or the other versions <ulink url="http://labs.jboss.com/portal/jbossas/download/index.html" @@ -126,7 +127,7 @@ </sect3> <sect3> <title>Database Setup</title> - <para>You will need a database for JBoss Portal to function, you can use any database + <para>You will need a database for JBoss Portal to run, you can use any database supported by Hibernate. <orderedlist> <listitem> @@ -271,7 +272,8 @@ <sect3> <title>Application Server Setup</title> <para>Of course you will need to install JBoss Application Server prior to installing JBoss - portal, if you didn't do so yet, please install JBoss 4.0.5+ from + portal, if you didn't do so yet, please install JBoss EAP 4.2, JBoss AS 4.2.1 or JBoss AS 4.0.5 if + you have to. You can have access to the EAP version from the support portal or the other versions <ulink url="http://labs.jboss.com/portal/jbossas/download/index.html" Modified: docs/trunk/referenceGuide/en/modules/migration.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/migration.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/trunk/referenceGuide/en/modules/migration.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -53,7 +53,7 @@ are visable. If you use default theme like "renaissance" that is present in 2.6, you shouldn't need to do anything. To update your custom themes please refer to those bundled with portal as an example. </para> - <note>If you stay with old theme files you may find JBP 2.6 unusable by not even be able to log in.</note> + <note>If you stay with old theme files you may find JBP 2.6 unusable to the point that you may not even be able to log in</note> </sect2> <sect2> <title>Database</title> Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-08-28 23:44:23 UTC (rev 8090) +++ docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-08-29 08:41:42 UTC (rev 8091) @@ -20,10 +20,10 @@ that no changes should be required when code is written against the API provided by the JBoss Portal 2.x versions and used in a later version of JBoss Portal 2.x.</para> - <para>The Portal API package prefix is <emphasis>org.jboss.portal.api</emphasis> and all the classes - part of the API are prefixed with that package except for two of them which are the <emphasis>org.jboss.portal.Mode</emphasis> - and <emphasis>org.jboss.portal.WindowState</emphasis> classes, the main reason being that twose two classes were defined - very early before the official Portal API framework was created.</para> + <para>The Portal API package prefix is <emphasis>org.jboss.portal.api</emphasis>. All of the classes that are part + of this API are prefixed with this package name except for the <emphasis>org.jboss.portal.Mode</emphasis> + and <emphasis>org.jboss.portal.WindowState</emphasis> classes. These two classes were defined before the official + Portal API framework was created and so the names have been maintained for backward compatibility.</para> <para>The Portlet API defines two classes that represents a portion of the visual state of a Portlet which are <emphasis>javax.portlet.PortletMode</emphasis> and <emphasis>javax.portlet.WindowState</emphasis>. Likewise the Portal API defines similar classes named <emphasis>org.jboss.portal.Mode</emphasis> and @@ -104,8 +104,8 @@ </caption> </mediaobject> <para>The <emphasis>org.jboss.portal.api.PortalRuntimeContext</emphasis> gives access to state or operations - associated at runtime with the current user of the portal. It allows to retrieve the user id when the method - <emphasis>String getUserId()</emphasis> returns a non null string. It also gives access to the + associated at runtime with the current user of the portal. The <emphasis>String getUserId()</emphasis> retrieve + the user id and can return null if no user is associated with the context. It also gives access to the <emphasis>PortalSession</emphasis> instance associated with the current user. Finally it gives access to the <emphasis>NavigationalStateContext</emphasis> associated with the current user.</para> </sect1> @@ -210,8 +210,8 @@ </mediaobject> <para> The <emphasis>org.jboss.portal.api.event.PortalEventContext</emphasis> interface defines the context in which - an event is created and propagated. It allows to retrieve the <emphasis>PortalRuntimeContext</emphasis> in - order to obtain the portal context. Note that this method may return null if no context is available. + an event is created and propagated. It allows retrieval of the <emphasis>PortalRuntimeContext</emphasis> which + can in turn be used to obtain the portal context. </para> <mediaobject> <imageobject> @@ -292,9 +292,9 @@ interface semantic allows only traditional event delivering. The <emphasis>PortalNodeEventListener</emphasis> interface is designed to match the bubbling effect during an event delivery.</para> <para>The <emphasis>PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)</emphasis> - declare a <emphasis>PortalNodeEvent</emphasis> as return type. In normal circumstances it will return the - null value, however if the method call returns an event then this event should be considered by the portal - as behavior replacing the current one. + method declares a <emphasis>PortalNodeEvent</emphasis> as return type. Commonly the method returns null; + however, a returned PortalNodeEvent replaces the event in the listeners subsequently called during + the event bubbling process. </para> </sect3> <sect3> @@ -459,7 +459,7 @@ <para>The first version of the Portlet Specification (JSR 168), regretfully, did not cover interaction between portlets. The side-effect of diverting the issue to the subsequent release of the specification, has forced portal vendors to each craft their own proprietary API to achieve interportlet communication. Here we will - see how we can use the event mechanism to pass parameters from one portlet to the other.</para> + see how we can use the event mechanism to pass parameters from one portlet to the other (and only to the other portlet).</para> <para>The overall scenario will be that Portlet B will need to be updated based on some parameter set on Portlet A. To achieve that we will use a portal node event.</para> <para>Portlet A is a simple Generic portlet that has a form that sends a color name: @@ -539,6 +539,12 @@ // We can redirect newEvent = new WindowActionEvent(windowB); newEvent.setParameters(wae.getParameters()); + + // Due to a bug those 2 following lines are required but have no meaning for now + // See: http://jira.jboss.com/jira/browse/JBPORTAL-1604 + newEvent.setMode(wae.getMode()); + newEvent.setWindowState(WindowState.MAXIMIZED); + // Redirect to the new event return newEvent; } @@ -570,6 +576,41 @@ newEvent.setWindowState(wae.getWindowState()); // WindowState.MAXIMIZED</programlisting> </para> --> + <para> + We still need to register our listener as an mbean: + <programlisting> +<![CDATA[<mbean + code="org.jboss.portal.core.event.PortalEventListenerServiceImpl" + name="portal:service=ListenerService,type=test_listener" + xmbean-dd="" + xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> + <xmbean/> + <depends + optional-attribute-name="Registry" + proxy-type="attribute">portal:service=ListenerRegistry</depends> + <attribute name="RegistryId">test_listener</attribute> + <attribute name="ListenerClassName">org.jboss.portal.core.samples.basic.event.PortletB$Listener</attribute> +</mbean>]]></programlisting> + For node events, we also need to declare on which node we want to listen, this is done by modifying + the <literal>*-object.xml</literal> that defines your portal nodes. In this example we want to trigger + the listener each time the window containing the portlet A is actioned. We can add the <literal>listener</literal> + tag to specify that out listener with <literal>RegistryId</literal>=test_listener should be triggered + on events on the embedding object. + <programlisting> +<![CDATA[... + <window> + <window-name>PortletAWindow</window-name> + <instance-ref>PortletAInstance</instance-ref> + <region>center</region> + <height>0</height> + <listener>test_listener</listener> + </window> +...]]> + </programlisting> + Of course we could have added it at the page level instead of the window level. Note that a unique listener + can be specified, the event mechanism is primarily done to let the developer change the navigation state of the + portal, this example being a nice side-effect of this feature. + </para> <note>The portlet 2.0 specification (JSR 286) will cover Inter Portlet Communication so that portlets using it can work with different portal vendors.</note> </sect2>