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

Author: thomas.heute(a)jboss.com Date: 2008-08-28 07:12:43 -0400 (Thu, 28 Aug 2008) New Revision: 11755 Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml Log: Added some documentation Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml 2008-08-28 09:05:23 UTC (rev 11754) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml 2008-08-28 11:12:43 UTC (rev 11755) @@ -1,4 +1,6 @@ -<chapter id="portalapi"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"><chapter id="portalapi"> <chapterinfo> <author> <firstname>Julien</firstname> @@ -28,12 +30,12 @@ <emphasis>org.jboss.portal.WindowState</emphasis> which offer comparable characteristics, the main differences are:</para> <itemizedlist> - <listitem>Usage of factory methods to obtain instances.</listitem> - <listitem>Classes implements the <emphasis>java.io.Serializable</emphasis> interface.</listitem> + <listitem><para>Usage of factory methods to obtain instances.</para></listitem> + <listitem><para>Classes implements the <emphasis>java.io.Serializable</emphasis> interface.</para></listitem> </itemizedlist> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/Mode.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/Mode.png" format="PNG"/> </imageobject> <caption> <para>The Mode class</para> @@ -41,45 +43,81 @@ </mediaobject> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/WindowState.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/WindowState.png" format="PNG"/> </imageobject> <caption> <para>The WindowState class</para> </caption> </mediaobject> - <note>In the Portal API, the <emphasis>Mode</emphasis> interface is named like this because it does + <note><para>In the Portal API, the <emphasis>Mode</emphasis> interface is named like this because it does represent the mode of some visual object. The Portlet API names it <emphasis>PortletMode</emphasis> because - it makes the assumption that the underlying object is of type Portlet.</note> + it makes the assumption that the underlying object is of type Portlet.</para></note> </sect1> + <sect1> + <title>Portlet to Portal communication</title> + <para>There are times when a portlet needs to signal the portal or share information with it. The portal is the only authority + to decide if it will take into account that piece of information or ignore it. In JBoss Portal we use as much as possible the + mechanisms offered by the portlet spec to achieve that communication.</para> + <sect2> + <title>Requesting a sign out</title> + <para> + If a portlet desires to sign out the user, it can let the portal know by triggering a JSR-286 portlet event. + To do so, simply defines the event "signOut" in the namespace "urn:jboss:portal" as a publishing event. + In the action phase of the portlet, trigger the event, as a payload you can specify a redirection URL. If the payload is null, + it will redirect the user to the default page of the default portal. + See the following snippet to use in the action phase, it will ask the portal to sign out the user and redirect him to the JBoss + Portal blog: + <programlisting role="java"><![CDATA[QName name = new QName("urn:jboss:portal", "signOut"); +response.setEvent(name, "http://blog.jboss-portal.org"); ]]></programlisting> + </para> + </sect2> + <sect2> + <title>Setting up the web browser title</title> + <para> + The JSR-286 specification introduced a new phase for setting up the HTML headers. It is commonly used to add stylesheets + and javascript to the page. An extension of it for JBoss Portal lets you define the web browser title. + To define the web browser title, a portlet simply needs to define a new header element "title". This could be done by a portlet overriding + the method <literal>doHeaders(RenderRequest req, RenderResponse resp)</literal> to add such an element. + <programlisting role="java"><![CDATA[public void doHeaders(RenderRequest req, RenderResponse resp) +{ + Element element = resp.createElement("title"); + element.setTextContent("My new web browser title"); + resp.addProperty(MimeResponse.MARKUP_HEAD_ELEMENT, element); +}]]></programlisting> + <warning><para>It several portlets on a page defines a web browser title, only one of them will be displayed. + We can consider that the title to be displayed will be randomly chosen.</para></warning> + </para> + </sect2> + </sect1> <sect1> <title>Portal URL</title> <para>The Portal API defines the <emphasis>org.jboss.portal.api.PortalURL</emphasis> interface to represent URL managed by the portal.</para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalURL.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalURL.png" format="PNG"/> </imageobject> <caption> <para>The PortalURL interface</para> </caption> </mediaobject> <itemizedlist> - <listitem>The <emphasis>setAuthenticated(Boolean wantAuthenticated)</emphasis> methods defines if the + <listitem><para>The <emphasis>setAuthenticated(Boolean wantAuthenticated)</emphasis> methods defines if the URL requires the authentication of the user. If the argument value is true then the user must be authenticated to access the URL, if the argument value is false then the user should not be authenticated. Finally if the argument value is - null then it means that the URL authenticated mode should reuse the current mode.</listitem> - <listitem>The <emphasis>setSecure(Boolean wantSecure)</emphasis> methods defines the same as above but for the - transport guarantee offered by the underlying protocol which means most of the time the secure HTTP protocol (HTTPS).</listitem> - <listitem>The <emphasis>setRelative(boolean relative)</emphasis> defines the output format of the URL and - whether the created URL will be an URL relative to the same web server or will be the full URL.</listitem> - <listitem>The <emphasis>toString()</emphasis> method will create the URL as a string.</listitem> + null then it means that the URL authenticated mode should reuse the current mode.</para></listitem> + <listitem><para>The <emphasis>setSecure(Boolean wantSecure)</emphasis> methods defines the same as above but for the + transport guarantee offered by the underlying protocol which means most of the time the secure HTTP protocol (HTTPS).</para></listitem> + <listitem><para>The <emphasis>setRelative(boolean relative)</emphasis> defines the output format of the URL and + whether the created URL will be an URL relative to the same web server or will be the full URL.</para></listitem> + <listitem><para>The <emphasis>toString()</emphasis> method will create the URL as a string.</para></listitem> </itemizedlist> </sect1> <sect1> <title>Portal session</title> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalSession.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalSession.png" format="PNG"/> </imageobject> <caption> <para>The PortalSession interface</para> @@ -95,7 +133,7 @@ <title>Portal runtime context</title> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalRuntimeContext.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalRuntimeContext.png" format="PNG"/> </imageobject> <caption> <para>The PortalRuntimeContext interface</para> @@ -113,13 +151,13 @@ <para>The portal structure is a tree formed by nodes. It is possible to programmatically access the portal tree in order to </para> <itemizedlist> - <listitem>discover the tree structure of the portal</listitem> - <listitem>create URL that will render the different portal nodes</listitem> - <listitem>access the properties of a specific node</listitem> + <listitem><para>discover the tree structure of the portal</para></listitem> + <listitem><para>create URL that will render the different portal nodes</para></listitem> + <listitem><para>access the properties of a specific node</para></listitem> </itemizedlist> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalNode.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalNode.png" format="PNG"/> </imageobject> <caption> <para>The PortalNode interface</para> @@ -142,9 +180,9 @@ <para>The interface offers methods to retrieve informations for a given node such as the node type, the node name or the properties of the node. The noticeable node types are:</para> <itemizedlist> - <listitem>PortalNode.TYPE_PORTAL : the node represents a portal</listitem> - <listitem>PortalNode.TYPE_PAGE : the node represents a portal page</listitem> - <listitem>PortalNode.TYPE_WINDOW : the node represents a page window</listitem> + <listitem><para>PortalNode.TYPE_PORTAL : the node represents a portal</para></listitem> + <listitem><para>PortalNode.TYPE_PAGE : the node represents a portal page</para></listitem> + <listitem><para>PortalNode.TYPE_WINDOW : the node represents a page window</para></listitem> </itemizedlist> <para>The <emphasis>org.jboss.portal.api.node.PortalNodeURL</emphasis> is an extension of the <emphasis>PortalURL</emphasis> interface which adds additional methods useful for setting parameters on the URL. There are no guarantees that the @@ -174,7 +212,7 @@ mode and window states of portal nodes of type window.</para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/NavigationalStateContext.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/NavigationalStateContext.png" format="PNG"/> </imageobject> <caption> <para>The NavigationalStateContext interface</para> @@ -189,7 +227,7 @@ </para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalEvent.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalEvent.png" format="PNG"/> </imageobject> <caption> <para>The PortalEvent class</para> @@ -200,7 +238,7 @@ </para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalEventContext.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalEventContext.png" format="PNG"/> </imageobject> <caption> <para>The PortalEventContext interface</para> @@ -213,7 +251,7 @@ </para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalEventListener.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalEventListener.png" format="PNG"/> </imageobject> <caption> <para>The PortalEventListener interface</para> @@ -229,9 +267,9 @@ and register it with the service registry. We will see how to achieve that in the example section of this chapter. </para> <note> - The event propagation model uses one instance of a listener class to receive all portal events that + <para>The event propagation model uses one instance of a listener class to receive all portal events that may be routed to that class when appropriate. Therefore implementors needs to be aware of that model - and must provide <emphasis role="bold">thread safe</emphasis> implementations. + and must provide <emphasis role="bold">thread safe</emphasis> implementations.</para> </note> <sect2> <title>Portal node events</title> @@ -240,7 +278,7 @@ a corresponding event will be fired.</para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalNodeEvent.png" format="png" scalefit="1"/> + <imagedata align="center" fileref="images/portalapi/PortalNodeEvent.png" format="PNG" scalefit="1"/> </imageobject> <caption> <para>The portal node event class hierarchy</para> @@ -275,7 +313,7 @@ </para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/eventpropagation.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/eventpropagation.png" format="PNG"/> </imageobject> <caption> <para>The portal node event propagation model</para> @@ -299,7 +337,7 @@ <title>Portal node event context</title> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalNodeEventContext.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalNodeEventContext.png" format="PNG"/> </imageobject> <caption> <para>The PortalNodeEventContext interface</para> @@ -331,7 +369,7 @@ event is not bound to a portal node since it is triggered whenever a portal session is created or destroyed</para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/PortalSessionEvent.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/PortalSessionEvent.png" format="PNG"/> </imageobject> <caption> <para>The PortalSessionEvent class</para> @@ -339,8 +377,8 @@ </mediaobject> <para>There are two different types of events: <itemizedlist> - <listitem>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_CREATED, fired when a new portal session is created</listitem> - <listitem>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_DESTROYED, fired when a new portal session is destroyed</listitem> + <listitem><para>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_CREATED, fired when a new portal session is created</para></listitem> + <listitem><para>org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_DESTROYED, fired when a new portal session is destroyed</para></listitem> </itemizedlist> </para> </sect2> @@ -351,7 +389,7 @@ the method <emphasis>String getId()</emphasis>.</para> <mediaobject> <imageobject> - <imagedata align="center" fileref="images/portalapi/user.event.png" format="png"/> + <imagedata align="center" fileref="images/portalapi/user.event.png" format="PNG"/> </imageobject> <caption> <para>The UserEvent class and UserAuthenticationEvent sub-classes</para> @@ -359,8 +397,8 @@ </mediaobject> <para>The UserAuthenticationEvent triggers two events that can be catched: <itemizedlist> - <listitem>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_IN, fired when a portal user signs in</listitem> - <listitem>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_OUT, fired when a portal user signs out</listitem> + <listitem><para>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_IN, fired when a portal user signs in</para></listitem> + <listitem><para>org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_OUT, fired when a portal user signs out</para></listitem> </itemizedlist> </para> <para>Based on the UserEvent class other custom user related events could be added like one that would trigger when a new user is @@ -377,7 +415,7 @@ do that we just need to keep track of Sign-in and Sign-out events.</para> <para>First, let's write our listener. It just a class that will implement <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> and its unique method <emphasis>void onEvent(PortalEventContext eventContext, PortalEvent event)</emphasis>. Here is such an example: - <programlisting><![CDATA[ + <programlisting role="java"><![CDATA[ package org.jboss.portal.core.portlet.test.event; import[...] @@ -439,14 +477,14 @@ This snippet can be kept as it is, providing you change the values: <itemizedlist> <listitem> - <emphasis role="bold">name:</emphasis> Must follow the pattern: portal:service=ListenerService,type={{UNIQUENAME}} + <para><emphasis role="bold">name:</emphasis> Must follow the pattern: portal:service=ListenerService,type={{UNIQUENAME}}</para> </listitem> <listitem> - <emphasis role="bold">RegistryId:</emphasis> Must match the type (here: counter_listener) + <para><emphasis role="bold">RegistryId:</emphasis> Must match the type (here: counter_listener)</para> </listitem> <listitem> - <emphasis role="bold">ListenerClassName:</emphasis> Full path to the listener - (here: org.jboss.portal.core.portlet.test.event.UserCounterListener). + <para><emphasis role="bold">ListenerClassName:</emphasis> Full path to the listener + (here: org.jboss.portal.core.portlet.test.event.UserCounterListener).</para> </listitem> </itemizedlist> </para> @@ -517,7 +555,7 @@ as a request parameter in our case). In order to achieve this goal, we will write an inner Listener in Portlet B that will be triggered on any WindowActionEvent of Portlet A. This listener will create a new WindowActionEvent on the window of Portlet B. - <programlisting><![CDATA[ + <programlisting role="java"><![CDATA[ public static class Listener implements PortalNodeEventListener { public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) @@ -574,7 +612,7 @@ --> <para> We still need to register our listener as an mbean: - <programlisting> + <programlisting role="xml"> <![CDATA[<mbean code="org.jboss.portal.core.event.PortalEventListenerServiceImpl" name="portal:service=ListenerService,type=test_listener" @@ -609,8 +647,8 @@ 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> + <note><para>The portlet 2.0 specification (JSR 286) will cover Inter Portlet Communication so that portlets using it + can work with different portal vendors.</para></note> </sect2> <sect2> <title>Link to other pages</title> @@ -618,7 +656,7 @@ specification. As seen previously JBoss Portal offers an API in order to create links to other portal nodes. The JBoss request gives access to the current window node from which we can navigate from.</para> - <programlisting> + <programlisting role="java"> <![CDATA[ // Get the ParentNode. Since we are inside a Window, the Parent is the Page PortalNode thisNode = req.getPortalNode().getParent(); @@ -636,13 +674,13 @@ <para>From this, it is easy to create a menu or sitemap, the <emphasis>List getChildren()</emphasis> method will return all the child nodes on which the user has the view right access.</para> </sect2> - <note> + <sect2> <title>Samples</title> <para>Those examples are available in the core-samples package in the sources of JBoss Portal. There are more examples of events usage in the samples delivered with JBoss Portal. One of them shows the usage of a portal node event to only have one window in normal mode at a time in a region. Anytime another window is being put in normal mode, all the other windows of the same regions are automatically minimized.</para> - </note> + </sect2> </sect1> </chapter> Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml 2008-08-28 09:05:23 UTC (rev 11754) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml 2008-08-28 11:12:43 UTC (rev 11755) @@ -389,7 +389,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>JBoss Portal</title> + <title><p:title default="My Great Portal"/></title> <meta http-equiv="Content-Type" content="text/html;" /> <p:theme themeName='renaissance' /> <p:headerContent /> @@ -425,8 +425,14 @@ </body> </html>]]></programlisting> </para> - <para> <sect3> + <title>The title tag</title> + <para>The title tag is used to insert the web browser title defined by a portlet which + is part of the page rendering. The default attribute defines the title to use if no + portlet defined a web browser title. + </para> + </sect3> + <sect3> <title>The theme tag</title> <para>The theme tag looks for the determined theme of the current request (see Portal Themes for more details). If no theme was determined, this tag allows an @@ -456,7 +462,6 @@ for this region. This id in turn can be picked up by the CSS to style the region. </para> </sect3> - </para> </sect2> </sect1> <!-- Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml 2008-08-28 09:05:23 UTC (rev 11754) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml 2008-08-28 11:12:43 UTC (rev 11755) @@ -51,6 +51,7 @@ </para> </listitem> </itemizedlist> + <note>The default page or portal can be specified either by using the admin portlet or by using the XML descriptors as explained in the <link linkend="xml.default.objectname.property">XML descriptor chapter</link>.</note> </para> </sect1> <sect1> Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-08-28 09:05:23 UTC (rev 11754) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-08-28 11:12:43 UTC (rev 11755) @@ -4,17 +4,19 @@ <chapter id="xmldescriptors"> <chapterinfo> <author> + <firstname>Thomas</firstname> + <surname>Heute</surname> + </author> + <author> <firstname>Roy</firstname> <surname>Russo</surname> </author> </chapterinfo> <title>XML Descriptors</title> <sect1> - <title>Changes from previous Releases</title> - <para>The previous releases of JBoss Portal did not have an external schema to validate XML descriptors; however, they were internally validated by the portal. Since JBoss Portal 2.6, a Document Type Definition (DTD) has been provided to validate descriptors. - </para> + <title>DTDs</title> <para> - To use the DTD, add the following declaration to the start of the desired descriptors: + To use a DTD, add the following declaration to the start of the desired descriptors: </para> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> @@ -631,13 +633,42 @@ <!ELEMENT properties (property*)>]]> </programlisting> <para> - A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</computeroutput> elements contains definitions specific to a page. This is commonly used to define the specific theme and layout to use. If not defined, the default portal theme and layout are used. + A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</computeroutput> elements contains definitions specific to a portal object. </para> <programlisting><![CDATA[ <!ELEMENT property (name,value)>]]> </programlisting> <para> A generic string property. + The following non exhaustive values are used: + <table> + <title>Properties</title> + <tgroup cols="2" align="left" colsep="1" rowsep="1"> + <colspec colname="name"/> + <colspec colname="description"/> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>layout.id</entry> + <entry>Defines the layout to use for this portal object and sub-objects if they don't override the value</entry> + </row> + <row> + <entry>theme.id</entry> + <entry>Defines the theme to use for this portal object and sub-objects if they don't override the value</entry> + </row> + <row id="xml.default.objectname.property"> + <entry>portal.defaultObjectName</entry> + <entry>This value is used to define the default child object. If applied on a <literal>context</literal>, it will define which portal is the default one. + If applied on a <literal>portal</literal>, it will define which page is the default one.</entry> + </row> + </tbody> + </tgroup> + </table> </para> <programlisting><![CDATA[ <!ELEMENT name (#PCDATA)>]]> @@ -1829,7 +1860,7 @@ <note> <title>Portal Instance <computeroutput>default</computeroutput> Page</title> <para> - For a portal instance to be accessible via a Web browser, you must define a page named <computeroutput>default</computeroutput>. + For a portal instance to be accessible via a Web browser, you must define a default page. </para> </note> </para>