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

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

Immediately files uploading could be performed by means of the "immediateUpload" attribute. If the value of this attribute is "true" files are uploaded immediately 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"/>
    ...

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:

  <rich:fileUpload>with "maxFilesQuantity" attribute

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

- 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

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:

<rich:fileUpload> with "label" facet

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:

<rich:fileUpload> with labels

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:

<rich:fileUpload>with "disabled" attribute

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 component

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 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 items in the list

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

Skin parameters redefinition for a "Cancel", "Clear" links

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

Skin parameters redefinition for a button

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

Skin parameters redefinition for a button border

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

Skin parameters redefinition for a highlighted button

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

Skin parameters redefinition for a pressed button

Skin parameters | CSS properties
--- | ---
selectControlColor | border-color
additionalBackgroundColor | background-color

Skin parameters redefinition for "Upload", "Clean" buttons

Skin parameters | CSS properties
--- | ---
generalTextColor | 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

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

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

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

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" and "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:

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