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><rich:layouPanel></property>
- </emphasis>
+ </emphasis> is an auxiliary component used to create layout areas within the
<emphasis
role="bold"><property><rich:layout></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><layoutPanel></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><rich:layout></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
"true" (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
"false".
- This is a better way for storing small-sized files. </para>
- </listitem>
- </itemizedlist>
-
- <para> The <emphasis>
- <property>"uploadData"</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>"layoutPaneledListener"</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
"true" 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> "immediateUpload"</property>
- </emphasis> attribute. If the value of this attribute is
"true" 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't started to upload till you press the
"Upload"
- 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> "autoclear"</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
"Cancel" opposite its name.
- Clicking this link invokes JS API <code>remove()</code> function,
which gets <code>$('id').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 "Cancel" changes to
"Clear".
- Clicking "Clear" 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><layoutPanel></property>
- </emphasis> component provides following restrictions: </para>
- <itemizedlist>
- <listitem>
- <para> On <property> file types</property>, use
<emphasis>
- <property>
"acceptedTypes"</property>
- </emphasis> attribute to define file types accepted by
component. In the example
- below only files with "html" and
"jpg"
- 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>
"maxFilesQuantity"</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
- "Add" 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><layoutPanel></property>
- </emphasis>with <emphasis>
- <property>
"maxFilesQuantity"</property>
- </emphasis> attribute</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/layoutPanel2.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </listitem>
- </itemizedlist>
-
-
-
-
- <para id="layoutPanelEventAttributes">The <emphasis
role="bold">
- <property><layoutPanel></property>
- </emphasis> component provides a number of specific event attributes:
</para>
- <itemizedlist>
-
- <listitem>
- <para> The <emphasis>
- <property> "onadd"</property>
- </emphasis>a event handler called on an add file operation
</para>
- </listitem>
-
- <listitem>
- <para> The <emphasis>
- <property> "onupload"</property>
- </emphasis> which gives you a possibility to cancel the upload
at client side
- </para>
- </listitem>
- <listitem>
- <para> The <emphasis>
- <property>
"onuploadcomplete"</property>
- </emphasis> which is called after all files from the list are
uploaded </para>
- </listitem>
- <listitem>
- <para> The <emphasis>
- <property>
"onuploadcanceled"</property>
- </emphasis> which is called after upload has been canceled via
cancel control
- </para>
- </listitem>
- <listitem>
- <para> The <emphasis>
- <property> "onerror"</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><layoutPanel></property>
- </emphasis> component has an embedded Flash module that adds extra
functionality to the
- component. The module is enabled with <emphasis>
- <property> "allowFlash"</property>
- </emphasis> attribute set to "true". </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 "Open
File" 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="alert(event.memo.entry.fileName);" </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><layoutPanel></property>
- </emphasis>
- </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/flash_layoutPanel.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>However, the Flash module doens'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>"label"</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>
"header"</property></emphasis>
-
- <emphasis>
- <property>
"footer"</property></emphasis>
- <emphasis>
- <property>
"label"</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><layoutPanel></property>
- </emphasis> with <emphasis>
- <property> "label"</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> "addControlLabel"</property>
- </emphasis>, <emphasis>
- <property>
"clearAllControlLabel"</property>
- </emphasis>, <emphasis>
- <property> "clearControlLabel"</property>
- </emphasis>, <emphasis>
- <property>
"stopEntryControlLabel"</property>
- </emphasis>, <emphasis>
- <property> "uploadControlLabel"</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><layoutPanel></property>
- </emphasis> with labels </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/layoutPanel4.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para> The <emphasis role="bold">
- <property><layoutPanel></property>
- </emphasis> component allows to use sizes attributes: </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>
- <property> "listHeight"</property>
- </emphasis> attribute specify height for list of files in
pixels </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>
- <property> "listWidth"</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> "disabled"</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><layoutPanel></property>
- </emphasis>with <emphasis>
- <property> "disabled"</property>
- </emphasis> attribute </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/layoutPanel5.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>It'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><layoutPanel></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><layoutPanel></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><layoutPanel></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><layoutPanel></property>
- </emphasis> requests. </para>
- <para>To make <property><layoutPanel></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>"position"</property></emphasis>
attribute defines the position of the <emphasis
role="bold"><property><rich:layoutPanel></property></emphasis>
in the area created with <emphasis
role="bold"><property><rich:layout></property></emphasis>
.</para>
+ <para>In more detail the component is covered in the <link
linkend="DofURichLayout"><emphasis
role="bold"><property><rich:layout></property></emphasis></link></para>
+
</section>
<!-- JavaScript API-->
<section>