[richfaces-svn-commits] JBoss Rich Faces SVN: r13302 - trunk/docs/userguide/en/src/main/docbook/included.

Author: msorokin Date: 2009-03-30 13:10:12 -0400 (Mon, 30 Mar 2009) New Revision: 13302 Modified: trunk/docs/userguide/en/src/main/docbook/included/layout.desc.xml trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.desc.xml trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.xml Log: https://jira.jboss.org/jira/browse/RF-6593 files with components' descriptions Modified: trunk/docs/userguide/en/src/main/docbook/included/layout.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/layout.desc.xml 2009-03-30 17:07:49 UTC (rev 13301) +++ trunk/docs/userguide/en/src/main/docbook/included/layout.desc.xml 2009-03-30 17:10:12 UTC (rev 13302) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section role="updated"> +<section role="new"> <sectioninfo> <keywordset> <keyword>layout</keyword> Modified: trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.desc.xml 2009-03-30 17:07:49 UTC (rev 13301) +++ trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.desc.xml 2009-03-30 17:10:12 UTC (rev 13302) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<section role="updated"> +<section role="new"> <sectioninfo> <keywordset> <keyword>layouPanel</keyword> @@ -10,16 +10,11 @@ <title>Description</title> <para>The <emphasis role="bold"> <property>&lt;rich:layouPanel&gt;</property> - </emphasis> + </emphasis> is an auxiliary component used to create layout areas within the <emphasis role="bold"><property>&lt;rich:layout&gt;</property></emphasis> container. </para> </section> -<section> - <title>Key Features</title> - <itemizedlist> - <listitem><para>P</para></listitem> - </itemizedlist> + </section> -</section> \ No newline at end of file Modified: trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.xml 2009-03-30 17:07:49 UTC (rev 13301) +++ trunk/docs/userguide/en/src/main/docbook/included/layoutPanel.xml 2009-03-30 17:10:12 UTC (rev 13302) @@ -47,7 +47,11 @@ <emphasis role="bold">Example:</emphasis> </para> <programlisting role="XML"><![CDATA[... -<layoutPanel /> +<rich:layout> + <rich:layoutPanel position="center"> + <!--center--> +</rich:layoutPanel> +</rich:layout> ...]]></programlisting> </section> <section> @@ -65,506 +69,12 @@ <title>Details of Usage</title> <para>The <emphasis role="bold"> <property>&lt;layoutPanel&gt;</property> - </emphasis> component consists of two parts:<itemizedlist> - <listitem> - <para> - <property>List of files</property> which contains the list of currently - chosen files to upload with possibility to manage every file </para> - </listitem> - <listitem> - <para> - <property>Component controls</property> - the bar with controls for managing - the whole component </para> - </listitem> - </itemizedlist> + </emphasis> component is used to split the area inside the <emphasis role="bold"><property>&lt;rich:layout&gt;</property></emphasis> into up to 5 parts: top, left, center, right, bottom. + </para> - - - <para> There are two places where the uploaded files are stored: </para> - <itemizedlist> - <listitem> - <para> In the temporary folder (depends on OS) if the value of the - <code>createTempFile</code> parameter in <property>Ajax4jsf - Filter</property> (in web.xml) section is &quot;true&quot; (by Default) </para> - <programlisting role="XML"><![CDATA[... -<init-param> - <param-name>createTempFiles</param-name> - <param-value>true</param-value> -</init-param> -...]]></programlisting> - </listitem> - <listitem> - <para> In the RAM if the value of the <code>createTempFile</code> parameter in - <property>Ajax4jsf Filter</property> section is &quot;false&quot;. - This is a better way for storing small-sized files. </para> - </listitem> - </itemizedlist> - - <para> The <emphasis> - <property>&quot;uploadData&quot;</property> - </emphasis> attribute defines the collection of files uploaded. See the example below. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel uploadData="#{bean.data}"/> -...]]></programlisting> - - <para>The <emphasis> - <property>&quot;layoutPaneledListener&quot;</property> - </emphasis> is called at server side after every file uploaded and used for the saving - files from temporary folder or RAM. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel uploadData="#{bean.data}" layoutPanelListener="#{bean.listener}"/> - ...]]></programlisting> - <para> The following methods for processing the uploaded files are available: </para> - <itemizedlist> - <listitem> - <para> - <code>isMultiUpload()</code>. It returns &quot;true&quot; if several - files have been uploaded </para> - </listitem> - <listitem> - <para> - <code>getUploadItems()</code>. It returns the list of the uploaded files. If one - file was uploaded, the <code>getUploadItems()</code> method will return the list - consisting of one file </para> - </listitem> - <listitem> - <para> - <code>getUploadItem()</code>. It returns the whole list in case of uploading one - file only. If several files were uploaded, the <code>getUploadItem()</code> - method will return the first element of the uploaded files list. </para> - </listitem> - </itemizedlist> - <para> Automatically files uploading could be performed by means of the <emphasis> - <property> &quot;immediateUpload&quot;</property> - </emphasis> attribute. If the value of this attribute is &quot;true&quot; files - are uploaded automatically once they have been added into the list. All next files in - the list are uploaded automatically one by one. If you cancel uploading process next - files aren&apos;t started to upload till you press the &quot;Upload&quot; - button or clear the list. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel uploadData="#{bean.data}" layoutPanelListener="#{bean.listener}" immediateUpload="true"/> - ...]]></programlisting> - - <para> The <emphasis> - <property> &quot;autoclear&quot;</property> - </emphasis> attribute is used to remove automatically files from the list after upload - completed. See the simple example below. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel uploadData="#{bean.data}" autoclear="true"/> -...]]></programlisting> - <para> Each file in list waiting for upload has link &quot;Cancel&quot; opposite its name. - Clicking this link invokes JS API <code>remove()</code> function, which gets <code>$(&apos;id&apos;).component.entries[i]</code> as a parameter - and removes the particular file from list and from the queue for upload. - After a file has been uploaded the link &quot;Cancel&quot; changes to &quot;Clear&quot;. - Clicking &quot;Clear&quot; invokes <code>clear()</code> JS API function, which also gets ID of the particular entry and removes it from the list. - Uploaded to server file itself is kept untouched. - </para> - - <!--RESTRICTIONS--> - - <para> The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component provides following restrictions: </para> - <itemizedlist> - <listitem> - <para> On <property> file types</property>, use <emphasis> - <property> &quot;acceptedTypes&quot;</property> - </emphasis> attribute to define file types accepted by component. In the example - below only files with &quot;html&quot; and &quot;jpg&quot; - extensions are accepted to upload. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel acceptedTypes="html, jpg"/> -...]]></programlisting> - </listitem> - <listitem> - <para> On <property> file size</property>, use the <code>maxRequestSize</code> - parameter(value in bytes) inside <property>Ajax4jsf Filter</property> section in - <property>web.xml</property>: </para> - <programlisting role="XML"><![CDATA[... -<init-param> - <param-name>maxRequestSize</param-name> - <param-value>1000000</param-value> -</init-param> -...]]></programlisting> - </listitem> - <listitem> - <para> On <property>max files quantity</property>, use the <emphasis> - <property> &quot;maxFilesQuantity&quot;</property> - </emphasis> attribute to define max number of files allowed to be uploaded. - After a number of files in the list equals to the value of this attribute - &quot;Add&quot; button is disabled and nothing could be uploaded even if - you clear the whole list. In order to upload files again you should rerender the - component. As it could be seen in the example below, only 2 files are accepted - for uploading. </para> - - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel maxFilesQuantity="2"/> - ...]]></programlisting> - <para> This is the result: </para> - <figure> - <title><emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis>with <emphasis> - <property> &quot;maxFilesQuantity&quot;</property> - </emphasis> attribute</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/layoutPanel2.png"/> - </imageobject> - </mediaobject> - </figure> - </listitem> - </itemizedlist> - - - - - <para id="layoutPanelEventAttributes">The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component provides a number of specific event attributes: </para> - <itemizedlist> - - <listitem> - <para> The <emphasis> - <property> &quot;onadd&quot;</property> - </emphasis>a event handler called on an add file operation </para> - </listitem> - - <listitem> - <para> The <emphasis> - <property> &quot;onupload&quot;</property> - </emphasis> which gives you a possibility to cancel the upload at client side - </para> - </listitem> - <listitem> - <para> The <emphasis> - <property> &quot;onuploadcomplete&quot;</property> - </emphasis> which is called after all files from the list are uploaded </para> - </listitem> - <listitem> - <para> The <emphasis> - <property> &quot;onuploadcanceled&quot;</property> - </emphasis> which is called after upload has been canceled via cancel control - </para> - </listitem> - <listitem> - <para> The <emphasis> - <property> &quot;onerror&quot;</property> - </emphasis> which is called if the file upload was interrupted according to any - errors </para> - </listitem> - </itemizedlist> - - - - - <!--Flash Module--> - <para> The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component has an embedded Flash module that adds extra functionality to the - component. The module is enabled with <emphasis> - <property> &quot;allowFlash&quot;</property> - </emphasis> attribute set to &quot;true&quot;. </para> - <para>These are the additional features that the Flash module provides:</para> - - <itemizedlist> - <listitem> - <para>Multiple files choosing;</para> - </listitem> - <listitem> - <para>Permitted file types are specified in the &quot;Open File&quot; dialog - window;</para> - </listitem> - <listitem> - <para>A number of additional entry object properties are also available, which can - be found <link linkend="objectProperties">here</link>. </para> - </listitem> - </itemizedlist> - - <para>Apart from uploading files to the sever without using AJAX, the Flash module provides - a number of useful API functions that can be used to obtain information about the - uploaded file. </para> - - <para>There are 2 ways to obtain the data stored in the layoutPanelEntry object. </para> - - <itemizedlist> - <listitem> - <para>By means of JavaScript on the client side. Use the following syntax for that - <code>entries[i].propertyName</code>. For example - <code>entries[0].state</code> will return the state of the file the is being - processed or has just been processed.</para> - </listitem> - - - <listitem> - <para>The properties of <code>layoutPanelEntry</code> object can be retrieved using - the <code>entry.propertyName</code> expression in the specific event attributes. - For example, - <code>onupload=&quot;alert(event.memo.entry.fileName);&quot; </code> - will display a message with the name of the file at the very moment when upload - operation starts. A full list of properties can be found <link - linkend="objectPropertiesWithAttributes">here</link>.</para> - </listitem> - - - </itemizedlist> - <para>The given bellow code sample demonstrates how the properties can be used. Please study - it carefully. </para> - <programlisting role="XML"><![CDATA[... - <head> - <script> - function _onaddHandler (e) { - var i = 0; - for (; i < e.memo.entries.lenght; i++) { - alert(e.memo.entries[i].creator); //Shows creators of the added files - } - } - - function _onerrorhandle(e) { - alert(e.memo.entry.fileName + "file was not uploaded due transfer error"); - } - </script> - </head> - ...]]></programlisting> - - - - <para> Moreover, embedded Flash module provides a smoother representation of progress bar - during the uploading process: the polling is performed is not by AJAX, but my means of - the flash module. </para> - <figure> - <title> Uploading using Flash module <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> - </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/flash_layoutPanel.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>However, the Flash module doens&apos;t perform any visual representation of the - component.</para> - - <!--End of Flash Module--> - - - - - - <para> In order to customize the information regarding the ongoing process you could use <emphasis> - <property>&quot;label&quot;</property> - </emphasis> facet with the following macrosubstitution: <itemizedlist> - <listitem> - <para> - <code> {B}</code>, <code>{KB}</code>, <code>{MB}</code> contains the size of - file uploaded in bytes, kilobytes, megabytes respectively </para> - </listitem> - <listitem> - <para> - <code>{_B}</code>, <code>{_KB}</code>, <code>{_MB}</code> contains the - remain file size to upload in bytes, kilobytes, megabytes respectively - </para> - </listitem> - <listitem> - <para> - <code>{ss}</code>, <code>{mm}</code>, <code>{hh}</code> contains elapsed - time in seconds, minutes and hours respectively </para> - </listitem> - </itemizedlist> - </para> - - <!-- - There is a number of facets providing for this component: - <emphasis> - <property> &quot;header&quot;</property></emphasis> - - <emphasis> - <property> &quot;footer&quot;</property></emphasis> - <emphasis> - <property> &quot;label&quot;</property></emphasis>. could be used to provide displaying the progress of uploading. - --> - - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel uploadData="#{bean.data}" layoutPanelListener="#{bean.listener}"> - <f:facet name="label"> - <h:outputText value="{_KB}KB from {KB}KB uploaded --- {mm}:{ss}" /> - </f:facet> -</layoutPanel> -...]]></programlisting> - <para>This is the result:</para> - <figure> - <title> - <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> with <emphasis> - <property> &quot;label&quot;</property> - </emphasis> facet </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/layoutPanel3.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>You could define labels of the <property>component controls</property> with the help - of <emphasis> - <property> &quot;addControlLabel&quot;</property> - </emphasis>, <emphasis> - <property> &quot;clearAllControlLabel&quot;</property> - </emphasis>, <emphasis> - <property> &quot;clearControlLabel&quot;</property> - </emphasis>, <emphasis> - <property> &quot;stopEntryControlLabel&quot;</property> - </emphasis>, <emphasis> - <property> &quot;uploadControlLabel&quot;</property> - </emphasis> attributes. See the following example. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel addControlLabel="Add file..." clearAllControlLabel="Clear all" clearControlLabel="Clear" - stopEntryControlLabel="Stop process" uploadControlLabel="Upload file"/> -...]]></programlisting> - <para> This is the result: </para> - <figure> - <title> - <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> with labels </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/layoutPanel4.png"/> - </imageobject> - </mediaobject> - </figure> - <para> The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component allows to use sizes attributes: </para> - <itemizedlist> - <listitem> - <para> - <emphasis> - <property> &quot;listHeight&quot;</property> - </emphasis> attribute specify height for list of files in pixels </para> - </listitem> - <listitem> - <para> - <emphasis> - <property> &quot;listWidth&quot;</property> - </emphasis> attribute specify width for list of files in pixels </para> - </listitem> - </itemizedlist> - - <para> In order to disable the whole component you could use the <emphasis> - <property> &quot;disabled&quot;</property> - </emphasis> attribute. See the following example. </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel disabled="true"/> -...]]></programlisting> - <para>This is the result:</para> - <figure> - <title> - <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis>with <emphasis> - <property> &quot;disabled&quot;</property> - </emphasis> attribute </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/layoutPanel5.png"/> - </imageobject> - </mediaobject> - </figure> - <para>It&apos;s possible to handle events for layoutPanel using JavaScript code. A - simplest example of usage JavaScript API is placed below:</para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML"><![CDATA[... -<layoutPanel id="upload" disabled="false"/> -<h:commandButton onclick="${rich:component('upload')}.disable();" value="Disable" /> -...]]></programlisting> - - <para> - <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component also provides a number of JavaScript property, that can be used to - process uploaded files, file states etc. The given below example illustrates how the - <code>entries[0].state</code> property can be used to get access to the file state. - Full list of JavaScript properties can be found <link linkend="objectProperties" - >below</link>. </para> - - - <programlisting role="XML"><![CDATA[... -<layoutPanel layoutPanelListener="#{layoutPanelBean.listener}" - maxFilesQuantity="#{layoutPanelBean.uploadsAvailable}" - id="upload" - immediateUpload="#{layoutPanelBean.autoUpload}" - acceptedTypes="jpg, gif, png, bmp"> - <a4j:support event="onuploadcomplete" reRender="info" /> -</layoutPanel> -<h:commandButton onclick="if($('j_id232:upload').component.entries[0].state == layoutPanelEntry.UPLOAD_SUCCESS) alert ('DONE');" value="Check file state"/> -...]]></programlisting> - - - <para>The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component allows to use internationalization method to redefine and localize - the labels. You could use application resource bundle and define - <code>RICH_FILE_UPLOAD_CANCEL_LABEL</code>, - <code>RICH_FILE_UPLOAD_STOP_LABEL</code>, <code>RICH_FILE_UPLOAD_ADD_LABEL</code>, - <code>RICH_FILE_UPLOAD_UPLOAD_LABEL</code>, - <code>RICH_FILE_UPLOAD_CLEAR_LABEL</code>, - <code>RICH_FILE_UPLOAD_CLEAR_ALL_LABEL</code>, - <code>RICH_FILE_UPLOAD_PROGRESS_LABEL</code>, - <code>RICH_FILE_UPLOAD_SIZE_ERROR_LABLE</code>, - <code>RICH_FILE_UPLOAD_TRANSFER_ERROR_LABLE</code>, - <code>RICH_FILE_UPLOAD_ENTRY_STOP_LABEL</code>, - <code>RICH_FILE_UPLOAD_ENTRY_CLEAR_LABEL</code>, - <code>RICH_FILE_UPLOAD_ENTRY_CANCEL_LABEL</code> there. </para> - - - - <para> The <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> component could work together with Seam framework. <ulink - url="http://www.jboss.org/file-access/default/members/jbossrichfaces... - >Here</ulink> you can see how to configure filter for this framework in web.xml file - in order to handle <emphasis role="bold"> - <property>&lt;layoutPanel&gt;</property> - </emphasis> requests. </para> - <para>To make <property>&lt;layoutPanel&gt;</property> component work properly - with MyFaces extensions, the order in which filters are defined and mapped in web.xml, - is important. See <ulink - url="http://www.jboss.org/file-access/default/members/jbossrichfaces... - >corresponding FAQ chapter</ulink>. </para> - + <para>The <emphasis><property>&quot;position&quot;</property></emphasis> attribute defines the position of the <emphasis role="bold"><property>&lt;rich:layoutPanel&gt;</property></emphasis> in the area created with <emphasis role="bold"><property>&lt;rich:layout&gt;</property></emphasis> .</para> + <para>In more detail the component is covered in the <link linkend="DofURichLayout"><emphasis role="bold"><property>&lt;rich:layout&gt;</property></emphasis></link></para> + </section> <!-- JavaScript API--> <section>