rich:fileUpload fileUpload

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

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

## Creating the Component Dynamically Using Java

Example:

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

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

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

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

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.

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

## Skin Parameters Redefinition

Skin parameters redefinition for a list

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background-color
tableBorderColor | border-color

Skin parameters redefinition for a font

Skin parameters | CSS properties
--- | ---
generalFamilyFont | font-family
generalSizeFont | font-size

Skin parameters redefinition for an items

Skin parameters | CSS properties
--- | ---
tableBorderColor | border-bottom-color

Skin parameters redefinition for a cancel link

Skin parameters | CSS properties
--- | ---
generalLinkColor | color

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

Skin parameters redefinition for a button

Skin parameters | CSS properties
--- | ---
trimColor | background-color

Skin parameters redefinition for a highlighted button

Skin parameters | CSS properties
--- | ---
trimColor | background-color

Skin parameters redefinition for a pressed button

Skin parameters | CSS properties
--- | ---
trimColor | background-color

Skin parameters redefinition for a disabled add button icon

Skin parameters | CSS properties
--- | ---
tableBorderColor | color

Skin parameters redefinition for a disabled start button icon

Skin parameters | CSS properties
--- | ---
tableBorderColor | color

Skin parameters redefinition for a disabled clear button icon

Skin parameters | CSS properties
--- | ---
tableBorderColor | color

## Definition of Custom Style Classes

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

Classes names

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

Classes names that define toolbar representation

Class name | Description
--- | ---
upload_toolbar_decor | Defines styles for a toolbar

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

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

Classes names that define disabled add button icon representation

Class name | Description
--- | ---
upload_ico_add_dis | Defines styles for a disabled add button icon

Classes names that define disabled upload button icon representation

Class name | Description
--- | ---
upload_ico_start_dis | Defines styles for a disabled upload button icon

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:

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

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

## Relevant Resources Links

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