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

Author: smumford Date: 2010-02-01 03:12:27 -0500 (Mon, 01 Feb 2010) New Revision: 1478 Modified: portal/trunk/docs/reference-guide/en/modules/development/Accessing_User_Profile.xml portal/trunk/docs/reference-guide/en/modules/development/Ajax_Loading_Mask_Layer_Deactivation.xml portal/trunk/docs/reference-guide/en/modules/development/Dynamic_Layouts.xml portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml portal/trunk/docs/reference-guide/en/modules/development/JavaScript_Inter_Application_Communication.xml portal/trunk/docs/reference-guide/en/modules/development/Upload_Component.xml portal/trunk/docs/reference-guide/en/modules/development/XML_Resource_Bundles.xml Log: edits to Chapter 3 Modified: portal/trunk/docs/reference-guide/en/modules/development/Accessing_User_Profile.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Accessing_User_Profile.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/Accessing_User_Profile.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -6,7 +6,7 @@ <section id="sect-Reference_Guide-Accessing_User_Profile"> <title>Accessing User Profile</title> <para> - To retrieve the logged in user you can do as follows : + The following code retrieves the details for a logged-in user: </para> <programlisting role="JAVA">// Alternative context: WebuiRequestContext context = WebuiRequestContext.getCurrentInstance() ; @@ -27,7 +27,7 @@ } </programlisting> <para> - Alternatives for retrieving the Organization Service + Below are two alternatives for retrieving the Organization Service: </para> <orderedlist> <listitem> Modified: portal/trunk/docs/reference-guide/en/modules/development/Ajax_Loading_Mask_Layer_Deactivation.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Ajax_Loading_Mask_Layer_Deactivation.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/Ajax_Loading_Mask_Layer_Deactivation.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -5,7 +5,7 @@ ]> <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_"> <title>Deactivation of the Ajax Loading Mask Layer </title> - <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-Overview"> +<!-- <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-Overview"> <title>Overview</title> <para> In this article, you will learn: @@ -27,83 +27,72 @@ </para> </listitem> </itemizedlist> - </section> + </section> --> <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-Purpose_of_requirement"> - <title>Purpose of requirement</title> - <itemizedlist> - <listitem> - <para> - Loading mask layer is displayed after ajax-call for blocking GUI to prevent user's action until the the ajax-request is completed. - </para> - </listitem> - <listitem> - <para> - Sometimes portal needs to be ready for user instructions without waiting previous instructions completed. So mask layer may need to be deactivated. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-How_to_deactivate_ajax_loading_mask_in_your_code"> - <title>How to deactivate ajax-loading mask in your code</title> - <para> - To generate script to make an asynchronous ajax-call, we use uicomponent.doAsync() method instead of uicomponent.event() method. - </para> - <para> - Here is an example: - </para> + <title>Purpose</title> + <para> + The loading mask layer is deployed after an ajax-call. Its purpose is to block the GUI in order to prevent further user actions until the the ajax-request has been completed. + </para> + <para> + However, the mask layer may need to be deactivated in instances where the portal requires user instructions before previous instructions have been carried out. + </para> + <procedure> + <title>How to deactivate the ajax-loading mask</title> + <step> + <para> + Generate a script to make an asynchronous ajax-call. Use the <literal>uicomponent.doAsync()</literal> method rather than the <literal>uicomponent.event()</literal> method. + </para> + <para> + For example: + </para> <programlisting>&lt;a href="&lt;%=uicomponent.doAsync(action, beanId, params)%&gt;" alt=""&gt;Asynchronous&lt;/a&gt; </programlisting> - <para> - Method doAsync() automatically adds a parameter into parameters list. Parameter async <emphasis>param = new Parameter(AJAX</emphasis> ASYNC,"true"); (AJAX <emphasis>ASYNC == "ajax</emphasis> async") - </para> - <para> - After all, its call method event() to generate script that make Ajax Request. This request is asynchronous and ajax-loading mask will not displayed. - </para> - <note> - <orderedlist> - <listitem> - <para> - You still also make an asynchronous request by using method uicomponent.event(). Using this way, you must add asyncparam manually. - </para> - </listitem> - <listitem> - <para> - GUI is blocked so that user can do only one action at a time (Request seems to be synchronous). But in fact ajax request always be asynchronous. See Synchronous issue section. - </para> - </listitem> - </orderedlist> - </note> + </step> + <step> + <para> + The <literal>doAsync()</literal> method automatically adds the following new parameter into the parameters list; <literal>asyncparam = new Parameter(AJAX ASYNC,"true"); (AJAX ASYNC == "ajax async")</literal> + </para> + <para> + This request is asynchronous and the ajax-loading mask will not deployed. + </para> + <note> + <para> + An asynchronous request can still be made using the <literal>uicomponent.event()</literal>. When using this method, however, the asyncparam must be added manually. + </para> + </note> + </step> + </procedure> + <para> + The GUI will be blocked to ensure a user can only request one action at a time and while the request seems to be synchronous, all ajax requests are, in fact always asynchronous. For further information refer to <xref linkend="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-Synchronous_issue"/>. + </para> </section> <section id="sect-Reference_Guide-Deactivation_of_the_Ajax_Loading_Mask_Layer_-Synchronous_issue"> <title>Synchronous issue</title> <para> - Almost web browser such as (IE, Chrome, Safari .. ) support ajax requests in two modes: Synchronous / Asynchronous with boolean value of bAsyn parameter. + Most web browsers support ajax requests in two modes: <emphasis>Synchronous</emphasis> and <emphasis>Asynchronous</emphasis>. This mode is specified with a boolean <literal>bAsync</literal> parameter. </para> <programlisting>var bAsync = false; // Synchronous request.open(instance.method, instance.url, bAsync); </programlisting> <para> - But in Mozilla Firefox versions prior to 3.5 it wouldn't support synchronous request. + However, in order to work with browsers that do not support <emphasis>Synchronous</emphasis> requests, <literal>bAsync</literal> is set to always be true (Ajax request will always be asynchronous). </para> - +<!-- <programlisting>var bAsync = false; // Synchronous request.open(instance.method, instance.url, bAsync); // Firefox will not execute </programlisting> <para> - So bAsync is set to always be true (Ajax request to always be asynchronous). - </para> + So + </para> --> <programlisting>// Asynchronous request request.open(instance.method, instance.url, true); </programlisting> - <para> - As a consequence that Ajax Request will always be asynchronous. - </para> + </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/development/Dynamic_Layouts.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Dynamic_Layouts.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/Dynamic_Layouts.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -8,14 +8,17 @@ <section id="sect-Reference_Guide-Dynamic_Layouts-Overview"> <title>Overview</title> <para> - The traditional way of rendering a portal page is a static one where you need a template, usually a jsp page, for each layout (2 columns, 3 columns and so on). That makes you depend on the integrator or developers as for each new layout you will need to ask for a custom development. + The traditional way of rendering a portal page is static, using a templat (usually a jsp page) for each layout (2 columns, 3 columns and so on). This method depends on the integrator or developers as each new layout will need a custom development. </para> <para> - GateIn has a dynamic way which creates a tree of nested UI containers that contain portlets as shown in the picture below. Each container is responsible for rendering its children. In the picture, the main container renders its children in several rows while the nested container displays them as columns. + &PRODUCT; has a dynamic rendering method which creates a tree of nested UI containers that contain portlets (as shown in the image below). </para> <para> - Furthermore, by manipulating the tree using the WYSIWYG editor, it allows you to create new containers, define how they will render their children, add new portlets. + Each container is responsible for rendering its children. In the below example the main container renders its children in several rows while the nested container displays them as columns. </para> + <para> + By manipulating the tree using a WYSIWYG editor new containers can be added, their child rendering can be defined and new portlets can be nested. + </para> <mediaobject> <imageobject> <imagedata fileref="images/portal.gif" format="GIF" /> @@ -26,10 +29,10 @@ <section id="sect-Reference_Guide-Dynamic_Layouts-Advanced_Drag_and_Drop_mechanism"> <title>Advanced Drag and Drop mechanism</title> <para> - As most portal use the static layout mechanism, they can only drag portlets from one static location, let's say a column, to another one. + As most portals use the static layout mechanism, portlets can only be dragged from one static location, such as a column, to another static location. </para> <para> - With GateIn Portal, it is possible to also drag the UI containers and the portlets and drop them in containers that are deeper or upper in the Portal component tree. This feature is unique and not just a tool! + In &PRODUCT;, it is possible to drag UI containers (and their portlets) and drop them in containers that are higher or lower in the Portal component tree. This feature is unique to &PRODUCT; </para> <mediaobject> <imageobject> @@ -37,13 +40,6 @@ </imageobject> </mediaobject> </section> - - <section id="sect-Reference_Guide-Dynamic_Layouts-Summary"> - <title>Summary</title> - <para> - With this innovative concept of dynamic layout, you can easily create portal pages with complex layout. - </para> - </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -7,29 +7,27 @@ <title>Internationalization Configuration</title> <section id="sect-Reference_Guide-Internationalization_Configuration-Overview"> <title>Overview</title> + <note> + <title>Assumed Knowledge</title> + <para> + &PRODUCT; is fully configurable for internationalization, however users should have a general knowledge of Internationalization in Java products before attempting these configurations. + </para> + <para> + Sun Java hosts a comprehensive guide to internationalizing java products at <ulink url="http://java.sun.com/docs/books/tutorial/i18n/TOC.html">...;. + </para> + </note> + <para> - All aspects of internationalization in &PRODUCT; are covered. You should have a general knowledge of Internationalization in Java products. Sun created a <ulink url="http://java.sun.com/docs/books/tutorial/i18n/TOC.html">... internationalization tutorial</ulink> . + All &PRODUCT; applications contain property files for various languages. They are packaged with the portlets applications in a <filename>WEB-INF/classes/locale/</filename> directory. </para> <para> - All embedded applications contains property files for various languages. They are packaged with the portlets applications in a WEB-INF/classes/locale/ directory. + These files are located in the <literal>classes</literal> folder of the WEB-INF directory, so as to be loaded by the ClassLoader. </para> <para> - You should notice that + All resource files are in a subfolder named <literal>locale</literal>. </para> - <itemizedlist> - <listitem> - <para> - the files are located in the <literal>classes</literal> folder of your WEB-INF, this way they are loaded by the ClassLoader. - </para> - </listitem> - <listitem> - <para> - all resource files are in a subfolder named <literal>locale</literal> - </para> - </listitem> - </itemizedlist> <para> - For instance you will find the translations for the NavigationPortlet in <literal>web.war/WEB-INF/classes/locale/portlet/portal</literal> + For instance; the translations for the <emphasis>NavigationPortlet</emphasis> are located in <literal>web.war/WEB-INF/classes/locale/portlet/portal</literal> </para> <programlisting>NavigationPortlet_de.properties @@ -42,21 +40,24 @@ NavigationPortlet_ar.xml </programlisting> <para> - Inside those file we find typical <literal>key=value</literal> Java EE properties. For example the French one: + Inside those file are typical <literal>key=value</literal> Java EE properties. For example the French one: </para> <programlisting>javax.portlet.title=Portlet Navigation </programlisting> <para> - Furthermore there are properties files in the portal itself. They form together the <emphasis role="bold">portal resource bundle</emphasis>. From a portlet you can then access translations from the portlet itself or shared at the portal level, both are aggregated when you need them. + There are also properties files in the portal itself. They form the <emphasis role="bold">portal resource bundle</emphasis>. </para> + <para> + From a portlet you can then access translations from the portlet itself or shared at the portal level, both are aggregated when you need them. + </para> <note> <title>Translation in XML format</title> <para> It is also possible to use a proprietary XML format to define translations. This is a more convenient way to translate a document for some languages such as Japanese, Arabic or Russian. Property files have te be ASCII encoded, while the XML file can define its encoding. As a result it's easier for a human being to read (and fix) a translation in XML instead of having to decode and encode the property file. </para> <para> - More information are available here: <xref linkend="sect-Reference_Guide-XML_Resources_Bundles" /> + For more information refer to: <xref linkend="sect-Reference_Guide-XML_Resources_Bundles" /> </para> </note> </section> @@ -64,10 +65,10 @@ <section id="sect-Reference_Guide-Internationalization_Configuration-Locales_configuration"> <title>Locales configuration</title> <para> - Various languages are available in the shipped portal, one may want to add or remove languages. This configuration will define the list of languages in the "Change Language" section of the portal that the user can pick from. + Various languages are available in the portal package. The configuration below will define which languages are shown in the "Change Language" section and made available to users. </para> <para> - In the <filename>02portal.war:/WEB-INF/conf/common/common-configuration.xml</filename> file of your installation you can find the following section: + The <filename>02portal.war:/WEB-INF/conf/common/common-configuration.xml</filename> file of your installation contains the following section: </para> <programlisting role="XML">&lt;component&gt; @@ -82,7 +83,10 @@ &lt;/component&gt; </programlisting> <para> - The configuration points to the locale configuration file such as the following one located in <filename>02portal.war:/WEB-INF/conf/common/locales-config.xml</filename>: + This configuration points to the locale configuration file. + </para> + <para> + The locale configuration file (<filename>02portal.war:/WEB-INF/conf/common/locales-config.xml</filename>) contains the following code: </para> <programlistingco> <areaspec> @@ -121,12 +125,12 @@ <calloutlist> <callout arearefs="area-Reference_Guide-i18n.locales.configuration.locale"> <para> - <emphasis>locale</emphasis> The locale has to be defined such as defined here <ulink type="http" url="http://ftp.ics.uci.edu-pub-ietf-http-related-iso639.txt" />, in this example "ar" is Arabic. + <emphasis>locale</emphasis> The locale has to be defined such as defined here <ulink type="http" url="http://ftp.ics.uci.edu-pub-ietf-http-related-iso639.txt" />. In this example "<emphasis>ar</emphasis>" is Arabic. </para> </callout> <callout arearefs="area-Reference_Guide-i18n.locales.configuration.output-encoding"> <para> - <emphasis>output-encoding</emphasis> Encoding It's highly recommended to always use <emphasis role="bold">UTF-8</emphasis>. + <emphasis>output-encoding</emphasis> deals with character encoding. It is recommended that <emphasis role="bold">UTF-8</emphasis> be used. </para> </callout> <callout arearefs="area-Reference_Guide-i18n.locales.configuration.input-encoding"> @@ -141,7 +145,7 @@ </callout> <callout arearefs="area-Reference_Guide-i18n.locales.configuration.orientation"> <para> - <emphasis>description</emphasis> The default orientation of text and images is Left-To-Right. GateIn supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Therefore you can define the orientation to use as explained in <xref linkend="sect-Reference_Guide-RTL_Right_To_Left_Framework" />. + <emphasis>description</emphasis> The default orientation of text and images is Left-To-Right. &PRODUCT; supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Modifying text orientation is explained in <xref linkend="sect-Reference_Guide-RTL_Right_To_Left_Framework" />. </para> </callout> </calloutlist> @@ -198,7 +202,7 @@ <calloutlist> <callout arearefs="area-Reference_Guide-i18n.rb.service.classpath_resources"> <para> - <emphasis>classpath.resources</emphasis> We will talk later about classpath.resources + <emphasis>classpath.resources</emphasis> are discussed in a later section. </para> </callout> <callout arearefs="area-Reference_Guide-i18n.rb.service.init_resources"> @@ -208,8 +212,11 @@ </callout> <callout arearefs="area-Reference_Guide-i18n.rb.service.portal_resource_names"> <para> - <emphasis>portal.resource.names</emphasis> Defines all resources that belong to the <emphasis>Portal Resource Bundle</emphasis>. This means that these resources are merged to a single resource bundle which is accessible from anywhere in GateIn products. As mentioned, all these keys are located in the same bundle, which is separated from the navigation resource bundles. + <emphasis>portal.resource.names</emphasis> Defines all resources that belong to the <emphasis>Portal Resource Bundle</emphasis>. </para> + <para> + These resources are merged to a single resource bundle which is accessible from anywhere in &PRODUCT;. All these keys are located in the same bundle, which is separated from the navigation resource bundles. + </para> </callout> </calloutlist> </programlistingco> @@ -219,54 +226,71 @@ <section id="sect-Reference_Guide-Internationalization_Configuration-Navigation_Resource_Bundles"> <title>Navigation Resource Bundles</title> <para> - There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. In the example above you see bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles lives in a different sphere, they are independent of each other and they do not belong to the portal.resource.names parameter (because they are not mentioned in portal.resource.names). + There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. </para> <para> - As you learned in the introduction you must put the properties for a group in the WEB-INF/classes/locale/navigation/group/ folder. Such as: <literal>/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties</literal> The folder and file names must correspond to the group hierarchy. The group name "executive-board" is followed by the iso 639 code. For each language you defined in the LocalesConfig you must provide a resource file. If you ever change the name of a group you also need to change the name of the folder and/or files of the correspondent navigation resource bundles. Content of executive-board_en.properties: + The previous example shows bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles occupies a different sphere, they are independent of each other and they are not included in the <parameter>portal.resource.names</parameter> parameter. + </para> + <para> + The properties for a group must be in the <filename>WEB-INF/classes/locale/navigation/group/</filename> folder. <literal>/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties</literal>, for example. + </para> + <para> + The folder and file names must correspond to the group hierarchy. The group name "<parameter>executive-board</parameter>" is followed by the iso 639 code. + </para> + <para> + For each language defined in <parameter>LocalesConfig</parameter> must have a resource file defined. If the name of a group is changed the name of the folder and/or files of the correspondent navigation resource bundles must also be changed. + </para> + <para> + Content of <filename>executive-board_en.properties</filename>: + <programlisting>organization.title=Organization organization.newstaff=New Staff organization.management=Management </programlisting> </para> <para> - This resource bundle is only accessible for the navigation of the organization.management.executive-board group. + This resource bundle is only accessible for the navigation of the <parameter>organization.management.executive-board</parameter> group. </para> </section> - + <section id="sect-Reference_Guide-Internationalization_Configuration-Portlets"> <title> Portlets </title> <para> - classpath.resources + Portlets are independent applications and deliver their own resource files. </para> <para> - Portlets are independent application and they deliver their own resource files. + All shipped portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> subfolder. The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines this subfolder. <!-- Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. --> </para> - <para> - All shipped-in portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> subfolder. The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines this subfolder. <!-- Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. --> - </para> - <section id="sect-Reference_Guide-Portlets-Example"> + <procedure> <title>Example</title> - <para> - Let's suppose you want to add a Spanish translation to the GadgetPortlet. - </para> - <para> - Create the file <literal>GadgetPortlet_es.properties</literal> in: <filename>WEB-INF/classes/locale/portlet/gadget/GadgetPortlet</filename> - </para> - <para> - In <emphasis role="bold">portlet.xml</emphasis>, add Spanish as a <emphasis role="bold">supported-locale</emphasis> ('es' is the 2 letters code for Spanish), the <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : - </para> - + <step> + <para> + To add a Spanish translation to the <parameter>GadgetPortlet</parameter>. + </para> + </step> + <step> + <para> + Create the file <literal>GadgetPortlet_es.properties</literal> in: <filename>WEB-INF/classes/locale/portlet/gadget/GadgetPortlet</filename>. + </para> + </step> + <step> + <para> + In <filename>portlet.xml</filename>, add <parameter>Spanish</parameter> as a <emphasis role="bold">supported-locale</emphasis> ('es' is the 2 letters code for Spanish), the <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : + </para> <programlisting role="XML">&lt;supported-locale&gt;en&lt;/supported-locale&gt; &lt;supported-locale&gt;es&lt;/supported-locale&gt; &lt;resource-bundle&gt;locale.portlet.gadget.GadgetPortlet&lt;/resource-bundle&gt; </programlisting> + </step> + </procedure> <para> See the portlet specification for more details about portlet internationalization. </para> + <section id="sect-Reference_Guide-Example-Standard_portlet_resource_keys"> <title>Standard portlet resource keys</title> <para> - The portlet specifications defines three standard keys: Title, Short Title and Keywords. Keywords contain a comma-separated list of keywords. + The portlet specifications defines three standard keys: Title, Short Title and Keywords. Keywords is formatted as a comma-separated list of tags. </para> <programlisting> javax.portlet.title=Breadcrumbs Portlet @@ -278,7 +302,10 @@ <section id="sect-Reference_Guide-Example-Access"> <title>Access</title> <para> - Whenever you want to display a property in the user language you use its <emphasis>key</emphasis>. Using the below access method the translation is returned in the preferred language for the connected user: + These <emphasis>key</emphasis>s are used to display a property in the user language. + </para> + <para> + The following access method enables translation to the preferred language for the connected user: </para> <itemizedlist> <listitem> @@ -298,17 +325,22 @@ </para> </listitem> </itemizedlist> - </section> </section> <section id="sect-Reference_Guide-Portlets-Debugging_resource_bundle_usage"> <title>Debugging resource bundle usage</title> <para> - When an application needs to be translated, it is never obvious to find out the right key for a given translated property. When the portal is executed in <emphasis role="bold">debug mode</emphasis> it is possible to select among the available languages a special language called <emphasis role="bold">Magic locale</emphasis>. + When translating an application it can sometimes be difficult to find the right key for a given property. + </para> + <para> + Execute the portal in <emphasis role="bold">debug mode</emphasis> and select, from the available languages, select the special language; <emphasis role="bold">Magic locale</emphasis>. </para> <para> - This feature translates a key to the same key value. For instance, the translated value for the key "organization.title" is simply the value "organization.title". Selecting that language allows to use the portal and its applications with <emphasis role="bold">all the keys visible</emphasis> and it is easy to find out the correct key for a given label in the portal page. + This feature translates a key to the same key value. + </para> + <para> + For example, the translated value for the key "<parameter>organization.title</parameter>" is simply the value "<parameter>organization.title</parameter>". Selecting that language allows use of the portal and its applications with all the keys visible. This makes it easier to find out the correct key for a given label in the portal page. </para> </section> Modified: portal/trunk/docs/reference-guide/en/modules/development/JavaScript_Inter_Application_Communication.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/JavaScript_Inter_Application_Communication.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/JavaScript_Inter_Application_Communication.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -8,36 +8,53 @@ <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Overview"> <title>Overview</title> <para> - This kind of communication is made to allow applications within a page to exchange data. This library is made for broadcasting messages on topic. This is basically based on 3 functions : subscribe, publish and unsubscribe. + JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. This library is made for broadcasting messages on topic. </para> <para> - When you subscribe to a topic, you receive all the subtopic message. for example, if I subscribe to "/eXo/application", and an application send a message on "/eXo/application/map", i will receive it, but if another application send a message on "/eXo", i will not receive it. + It is based on 3 functions: </para> - </section> - - <!-- - <section - id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Common_topics"> - <title>Common topics</title> - <para> - Stuff Goes Here? - </para> - </section> - --> - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-eXo"> - <title>/eXo</title> + <itemizedlist> + <listitem> + <para> + Subscribe. + </para> + </listitem> + <listitem> + <para> + Publish. + </para> + </listitem> + <listitem> + <para> + Unsubscribe. + </para> + </listitem> + </itemizedlist> <para> - It contains all the events generated by the platform. + A subscription to a topic will receive any subtopic messages. For example; An application subscribed to "<literal>/eXo/application</literal>" will receive messages sent on the "<literal>/eXo/application/map</literal>" topic. A message sent on "<literal>/eXo</literal>", however, would not be received. </para> + <variablelist> + <title>Subscription Topics</title> + <varlistentry> + <term>/eXo</term> + <listitem> + <para> + This topic contains all the events generated by the platform. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>/eXo/portal/notification</term> + <listitem> + <para> + A message is sent on this topic will prompt a popup notification in the top right of the screen. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> - <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-eXoportalnotification_"> - <title>/eXo/portal/notification </title> - <para> - When a message is sent on this topic, a popup message appears on the top right of the screen. - </para> - </section> - <!-- <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInportalchangeTitle"> @@ -88,7 +105,7 @@ <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Library"> <title>Library</title> <para> - The inter application communication library can be found in <filename>01eXoResources.war:/javascript/eXo/core/Topic.js</filename> + The Inter Application Communication library is found in <filename>01eXoResources.war:/javascript/eXo/core/Topic.js</filename> </para> <programlisting>/** @@ -131,65 +148,107 @@ <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Syntax"> <title>Syntax</title> <para> - <literal>subscribe</literal> is used to subscribe a callback to a topic. Parameters: - <itemizedlist> + The three messaging functions require particular objects and definitions in their syntax: + </para> + + <variablelist> + <varlistentry> + <term>Subscribe</term> <listitem> - <para> - <literal>topic</literal> is the topic that will be listened + <para> + The <literal>subscribe</literal> function is used to subscribe a callback to a topic. It uses the following parameters: </para> - </listitem> - <listitem> - <para> - <literal>func</literal> is the name of the function of obj to call when a message is received on the topic. It has to be a function that take an Object in parameter. the event received have this format: + <variablelist> + <varlistentry> + <term>topic</term> + <listitem> + <para> + The topic that will be listened for. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>func</term> + <listitem> + <para> + The name of the object function to call when a message is received on the topic. It has to be a function that takes an Object parameter. The event received will have this format: <programlisting>{ senderId:senderId, message:message, topic: topic } </programlisting> - </para> + </para> + </listitem> + </varlistentry> + </variablelist> </listitem> - </itemizedlist> - </para> - <para> - <literal>publish</literal> is used to publish an event to the other subscribers to the given channels. Parameters: - <itemizedlist> + </varlistentry> + <varlistentry> + <term>Publish</term> <listitem> <para> - <literal>senderId</literal> is a string that identify the sender + The <literal>publish</literal> function is used to publish an event to the other subscribered applications through the given channels. Its parameters are: </para> + <variablelist> + <varlistentry> + <term>senderId</term> + <listitem> + <para> + This is a string that identifies the sender. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>topicName</term> + <listitem> + <para> + The topic that the message will be published. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>message</term> + <listitem> + <para> + This is the message body to be delivered to the subscribers to the topic. + </para> + </listitem> + </varlistentry> + </variablelist> </listitem> + </varlistentry> + <varlistentry> + <term>Unsubscribe</term> <listitem> <para> - <literal>topicName</literal> is the topic that the message will be published + The <literal>unsubscribe</literal> function is used to unsubscribe a callback to a topic. The required parameters are: </para> + <variablelist> + <varlistentry> + <term>topic</term> + <listitem> + <para> + The topic that will is to be unsubscribed from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>id</term> + <listitem> + <para> + This is the context object. + </para> + </listitem> + </varlistentry> + </variablelist> </listitem> - <listitem> - <para> - <literal>message</literal> is the message that's going to be delivered to the subscribers to the topic - </para> - </listitem> - </itemizedlist> - </para> - <para> - <literal>unsubscribe</literal> is used to unsubscribe a callback to a topic Parameters: - <itemizedlist> - <listitem> - <para> - <literal>topic</literal> is the topic that will be unsubscribe - </para> - </listitem> - <listitem> - <para> - <literal>id</literal> is the context object - </para> - </listitem> - </itemizedlist> - </para> + </varlistentry> + </variablelist> </section> <section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Example"> - <title>Example</title> + <title>Example [of what?]</title> <programlisting role="HTML">&lt;%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %&gt; &lt;portlet:defineObjects/&gt; Modified: portal/trunk/docs/reference-guide/en/modules/development/Upload_Component.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Upload_Component.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/Upload_Component.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -5,7 +5,7 @@ ]> <section id="sect-Reference_Guide-Upload_Component"> <title>Upload Component</title> - <section id="sect-Reference_Guide-Upload_Component-Overview"> +<!-- <section id="sect-Reference_Guide-Upload_Component-Overview"> <title>Overview</title> <para> In this article, you will learn how to : @@ -32,15 +32,15 @@ </para> </listitem> </itemizedlist> - </section> + </section> --> <section id="sect-Reference_Guide-Upload_Component-Upload_Service"> <title>Upload Service</title> <para> - The service is defined by the class : org.exoplatform.upload.UploadService; + The service is defined by the class: <literal>org.exoplatform.upload.UploadService</literal>; </para> <para> - You can configure it with the following xml code : + This can be configured with the following xml code: </para> <programlisting role="XML">&lt;component&gt; @@ -55,40 +55,48 @@ &lt;/component&gt; </programlisting> <para> - As you can see, you can configure a default upload size limit for the service. The value unit is in MegaBytes. This limit will be used by default by all applications if no specific limit is set. You will see in the next chapter how to set a different limit for your application. - </para> + This code allows for a default upload size limit for the service to be configured. The value unit is in MegaBytes. + </para> <para> - If you set the value at 0, the upload size will be unlimited. + This limit will be used by default by all applications if no application-specific limit is set. Setting a different limit for applications is discussed in a later section. </para> - </section> - - <section id="sect-Reference_Guide-Upload_Component-How_to_use_the_upload_component_in_your_application_"> - <title>How to use the upload component in your application </title> <para> - To use the component, you must create an object of type org.exoplatform.webui.form.UIFormUploadInput, using one of the two available constructors : + If the value is set at <parameter>0</parameter> the upload size is unlimited. </para> - + + <procedure id="proc-Reference_Guide-Upload_Component-How_to_use_the_upload_component"> + <title>How to use the upload component</title> + <step> + <para> + Create an object type <literal>org.exoplatform.webui.form.UIFormUploadInput</literal>. + </para> + <para> + Two constructors are available for this: + </para> + <programlisting>public UIFormUploadInput(String name, String bindingExpression) </programlisting> - <para> - or: - </para> - + <para> + or: + </para> + <programlisting>public UIFormUploadInput(String name, String bindingExpression, int limit) </programlisting> - <para> - Here is an example using the second form : - </para> - + <para> + This is an example using the second form : + </para> + <programlisting role="JAVA">PortletRequestContext pcontext = (PortletRequestContext)WebuiRequestContext.getCurrentInstance(); PortletPreferences portletPref = pcontext.getRequest().getPreferences(); int limitMB = Integer.parseInt(portletPref.getValue("uploadFileSizeLimitMB", "").trim()); UIFormUploadInput uiInput = new UIFormUploadInput("upload", "upload", limitMB); </programlisting> - <para> - To get the limit from the xml configuration, you can add this piece of code in the files portlet.xml or portlet-preferences.xml : - </para> - + </step> + <step> + <para> + To obtain the limit from the <literal>xml</literal> configuration, this piece of code can be added to the either <filename>portlet.xml</filename> or <filename>portlet-preferences.xml</filename> : + </para> + <programlisting role="XML">&lt;preference&gt; &lt;name&gt;uploadFileSizeLimitMB&lt;/name&gt; &lt;value&gt;30&lt;/value&gt; @@ -96,46 +104,52 @@ &lt;/preference&gt; </programlisting> <para> - Again, a 0 value means unlimited upload size, and the value unit is set in MegaBytes. + Again, a <parameter>0</parameter> value means an unlimited upload size, and the value unit is set in MegaBytes. </para> - <para> - To get the uploaded data use the <literal>getUploadDataAsStream()</literal> method: - </para> + </step> + <step> + <para> + Use the <literal>getUploadDataAsStream()</literal> method to get the uploaded data: + </para> <programlisting role="JAVA">UIFormUploadInput input = (UIFormUploadInput)uiForm.getUIInput("upload"); InputStream inputStream = input.getUploadDataAsStream(); ... jcrData.setValue(inputStream); </programlisting> - <para> - Clean the uploaded file - </para> - <para> - The upload service stores a temporary file on the filesystem during the process. When the upload is finished, you must clean the service in order to : - </para> - <itemizedlist> - <listitem> + </step> + <step> <para> - delete the temporary file + The upload service stores a temporary file on the filesystem during the upload process. When the upload is finished, the service must be cleaned in order to: </para> - </listitem> - <listitem> + <orderedlist numeration="arabic"> + <listitem> + <para> + Delete the temporary file. + </para> + </listitem> + <listitem> + <para> + Delete the classes used for the upload. + </para> + </listitem> + </orderedlist> <para> - delete the classes used for the upload + Use the<literal>removeUpload()</literal> method defined in the upload service to purge the file: </para> - </listitem> - </itemizedlist> - <para> - To do that, use the<literal>removeUpload()</literal> method defined in the upload service, like this : - </para> <programlisting role="JAVA">UploadService uploadService = uiForm.getApplicationComponent(UploadService.class) ; UIFormUploadInput uiChild = uiForm.getChild(UIFormUploadInput.class) ; uploadService.removeUpload(uiChild.getUploadId()) ; </programlisting> - <para> - Be sure to get and save the file <emphasis role="bold">before</emphasis> you clean the service - </para> +<note> + <title>Saving the uploaded file</title> + <para> + Ensure the file is saved <emphasis role="bold">before</emphasis> the service is cleaned. + </para> +</note> + </step> + </procedure> </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/development/XML_Resource_Bundles.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/XML_Resource_Bundles.xml 2010-02-01 07:51:11 UTC (rev 1477) +++ portal/trunk/docs/reference-guide/en/modules/development/XML_Resource_Bundles.xml 2010-02-01 08:12:27 UTC (rev 1478) @@ -8,38 +8,31 @@ <section id="sect-Reference_Guide-XML_Resources_Bundles-Motivation"> <title>Motivation</title> <para> - Usually resource bundles are stored in property files however as property files are plain files it raise issues with the encoding of the file. The XML resource bundle format has been developed to provide an alternative to property files. + Resource bundles are usually stored in property files. However, as property files are plain files, issues with the encoding of the file may arise. The XML resource bundle format has been developed to provide an alternative to property files. </para> <itemizedlist> <listitem> <para> - The XML format declares the encoding of the file in the XML declaration which avoids to use the native2ascii program and mess with encoding. + The XML format declares the encoding of the file. This avoids use of the native2ascii program which can interfere with encoding. </para> </listitem> <listitem> <para> - Property files use the ISO 8859-1 which does not cover the full unicode charset and language such as Arabic would not be supported natively and require the use of escaping, leading the files to be barely maintainable. + Property files generally use ISO 8859-1 character encoding which does not cover the full unicode charset. As a result, languages such as Arabic would not be natively supported. </para> </listitem> <listitem> <para> - Tooling support for XML files is better than the tooling for Java property files and usually the XML editor cope very well with the file encoding. + Tooling for XML files is better supported than the tooling for Java property files and thus the XML editor copes well with the file encoding. </para> </listitem> </itemizedlist> </section> - <section id="sect-Reference_Guide-XML_Resources_Bundles-Portal_support"> - <title>Portal support</title> - <para> - In order to be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file but instead of ending with the <emphasis role="bold">.properties</emphasis> suffix, it ends with the <emphasis role="bold">.xml</emphasis> suffix. For instance <emphasis role="bold"> AccountPortlet_ar.xml</emphasis> instead of <emphasis role="bold">AccountPortlet_ar.properties</emphasis>. - </para> - </section> - <section id="sect-Reference_Guide-XML_Resources_Bundles-XML_format"> <title>XML format</title> <para> - The XML format is very simple and has been developed based on the DRY (Don't Repeat Yourself) principle. Usually resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file: + The XML format is very simple and has been developed based on the <emphasis>DRY</emphasis> (Don't Repeat Yourself) principle. Usually resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file: </para> <programlisting>UIAccountForm.tab.label.AccountInputSet = ... @@ -77,6 +70,16 @@ &lt;/bundle&gt; </programlisting> </section> + + <section id="sect-Reference_Guide-XML_Resources_Bundles-Portal_support"> + <title>Portal support</title> + <para> + In order to be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file and it must use the <emphasis role="bold">.xml</emphasis> suffix. + </para> + <para> + For example; for the Account Portlet to be displayed in Arabic, the resource bundle would be <emphasis role="bold"> AccountPortlet_ar.xml</emphasis> rather than <emphasis role="bold">AccountPortlet_ar.properties</emphasis>. + </para> + </section> </section>