[gatein-commits] gatein SVN: r1505 - portal/trunk/docs/reference-guide/en/modules/portlets.

Author: smumford Date: 2010-02-03 01:59:13 -0500 (Wed, 03 Feb 2010) New Revision: 1505 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.xml portal/trunk/docs/reference-guide/en/modules/portlets/Portlet_Lifecycle.xml Log: Edits to Chapter 4 Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.xml 2010-02-03 04:35:37 UTC (rev 1504) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Groovy_Templates.xml 2010-02-03 06:59:13 UTC (rev 1505) @@ -5,38 +5,32 @@ ]> <section id="sect-Reference_Guide-Groovy_Templates"> <title>Groovy Templates</title> - <section id="sect-Reference_Guide-Groovy_Templates-Overview"> - <title>Overview</title> <para> - This article gives a glance at the Groovy language, and explains how to configure the portlet and and the groovy template. + In addition to the content in this chapter, refer also to <xref linkend="sect-Reference_Guide-AJAX_Framework" /> in order to better understand the communication between the Groovy Template and the portlet. </para> - <para> - It's recommended to read also <xref linkend="sect-Reference_Guide-AJAX_Framework" /> in order to understand better the communication between the Groovy Template and the portlet. - </para> - </section> <section id="sect-Reference_Guide-Groovy_Templates-Basic_structure"> <title>Basic structure</title> <para> - The structure of a template is very easy : + The structure of a template is quite simple. It consists of only two elements: </para> - <itemizedlist> + <orderedlist> <listitem> <para> - The HTML code + The HTML code and; </para> </listitem> <listitem> <para> - zero or more groovy language code blocks, enclosed by &lt;% ... %&gt; + zero or more groovy language code blocks, enclosed by &lt;% ... %&gt; enclosures. </para> </listitem> - </itemizedlist> + </orderedlist> <para> - The HTML code in the template doesn't have to contain the <literal>html</literal> , or <literal>body</literal> tags. Hence, you can use a groovy template for a component that will be rendered in another component. + The HTML code in the template doesn't have to contain the <literal>html</literal>, or <literal>body</literal> tags. This allows groovy templates for one component to also be rendered in another component. </para> <para> - Example : + For example: </para> <programlisting role="HTML">&lt;!DOCTYPE html @@ -57,25 +51,27 @@ <section id="sect-Reference_Guide-Groovy_Templates-Groovy_language"> <title>Groovy language</title> <para> - Groovy is a scripting language for Java. Here are a few examples on how to use it, but you can find more information in <ulink url="http://groovy.codehaus.org/Documentation">the full documentation</ulink> . + Groovy is a scripting language for Java. Some usage examples are included in this section, however further information is available at <ulink url="http://groovy.codehaus.org/Documentation"></ulink> . </para> - <para> - This language looks like Java a lot, so it's very easy to use. Examples : - </para> - <para> - Variables definition : - </para> - + <variablelist> + <title>Some examples of Groovy</title> + <varlistentry> + <term>Variables definition</term> + <listitem> + <para> <programlisting>int min = 1; def totalPage = uicomponent.getAvailablePage(); String name = "uiPortlet"; categories = uicomponent.getItemCategories(); String columns = uicomponent.getColumns(); </programlisting> - <para> - Other expressions : - </para> - + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Other expressions</term> + <listitem> + <para> <programlisting>for(category in categories) { ... } for(i in min..max) { ... } // min and max are int variables println "&lt;/div&gt;" ; @@ -86,18 +82,31 @@ &lt;%=uicomponent.getToolbarStyle();%&gt; // &lt;%= to avoid a call of println method import org.exoplatform.portal.config.model.PageNode; </programlisting> + + </para> + </listitem> + </varlistentry> + </variablelist> + </section> <section id="sect-Reference_Guide-Groovy_Templates-Linking_a_portlet_with_a_template"> <title>Linking a portlet with a template</title> + <section id="sect-Reference_Guide-Linking_a_portlet_with_a_template-Portlet_configuration"> <title>Portlet configuration</title> <para> - The configuration of a portlet is partly made with <literal>ComponentConfig</literal> annotations (others are ComponentConfigs, EventConfig, etc). One of the parameters of this annotation is called <literal>template</literal>, where you can define the path to the template file associated with this portlet. + The configuration of a portlet is partly made with <literal>ComponentConfig</literal> annotations (others are <literal>ComponentConfigs</literal>, <literal>EventConfig</literal>, etc). </para> <para> - To specify this parameter to your portlet, just add this statement to your configuration annotation, for example in <emphasis role="bold">src:/portlet/exoadmin/src/main/java/org/exoplatform/applicationregistry/webui/component/ </emphasis> you find <emphasis role="bold">UIApplicationForm.java</emphasis> : + One of the parameters of this annotation is <literal>template</literal>. This is where the path to the template file associated with this portlet is defined. </para> + <para> + To specify this parameter, add this statement to the configuration annotation. + </para> + <para> + For example, in <emphasis role="bold">src:/portlet/exoadmin/src/main/java/org/exoplatform/applicationregistry/webui/component/ </emphasis> is the <emphasis role="bold">UIApplicationForm.java</emphasis> file: + </para> <programlisting>@ComponentConfig( lifecycle = UIFormLifecycle.class, @@ -109,28 +118,64 @@ ) </programlisting> <para> - You see that the path is in the namespace called "system", "system" is a reference to the portal webapp. In this webapp you find some reusable groovy templates, just open the folder <emphasis role="bold">src:/web/portal/src/main/webapp/groovy/webui/form/ </emphasis> to see them. + The path is in the "<literal>system</literal>" namespace. This is a reference to the portal webapp. </para> <para> - As you want to create your own template, create a groovy file in your webbapp and refer to it. Please use the namespace "app" for refering to the same webapp as your component. GateIn always puts the component templates in a folder like "/webapp/groovy/<literal>your_portlet_name</literal>/webui/component". + This webapp contains reusable groovy templates in the folder; <emphasis role="bold">src:/web/portal/src/main/webapp/groovy/webui/form/ </emphasis>. </para> - + <para> + Use the following steps to create a new template; + </para> + <procedure> + <step> + <para> + Create a groovy file in the appropriate webbapp and refer to it. + </para> + </step> + <step> + <para> + Use the namespace "app" for refering to the same webapp as the component. + </para> + </step> + <step> + <para> + &PRODUCT; stores the component templates in a folder that follows this placement convention: "<filename>/webapp/groovy/<literal>your_portlet_name</literal>/webui/component</filename>". + </para> + <para> <programlisting>template = "app:/groovy/your_portlet_name/webui/component/your_component.gtmpl" </programlisting> - <para> - You can now edit your template file. - </para> + </para> + </step> + <step> + <para> + Edit the template file according to the information in the <xref linkend="sect-Reference_Guide-Linking_a_portlet_with_a_template-The_template_file"/>. + </para> + </step> + </procedure> </section> <section id="sect-Reference_Guide-Linking_a_portlet_with_a_template-The_template_file"> <title>The template file</title> <para> - As we said before, the template file is composed of HTML code and groovy code blocks. There are a few things more that you need to know to fully link your portlet with your template. + Component template files are composed in HTML code and groovy code blocks. There are a few things more that you need to know to fully link your portlet with your template. </para> <para> - If your template defines the UI of a component, you have an access to this component instance (the java object) using the variable <literal>uicomponent</literal>. This should be the case almost all the time, but we recommend that you check that your java class inherits from UIComponent before you use this variable. With this <literal>uicomponent</literal> variable, you can access all the attributes and functions of your component, to use them in your template. Example : UIPageIterator.gtmpl: + To successfully link a portlet with a template, please ensure the following: </para> - + <itemizedlist> + <listitem> + <para> + If the template defines the UI of a component, use the java object variable <literal>uicomponent</literal> to access this component instance. + </para> + <para> + This should be the case in most instances, but it is recommended that the java class inherits from <literal>UIComponent</literal> are checked before this variable is used. + </para> + <para> + Using the <literal>uicomponent</literal> variable, you can access all the attributes and functions of a component to use them in your template. + </para> + <para> + Take, for example <literal>UIPageIterator.gtmpl</literal>: + </para> <programlisting>&lt;% def currentPage = uicomponent.getCurrentPage(); %&gt; @@ -139,22 +184,42 @@ &lt;span&gt;&lt;/span&gt; &lt;/a&gt; </programlisting> - <para> - This example shows that <literal>uicomponent</literal> can be used to make Ajax calls, thanks to the <literal>event</literal> method. See <xref linkend="sect-Reference_Guide-AJAX_Framework" /> for more details. - </para> - <para> - Another variable that you can use is <literal>ctx</literal>. It gives access to the context in which the template is processed. Hence, you can get some elements like the request, the Javscript manager, or the resource resolver (ctx.appRes). Examples : - </para> - + <para> + The following example shows how <literal>uicomponent</literal> can be used to make Ajax calls using the <literal>event</literal> method. See <xref linkend="sect-Reference_Guide-AJAX_Framework" /> for more details. + </para> + </listitem> + <listitem> + <para> + Another variable available is <literal>ctx</literal>. This variable gives access to the context in which the template is processed. + </para> + <para> + Use this variable to retrieve elements such as; the request, the Javscript manager or the resource resolver (<literal>ctx.appRes</literal>). + </para> + <para> + Some usage examples are: + </para> <programlisting>&lt;% def rcontext = ctx.getRequestContext() ; context.getJavascriptManager().importJavascript('GateIn.webui.UIPopupWindow'); ctx.appRes(popupId + ".title."+ title); %&gt; </programlisting> - <para> - If you use your template to define the user interface of a component that includes a form, you can access the instance of UIForm in a variable named <literal>uiform</literal>. The UIForm class provides the methods, <literal>begin()</literal> and <literal>end()</literal>, that write the HTML tags of the form. Your form class must inherit from <literal>UIForm</literal> , in this class you add the input elements (fields, checkboxes, lists) which you wish to use in your form. In your groovy template you can render your input elements using <literal>uiform.renderField(field)</literal> - </para> + </listitem> + <listitem> + <para> + If the template defines the user interface of a component that includes a form use an instance of <literal>UIForm</literal> in a variable named <literal>uiform</literal>. + </para> + <para> + The <literal>UIForm</literal> class provides the methods <literal>begin()</literal> and <literal>end()</literal> which write the HTML tags of the form. + </para> + <para> + The form class must inherit from <literal>UIForm</literal>. In this class add the input elements (fields, checkboxes, lists) which are required in the form. + </para> + <para> + Render the input elements in the groovy template using <literal>uiform.renderField(field)</literal>. + </para> + </listitem> + </itemizedlist> </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Portlet_Lifecycle.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Portlet_Lifecycle.xml 2010-02-03 04:35:37 UTC (rev 1504) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Portlet_Lifecycle.xml 2010-02-03 06:59:13 UTC (rev 1505) @@ -5,26 +5,35 @@ ]> <section id="sect-Reference_Guide-Portlet_Lifecycle"> <title>Portlet Lifecycle</title> - <section id="sect-Reference_Guide-Portlet_Lifecycle-Overview"> - <title>Overview</title> <para> - The goal of this chapter is not to talk about the Portlet API specification lifecycle but more about GateIn UI framework to easily develop portlets. + This chapter does not to refer to the Portlet API specification lifecycle but focuses on the &PRODUCT; UI framework. </para> <para> - The web framework used here has been completely developed by GateIn and perfectly suits the portal environment, it even allows to send events from the portlet UIComponents to the Portal ones. + This web framework has been developed specifically for &PRODUCT; and, while it is not necessary to use the native web framework to build portlets, all portlets packaged with &PRODUCT; are developed using this framework. </para> + <para> + This consistency allows portlets to use several UI components that can be used in different abstracted contexts (such as the portal itself or some portlets). + </para> + <note> + <title>Recommended Reading</title> + <para> + This chapter is intended for advanced developers. It covers code implementation and logic. It is not a tutorial on how to write portlets. + </para> + <para> + Refer to <xref linkend="sect-Reference_Guide-Portal_Lifecycle" /> for information on concepts that are similar and top hierarchy classes that are shared. + </para> + </note> + + <section id="sect-Reference_Guide-Portlet_Lifecycle-Portlet_init"> + <title>Portlet init</title> <para> - Of course using the GateIn web framework to build portlets is not necessary and any other web framework that supports portlet environment can be used. But all GateIn portlets that are part of GateIn products are developed using that framework and we provide several UI components that can be used in different abstracted contexts such as the portal itself or some portlets. + The main entry point for configuring a portlet is in the <emphasis role="bold">portlet.xml</emphasis> file located in the portlet application WAR. </para> <para> - This chapter is not a tutorial on how to write portlets, it will go in the details of the code implementation and logic; hence it is intended for advanced developers. It is also advised to read the <xref linkend="sect-Reference_Guide-Portal_Lifecycle" /> article before as the that article explains concepts that are similar and top hierarchy classes that are shared. + Each portlet built using the &PRODUCT; web framework must reference the <emphasis role="bold">PortletApplicationController</emphasis> . </para> - </section> - - <section id="sect-Reference_Guide-Portlet_Lifecycle-Portlet_init"> - <title>Portlet init</title> <para> - The main entry point for configuring a portlet is in the <emphasis role="bold">portlet.xml</emphasis> file located in the portlet application WAR. Every portlet that shall be built using the GateIn web framework must reference the <emphasis role="bold">PortletApplicationController</emphasis> . The portlet configuration such as the root component is defined in a <emphasis role="bold">configuration.xml</emphasis> file. The path to this configuration.xml file is defined in the init-param " <emphasis role="bold">webui.configuration</emphasis> " of porlet.xml. + The portlet configuration (such as the root component) is defined in <filename>configuration.xml</filename>. The path to this file is defined in the init-param "<emphasis role="bold">webui.configuration</emphasis>" of <filename>portlet.xml</filename>. </para> <programlisting>&lt;portlet&gt; @@ -40,8 +49,11 @@ &lt;/portlet&gt; </programlisting> <para> - The structure of the <emphasis role="bold">configuration.xml</emphasis> file is exactly the same as the <emphasis>webui-configuration.xml</emphasis>which we have already introduced in the <xref linkend="sect-Reference_Guide-Portal_Lifecycle" /> article. In the case of the content portlet it looks like: + The structure of the <filename>configuration.xml</filename> file is exactly the same as the <filename>webui-configuration.xml</filename> which was introduced in <xref linkend="sect-Reference_Guide-Portal_Lifecycle" />. </para> + <para> + In the case of the content portlet it is formatted as: + </para> <programlisting>&lt;webui-configuration&gt; &lt;application&gt; @@ -51,10 +63,10 @@ &lt;/webui-configuration&gt; </programlisting> <para> - The <emphasis role="bold">PortletApplicationController</emphasis> class extends the <emphasis role="bold">GenericPortlet</emphasis> class defined in the Portlet API specification. + The <literal>PortletApplicationController</literal> class extends the <literal>GenericPortlet</literal> class defined in the Portlet API specification. </para> <para> - All methods like <emphasis>processAction()</emphasis> or <emphasis>render()</emphasis> are delegated to the <emphasis role="bold">PortletApplication</emphasis>. The creation and caching inside the <emphasis role="bold">WebController</emphasis> object is described in the following method: + All methods (like <literal>processAction()</literal> or <literal>render()</literal>) are delegated to the <literal>PortletApplication</literal>. The creation and caching inside the <literal>WebController</literal> object is shown in the example below: </para> <programlisting>/** @@ -81,14 +93,14 @@ <section id="sect-Reference_Guide-Portlet_Lifecycle-Portlet_request_handler"> <title>Portlet request handler</title> <para> - When a portlet, that is deployed in GateIn Portal, is using the GateIn web framework then all methods calls go through the <emphasis role="bold">PortletApplication</emphasis> object which extends the <emphasis role="bold">WebuiApplication</emphasis>. + When a portlet using the native web framework is deployed in &PRODUCT;, all methods calls go through the <literal>PortletApplication</literal> object which extends the <literal>WebuiApplication</literal>. </para> </section> <section id="sect-Reference_Guide-Portlet_Lifecycle-ProcessAction_phase"> <title>ProcessAction phase</title> <para> - The code of the method in PortletApplication is described here. The business logic is shown in the javadoc: + The code of the method in <literal>PortletApplication</literal> is described below. The business logic is shown in the javadoc: </para> <programlisting>/** @@ -131,7 +143,7 @@ } </programlisting> <para> - The <emphasis role="bold">PortletRequestContext</emphasis> extends <emphasis role="bold">WebuiRequestContext</emphasis> class and acts as a wrapper on top of all the portlet request information: + The <literal>PortletRequestContext</literal> extends the <literal>WebuiRequestContext</literal> class and acts as a wrapper on all the portlet request information: </para> <programlisting>/** @@ -166,10 +178,12 @@ } </programlisting> <para> - In the PortletApplication, the line + In the <literal>PortletApplication</literal>, the line; </para> +<programlisting>UIApplication uiApp = getStateManager().restoreUIRootComponent(context); +</programlisting> <para> - <emphasis>UIApplication uiApp = getStateManager().restoreUIRootComponent(context);</emphasis> asks the StateManager defined for the portlet to get the UI root component. In the case of a portlet the root component must extend UIPortletApplication. + asks the <literal>StateManager</literal> defined for the portlet to get the UI root component. In the case of a portlet the root component must extend <literal>UIPortletApplication</literal>. </para> <programlisting>public class ParentAppStateManager extends StateManager { @@ -219,7 +233,7 @@ <section id="sect-Reference_Guide-Portlet_Lifecycle-Render_phase"> <title>Render phase</title> <para> - The render method business logic is quite similar to processAction(). + The render method business logic is quite similar to <literal>processAction()</literal>. </para> <programlisting>/** @@ -268,7 +282,7 @@ } </programlisting> <para> - The processRender() call made on the UIPortletApplication is shown now: + The following is the <literal>processRender()</literal> call made on the <literal>UIPortletApplication</literal>: </para> <programlisting>/**