<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>rich:fileUpload</keyword>
            <keyword>fileUpload</keyword>
        </keywordset>
    </sectioninfo>
    <table>
        <title>Component identification parameters</title>
        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Name</entry>
                    <entry>Value</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>component-type</entry>
                    <entry>org.richfaces.component.FileUpload</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.richfaces.component.html.HtmlFileUpload</entry>
                </row>
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.component.FileUpload</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.renderkit.html.FileUploadRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.richfaces.taglib.FileUploadTag</entry>
                </row>
            </tbody>
        </tgroup>
    </table>
    <section>
        <title>Creating the Component with a Page Tag</title>
        <para>To create the simplest variant on a page use the following syntax:</para>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:fileUpload />
...]]></programlisting>
    </section>
    <section>
        <title>Creating the Component Dynamically Using Java</title>

        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlFileUpload;
...
HtmlFileUpload myFileUpload = new HtmlFileUpload();
...]]></programlisting>
    </section>
    <section>
        <title>Details of Usage</title>
        <para>The <emphasis role="bold">
                <property>&lt;rich:fileUpload&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>
        </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[...
<rich:fileUpload uploadData="#{bean.data}"/>
...]]></programlisting>

        <para>The <emphasis>
                <property>&quot;fileUploadedListener&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[...
<rich:fileUpload uploadData="#{bean.data}" fileUploadListener="#{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[...
<rich:fileUpload uploadData="#{bean.data}" fileUploadListener="#{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[...
<rich:fileUpload 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;rich:fileUpload&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[...
<rich:fileUpload 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[...
<rich:fileUpload maxFilesQuantity="2"/>
 ...]]></programlisting>
                <para> This is the result: </para>
                <figure>
                    <title><emphasis role="bold">
                            <property>&lt;rich:fileUpload&gt;</property>
                        </emphasis>with <emphasis>
                            <property> &quot;maxFilesQuantity&quot;</property>
                        </emphasis> attribute</title>
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="images/fileUpload2.png"/>
                        </imageobject>
                    </mediaobject>
                </figure>
            </listitem>
        </itemizedlist>




        <para id="fileUploadEventAttributes">The <emphasis role="bold">
                <property>&lt;rich:fileUpload&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;rich:fileUpload&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">RichFaces Developer Guide section on object properties</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 FileUploadEntry 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>FileUploadEntry</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 in <link
                        linkend="objectPropertiesWithAttributes">RichFaces Developer Guide section on properties and their attributes</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;rich:fileUpload&gt;</property>
                </emphasis>
            </title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/flash_fileUpload.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[...
<rich:fileUpload uploadData="#{bean.data}" fileUploadListener="#{bean.listener}">
        <f:facet name="label">
                <h:outputText value="{_KB}KB from {KB}KB uploaded --- {mm}:{ss}" />
        </f:facet>
</rich:fileUpload>
...]]></programlisting>
        <para>This is the result:</para>
        <figure>
            <title>
                <emphasis role="bold">
                    <property>&lt;rich:fileUpload&gt;</property>
                </emphasis> with <emphasis>
                    <property> &quot;label&quot;</property>
                </emphasis> facet </title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload3.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[...
<rich:fileUpload 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;rich:fileUpload&gt;</property>
                </emphasis> with labels </title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload4.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para> The <emphasis role="bold">
                <property>&lt;rich:fileUpload&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[...
<rich:fileUpload disabled="true"/>
...]]></programlisting>
        <para>This is the result:</para>
        <figure>
            <title>
                <emphasis role="bold">
                    <property>&lt;rich:fileUpload&gt;</property>
                </emphasis>with <emphasis>
                    <property> &quot;disabled&quot;</property>
                </emphasis> attribute </title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload5.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para>It&apos;s possible to handle events for fileUpload 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[...
<rich:fileUpload  id="upload" disabled="false"/>
<h:commandButton onclick="${rich:component('upload')}.disable();" value="Disable" />
...]]></programlisting>

        <para>
            <emphasis role="bold">
                <property>&lt;rich:fileUpload&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[...
<rich:fileUpload fileUploadListener="#{fileUploadBean.listener}"
        maxFilesQuantity="#{fileUploadBean.uploadsAvailable}"
        id="upload"
        immediateUpload="#{fileUploadBean.autoUpload}"
        acceptedTypes="jpg, gif, png, bmp">
            <a4j:support event="onuploadcomplete" reRender="info"  />
</rich:fileUpload>
<h:commandButton onclick="if($('j_id232:upload').component.entries[0].state == FileUploadEntry.UPLOAD_SUCCESS) alert ('DONE');" value="Check file state"/>
...]]></programlisting>


        <para>The <emphasis role="bold">
                <property>&lt;rich:fileUpload&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;rich:fileUpload&gt;</property>
            </emphasis> component could work together with Seam framework. <ulink
                url="http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/devguide/en/faq/faq.html#fileUploadConf"
                >On RichFaces LiveDemo page </ulink> you can see how to configure filter for this framework in web.xml file
            in order to handle <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> requests. </para>
        <para>To make <property>&lt;rich:fileUpload&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/freezone/docs/devguide/en/faq/faq.html#richfileUploadforMyFaces"
                >corresponding FAQ chapter</ulink>. </para>

    </section>
    <!-- JavaScript API-->
    <section>
        <title>JavaScript API</title>
        <table>
            <title>JavaScript API</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>beforeSubmit()</entry>
                        <entry>Sets up necessary request parameters for file uploading and submits
                            form to server by command button. This method should be used together
                            with commands. </entry>
                    </row>

                    <row>
                        <entry>clear()</entry>
                        <entry>Removes all files from the list. The function can also get the <code>$(&apos;id&apos;).component.entries[i]</code> as a parameter to remove a particular file.</entry>
                    </row>

                    <row>
                        <entry>disable()</entry>
                        <entry>Disables the component</entry>
                    </row>

                    <row>
                        <entry>enable()</entry>
                        <entry>Enables the component</entry>
                    </row>

                    <row>
                        <entry>remove()</entry>
                        <entry>Cancels the request for uploading a file by removing this file from
                              upload list and upload queue. Gets <code>$(&apos;id&apos;).component.entries[i]</code> as a parameter.</entry>
                    </row>

                    <row>
                        <entry>stop()</entry>
                        <entry>Stops the uploading process</entry>
                    </row>

                    <row>
                        <entry>submitForm()</entry>
                        <entry>Submits form to server. All added files will be put to model and
                            event.</entry>
                    </row>

                </tbody>
            </tgroup>
        </table>



        <table id="objectProperties">
            <title>Client side object properties</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Property</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>

                    <row>
                        <entry>entries</entry>
                        <entry>Returns a array of all files in the list </entry>
                    </row>



                    <row>
                        <entry>entries.length</entry>
                        <entry>Returns the number of files in the list </entry>
                    </row>


                    <row>
                        <entry>entries[i].fileName</entry>
                        <entry>Returns the file name, that is retrieved by the array index </entry>
                    </row>



                    <row>
                        <entry>entries[i].state </entry>
                        <entry>Returns the file state. Possible states are <itemizedlist>

                                <listitem>
                                    <para>&quot;initialized&quot; - the file is added,
                                        corresponds to FileUploadEntry.INITIALIZED constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;progress&quot; - the file is being uploaded,
                                        corresponds to FileUploadEntry.UPLOAD_IN_PROGRESS
                                        constant</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;ready&quot; - uploading is in process,
                                        corresponds to FileUploadEntry.READY constant The file will
                                        be uploaded on queue order.</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;canceled&quot; - uploading of the file is
                                        canceled, corresponds to FileUploadEntry.UPLOAD_CANCELED
                                        constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;done&quot; - the file is uploaded
                                        successfully, corresponds to FileUploadEntry.UPLOAD_SUCCESS
                                        constant</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;transfer_error&quot; - a file transfer error
                                        occurred, corresponds to
                                        FileUploadEntry.UPLOAD_TRANSFER_ERROR constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;size_error&quot; - the file exceeded maximum
                                        size, corresponds to FileUploadEntry.UPLOAD_SIZE_ERROR
                                        constant</para>
                                </listitem>


                            </itemizedlist>
                        </entry>
                    </row>



                    <row>
                        <entry>entries[i].size</entry>
                        <entry> Returns the size of the file. Available in flash enabled version
                            only</entry>
                    </row>
                    <row>
                        <entry>entries[i].Type</entry>
                        <entry>Returns the mime type of the file. Available in flash enabled version
                            only</entry>
                    </row>
                    <row>
                        <entry>entries[i].creator </entry>
                        <entry>Returns the name of the author of the file. Available in flash
                            enabled version only</entry>
                    </row>
                    <row>
                        <entry>entries[i].creationDate</entry>
                        <entry>Returns the date when the file was created. Available in flash
                            enabled version only</entry>
                    </row>
                    <row>
                        <entry>entries[i].modificationDate</entry>
                        <entry>Returns the date of the last file modification. Available in flash
                            enabled version only</entry>
                    </row>




                </tbody>
            </tgroup>
        </table>




        <table id="objectPropertiesWithAttributes">
            <title>Client side object properties available with specific <link
                    linkend="fileUploadEventAttributes"> event attributes</link></title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Property</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>




                    <row>
                        <entry>entry.state </entry>
                        <entry>Returns the file state. Possible states are <itemizedlist>

                                <listitem>
                                    <para>&quot;initialized&quot; - the file is added,
                                        corresponds to FileUploadEntry.INITIALIZED constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;progress&quot; - the file is being uploaded,
                                        corresponds to FileUploadEntry.UPLOAD_IN_PROGRESS
                                        constant</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;ready&quot; - uploading is in process,
                                        corresponds to FileUploadEntry.READY constant The file will
                                        be uploaded on queue order.</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;canceled&quot; - uploading of the file is
                                        canceled, corresponds to FileUploadEntry.UPLOAD_CANCELED
                                        constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;done&quot; - the file is uploaded
                                        successfully, corresponds to FileUploadEntry.UPLOAD_SUCCESS
                                        constant</para>
                                </listitem>
                                <listitem>
                                    <para>&quot;transfer_error&quot; - a file transfer error
                                        occurred, corresponds to
                                        FileUploadEntry.UPLOAD_TRANSFER_ERROR constant </para>
                                </listitem>
                                <listitem>
                                    <para>&quot;size_error&quot; - the file exceeded maximum
                                        size, corresponds to FileUploadEntry.UPLOAD_SIZE_ERROR
                                        constant</para>
                                </listitem>


                            </itemizedlist>
                        </entry>
                    </row>

                    <row>
                        <entry>entry.fileName </entry>
                        <entry>Returns the file&apos;s name. This property works with all event
                            handlers except for &quot;onadd&quot;. </entry>
                    </row>



                    <row>
                        <entry>entry.size</entry>
                        <entry> Returns the size of the file. Available in flash enabled version
                            only</entry>
                    </row>
                    <row>
                        <entry>entry.Type</entry>
                        <entry>Returns the mime type of the file. Available in flash enabled version
                            only</entry>
                    </row>
                    <row>
                        <entry>entry.creator </entry>
                        <entry>Returns the name of the author of the file. Available in flash
                            enabled version only</entry>
                    </row>
                    <row>
                        <entry>entry.creationDate</entry>
                        <entry>Returns the date when the file was created. Available in flash
                            enabled version only</entry>
                    </row>
                    <row>
                        <entry>entry.modificationDate</entry>
                        <entry>Returns the date of the last file modification. Available in flash
                            enabled version only</entry>
                    </row>




                </tbody>
            </tgroup>
        </table>



    </section>
    <!-- End of JavaScript API-->
	
	<section>
		<title>Facets</title>
		<table>
			<title>Facets</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Facet name</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>label</entry>
							<entry>Defines the information regarding the ongoing process</entry>
						</row>
						<row>
							<entry>progress</entry>
							<entry>Defines the information regarding the uploading process</entry>
						</row>

					</tbody>
				</tgroup>
		</table>
	</section>
	
    <section>
        <title>Look-and-Feel Customization</title>
        <para>For skinnability implementation, the components use a <emphasis>
                <property>style class redefinition method.</property>
            </emphasis> Default style classes are mapped on <emphasis>
                <property>skin parameters.</property>
            </emphasis></para>
        <para>There are two ways to redefine the appearance of all <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> components at once: <itemizedlist>
                <listitem>
                    <para>Redefine the corresponding skin parameters</para>
                </listitem>
                <listitem>
                    <para> Add to your style sheets style classes used by a <emphasis role="bold">
                            <property>&lt;rich:fileUpload&gt;</property>
                        </emphasis> component</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>

    <section>
        <title>Skin Parameters Redefinition</title>

        <table>
            <title>Skin parameters redefinition for a component</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tableBackgroundColor</entry>
                        <entry>background-color</entry>
                    </row>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>border-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for a font</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>generalFamilyFont</entry>
                        <entry>font-family</entry>
                    </row>
                    <row>
                        <entry>generalSizeFont</entry>
                        <entry>font-size</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for a toolbar</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>additionalBackgroundColor</entry>
                        <entry>background-color</entry>
                    </row>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>border-bottom-color</entry>
                    </row>
                    <row>
                        <entry>tableBackgroundColor</entry>
                        <entry>border-top-color</entry>
                    </row>
                    <row>
                        <entry>tableBackgroundColor</entry>
                        <entry>border-left-color</entry>
                    </row>

                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for items in the list</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>border-bottom-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for a &quot;Cancel&quot;,
                &quot;Clear&quot; links</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>generalLinkColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for a button</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>trimColor</entry>
                        <entry>background-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <table>
            <title>Skin parameters redefinition for a button border</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>border-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <table>
            <title>Skin parameters redefinition for a highlighted button</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>trimColor</entry>
                        <entry>background-color</entry>
                    </row>
                    <row>
                        <entry>selectControlColor</entry>
                        <entry>border-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for a pressed button</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>selectControlColor</entry>
                        <entry>border-color</entry>
                    </row>
                    <row>
                        <entry>additionalBackgroundColor</entry>
                        <entry>background-color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Skin parameters redefinition for &quot;Upload&quot;,
                &quot;Clean&quot; buttons</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>generalTextColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <table>
            <title>Skin parameters redefinition for a disabled &quot;Start&quot; button
                icon</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <table>
            <title>Skin parameters redefinition for a disabled &quot;Clear&quot; button
                icon</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Skin parameters</entry>
                        <entry>CSS properties</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>tableBorderColor</entry>
                        <entry>color</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>

    <section>
        <title>Definition of Custom Style Classes</title>

        <para>The following picture illustrates how CSS classes define styles for component
            elements.</para>
        <figure>
            <title>Classes names</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload_cn.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        <figure>
            <title>Classes names</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload_cn2.png"/>
                </imageobject>
            </mediaobject>
        </figure>

        <table id="fileUploadCN">
            <title>Classes names that define a component representation</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>rich-fileupload-list-decor</entry>
                        <entry>Defines styles for a wrapper &lt;div&gt; element of a
                            fileUpload</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-font</entry>
                        <entry>Defines styles for a font of buttons and items</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-toolbar-decor</entry>
                        <entry>Defines styles for a toolbar</entry>
                    </row>
                    <row>
                        <entry> rich-fileupload-list-overflow</entry>
                        <entry>Defines styles for a list of files</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>


        <table>
            <title>Classes names that define buttons representation</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>rich-fileupload-button</entry>
                        <entry>Defines styles for a buttons</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-button-border</entry>
                        <entry>Defines styles for a border of buttons</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-button-light</entry>
                        <entry>Defines styles for a highlight of button</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-button-press</entry>
                        <entry>Defines styles for a pressed button</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-button-dis</entry>
                        <entry>Defines styles for a disabled button</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-button-selection</entry>
                        <entry>Defines styles for &quot;Upload&quot;,
                            &quot;Clean&quot; buttons</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Classes names that define the representation of the buttons' icons</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>rich-fileupload-ico</entry>
                        <entry>Defines styles for an icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-add</entry>
                        <entry>Defines styles for a &quot;Add&quot; button icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-start</entry>
                        <entry>Defines styles for a &quot;Upload&quot; button icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-stop</entry>
                        <entry>Defines styles for a &quot;Stop&quot; button icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-clear</entry>
                        <entry>Defines styles for a &quot;Clear&quot; button icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-add-dis</entry>
                        <entry>Defines styles for a disabled &quot;Add&quot; button
                            icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-start-dis</entry>
                        <entry>Defines styles for a disabled &quot;Upload&quot; button
                            icon</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-ico-clear-dis</entry>
                        <entry>Defines styles for a disabled &quot;Clear&quot; button
                            icon</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <table>
            <title>Classes names that define list items representation</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>rich-fileupload-table-td</entry>
                        <entry>Defines styles for a wrapper &lt;td&gt; element of a list
                            items</entry>
                    </row>
                    <row>
                        <entry>rich-fileupload-anc</entry>
                        <entry>Defines styles for &quot;Cancel&quot;,
                            &quot;Stop&quot;, &quot;Clear&quot; links</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>


        <para>In order to redefine styles for all <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> components on a page using CSS, it&apos;s enough to create classes with
            the same names (possible classes could be found in the tables <link
                linkend="fileUploadCN"> above</link>) and define necessary properties in them. </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="CSS"><![CDATA[...
.rich-fileupload-anc{
    font-weight:bold;
    text-decoration:none;
}
...]]></programlisting>

        <para>This is the result:</para>

        <figure>
            <title>Redefinition styles with predefined classes</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload_pc.png"/>
                </imageobject>
            </mediaobject>
        </figure>

        <para>In the example above the font weight and text decoration for
            &quot;Cancel&quot; and &quot;Clear&quot; links are changed.</para>

        <para> Also it&apos;s possible to change styles of particular <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> component. In this case you should create own style classes and use them in
            the corresponding <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis>
            <emphasis>
                <property>styleClass</property>
            </emphasis> attributes. An example is placed below: </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="CSS"><![CDATA[...
.myClass{
        font-weight:bold;
}
...]]></programlisting>
        <para> The <emphasis>
                <property>&quot;addButtonClass&quot;</property>
            </emphasis> attribute for <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> is defined as it&apos;s shown in the example below: </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<rich:fileUpload ... addButtonClass="myClass"/>
]]></programlisting>

        <para>This is the result:</para>
        <figure>
            <title>Redefinition styles with own classes and <emphasis>
                    <property>styleClass</property>
                </emphasis> attributes</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/fileUpload_oc.png"/>
                </imageobject>
            </mediaobject>
        </figure>

        <para>As it could be seen on the picture above, the font style for &quot;Add&quot;
            button is changed.</para>

    </section>

    <section>
        <title>Relevant Resources Links</title>
        <para><ulink
                url="http://livedemo.exadel.com/richfaces-demo/richfaces/fileUpload.jsf?c=fileUpload"
                >On RichFaces LiveDemo page </ulink> you can see an example of <emphasis role="bold">
                <property>&lt;rich:fileUpload&gt;</property>
            </emphasis> usage and sources for the given example. </para>
    </section>

</section>
