Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.11.5.  < rich:fileUpload > available since 3.2.0

expand all
6.11.5.1. Description
6.11.5.2. Key Features
6.11.5.3. Details of Usage
6.11.5.4. Reference Data
6.11.5.5. Relevant Resources Links

The <rich:fileUpload> component is designed to perform Ajax-ed files upload to server.


The <rich:fileUpload> component consists of two parts:

There are two places where the uploaded files are stored:

The "uploadData" attribute defines the collection of files uploaded. See the example below.

Example:


...
<rich:fileUpload uploadData="#{bean.data}"/>
...

The "fileUploadedListener" is called at server side after every file uploaded and used for the saving files from temporary folder or RAM.

Example:


...
<rich:fileUpload uploadData="#{bean.data}" fileUploadListener="#{bean.listener}"/>
 ...

The following methods for processing the uploaded files are available:

Automatically files uploading could be performed by means of the "immediateUpload" 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.

Example:


...
<rich:fileUpload uploadData="#{bean.data}" fileUploadListener="#{bean.listener}" immediateUpload="true"/>
 ...

The "autoclear" attribute is used to remove automatically files from the list after upload completed. See the simple example below.

Example:


...
<rich:fileUpload uploadData="#{bean.data}" autoclear="true"/>
...

Each file in list waiting for upload has link "Cancel" opposite its name. Clicking this link invokes JS API remove() function, which gets $('id').component.entries[i] 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 clear() 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.

The <rich:fileUpload> component provides following restrictions:

The <rich:fileUpload> component provides a number of specific event attributes:

The <rich:fileUpload> component has an embedded Flash module that adds extra functionality to the component. The module is enabled with "allowFlash" attribute set to "true".

These are the additional features that the Flash module provides:

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.

There are 2 ways to obtain the data stored in the FileUploadEntry object.

  • By means of JavaScript on the client side. Use the following syntax for that entries[i].propertyName. For example entries[0].state will return the state of the file that is being processed or has just been processed.

  • The properties of FileUploadEntry object can be retrieved using the entry.propertyName expression in the specific event attributes. For example, onupload="alert(event.memo.entry.fileName);" 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 RichFaces Developer Guide section on properties and their attributes.

The given bellow code sample demonstrates how the properties can be used. Please study it carefully.


...
<head>
        <script>
                function _onaddHandler (e) {
                    var i = 0;
                        for (; i < e.memo.entries.lenghti++) {
                                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>
 ...

Moreover, embedded Flash module provides a smoother representation of progress bar during the uploading process: the polling is performed is not by Ajax, but by means of the flash module.


However, the Flash module doesn't perform any visual representation of the component.

In order to customize the information regarding the ongoing process you could use "label" facet with the following macrosubstitution:

  • {B}, {KB}, {MB} contains the size of file uploaded in bytes, kilobytes, megabytes respectively

  • {_B}, {_KB}, {_MB} contains the remain file size to upload in bytes, kilobytes, megabytes respectively

  • {ss}, {mm}, {hh} contains elapsed time in seconds, minutes and hours respectively

Example:


...
<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>
...

This is the result:


You could define labels of the component controls with the help of "addControlLabel" , "clearAllControlLabel" , "clearControlLabel" , "stopEntryControlLabel" , "uploadControlLabel" attributes. See the following example.

Example:


...
<rich:fileUpload addControlLabel="Add file..." clearAllControlLabel="Clear all" clearControlLabel="Clear"
                        stopEntryControlLabel="Stop process" uploadControlLabel="Upload file"/>
...

This is the result:


The <rich:fileUpload> component allows to use sizes attributes:

  • "listHeight" attribute specifies a height for list of files in pixels

  • "listWidth" attribute specifies a width for list of files in pixels

In order to disable the whole component you could use the "disabled" attribute. See the following example.

Example:


...
<rich:fileUpload disabled="true"/>
...

This is the result:


It's possible to handle events for fileUpload using JavaScript code. A simplest example of JavaScript API usage is placed below:

Example:


...
<rich:fileUpload  id="upload" disabled="false"/>
<h:commandButton onclick="${rich:component('upload')}.disable();" value="Disable" />
...

The <rich:fileUpload> component also provides a number of JavaScript properties, that can be used to process uploaded files, file states etc. The given below example illustrates how the entries[0].state property can be used to get access to the file state. Full list of JavaScript properties can be found below.


...
<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"/>
...

The <rich:fileUpload> component allows to use internationalization method to redefine and localize the labels. You could use application resource bundle and define RICH_FILE_UPLOAD_CANCEL_LABEL, RICH_FILE_UPLOAD_STOP_LABEL, RICH_FILE_UPLOAD_ADD_LABEL, RICH_FILE_UPLOAD_UPLOAD_LABEL, RICH_FILE_UPLOAD_CLEAR_LABEL, RICH_FILE_UPLOAD_CLEAR_ALL_LABEL, RICH_FILE_UPLOAD_PROGRESS_LABEL, RICH_FILE_UPLOAD_SIZE_ERROR_LABLE, RICH_FILE_UPLOAD_TRANSFER_ERROR_LABLE, RICH_FILE_UPLOAD_ENTRY_STOP_LABEL, RICH_FILE_UPLOAD_ENTRY_CLEAR_LABEL, RICH_FILE_UPLOAD_ENTRY_CANCEL_LABEL there.

To make <rich:fileUpload> component work properly with MyFaces extensions, the order in which filters are defined and mapped in web.xml is important. See corresponding FAQ chapter.

Table of <rich:fileUpload> attributes.



Table 6.180. Client-side object properties

PropertyDescription
entriesReturns a array of all files in the list
entries.lengthReturns the number of files in the list
entries[i].fileNameReturns the file name, that is retrieved by the array index
entries[i].state Returns the file state. Possible states are
  • "initialized" - the file is added, corresponds to FileUploadEntry.INITIALIZED constant

  • "progress" - the file is being uploaded, corresponds to FileUploadEntry.UPLOAD_IN_PROGRESS constant

  • "ready" - uploading is in process, corresponds to FileUploadEntry.READY constant The file will be uploaded on queue order.

  • "canceled" - uploading of the file is canceled, corresponds to FileUploadEntry.UPLOAD_CANCELED constant

  • "done" - the file is uploaded successfully, corresponds to FileUploadEntry.UPLOAD_SUCCESS constant

  • "transfer_error" - a file transfer error occurred, corresponds to FileUploadEntry.UPLOAD_TRANSFER_ERROR constant

  • "size_error" - the file exceeded maximum size, corresponds to FileUploadEntry.UPLOAD_SIZE_ERROR constant

entries[i].size Returns the size of the file. Available in flash enabled version only
entries[i].TypeReturns the mime type of the file. Available in flash enabled version only
entries[i].creator Returns the name of the author of the file. Available in flash enabled version only
entries[i].creationDateReturns the date when the file was created. Available in flash enabled version only
entries[i].modificationDateReturns the date of the last file modification. Available in flash enabled version only

Table 6.181. Client-side object properties available with specific event attributes

PropertyDescription
entry.state Returns the file state. Possible states are
  • "initialized" - the file is added, corresponds to FileUploadEntry.INITIALIZED constant

  • "progress" - the file is being uploaded, corresponds to FileUploadEntry.UPLOAD_IN_PROGRESS constant

  • "ready" - uploading is in process, corresponds to FileUploadEntry.READY constant The file will be uploaded on queue order.

  • "canceled" - uploading of the file is canceled, corresponds to FileUploadEntry.UPLOAD_CANCELED constant

  • "done" - the file is uploaded successfully, corresponds to FileUploadEntry.UPLOAD_SUCCESS constant

  • "transfer_error" - a file transfer error occurred, corresponds to FileUploadEntry.UPLOAD_TRANSFER_ERROR constant

  • "size_error" - the file exceeded maximum size, corresponds to FileUploadEntry.UPLOAD_SIZE_ERROR constant

entry.fileName Returns the file's name. This property works with all event handlers except for "onadd".
entry.size Returns the size of the file. Available in flash enabled version only
entry.TypeReturns the mime type of the file. Available in flash enabled version only
entry.creator Returns the name of the author of the file. Available in flash enabled version only
entry.creationDateReturns the date when the file was created. Available in flash enabled version only
entry.modificationDateReturns the date of the last file modification. Available in flash enabled version only


Table 6.183. Style classes (selectors) with the corresponding skin parameters

Class (selector) nameDescriptionSkin ParameterCSS properties mapped
.rich-fileupload-fontDefines styles for a font of buttons and itemsgeneralFamilyFontfont-family
generalSizeFontfont-size
.rich-fileupload-table-tdDefines styles for the <td> elements of the added itemtableBorderColorborder-bottom-color
.rich-fileupload-list-decorDefines styles for a wrapper <div> element of a fileUploadtableBorderColorborder-color
tableBackgroundColorbackground-color
.rich-fileupload-ancDefines styles for the "Cancel", "Stop", "Clear" linksgeneralLinkColorcolor
.rich-fileupload-toolbar-decorDefines styles for a toolbaradditionalBackgroundColorbackground-color
tableBorderColorborder-bottom-color
tableBackgroundColorborder-top-color, border-left-color
.rich-fileupload-button-borderDefines styles for a border of buttonstableBorderColorborder-color
.rich-fileupload-enrty-disDefines styles for a disabled entrytrimColorbackground-color
.rich-fileupload-button-contentDefines styles for the buttons contentgeneralTextColorcolor
.rich-fileupload-buttonDefines styles for a buttonstrimColorbackground-color
.rich-fileupload-button-lightDefines styles for a highlight of buttontrimColorbackground-color
selectControlColorborder-color
.rich-fileupload-button-pressDefines styles for a pressed buttonselectControlColorborder-color
additionalBackgroundColorbackground-color
.rich-fileupload-ico-add-disDefines styles for a disabled "Add" button icontableBorderColorcolor
.rich-fileupload-ico-start-disDefines styles for a disabled "Upload" button icontableBorderColorcolor
.rich-fileupload-ico-clear-disDefines styles for a disabled "Clear" button icontableBorderColorcolor


You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.

On RichFaces LiveDemo page you can see an example of <rich:fileUpload> usage and sources for the given example.

<rich:fileUpload> with MyFaces article describes how to avoid problems with <rich:fileUpload> compenent caused by wrong application configuration.