The <rich:fileUpload> component designed to perform Ajax-ed files upload to server.
Highly customizable look and feel
File types and file sizes restrictions
Multiple files upload support
Possibility to cancel the request
One request for every upload component
Different submit modes (Server/Client)
Asynchronous mode
Disablement support
Table 6.191. rich : fileUpload attributes
Attribute Name | Description |
---|---|
acceptedTypes | Files types allowed to upload |
accesskey | 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 | CSS style for add button |
addButtonClassDisabled | CSS style for add button disabled |
addControlLabel | Defines a label for an add button |
align | left|center|right|justify [CI] Deprecated. This attribute specifies the horizontal alignment of its element with respect to the surrounding context. Possible values: * left: text lines are rendered flush left. * center: text lines are centered. * right: text lines are rendered flush right. * justify: text lines are justified to both margins. The default depends on the base text direction. For left to right text, the default is align=left, while for right to left text, the default is align=right |
alt | 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 immediatelly removed from list after upload completed |
binding | The attribute takes a value-binding expression for a component property of a backing bean |
cancelButtonClass | CSS style for cancel button |
cancelButtonClassDisabled | CSS style for cancel button disabled |
cancelEntryControlLabel | Defines a label for a cancel control |
cleanButtonClass | CSS style for clean button |
cleanButtonClassDisabled | CSS style for clean button disabled |
clearAllControlLabel | Defines a label for a clearAll button |
clearControlLabel | Defines a label for a clear control |
converter | Id of Converter to be used or reference to a Converter |
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter |
disabled | Attribute 'disabled' provides possibility to make the whole component disabled if its value equals to "true". |
fileEntryClass | CSS style upload file entry |
fileEntryClassDisabled | CSS style upload file entry disabled |
fileEntryControlClass | CSS style for upload enrty control |
fileEntryControlClassDisabled | CSS style for upload enrty control disabled |
fileUploadListener | MethodExpression representing an action listener method that will be notified after file uploaded. |
id | 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 immediatelly uploaded after they have been added in list |
listHeight | Defines height of file list |
listWidth | Defines width of file list |
locale | Used for locale definition |
maxFilesQuantity | Defines max files count allowed for upload (optional). |
onblur | HTML: script expression; the element lost the focus |
onchange | HTML: script expression; the element value was changed |
onclick | HTML: a script expression; a pointer button is clicked |
ondblclick | HTML: a script expression; a pointer button is double-clicked |
onerror | A JavaScript event handler called when the file upload was interrupted according to any errors |
onfocus | HTML: script expression; the element got the focus |
onkeydown | HTML: a script expression; a key is pressed down |
onkeypress | HTML: a script expression; a key is pressed and released |
onkeyup | HTML: a script expression; a key is released |
onmousedown | HTML: script expression; a pointer button is pressed down |
onmousemove | HTML: a script expression; a pointer is moved within |
onmouseout | HTML: a script expression; a pointer is moved away |
onmouseover | HTML: a script expression; a pointer is moved onto |
onmouseup | HTML: script expression; a pointer button is released |
onselect | HTML: script expression; The onselect event occurs when you select some text in a text field. This attribute may be used with the INPUT and TEXTAREA elements |
onupload | A JavaScript event handler called on an upload operation |
onuploadcanceled | A JavaScript event handler called when upload is cancelled |
onuploadcomplete | A JavaScript event handler called when upload is completed |
rendered | If "false", this component is not rendered |
required | If "true", this component is checked for non-empty input |
requiredMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validation message for the "required" facility, if the "required" facility is used |
stopControlLabel | Defines a label for a stop button |
stopEntryControlLabel | Defines a label for a stop control |
style | CSS style(s) is/are to be applied when this component is rendered |
styleClass | Corresponds to the HTML class attribute |
tabindex | 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 |
uploadButtonClass | CSS style for upload button |
uploadButtonClassDisabled | CSS style for upload button disabled |
uploadControlLabel | Defines a label for an upload button |
uploadData | Collection of files uploaded |
uploadListClass | CSS style for upload list |
uploadListClassDisabled | CSS style for upload list disabled |
validator | 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 |
valueChangeListener | Listener for value changes |
Table 6.192. 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 uploaded files are stored:
In the temporary folder (depends on OS) if the value of the createTempFile parameter in Ajax4jsf Filter 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 "immediateUpload" attribute allows files to be uploaded immediately after they have been added into list. If you set this attribute to "true" files immediately upload after they have been added into the list, all next files automatically uploads one by one. If you cancel uploading – next files aren't start uploading till you press the general upload button or clear the list.
Example:
...
<rich:fileUpload uploadData="#{bean.data}" addControlLabel="myLabel" autoclear="true" maxFilesQuantity="2" fileUploadListener="#{bean.listener}"
acceptedTypes="html" immediateUpload="true"/>
...
The <rich:fileUpload> component provides following restrictions:
By 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"/>
...
By 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>
...
By 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. 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 "autoclear" attribute is used to remove automatically files from the list after upload completed.
Example:
...
<rich:fileUpload uploadData="#{bean.data}" addControlLabel="myLabel" autoclear="true"
acceptedTypes="html"/>
...
As it could be seen in the example above, files are removed from the list after upload completed.
The <rich:fileUpload> provides using a number of handlers. The "onupload" is available to cancel the upload at client side. The "onuploadcomplete" is called after all files in from list uploaded. The "onuploadcanceled" is called after upload was canceled via cancel control. The "onerror" is called if the file upload was interrupted according to any errors.
There is a number of facets providing for this component: "header" "footer" "label" . "label" facet could be used to provide displaying the progress of uploading.
Example:
...
<rich:fileUpload uploadData="#{bean.data}" addControlLabel="myLabel" autoclear="true" maxFilesQuantity="2" fileUploadListener="#{bean.listener}">
<f:facet name="label">
<h:outputText value="{_KB}KB from {KB}KB uploaded --- {mm}:{ss}"></h:outputText>
</f:facet>
</rich:fileUpload>
...
This is a result:
As it could be seen in the picture above, the label displays under the item.
Labels of component controls can be defined with "addControlLabel" , "clearAllControlLabel" , "clearControlLabel" , "stopEntryControlLabel" , "uploadControlLabel"
The <rich:fileUpload> component allows to use sizes attributes:
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.
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:
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:
Table 6.193. Skin parameters redefinition for a list
Skin parameters | CSS properties |
---|---|
tableBackgroundColor | background-color |
tableBorderColor | border-color |
Table 6.194. Skin parameters redefinition for a font
Skin parameters | CSS properties |
---|---|
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.195. Skin parameters redefinition for an items
Skin parameters | CSS properties |
---|---|
tableBorderColor | border-bottom-color |
Table 6.196. Skin parameters redefinition for a cancel link
Skin parameters | CSS properties |
---|---|
generalLinkColor | color |
Table 6.197. 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.198. Skin parameters redefinition for a button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
Table 6.199. Skin parameters redefinition for a highlighted button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
Table 6.200. Skin parameters redefinition for a pressed button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
Table 6.201. Skin parameters redefinition for a disabled add button icon
Skin parameters | CSS properties |
---|---|
tableBorderColor | color |
Table 6.202. Skin parameters redefinition for a disabled start button icon
Skin parameters | CSS properties |
---|---|
tableBorderColor | color |
Table 6.203. 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.204. Classes names that define a list representation
Class name | Description |
---|---|
upload_list_decor | Defines styles for a wrapper <table> element of a fileUpload |
upload_font | Defines styles for a font of buttons and items |
Table 6.205. Classes names that define toolbar representation
Class name | Description |
---|---|
upload_toolbar_decor | Defines styles for a toolbar |
Table 6.206. Classes names that define items representation
Class name | Description |
---|---|
upload_anc | Defines styles for a cancel link |
upload_table_td | Defines styles for an items |
Table 6.207. Classes names that define buttons representation
Class name | Description |
---|---|
upload_button_border | Defines styles for a border of buttons |
upload_button | Defines styles for a buttons |
upload_button_light | Defines styles for a highlight of button |
upload_button_press | Defines styles for a pressed button |
Table 6.208. Classes names that define disabled add button icon representation
Class name | Description |
---|---|
upload_ico_add_dis | Defines styles for a disabled add button icon |
Table 6.209. Classes names that define disabled upload button icon representation
Class name | Description |
---|---|
upload_ico_start_dis | Defines styles for a disabled upload button icon |
Table 6.210. Classes names that define disabled clear button icon representation
Class name | Description |
---|---|
upload_ico_clear_dis | Defines styles for a disabled clear button icon |
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:
...
.upload_list_decor{
background-color:#ecf4fe;
}
...
This is a result:
In the example the background color for list is 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 a result:
As it could be seen on the picture above, the font style for add button is changed.
Here you can see an example of <rich:fileUpload> usage and sources for the given example.