3:26 p.m.
Author: thomas.heute(a)jboss.com
Date: 2007-10-18 16:26:35 -0400 (Thu, 18 Oct 2007)
New Revision: 8700
Added:
docs/template/
docs/template/svn-commit.tmp
docs/template/user-guide/
docs/template/user-guide/build.xml
docs/template/user-guide/en/
docs/template/user-guide/en/ajax.xml
docs/template/user-guide/en/images/
docs/template/user-guide/en/images/sample/
docs/template/user-guide/en/images/sample/partial-refresh.png
docs/template/user-guide/en/master.xml
docs/template/user-guide/en/modules/
docs/template/user-guide/en/modules/sample.xml
Log:
Initial import
Added: docs/template/svn-commit.tmp
===================================================================
--- docs/template/svn-commit.tmp (rev 0)
+++ docs/template/svn-commit.tmp 2007-10-18 20:26:35 UTC (rev 8700)
@@ -0,0 +1,4 @@
+Initial import
+--This line, and those below, will be ignored--
+
+A .
Added: docs/template/user-guide/build.xml
===================================================================
--- docs/template/user-guide/build.xml (rev 0)
+++ docs/template/user-guide/build.xml 2007-10-18 20:26:35 UTC (rev 8700)
@@ -0,0 +1,26 @@
+<project name="CHANGE ME IN BUILD.XML" default="all.doc"
basedir=".">
+
+ <!-- Set the following property to generate the doco in the output folder -->
+ <!--property name="build.dir"
value="${basedir}/../../output/docs/guide"/-->
+
+ <property name="pdf.name"
value="ChangeMeInBuildXML.pdf" />
+ <import file="docbook-support/support.xml" />
+
+ <target name="en">
+ <antcall target="lang.dochtml">
+ <param name="lang" value="en"/>
+ </antcall>
+ </target>
+
+ <target name="all.doc" depends="clean">
+ <antcall target="lang.all"><param name="lang"
value="en"/></antcall>
+ </target>
+
+ <!-- Use this alternate target to enable uptodate checking, i.e.
+ don't generate docs if nothing has changed
+ <target name="all.doc">
+ <antcall target="lang.all.run"><param name="lang"
value="en"/></antcall>
+ </target>
+ -->
+
+</project>
Property changes on: docs/template/user-guide/build.xml
___________________________________________________________________
Name: svn:executable
+
Added: docs/template/user-guide/en/ajax.xml
===================================================================
--- docs/template/user-guide/en/ajax.xml (rev 0)
+++ docs/template/user-guide/en/ajax.xml 2007-10-18 20:26:35 UTC (rev 8700)
@@ -0,0 +1,273 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ajax">
+ <chapterinfo>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien.viet(a)jboss.com</email>
+ </author>
+ </chapterinfo>
+ <title>Ajax</title>
+ <para>This section covers the ajax features provided by the
portal.</para>
+ <sect1>
+ <title>Introduction</title>
+ <para>Todo</para>
+ </sect1>
+ <sect1>
+ <title>Ajaxified markup</title>
+ <sect2>
+ <title>Ajaxified layouts</title>
+ <para>Part of the Ajax capabilities are implemented in the layout
framework which provide the structure for
+ generating portal pages. The good news is that the existing layout only requires
a few modifications in
+ order to be ajaxified.</para>
+ <para>We will use as example an simplified version of the layout JSP
provided in JBoss Portal 2.6 and outline
+ what are the required changes that makes it an ajaxified layout:
+ <programlisting><![CDATA[
+<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p"
%>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="Content-Type" content="text/html;"/>
+ <!-- inject the theme, default to the Renaissance theme if
+ nothing is selected for the portal or the page -->
+ <p:theme themeName="renaissance"/>
+ <!-- insert header content that was possibly set by portlets on the page -->
+ <p:headerContent/>
+</head>
+
+<body id="body">
+<p:region regionName='AJAXScripts' regionID='AJAXScripts'/>
+<div id="portal-container">
+ <div id="sizer">
+ <div id="expander">
+ <div id="logoName"></div>
+ <table border="0" cellpadding="0"
cellspacing="0" id="header-container">
+ <tr>
+ <td align="center" valign="top"
id="header">
+
+ <!-- Utility controls -->
+ <p:region regionName='dashboardnav'
regionID='dashboardnav'/>
+
+ <!-- navigation tabs and such -->
+ <p:region regionName='navigation'
regionID='navigation'/>
+ <div id="spacer"></div>
+ </td>
+ </tr>
+ </table>
+ <div id="content-container">
+ <!-- insert the content of the 'left' region of the page,
+ and assign the css selector id 'regionA' -->
+ <p:region regionName='left' regionID='regionA'/>
+ <!-- insert the content of the 'center' region of the page,
+ and assign the css selector id 'regionB' -->
+ <p:region regionName='center' regionID='regionB'/>
+ <hr class="cleaner"/>
+ </div>
+ </div>
+ </div>
+</div>
+
+<p:region regionName='AJAXFooter' regionID='AJAXFooter'/>
+
+</body>
+</html>
+]]></programlisting>
+ <itemizedlist>
+ <listitem><![CDATA[<p:theme
themeName="renaissance"/>]]> should be already present as it exists since
2.4 but is even more
+ necessary as it will inject in the page the reference to the ajax
stylesheet.</listitem>
+ <listitem><![CDATA[<p:region regionName='AJAXScripts'
regionID='AJAXScripts'/>]]> should be added before any other region
+ in the markup of the layout.</listitem>
+ <listitem><![CDATA[<p:region regionName='AJAXFooter'
regionID='AJAXFooter'/>]]> should be added after any other region
+ in the markup of the layout.</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Ajaxified renderers</title>
+ <para>At runtime the portal combines the layout and the renderers in order
create the markup returned to the
+ web browser. The most used render set is the divRenderer. Renderers only need a
modification in the deployment
+ descriptor to indicate that they support ajax. Here is the declaration of the
default divRenderer now in 2.6:</para>
+ <programlisting><![CDATA[
+<renderSet name="divRenderer">
+ <set content-type="text/html">
+ <ajax-enabled>true</ajax-enabled>
+ <region-renderer>org.jboss.portal.theme.impl.render.div.DivRegionRenderer
+ </region-renderer>
+ <window-renderer>org.jboss.portal.theme.impl.render.div.DivWindowRenderer
+ </window-renderer>
+ <portlet-renderer>org.jboss.portal.theme.impl.render.div.DivPortletRenderer
+ </portlet-renderer>
+
<decoration-renderer>org.jboss.portal.theme.impl.render.div.DivDecorationRenderer
+ </decoration-renderer>
+ </set>
+</renderSet>
+]]></programlisting>
+ <para>You should notice the
<![CDATA[<ajax-enabled>true</ajax-enabled>]]> which indicates that the
render set
+ supports ajaxification.</para>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Ajaxified pages</title>
+ <para>The ajaxification of the portal pages can be configured in a fine
grained manner. Thanks to the portal
+ object properties it is possible to control which pages support ajax and which page
do not support ajax. The
+ administrator must pay attention to the fact that property values are inherited in
the object hierarchy.</para>
+ <sect2>
+ <title>Drag and Drop</title>
+ <para>That feature is only effective in dashboards as it requires the
offer personalization of the page
+ layout per user. By default the feature is enabled thanks to a property set on
the dashboard object.
+ It is possible to turn off that property if the administrator does not want to
expose that feature
+ to its user.</para>
+ <para>In the file
<emphasis>jboss-portal.sar/conf/data/default-object.xml</emphasis> is declared
and configured the
+ creation of the dashboard portal:</para>
+ <programlisting><![CDATA[
+<deployment>
+ <parent-ref/>
+ <if-exists>keep</if-exists>
+ <context>
+ <context-name>dashboard</context-name>
+ <properties>
+ ...
+ <property>
+ <name>theme.dyna.dnd_enabled</name>
+ <value>true</value>
+ </property>
+ ...
+ </properties>
+ ...
+ </context>
+</deployment>
+]]></programlisting>
+ <para>The property <emphasis>theme.dyna.dnd_enabled</emphasis>
is set to the value <emphasis>true</emphasis>
+ which means that the dashboard object will provide the drag and drop feature.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Partial refresh</title>
+ <para>Partial refresh is a very powerful feature which allows the portal
to optimize the refreshing
+ of portlets on a page. When one portlet is invoked, instead of redrawing the
full page, the portal is able
+ to detect which portlets needs to be refreshed and will update only these
portlets.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/ajax/partial-refresh.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The portal providing partial refresh</para>
+ </caption>
+ </mediaobject>
+ <sect3>
+ <title>Portal objects configuration</title>
+ <para>Like with the drag and drop feature, partial page refresh is
controlled via properties on portal objects.
+ The name of the property is
<emphasis>theme.dyna.partial_refresh_enabled</emphasis> and its values can
+ be <emphasis>true</emphasis> or
<emphasis>false</emphasis>. When this property is set on an object
+ it is automatically inherited by the sub hierarchy located under that
object. By default the drag
+ and drop feature is positionned on the dashboard object and not on the
rest of the portal objects.
+ </para>
+ <programlisting><![CDATA[
+<deployment>
+ <parent-ref/>
+ <if-exists>keep</if-exists>
+ <context>
+ <context-name>dashboard</context-name>
+ <properties>
+ ...
+ <property>
+ <name>theme.dyna.partial_refresh_enabled</name>
+ <value>true</value>
+ </property>
+ ...
+ </properties>
+ ...
+ </context>
+</deployment>
+]]></programlisting>
+ <note>
+ The partial page refresh feature is compatible with the Portal API. The
Portal API allows programmatic
+ update of the state of portlets at runtime. For instance it is possible to
modify the window state or
+ the mode of several portlets on a given page. When such event occurs, the
portal detects the changes
+ which occured and will update the portlet fragments in the page.
+ </note>
+ <para>It is possible to change that behavior at runtime using the
property editor of the management portlet.
+ If you want to enable partial refreshing on the default portal you should set
the property to true
+ directly on the portal and all the pages in that portal will automatically
inherit those properties.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/ajax/partial-refresh-admin.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The default portal configured for partial page
refresh</para>
+ </caption>
+ </mediaobject>
+ </sect3>
+ <sect3>
+ <title>Portlet configuration</title>
+ <para>
+ By default any portlet will support partial refreshing. When does the
portal performs partial page
+ refreshing ? By default it is enabled for action and render links with the
following exceptions. In those
+ situations, the portal will prefer to perform a full page refresh:
+ <itemizedlist>
+ <listitem>
+ <para>Form GET are not handled, however it should not be an
issue as this situation is discouraged
+ by the Portlet specification. It however taken in account, just in
case of. Here is an example
+ of a Java Server Page that would do one:</para>
+ <programlisting><![CDATA[
+<form action="<%= renderResponse.createActionURL() %>"
method="get">
+ ...
+</form>
+]]></programlisting>
+ </listitem>
+ <listitem>
+ <para>Form uploads are not handled.</para>
+ </listitem>
+ <listitem>Having an interaction that deals with the
<emphasis>MAXIMIZED</emphasis> window state.
+ When a window is entering a maximized state or leaving a maximized
window state, the portal will
+ perform a full page refresh.</listitem>
+ </itemizedlist>
+ </para>
+ <para>It can happen that a portlet does not want to support partial
refreshing, in those situations
+ the <emphasis>jboss-portlet.xml</emphasis> can be used to control
that behavior. Since 2.6 an ajax
+ section has been added in order to configure ajax features related to the
portlet.</para>
+ <programlisting><![CDATA[
+<portlet>
+ <portlet-name>MyPortletNoAjax</portlet-name>
+ <ajax>
+ <partial-refresh>false</partial-refresh>
+ </ajax>
+</portlet>
+]]></programlisting>
+ <para>The usage of the <emphasis>partial-refresh</emphasis>
set to the value false means that
+ the portlet will not be subject of a partial page refresh when it is invoked.
However the portlet
+ markup can still be subject to a partial rendering.</para>
+ </sect3>
+ <sect3>
+ <title>Limitations</title>
+ <para>Partial refreshing of portlets has limitations both on the server
side (portal) and on the client side (browser).</para>
+ <sect4>
+ <title>Application scoped session attributes</title>
+ <para>When partial refresh is activated, the state of a page can
potentially become inconsistent. for
+ example, if some objects are shared in the application scope of the
session between portlets. When one
+ portlet update a session object, the other portlet won't be refreshed
and will still display content based
+ on the previous value of the object in the session. To avoid that, partial
refresh can be desactivated
+ for certain portlets by adding
<portlet-refresh>false<portlet-refresh> in the
jboss-portlet.xml file.</para>
+ </sect4>
+ <sect4>
+ <title>Non ajax interactions</title>
+ <para>The solution developped by JBoss Portal on the client side is
built on top of DOM events emitted
+ by the web browser when the user interracts with the page. If an
interaction is done without an
+ emission of an event then JBoss Portal will not be able to transform it
into a partial refresh and
+ it will result instead of a full refresh. This can happen with
programmatic submission of forms.
+ </para>
+ <programlisting><![CDATA[
+<form id="<%= formId %>" action="<%=
renderResponse.createActionURL() %>" method="post">
+ ...
+ <select onclick="document.getElementById('<%= formId
%>').submit()">
+ ...
+ </select>
+ ...
+</form>
+]]></programlisting>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
Added: docs/template/user-guide/en/images/sample/partial-refresh.png
===================================================================
(Binary files differ)
Property changes on: docs/template/user-guide/en/images/sample/partial-refresh.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/template/user-guide/en/master.xml
===================================================================
--- docs/template/user-guide/en/master.xml (rev 0)
+++ docs/template/user-guide/en/master.xml 2007-10-18 20:26:35 UTC (rev 8700)
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+ "../docbook-support/support/docbook-dtd/docbookx.dtd" [
+ <!ENTITY sample SYSTEM "modules/sample.xml">
+ ]>
+<book lang="en">
+ <bookinfo>
+ <title>Change Title in master.xml</title>
+ <subtitle>Change SubTitle in master.xml</subtitle>
+ <releaseinfo>Change Release Info in master.xml</releaseinfo>
+ <releaseinfo>Change Release Info Date in master.xml</releaseinfo>
+ <author>
+ <firstname>Thomas</firstname>
+ <surname>Heute</surname>
+ <email>theute(a)jboss.org</email>
+ </author>
+ </bookinfo>
+ <toc/>
+ <!-- Sample--> &sample;
+
+</book>
Property changes on: docs/template/user-guide/en/master.xml
___________________________________________________________________
Name: svn:executable
+
Added: docs/template/user-guide/en/modules/sample.xml
===================================================================
--- docs/template/user-guide/en/modules/sample.xml (rev 0)
+++ docs/template/user-guide/en/modules/sample.xml 2007-10-18 20:26:35 UTC (rev 8700)
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ajax">
+ <chapterinfo>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien.viet(a)jboss.com</email>
+ </author>
+ </chapterinfo>
+ <title>My title</title>
+ <para>This section covers the ajax features provided by the
portal.</para>
+ <sect1>
+ <title>Introduction</title>
+ <para>Todo</para>
+ </sect1>
+ <sect1>
+ <title>Ajaxified markup</title>
+ <sect2>
+ <title>Ajaxified layouts</title>
+ <para>Part of the Ajax capabilities are implemented in the layout
framework which provide the structure for
+ generating portal pages. The good news is that the existing layout only requires
a few modifications in
+ order to be ajaxified.</para>
+ <para>We will use as example an simplified version of the layout JSP
provided in JBoss Portal 2.6 and outline
+ what are the required changes that makes it an ajaxified layout:
+ <programlisting><![CDATA[
+<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p"
%>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="Content-Type" content="text/html;"/>
+ <!-- inject the theme, default to the Renaissance theme if
+ nothing is selected for the portal or the page -->
+ <p:theme themeName="renaissance"/>
+ <!-- insert header content that was possibly set by portlets on the page -->
+ <p:headerContent/>
+</head>
+]]></programlisting>
+ <itemizedlist>
+ <listitem><![CDATA[<p:theme
themeName="renaissance"/>]]> should be already present as it exists since
2.4 but is even more
+ necessary as it will inject in the page the reference to the ajax
stylesheet.</listitem>
+ <listitem><![CDATA[<p:region regionName='AJAXScripts'
regionID='AJAXScripts'/>]]> should be added before any other region
+ in the markup of the layout.</listitem>
+ <listitem><![CDATA[<p:region regionName='AJAXFooter'
regionID='AJAXFooter'/>]]> should be added after any other region
+ in the markup of the layout.</listitem>
+ </itemizedlist>
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/sample/partial-refresh.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The portal providing partial refresh</para>
+ </caption>
+ </mediaobject>
+ </sect2>
+ </sect1>
+</chapter>