[gatein-commits] gatein SVN: r1575 - in portal/trunk/docs/reference-guide/en/modules: gadgets and 1 other directories.

Author: smumford Date: 2010-02-08 23:49:33 -0500 (Mon, 08 Feb 2010) New Revision: 1575 Modified: portal/trunk/docs/reference-guide/en/modules/Portlets.xml portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml portal/trunk/docs/reference-guide/en/modules/portlets/Create_a_WebUI_Portlet.xml portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml Log: Edits to Chapters 4 & 5 Modified: portal/trunk/docs/reference-guide/en/modules/Portlets.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Portlets.xml 2010-02-09 03:44:16 UTC (rev 1574) +++ portal/trunk/docs/reference-guide/en/modules/Portlets.xml 2010-02-09 04:49:33 UTC (rev 1575) @@ -10,6 +10,6 @@ <xi:include href="portlets/Groovy_Templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portlets/Portlet_Lifecycle.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="portlets/Standard.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="portlets/Create_a_WebUI_Portlet.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- Unedited pending new example --> <xi:include href="portlets/Create_a_WebUI_Portlet.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Modified: portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml 2010-02-09 03:44:16 UTC (rev 1574) +++ portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml 2010-02-09 04:49:33 UTC (rev 1575) @@ -5,43 +5,80 @@ ]> <section id="sect-Reference_Guide-Gadgets"> <title>Gadgets</title> - <section id="sect-Reference_Guide-Gadgets-Overview"> - <title>Overview</title> <para> - An gadget is a mini web application running on a platform and you can put it in a web page. This is a small application that helps users to do some private actions. + A gadget is a mini web application, embedded in a web page and running on an application server platform. These small applications help users perform various tasks. </para> <para> - GateIn Portal supports some gadgets such as: Todo gadget, Calendar gadget, Calculator gadget, Weather Forecasts, RSS Reader gadget. + &PRODUCT; supports gadgets such as: Todo gadget, Calendar gadget, Calculator gadget, Weather Forecasts and and RSS Reader. </para> - <itemizedlist> - <listitem> - <para> - Todo: This mini - application helps you to organize your day and work group. - </para> - </listitem> - <listitem> - <para> - Calendar: A cool calendar to keep track of date in style. - </para> - </listitem> - <listitem> - <para> - Calculator: This is the coolest calculator for your page. - </para> - </listitem> - <listitem> - <para> - RSS Reader: This gadget lets you het a sneak preview of your favourite feeds around web - </para> - </listitem> - <listitem> - <para> - Weather Forecasts: This gadget notifies you of current weather condition and gives tomorrow's forecast. - </para> - </listitem> - </itemizedlist> - </section> - + <variablelist id="vari-User_Guide-Using_the_Dashboard_Workspace-Default_Gadgets"> + <title>Default Gadgets:</title> + <varlistentry> + <term>Calendar</term> + <listitem> + <para> + The calendar gadget allows users to switch easily between daily, monthly and yearly view and, again, is customizable to match your portal's theme. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/Calendar.png" format="PNG" /> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>ToDo</term> + <listitem> + <para> + This application helps you organize your day and work group. It is designed to keep track of your tasks in a convenient and transparent way. Tasks can be highlighted with different colors. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/Todo.png" format="PNG" /> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>Calculator</term> + <listitem> + <para> + This mini-application lets you perform most basic arithmetic operations and can be themed to match the rest of your portal. + </para> + <mediaobject> + <imageobject> + <imagedata fileref="images/Calculator.png" format="PNG" /> + </imageobject> + </mediaobject> + </listitem> + </varlistentry> + <varlistentry> + <term>RSS Reader</term> + <listitem> + <para> + An RSS reader, or aggregator, collates content from various, user-specified feed sources and displays them in one location. This content can include, but isn't limited to, news headlines, blog posts or email. The RSS Reader gadget displays this content in a single window on your Portal page. + </para> + <!-- <mediaobject> + <imageobject> + <imagedata fileref="images/RSS.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> --> + </listitem> + </varlistentry> + <varlistentry> + <term>More Gadgets</term> + <listitem> + <para> + Further gadgets can be obtained from the <ulink type="http" url="http://www.google.com/ig/directory?synd=open">Google Gadget</ulink> site. &PRODUCT; is compatible with most of the gadgets available here. + </para> + </listitem> + </varlistentry> + </variablelist> +<important> + </para> + The following sections require more textual information. + <para> +</important> <section id="sect-Reference_Guide-Gadgets-Existing_Gadgets"> <title>Existing Gadgets</title> <mediaobject> Modified: portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml 2010-02-09 03:44:16 UTC (rev 1574) +++ portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml 2010-02-09 04:49:33 UTC (rev 1575) @@ -5,16 +5,17 @@ ]> <section id="sect-Reference_Guide-Setup_a_Gadget_Server"> <title>Setup a Gadget Server</title> - <section id="sect-Reference_Guide-Setup_a_Gadget_Server-Setup_virtual_servers_for_the_gadget_rendering"> - <title>Setup virtual servers for the gadget rendering</title> + <section id="sect-Reference_Guide-Setup_a_Gadget_Server-Virtual_servers_for_gadget_rendering"> + <title>Virtual servers for gadget rendering</title> <para> - GateIn recommend you to setup 2 different virtual hosts because it's the basis of the security model of gadgets. Having the gadget running on a different domain than the container (the website that 'contains' the app), the gadget can't read / modify / do anything nasty to GateIn Portal (like adding spam messages, stealing your cookies, whatever). + &PRODUCT; recommends using two virtual hosts for security. If the gadget is running on a different domain than the container (the website that 'contains' the app), it is unable to interfere with the portal by modifying code or cookies. </para> <para> - For example you can server the portal from <emphasis role="bold">http://www.sample.com</emphasis> and the gadgets from <emphasis role="bold">http://www.samplemodules.com</emphasis> + An example would hosting the portal from <emphasis role="bold">http://www.sample.com</emphasis> and the gadgets from <emphasis role="bold">http://www.samplemodules.com</emphasis>. </para> <para> - To do this, we need to configure a parameter with the name is <emphasis>gadgets.hostName</emphasis> , the value is the <emphasis>path/to/gadgetServer</emphasis> in GadgetRegisteryService service like following: + To do this, configure a parameter called <emphasis>gadgets.hostName</emphasis>. The value is the <emphasis>path/to/gadgetServer</emphasis> in <literal>GadgetRegisteryService</literal>: + </para> <programlisting>&lt;component&gt; &lt;key&gt;org.exoplatform.application.gadget.GadgetRegistryService&lt;/key&gt; &lt;type&gt;org.exoplatform.application.gadget.jcr.GadgetRegistryServiceImpl&lt;/type&gt; @@ -27,12 +28,12 @@ &lt;/init-params&gt; &lt;/component&gt; </programlisting> - </para> + <para> - It's possible to have multiple rendering servers. That would help to balance the load across multiple servers. + It is also possible to have multiple rendering servers. This helps to balance the rendering load across multiple servers. </para> <para> - If you still want to deploy it on the same server, make sure that it starts before anything that use the gadgets (for example the webapp GateInGadgets that use org.exoplatform.application.gadget.GadgetRegister) + When deploying on the same server ensure the gadget initiates before anything that calls it (for example; the webapp <literal>GateInGadgets</literal> which uses <literal>org.exoplatform.application.gadget.GadgetRegister</literal>). </para> </section> @@ -41,17 +42,21 @@ <section id="sect-Reference_Guide-Configuration-Security_key"> <title>Security key</title> <para> - A file <emphasis role="bold">key.txt</emphasis> has to be generated <emphasis role="bold">for every installation of GateIn to be secure</emphasis> . This file contains a secret key used to crypt the security token used for authenticating the user. On Linux this can be generated such as: + A file called <emphasis role="bold">key.txt</emphasis> has to be generated for every installation of &PRODUCT; to be secure. This file contains a secret key used to encrypt the security token used for authenticating the user. </para> + <para> + In Linux systems this file can be generated with: + </para> -<programlisting>dd if=/dev/random bs=32 count=1 | openssl base64 &gt; /tmp/key.txt +<programlisting><command>dd if=/dev/random bs=32 count=1 | openssl base64 &gt; /tmp/key.txt</command> </programlisting> </section> <section id="sect-Reference_Guide-Configuration-Gadget_proxy_and_concat_configuration"> <title>Gadget proxy and concat configuration</title> <para> - These servers have to be on the same domain as the gadget server. You can configure it in: <filename>eXoGadgetServer:/WEB-INF/classes/containers/default/container.js</filename>. + These servers have to be on the same domain as the gadget server. You can configure the container in <filename>eXoGadgetServer:/WEB-INF/classes/containers/default/container.js</filename>. + </para> <programlisting>"gadgets.content-rewrite" : { "include-urls": ".*", "exclude-urls": "", @@ -61,13 +66,12 @@ "concat-url": "http://localhost:8080/eXoGadgetServer/gadgets/concat?" }, </programlisting> - </para> </section> <section id="sect-Reference_Guide-Configuration-Proxy"> <title>Proxy</title> <para> - if your server is behind a proxy and you want to allow external gadgets, you should configure the proxy of your JVM adding this code at the begining. + To allow external gadgets when the server is behind a proxy, add the following code to the beginning of the JVM : </para> <programlisting>-Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Create_a_WebUI_Portlet.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Create_a_WebUI_Portlet.xml 2010-02-09 03:44:16 UTC (rev 1574) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Create_a_WebUI_Portlet.xml 2010-02-09 04:49:33 UTC (rev 1575) @@ -6,12 +6,15 @@ <section id="sect-Reference_Guide-Create_a_WebUI_Portlet"> <title>Create a WebUI Portlet</title> <section id="sect-Reference_Guide-Create_a_WebUI_Portlet-Overview"> - <title>Overview</title> + <title>Overview</title> + <important> + <title>TODO</title> <para> - TODO: Create example (This one doesn't exist anymore). Overall this chapter need to be reviewed, any taker ? :) + Create example (This one doesn't exist anymore). Overall this chapter need to be reviewed, any taker ? :) </para> + </important> <para> - This example is based on the testPortlet in portal/trunk/portlet/test. + This example is based on the <literal>testPortlet</literal> in <filename>portal/trunk/portlet/test</filename>. </para> </section> Modified: portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml 2010-02-09 03:44:16 UTC (rev 1574) +++ portal/trunk/docs/reference-guide/en/modules/portlets/Standard.xml 2010-02-09 04:49:33 UTC (rev 1575) @@ -531,13 +531,13 @@ </programlistingco> <para> - As well as the <literal>VIEW</literal> portlet mode, the spec defines two other modes; <literal>EDIT</literal> and <literal>HELP</literal>. + As well as the <literal>VIEW</literal> portlet mode, the specification defines two other modes; <literal>EDIT</literal> and <literal>HELP</literal>. </para> <para> - These modes need to be defined in the <filename>portlet.xml</filename> descriptor. Having those modes defined will enable the corresponding buttons on the portlet's window. + These modes need to be defined in the <filename>portlet.xml</filename> descriptor. This will enable the corresponding buttons on the portlet's window. </para> <para> - The generic portlet that is inherited dispatches the different views to methods named: <literal>doView</literal> , <literal>doHelp</literal> and <literal>doEdit</literal> . Let's watch the code for those two last portlet modes. + The generic portlet that is inherited dispatches the different views to the methods: <literal>doView</literal> , <literal>doHelp</literal> and <literal>doEdit</literal>. </para> <programlisting role="JAVA">... @@ -559,9 +559,12 @@ ... </programlisting> <para> - If you have read the portlet specification carefully you should have notice that portlet calls happen in one or two phases. One when the portlet is just rendered, two when the portlet is actionned then rendered. An action phase is a phase where some state change. The render phase will have access to render parameters that will be passed each time the portlet is refreshed (with the exception of caching capabilities). + Portlet calls happen in one or two phases. One when the portlet is rendered and two when the portlet is actioned <emphasis>then</emphasis> rendered. </para> <para> + An action phase is a phase where some state changes. The render phase will have access to render parameters that will be passed each time the portlet is refreshed (with the exception of caching capabilities). + </para> + <para> The code to be executed during an action has to be implemented in the <emphasis>processAction</emphasis> method of the portlet. </para> <programlistingco> @@ -583,17 +586,17 @@ <calloutlist> <callout arearefs="area-Reference_Guide-tutorials.jsphello.processAction"> <para> - <literal>processAction</literal> is the method from GernericPorlet to override for the <emphasis>action</emphasis> phase. + <literal>processAction</literal> is the method from <literal>GernericPorlet</literal> to override for the <emphasis>action</emphasis> phase. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.getActionParameter"> <para> - Here we retrieve the parameter obtained through an <emphasis>action URL</emphasis> . + Here the parameter is retrieved through an <emphasis>action URL</emphasis> . </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.setRenderParameter"> <para> - Here we need to keep the value of <literal>yourname</literal> to make it available in the rendering phase. With the previous line, we are simply copying an action parameter to a render parameter for the sake of this example. + The value of <literal>yourname</literal> is kept to make it available in the rendering phase. The previous line simply copies an action parameters to a render parameter for this example. </para> </callout> </calloutlist> @@ -602,10 +605,9 @@ </section> <section id="sect-Reference_Guide-_JavaServer_Pages_Portlet_Example_-_JSP_files_and_the_Portlet_Tag_Library_"> - <title><trademark class="trade">JSP</trademark> files and the Portlet Tag Library </title> - <bridgehead>Let's have a look inside the JSP pages. </bridgehead> + <title>JSP files and the Portlet Tag Library</title> <para> - The <filename>help.jsp</filename> and <filename>edit.jsp</filename> files are very simple, they simply display some text. Note that we used CSS styles as defined in the portlet specification. It ensures that the portlet will look "good" within the theme and accross portal vendors. + The <filename>help.jsp</filename> and <filename>edit.jsp</filename> files are very simple. Note that CSS styles are used as defined in the portlet specification. This ensures that the portlet will render well within the theme and across portal vendors. </para> <programlisting role="XHTML">&lt;div class="portlet-section-header"&gt;Help mode&lt;/div&gt; @@ -616,7 +618,7 @@ &lt;div class="portlet-section-body"&gt;This is the edit mode, a convenient place to let the user change his portlet preferences.&lt;/div&gt; </programlisting> <para> - Now let's have a look at the landing page, it contains the links and form to call our portlet: + The landing page contains the links and form to call our portlet: </para> <programlistingco> <areaspec> @@ -668,17 +670,17 @@ <calloutlist> <callout arearefs="area-Reference_Guide-tutorials.jsphello.taglib"> <para> - Since we will use the portlet taglib, we first need to declare it. + The portlet taglib, needs to be declared. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.method1"> <para> - The first method showed here is the simplest one, <literal>portlet:renderURL</literal> will create a URL that will call the render phase of the current portlet and append the result at the place of the markup (Here within a tag...). We also added a parameter directly on the URL. + The first method showed here is the simplest one. <literal>portlet:renderURL</literal> will create a URL that calls the render phase of the current portlet and append the result at the place of the markup (within a tag). A parameter is also added directly to the URL. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.method2.1"> <para> - In this method instead of having a tag within another tag, which is not XML valid, we use the <literal>var</literal> attribute. Instead of printing the url the <literal>portlet:renderURL</literal> tag will store the result in the referenced variable ( <literal>myRenderURL</literal> in our case). + In this method the <literal>var</literal> attribute is used. This avoids having one XML tag within another. Instead of printing the url the <literal>portlet:renderURL</literal> tag will store the result in the referenced variable ( <literal>myRenderURL</literal>). </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.method2.2"> @@ -688,19 +690,19 @@ </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.method3.1"> <para> - The third method mixes form submission and action request. Like in the second method, we used a temporary variable to put the created URL into. + The third method mixes form submission and action request. Again, a temporary variable is used to put the created URL into. </para> </callout> <callout arearefs="area-Reference_Guide-tutorials.jsphello.method3.2"> <para> - The action URL is used in the HTML form. + The action URL is used in HTML form. </para> </callout> </calloutlist> </programlistingco> <para> - On the third method, first the action phase is triggered then later in the request, the render phase is triggered, which output some content back to the web browser based on the available render parameters. + In the third method the action phase is triggered first then the render phase is triggered, which outputs some content back to the web browser based on the available render parameters. <mediaobject> <imageobject> <imagedata fileref="images/tutorials/jsp_portlet/process.png" format="PNG" scalefit="1" width="444" /> @@ -710,14 +712,16 @@ </section> <section id="sect-Reference_Guide-_JavaServer_Pages_Portlet_Example_-_JSF_example_using_the_JBoss_Portlet_Bridge_"> - <title><trademark class="trade">JSF</trademark> example using the JBoss Portlet Bridge </title> - <bridgehead>In order to write a portlet using JSF we need a piece of software called 'bridge' that lets us write a portlet application as if it was a JSF application, the bridge takes care of the interactions between the two layers.</bridgehead> + <title>JSF example using the JBoss Portlet Bridge </title> <para> - Such an example is available in examples/JSFHelloUser, it uses the JBoss Portlet Bridge. The configuration is slightly different from a JSP application, since it is a bit tricky it is usally a good idea to copy an existing application that starting from scratch. + In order to write a portlet using JSF a 'bridge' is needed. This software allows developers to write a portlet application as if it was a JSF application. The bridge then negotiates the interactions between the two layers. </para> <para> - First, as any JSF application, the file <literal>faces-config.xml</literal> is required. It includes the following required information in it: + An example of the JBoss Portlet Bridge is available in <filename>examples/JSFHelloUser</filename>. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. </para> + <para> + As in any JSF application, the file <literal>faces-config.xml</literal> is required. It must contain the following information: + </para> <programlisting role="XML">&lt;faces-config&gt; ...