The ICEfaces Tutorial
Table of Contents


Lesson: Using the InputFile component

How to Use the ICEfaces InputFile Component

The inputFile component can upload a file from a client machine to the server. The inputFile component renders an file input HTML element. Users specify a file to upload either by entering the path to a file directly, or by clicking the Browse button to open a file-system navigation dialog window. Clicking the Upload button uploads the specified file to the server.

This tutorial will discuss the following topics related to the use of the inputFile component:

Basic InputFile Component

There are three things you must keep in mind before using the ice:inputFile component. You need to have the commons-fileupload.jar on your classpath. The ice:inputFile component must be inside a form element and you must add the following to your web.xml file:

    <!-- file upload Servlet -->
    <servlet>
         <servlet-name>uploadServlet</servlet-name>
         <servlet-class>com.icesoft.faces.component.inputfile.FileUploadServlet</servlet-class>
         <load-on-startup> 1 </load-on-startup>
    </servlet>
    <servlet-mapping>
         <servlet-name>uploadServlet</servlet-name>
         <url-pattern>/uploadHtml</url-pattern>
    </servlet-mapping>
    

In our demo, a bean named 'user' has been defined in the faces.config file as a session scope bean. The ice:inputFile actionListener is bound to a method in 'user'. The actionListener will retrieve a reference to com.icesoft.faces.component.inputfile.FileInfo from the component. You can then retrieve a reference to the File itself from the FileInfo object.

We also have the following entry in our web.xml, which means the location of the uploaded files will be in a folder named 'upload' located in the root of the application-context.

    <context-param>
            <param-name>com.icesoft.faces.uploadDirectory</param-name>
            <param-value>upload</param-value>
    </context-param>
    

If you attempt to upload an invalid entry, or a file greater in size than 10 MB (the default limit for this component), you should see an appropriate error message output via an ice:message component. The inputFile component sends exception information to the client using FacesMessage, so it is a good idea to have an instance of ice:message or ice:messages on your page.

In the demo, we have added an ice:outputText component at the bottom, to show the location of the file on the server after it has been uploaded.


Download the demo:

InputFile Component with OutputProgress Component

In order to see the progress of a file as it uploads, we must place an ice:outputProgress component on the page and add a progressListener to the ice:inputFile component. The progressListener on the inputFile component sets the value of an integer in the backing bean that in turn, is bound to the value attribute of the ice:outputProgress component. This integer lets the ice:outputProgress component know the percentage progress of the file as it is being uploaded.

Download the demo:

Advanced InputFile Component

Maximum File Size

If you want to change the maximum file size that can be uploaded with the ice:inputFile component, you must add a context parameter to the web.xml file. The default maximum is 10 MB, we will change the maximum to 1 MB in the advanced demos by adding the following:

    <context-param>
        <param-name>com.icesoft.faces.uploadMaxFileSize</param-name>
        <param-value>1048576</param-value>
    </context-param>
    

ActionListener Attribute

An actionListener is invoked when the uploaded file is saved, or on any exception. This means the developer can perform an operation when the component reaches one of the following InputFile states: [SAVED, INVALID, INVALID_CONTENT_TYPE, INVALID_NAME_PATTERN, SIZE_LIMIT_EXCEEDED, UNKNOWN_SIZE, UNSPECIFIED_NAME, UPLOADING].

The advanced demo removes the ice:message component we used previously to output error messages. Now we will use the actionListener method to query the component for its state and output the state with an ice:outputText component.

When using the demo, try uploading a file greater than 1 MB in size to confirm we have changed the maximum file size with the addition of the context parameter above.

We have also added fileNamePattern=".+\.pdf" as an attribute to the component. Try uploading valid .pdf and non-pdf files to test the component's ability to apply a name pattern to the files selected for uploading.

UniqueFolder Attribute

The ice:inputFile component features an attribute that lets you manipulate where the file will be saved. The default behaviour of the component is to upload files to the context root. If you add the attribute uniqueFolder="true" to the component it will create a folder with the session id as its name. This allows you to easily associate files to a specific session.

The advanced demo has two components under the heading UniqueFolder Attribute, both of them have an outputText component underneath to show the location of the file after it has been uploaded. The first component shows the default behaviour of the component without uniqueFolder set to 'true'. The second component has the attribute uniqueFolder="true" which means a folder with the session id will be created and the file will be placed in that folder.

Download the demo:

Examples that Use InputFile

Example Source Notes
Component Showcase Available in release bundles Contains basic inputFile example.
inputFile-basic inputFile-basic source code Simple example of how to use inputFile component.
inputFile-progress inputFile-progress source code An outputProgress component is added to the page and connected to the progress of the uploading file.
inputFile-advanced inputFile-advanced source code The maximum file size is altered. The actionListener, uniqueFolder and fileNamePattern attributes are explained.

The ICEfaces Tutorial
Table of Contents

Copyright 2009 ICEsoft Technologies Inc. All rights reserved.