[portal-commits] JBoss Portal SVN: r7118 - in docs/trunk/referenceGuide/en: images/ajax and 1 other directories.

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