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
The <rich:fileUpload> component designed to perform Ajax-ed files upload to server.
ProgressBar shows the status of downloads
Restriction on File type, file size and number of files to be uploaded
Multiple files upload support
Embedded Flash module
Possibility to cancel the request
One request for every upload
Automatic uploads
Supports standard JSF internationalization
Highly customizable look and feel
Disablement support
Table 6.404. rich : fileUpload attributes
| Attribute Name |
Description
|
|---|---|
| acceptedTypes | Files types allowed to upload |
| accesskey | HTML: This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey |
| addButtonClass | Assigns one or more space-separated CSS class names to the component 'Add' button |
| addButtonClassDisabled | Assigns one or more space-separated CSS class names to the component 'Add' button disabled |
| addControlLabel | Defines a label for an add button |
| ajaxSingle | Boolean attribute which provides possibility to limit JSF tree processing(decoding, conversion/validation, value applying) to the component which send the request only. Default value is "false" |
| allowFlash | Attribute which allow the component to use the flash module that provides file upload functionality [false, true, auto]. Default value is "false" |
| alt | HTML: For a user agents that cannot display images, forms, or applets, this attribute specifies alternate text. The language of the alternate text is specified by the lang attribute |
| autoclear | If this attribute is "true" files will be immediately removed from list after upload completed. Default value is "false". |
| binding | JSF: The attribute takes a value-binding expression for a component property of a backing bean |
| cancelEntryControlLabel | Defines a label for a cancel control |
| cleanButtonClass | Assigns one or more space-separated CSS class names to the component 'Clean' button |
| cleanButtonClassDisabled | Assigns one or more space-separated CSS class names to the component 'Clean' button disabled |
| clearAllControlLabel | Defines a label for a clearAll button |
| clearControlLabel | Defines a label for a clear control |
| disabled | HTML: Attribute 'disabled' provides a possibility to make the whole component disabled if its value equals to "true". Default value is "false". |
| doneLabel | Defines a label for a done label |
| fileEntryClass | Assigns one or more space-separated CSS class names to the file entries |
| fileEntryClassDisabled | Assigns one or more space-separated CSS class names to the file entries disabled |
| fileEntryControlClass | Assigns one or more space-separated CSS class names to the controls of the file entries |
| fileEntryControlClassDisabled | Assigns one or more space-separated CSS class names to the disabled controls of the file entries |
| fileUploadListener | MethodExpression representing an action listener method that will be notified after file uploaded. |
| id | JSF: Every component may have a unique id that is automatically created if omitted |
| immediate | A flag indicating that this component value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until a Process Validations phase |
| immediateUpload | If this attribute is true files will be immediately uploaded after they have been added in list. Default value is "false". |
| listHeight | Defines height of file list. Default value is "210px". |
| listWidth | Defines width of file list. Default value is "400px". |
| locale | Used for locale definition |
| maxFilesQuantity | Defines max files count allowed for upload (optional). Default value is "1". |
| noDuplicate | Defines if component should allow to add files that were already in list. Default value is "false". |
| onadd | The client-side script method to be called before a file is added |
| onblur | DHTML: The client-side script method to be called when the element loses the focus |
| onchange | DHTML: The client-side script method to be called when the element value is changed |
| onclear | The client-side script method to be called when a file entry is cleared |
| onclick | DHTML: The client-side script method to be called when the element is clicked |
| ondblclick | DHTML: The client-side script method to be called when the element is double-clicked |
| onerror | The client-side script method to be called when a file uploading is interrupted according to any errors |
| onfileuploadcomplete | The client-side script method to be called when a file is uploaded to the server |
| onfocus | DHTML: The client-side script method to be called when the element gets the focus |
| onkeydown | DHTML: The client-side script method to be called when a key is pressed down over the element |
| onkeypress | DHTML: The client-side script method to be called when a key is pressed over the element and released |
| onkeyup | DHTML: The client-side script method to be called when a key is released |
| onmousedown | DHTML: The client-side script method to be called when a mouse button is pressed down over the element |
| onmousemove | DHTML: The client-side script method to be called when a pointer is moved within the element |
| onmouseout | DHTML: The client-side script method to be called when a pointer is moved away from the element |
| onmouseover | DHTML: The client-side script method to be called when a pointer is moved onto the element |
| onmouseup | DHTML: The client-side script method to be called when a mouse button is released |
| onselect | DHTML: The client-side script method to be called when some text is selected in the text field. This attribute can be used with the INPUT and TEXTAREA elements. |
| onsizerejected | The client-side script method to be called when a file uploading is rejected by the file size overflow |
| ontyperejected | The client-side script method to be called when a file type is rejected according to the file types allowed |
| onupload | The client-side script method to be called when a file uploading is started |
| onuploadcanceled | The client-side script method to be called when a file uploading is cancelled |
| onuploadcomplete | The client-side script method to be called when uploading of all files from the list is completed |
| progressLabel | Defines a label for a progress label |
| rendered | JSF: If "false", this component is not rendered |
| required | JSF: If "true", this component is checked for non-empty input |
| requiredMessage | A ValueExpression enabled attribute which defines text of validation message to show, if a required field is missing |
| sizeErrorLabel | Defines a label for a size error label |
| status | ID (in format of call UIComponent.findComponent()) of Request status component |
| stopButtonClass | Assigns one or more space-separated CSS class names to the component 'Cancel' button |
| stopButtonClassDisabled | Assigns one or more space-separated CSS class names to the component 'Cancel' button disabled |
| stopControlLabel | Defines a label for a stop button |
| stopEntryControlLabel | Defines a label for a stop control |
| style | HTML: CSS style rules to be applied to the component |
| styleClass | JSF: Assigns one or more CSS class names to the component. Corresponds to the HTML "class" attribute. |
| tabindex | HTML: This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros |
| transferErrorLabel | Defines a label for a transfer error label |
| uploadButtonClass | Assigns one or more space-separated CSS class names to the component 'Upload' button |
| uploadButtonClassDisabled | Assigns one or more space-separated CSS class names to the component 'Upload' button disabled |
| uploadControlLabel | Defines a label for an upload button |
| uploadData | Collection of files uploaded |
| uploadListClass | Assigns one or more space-separated CSS class names to the upload list |
| uploadListClassDisabled | Assigns one or more space-separated CSS class names to the upload list disabled |
| validator | JSF: MethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component |
| validatorMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator |
Table 6.405. Component identification parameters
| Name | Value |
|---|---|
| component-type | org.richfaces.component.FileUpload |
| component-class | org.richfaces.component.html.HtmlFileUpload |
| component-family | org.richfaces.component.FileUpload |
| renderer-type | org.richfaces.renderkit.html.FileUploadRenderer |
| tag-class | org.richfaces.taglib.FileUploadTag |
To create the simplest variant on a page use the following syntax:
Example:
...
<rich:fileUpload />
...
Example:
import org.richfaces.component.html.HtmlFileUpload;
...
HtmlFileUpload myFileUpload = new HtmlFileUpload();
...
The <rich:fileUpload> component consists of two parts:
List of files which contains the list of currently chosen files to upload with possibility to manage every file
Component controls - the bar with controls for managing the whole component
There are two places where the uploaded files are stored:
In the temporary folder (depends on OS) if the value of the
createTempFile parameter in Ajax4jsf
Filter (in web.xml) section is "true" (by Default)
...
<init-param>
<param-name>createTempFiles</param-name>
<param-value>true</param-value>
</init-param>
...
In the RAM if the value of the createTempFile parameter in
Ajax4jsf Filter section is "false".
This is a better way for storing small-sized files.
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:
isMultiUpload(). It returns "true" if several
files have been uploaded
getUploadItems(). It returns the list of the uploaded files. If one
file was uploaded, the getUploadItems() method will return the list
consisting of one file
getUploadItem(). It returns the whole list in case of uploading one
file only. If several files were uploaded, the getUploadItem()
method will return the first element of the uploaded files list.
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:
On file types, use "acceptedTypes" attribute to define file types accepted by component. In the example below only files with "html" and "jpg" extensions are accepted to upload.
Example:
...
<rich:fileUpload acceptedTypes="html, jpg"/>
...
On file size, use the maxRequestSize
parameter(value in bytes) inside Ajax4jsf Filter section in
web.xml:
...
<init-param>
<param-name>maxRequestSize</param-name>
<param-value>1000000</param-value>
</init-param>
...
On max files quantity, use the "maxFilesQuantity" 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.
Example:
...
<rich:fileUpload maxFilesQuantity="2"/>
...
This is the result:
The <rich:fileUpload> component provides a number of specific event attributes:
The "onadd" a event handler called on an add file operation
The "onupload" which gives you a possibility to cancel the upload at client side
The "onuploadcomplete" which is called after all files from the list are uploaded
The "onuploadcanceled" which is called after upload has been canceled via cancel control
The "onerror" which is called if the file upload was interrupted according to any errors
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:
Multiple files choosing;
Permitted file types are specified in the "Open File" dialog window;
A number of additional entry object properties are also available, which can be found RichFaces Developer Guide section on object properties.
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 the 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.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>
...
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.
However, the Flash module doens'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 specify height for list of files in pixels
"listWidth" attribute specify 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 usage JavaScript API is placed below:
Example:
...
<rich:fileUpload id="upload" disabled="false"/>
<h:commandButton onclick="${rich:component('upload')}.disable();" value="Disable" />
...
<rich:fileUpload>
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
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.
The <rich:fileUpload> component could work together with Seam framework. On RichFaces LiveDemo page you can see how to configure filter for this framework in web.xml file in order to handle <rich:fileUpload> requests.
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 6.406. JavaScript API
| Function | Description |
|---|---|
| beforeSubmit() | Sets up necessary request parameters for file uploading and submits form to server by command button. This method should be used together with commands. |
| clear() | Removes all files from the list. The function can also get the $('id').component.entries[i] as a parameter to remove a particular file. |
| disable() | Disables the component |
| enable() | Enables the component |
| remove() | Cancels the request for uploading a file by removing this file from
upload list and upload queue. Gets $('id').component.entries[i] as a parameter. |
| stop() | Stops the uploading process |
| submitForm() | Submits form to server. All added files will be put to model and event. |
Table 6.407. Client-side object properties
| Property | Description |
|---|---|
| entries | Returns a array of all files in the list |
| entries.length | Returns the number of files in the list |
| entries[i].fileName | Returns the file name, that is retrieved by the array index |
| entries[i].state | Returns the file state. Possible states are
|
| entries[i].size | Returns the size of the file. Available in flash enabled version only |
| entries[i].Type | Returns 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].creationDate | Returns the date when the file was created. Available in flash enabled version only |
| entries[i].modificationDate | Returns the date of the last file modification. Available in flash enabled version only |
Table 6.408. Client-side object properties available with specific event attributes
| Property | Description |
|---|---|
| entry.state | Returns the file state. Possible states are
|
| 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.Type | Returns 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.creationDate | Returns the date when the file was created. Available in flash enabled version only |
| entry.modificationDate | Returns the date of the last file modification. Available in flash enabled version only |
Table 6.409. Facets
| Facet name | Description |
|---|---|
| label | Defines the information regarding the ongoing process |
| progress | Defines the information regarding the uploading process |
For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.
There are two ways to redefine the appearance of all <rich:fileUpload> components at once:
Redefine the corresponding skin parameters
Add to your style sheets style classes used by a <rich:fileUpload> component
Table 6.410. Skin parameters redefinition for a component
| Skin parameters | CSS properties |
|---|---|
| tableBackgroundColor | background-color |
| tableBorderColor | border-color |
Table 6.411. Skin parameters redefinition for a font
| Skin parameters | CSS properties |
|---|---|
| generalFamilyFont | font-family |
| generalSizeFont | font-size |
Table 6.412. Skin parameters redefinition for a toolbar
| Skin parameters | CSS properties |
|---|---|
| additionalBackgroundColor | background-color |
| tableBorderColor | border-bottom-color |
| tableBackgroundColor | border-top-color |
| tableBackgroundColor | border-left-color |
Table 6.413. Skin parameters redefinition for items in the list
| Skin parameters | CSS properties |
|---|---|
| tableBorderColor | border-bottom-color |
Table 6.414. Skin parameters redefinition for a "Cancel", "Clear" links
| Skin parameters | CSS properties |
|---|---|
| generalLinkColor | color |
Table 6.415. Skin parameters redefinition for a button
| Skin parameters | CSS properties |
|---|---|
| trimColor | background-color |
Table 6.416. Skin parameters redefinition for a button border
| Skin parameters | CSS properties |
|---|---|
| tableBorderColor | border-color |
Table 6.417. Skin parameters redefinition for a highlighted button
| Skin parameters | CSS properties |
|---|---|
| trimColor | background-color |
| selectControlColor | border-color |
Table 6.418. Skin parameters redefinition for a pressed button
| Skin parameters | CSS properties |
|---|---|
| selectControlColor | border-color |
| additionalBackgroundColor | background-color |
Table 6.419. Skin parameters redefinition for "Upload", "Clean" buttons
| Skin parameters | CSS properties |
|---|---|
| generalTextColor | color |
Table 6.420. Skin parameters redefinition for a disabled "Start" button icon
| Skin parameters | CSS properties |
|---|---|
| tableBorderColor | color |
Table 6.421. Skin parameters redefinition for a disabled "Clear" button icon
| Skin parameters | CSS properties |
|---|---|
| tableBorderColor | color |
The following picture illustrates how CSS classes define styles for component elements.
Table 6.422. Classes names that define a component representation
| Class name | Description |
|---|---|
| rich-fileupload-list-decor | Defines styles for a wrapper <div> element of a fileUpload |
| rich-fileupload-font | Defines styles for a font of buttons and items |
| rich-fileupload-toolbar-decor | Defines styles for a toolbar |
| rich-fileupload-list-overflow | Defines styles for a list of files |
Table 6.423. Classes names that define buttons representation
| Class name | Description |
|---|---|
| rich-fileupload-button | Defines styles for a buttons |
| rich-fileupload-button-border | Defines styles for a border of buttons |
| rich-fileupload-button-light | Defines styles for a highlight of button |
| rich-fileupload-button-press | Defines styles for a pressed button |
| rich-fileupload-button-dis | Defines styles for a disabled button |
| rich-fileupload-button-selection | Defines styles for "Upload", "Clean" buttons |
Table 6.424. Classes names that define the representation of the buttons' icons
| Class name | Description |
|---|---|
| rich-fileupload-ico | Defines styles for an icon |
| rich-fileupload-ico-add | Defines styles for a "Add" button icon |
| rich-fileupload-ico-start | Defines styles for a "Upload" button icon |
| rich-fileupload-ico-stop | Defines styles for a "Stop" button icon |
| rich-fileupload-ico-clear | Defines styles for a "Clear" button icon |
| rich-fileupload-ico-add-dis | Defines styles for a disabled "Add" button icon |
| rich-fileupload-ico-start-dis | Defines styles for a disabled "Upload" button icon |
| rich-fileupload-ico-clear-dis | Defines styles for a disabled "Clear" button icon |
Table 6.425. Classes names that define list items representation
| Class name | Description |
|---|---|
| rich-fileupload-table-td | Defines styles for a wrapper <td> element of a list items |
| rich-fileupload-anc | Defines styles for "Cancel", "Stop", "Clear" links |
In order to redefine styles for all <rich:fileUpload> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.
Example:
...
.rich-fileupload-anc{
font-weight:bold;
text-decoration:none;
}
...
This is the result:
In the example above the font weight and text decoration for "Cancel" and "Clear" links are changed.
Also it's possible to change styles of particular <rich:fileUpload> component. In this case you should create own style classes and use them in the corresponding <rich:fileUpload> styleClass attributes. An example is placed below:
Example:
...
.myClass{
font-weight:bold;
}
...
The "addButtonClass" attribute for <rich:fileUpload> is defined as it's shown in the example below:
Example:
<rich:fileUpload ... addButtonClass="myClass"/>
This is the result:
As it could be seen on the picture above, the font style for "Add" button is changed.
On RichFaces LiveDemo page you can see an example of <rich:fileUpload> usage and sources for the given example.
