Author: julien(a)jboss.com
Date: 2007-04-27 18:52:48 -0400 (Fri, 27 Apr 2007)
New Revision: 7118
Added:
docs/trunk/referenceGuide/en/images/ajax/
docs/trunk/referenceGuide/en/images/ajax/partial-refresh-admin.png
docs/trunk/referenceGuide/en/images/ajax/partial-refresh.png
Modified:
docs/trunk/referenceGuide/en/modules/ajax.xml
Log:
completing ajax chapter
Added: docs/trunk/referenceGuide/en/images/ajax/partial-refresh-admin.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/ajax/partial-refresh-admin.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/ajax/partial-refresh.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/ajax/partial-refresh.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: docs/trunk/referenceGuide/en/modules/ajax.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/ajax.xml 2007-04-27 15:24:04 UTC (rev 7117)
+++ docs/trunk/referenceGuide/en/modules/ajax.xml 2007-04-27 22:52:48 UTC (rev 7118)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="clustering">
+<chapter id="ajax">
<chapterinfo>
<author>
<firstname>Julien</firstname>
@@ -102,10 +102,136 @@
</sect1>
<sect1>
<title>Ajaxified pages</title>
- <para>todo</para>
+ <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 refreshing</title>
+ <para>Partial refreshing 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
objects. 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>
+ </sect2>
</sect1>
- <sect1>
- <title>Ajaxified portlets</title>
- <para>todo</para>
- </sect1>
</chapter>
\ No newline at end of file
Show replies by date