6.50.  < rich:fileUpload >

6.50.1. Description

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

<rich:fileUpload> component

Figure 6.88.  <rich:fileUpload> component


6.50.2. Key Features

  • Highly customizable look and feel
  • File types/File sizes restrictions
  • Multiple files upload support
  • Cancel the request possibility
  • One request for every upload component
  • Different submit modes (Server/Client)
  • Asynchronous mode

Table 6.190. rich : fileUpload attributes

Attribute NameDescription
acceptedTypesFiles types allowed to upload
accesskeyThis 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
addButtonClassCSS style for add button
addButtonClassDisabledCSS style for add button disabled
addControlLabelDefines a label for an add control
alignleft|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
altFor 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
autoclearIf this attribute is true files will be immediatelly removed from list after upload completed
bindingThe attribute takes a value-binding expression for a component property of a backing bean
cancelButtonClassCSS style for cancel button
cancelButtonClassDisabledCSS style for cancel button disabled
cancelEntryControlLabelDefines a label for a cancel control
cleanButtonClassCSS style for clean button
cleanButtonClassDisabledCSS style for clean button disabled
clearAllControlLabelDefines a label for a clearAll control
clearControlLabelDefines a label for a clear control
converterId of Converter to be used or reference to a Converter
converterMessageA ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
disabledAttribute 'disabled' provides possibility to make the whole component disabled if its value equals to "true".
fileEntryClassCSS style upload file entry
fileEntryClassDisabledCSS style upload file entry disabled
fileEntryControlClassCSS style for upload enrty control
fileEntryControlClassDisabledCSS style for upload enrty control disabled
fileUploadListenerMethodExpression representing an action listener method that will be notified after file uploaded.
idEvery component may have a unique id that is automatically created if omitted
immediateA 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
immediateUploadIf this attribute is true files will be immediatelly uploaded after they have been added in list
listHeightDefines height of file list
listWidthDefines width of file list
localeUsed for locale definition
maxFilesQuantityDefines max files count allowed for upload (optional).
maxlengthWhen the type attribute has the value "text" or "password", this attribute specifies the maximum number of characters you may enter. This number may exceed the specified size, in which case the user agent should offer a scrolling mechanism. The default value for this attribute is an unlimited number
onblurHTML: script expression; the element lost the focus
onchangeHTML: script expression; the element value was changed
onclickHTML: a script expression; a pointer button is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
onerrorA JavaScript event handler called when the file upload was interrupted according to any errors
onfocusHTML: script expression; the element got the focus
onkeydownHTML: a script expression; a key is pressed down
onkeypressHTML: a script expression; a key is pressed and released
onkeyupHTML: a script expression; a key is released
onmousedownHTML: script expression; a pointer button is pressed down
onmousemoveHTML: a script expression; a pointer is moved within
onmouseoutHTML: a script expression; a pointer is moved away
onmouseoverHTML: a script expression; a pointer is moved onto
onmouseupHTML: script expression; a pointer button is released
onselectHTML: 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
onuploadA JavaScript event handler called on an upload operation
onuploadcanceledA JavaScript event handler called when upload is cancelled
onuploadcompleteA JavaScript event handler called when upload is completed
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
requiredMessageA 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
stopControlLabelDefines a label for a stop control
stopEntryControlLabelDefines a label for a stop control
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
tabindexThis 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
uploadButtonClassCSS style for upload button
uploadButtonClassDisabledCSS style for upload button disabled
uploadControlLabelDefines a label for an upload control
uploadDataCollection of files uploaded
uploadListClassCSS style for upload list
uploadListClassDisabledCSS style for upload list disabled
validvalid
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
valueThe initial value to set when rendered for the first time
valueChangeListenerListener for value changes

Table 6.191. Component identification parameters

NameValue
component-typeorg.richfaces.component.FileUpload
component-classorg.richfaces.component.html.HtmlFileUpload
component-familyorg.richfaces.component.FileUpload
renderer-typeorg.richfaces.renderkit.html.FileUploadRenderer
tag-classorg.richfaces.taglib.FileUploadTag

6.50.3. Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:


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

6.50.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlFileUpload;
... 
HtmlFileUpload myFileUpload = new HtmlFileUpload();
...

6.50.5. Details of Usage

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

  • List of files which contains the list of currently chosen files with possibility to manage every file.
  • Component controls- the bar with controls for managing the whole component.

The "disabled" attribute is used to disable all elements of the component. All the controls disables too.

Example:


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

This is a result:

<rich:fileUpload> with "disabled" attribute

Figure 6.89.  <rich:fileUpload> with "disabled" attribute


The "acceptedTypes" attribute is used to define file types which are accepted to upload.

Example:


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

As it could be seen in the example above, only files with "html" extension are accepted to upload.

The "autoclear" attribute is used to remove automatically files from 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 removes from list after upload completed.

The "maxFilesQuantity" defines max number of files allowed for upload. After number of files in the list is equals to this attribute – add button is disabled. The add button is not available until all list items are uploaded.

Example:


...
<rich:fileUpload uploadData="#{bean.data}" addControlLabel="myLabel" autoclear="true" maxFilesQuantity="2"
 acceptedTypes="html"/>
 ...

This is a result:

<rich:fileUpload> with "maxFilesQuantity" attribute

Figure 6.90.  <rich:fileUpload> with "maxFilesQuantity" attribute


As it could be seen in the picture above, only 2 files allows for upload.

The "fileUploadedListener" is called at server side after every file uploaded and used for the file saving by end developer.

Example:


...
<rich:fileUpload uploadData="#{bean.data}" addControlLabel="myLabel" autoclear="true" maxFilesQuantity="2" fileUploadListener="#{bean.listener}" 
 acceptedTypes="html"/>
 ...

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 uploads after they have been added into 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> 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 are 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}" 
 acceptedTypes="html">
        <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:

<rich:fileUpload> with "label" facet

Figure 6.91.  <rich:fileUpload> with "label" facet


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:

  • "listHeight" attribute specify height for list of files in pixels
  • "listWidth" attribute specify width for list of files in pixels.

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.

6.50.6. Look-and-Feel Customization

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

6.50.7. Skin Parameters Redefinition

Table 6.192. Skin parameters redefinition for a list

Skin parametersCSS properties
tableBackgroundColorbackground-color
tableBorderColorborder-color

Table 6.193. Skin parameters redefinition for a font

Skin parametersCSS properties
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.194. Skin parameters redefinition for an items

Skin parametersCSS properties
tableBorderColorborder-bottom-color

Table 6.195. Skin parameters redefinition for a cancel link

Skin parametersCSS properties
generalLinkColorcolor

Table 6.196. Skin parameters redefinition for a toolbar

Skin parametersCSS properties
additionalBackgroundColorbackground-color
tableBorderColorborder-bottom-color
tableBackgroundColorborder-top-color
tableBackgroundColorborder-left-color

Table 6.197. Skin parameters redefinition for a button

Skin parametersCSS properties
trimColorbackground-color

Table 6.198. Skin parameters redefinition for a highlighted button

Skin parametersCSS properties
trimColorbackground-color

Table 6.199. Skin parameters redefinition for a pressed button

Skin parametersCSS properties
trimColorbackground-color

Table 6.200. Skin parameters redefinition for a disabled add button icon

Skin parametersCSS properties
tableBorderColorcolor

Table 6.201. Skin parameters redefinition for a disabled start button icon

Skin parametersCSS properties
tableBorderColorcolor

Table 6.202. Skin parameters redefinition for a disabled clear button icon

Skin parametersCSS properties
tableBorderColorcolor

6.50.8. Definition of Custom Style Classes

The following picture illustrates how CSS classes define styles for component elements.

Classes names

Figure 6.92. Classes names


Table 6.203. Classes names that define a list representation

Class nameDescription
upload_list_decorDefines styles for a wrapper <table> element of a fileUpload
upload_fontDefines styles for a font of buttons and items

Table 6.204. Classes names that define toolbar representation

Class nameDescription
upload_toolbar_decorDefines styles for a toolbar

Table 6.205. Classes names that define items representation

Class nameDescription
upload_ancDefines styles for a cancel link
upload_table_tdDefines styles for an items

Table 6.206. Classes names that define buttons representation

Class nameDescription
upload_button_borderDefines styles for a border of buttons
upload_buttonDefines styles for a buttons
upload_button_lightDefines styles for a highlight of button
upload_button_pressDefines styles for a pressed button

Table 6.207. Classes names that define disabled add button icon representation

Class nameDescription
upload_ico_add_disDefines styles for a disabled add button icon

Table 6.208. Classes names that define disabled upload button icon representation

Class nameDescription
upload_ico_start_disDefines styles for a disabled upload button icon

Table 6.209. Classes names that define disabled clear button icon representation

Class nameDescription
upload_ico_clear_disDefines 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:

Redefinition styles with predefined classes

Figure 6.93. Redefinition styles with predefined classes


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:

Redefinition styles with own classes and styleClass attributes

Figure 6.94. Redefinition styles with own classes and styleClass attributes


As it could be seen on the picture above, the font style for add button is changed.

6.50.9. Relevant Resources Links

Here you can see an example of <rich:fileUpload> usage and sources for the given example.