1:30 a.m.
Author: julien(a)jboss.com
Date: 2007-10-18 19:29:59 -0400 (Thu, 18 Oct 2007)
New Revision: 8707
Added:
modules/test/trunk/docs/user-guide/en/modules/introduction.xml
Removed:
modules/test/trunk/docs/user-guide/en/ajax.xml
Modified:
modules/test/trunk/docs/user-guide/en/master.xml
Log:
setup base info in docbook
Deleted: modules/test/trunk/docs/user-guide/en/ajax.xml
===================================================================
--- modules/test/trunk/docs/user-guide/en/ajax.xml 2007-10-18 23:22:29 UTC (rev 8706)
+++ modules/test/trunk/docs/user-guide/en/ajax.xml 2007-10-18 23:29:59 UTC (rev 8707)
@@ -1,273 +0,0 @@
-<?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
Modified: modules/test/trunk/docs/user-guide/en/master.xml
===================================================================
--- modules/test/trunk/docs/user-guide/en/master.xml 2007-10-18 23:22:29 UTC (rev 8706)
+++ modules/test/trunk/docs/user-guide/en/master.xml 2007-10-18 23:29:59 UTC (rev 8707)
@@ -1,21 +1,20 @@
<?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">
+ <!ENTITY introduction SYSTEM "modules/introduction.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>
+ <title>JBoss Unit</title>
+ <subtitle>User Guide</subtitle>
+ <releaseinfo>Release 1.0</releaseinfo>
<author>
- <firstname>Thomas</firstname>
- <surname>Heute</surname>
- <email>theute(a)jboss.org</email>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien(a)jboss.org</email>
</author>
</bookinfo>
<toc/>
- <!-- Sample--> &sample;
+ <!-- Introduction --> &introduction;
</book>
Copied: modules/test/trunk/docs/user-guide/en/modules/introduction.xml (from rev 8705,
modules/test/trunk/docs/user-guide/en/modules/sample.xml)
===================================================================
--- modules/test/trunk/docs/user-guide/en/modules/introduction.xml
(rev 0)
+++ modules/test/trunk/docs/user-guide/en/modules/introduction.xml 2007-10-18 23:29:59 UTC
(rev 8707)
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="introduction">
+ <chapterinfo>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien(a)jboss.org</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>