ICEfaces Component Suite
Tag inputFile


The inputFile component can be used to provide a user-specified file upload capability.
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.
Note: Newer browsers now make the field, where users previously could type in the file path, be read-only, to prevent users from entering invalid file paths. Clicking into that field can summon the file selection dialog, just as clicking on the Browse button would.
Note: The web.xml parameter com.icesoft.faces.uploadDirectoryAbsolute when set to true will use the value of the com.icesoft.faces.uploadDirectory parameter as an absolute directory.
Note: If the styleClass, buttonClass or the inputTextClass need to be set, then the css file must be referenced using the ice:outputStyle component.
Note: In order to set the height and width of this component, it is recomended to use the height and the width attribute of this component instead of setting it using the style or styleClass. This is due to the rendering of an iframe.


Tag Information
Tag Classcom.icesoft.faces.component.inputfile.InputFileTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
acceptfalsefalsejava.lang.String Passed through to root element.
accesskeyfalsefalsejava.lang.String Access key that, when pressed, transfers focus to this element.
actionfalsefalsejava.lang.String MethodBinding representing the application action to invoke when this component is activated by the user. The expression must evaluate to a either a String or a public method that takes no parameters, and returns a String (the logical outcome) which is passed to the NavigationHandler for this application.
Note: Long processing, for more than a few seconds, should be done from a worker thread, spawned by your action method. Otherwise the browser will timeout, and the inputFile component will disappear.
actionListenerfalsefalsejava.lang.String MethodBinding representing an action listener method that will be notified when this component is activated by the user. The expression must evaluate to a public method that takes an ActionEvent parameter, with a return type of void.
Note: Long processing, for more than a few seconds, should be done from a worker thread, spawned by your action method. Otherwise the browser will timeout, and the inputFile component will disappear.
autoUploadfalsefalsejava.lang.String This attribute is false by default. It makes the inputFile component to automatically upload the file on selection.
bindingfalsefalsejava.lang.String The value binding expression linking this component to a property in a backing bean
buttonClassfalsefalsejava.lang.String style class for the submit button.
disabledfalsefalsejava.lang.String Flag indicating that this element must never receive focus or be included in a subsequent submit.
enabledOnUserRolefalsefalsejava.lang.String If user is in given role, this component will be rendered normally. If not, the component will be in disabled state.
failOnEmptyFilefalsefalsejava.lang.String This attribute is true by default. It makes the inputFile component throw an exception if the file size is 0. Setting it to false lets files be uploaded with 0 size, without the component throwing any exception. In that case, the application can handle 0 sized file using the actionListener.
filefalsefalsejava.lang.String Bean property that will be a reference to the uploaded file. Note: This is deprecated. Instead you should use actionListener, and when in the callback method, call InputFile.getFileInfo(), which will give you information on both successful and failed file upload attempts.
fileNamePatternfalsefalsejava.lang.String The name of the file being uploaded must conform with this pattern. The regular expression can be use to define the valid file name to be uploaded.
If the file name does not match with the pattern, the file will not be uploaded and an actionEvent and an exception would be fired and thrown respectively.
		public void action(ActionEvent event) {
             InputFile inputFile = (InputFile) event.getSource();
		     if (inputFile.getStatus() == InputFile.INVALID) {
                inputFile.getFileInfo().getException().printStackTrace();
             }
        }
        
The default pattern is set to ".+" for any name lenght > 0. Let say to allow only .pdf files to be uploaded the pattern would be ".+\.pdf"
heightfalsefalsejava.lang.String height of the component.
idfalsefalsejava.lang.String The component identifier for this component. This value must be unique within the closest parent component that is a naming container.
immediatefalsefalsejava.lang.String Flag indicating that, if this component is activated by the user, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase.
inputTextClassfalsefalsejava.lang.String style class for the inputText.
inputTextSizefalsefalsejava.lang.String size of the input text.
labelfalsefalsejava.lang.String Text that will appear on the submit button.
onblurfalsefalsejava.lang.String Javascript code executed when this element loses focus.
onchangefalsefalsejava.lang.String Javascript code executed when this element loses focus and its value has been modified since gaining focus.
onfocusfalsefalsejava.lang.String Javascript code executed when this element receives focus.
progressListenerfalsefalsejava.lang.String

MethodBinding representing a progress listener method that will be notify the application on the percentage of the file being uploaded. The expression must evaluate to a public method that takes a single parameter of type com.icesoft.faces.component.inputfile.InputFileProgressEvent, with a return type of void.

These are some things to consider when implementing the progressListener.

  • Beans which implement the progressListener must be in session scope.
  • The PersistentFacesState must be set in the constructor of session bean.
  • The progressListener method may invoke the executeAndRender() call on the PersistentFacesState instance, or may use the OnDemandRenderer, in order to render the page.
  • The progressListener method must take a single argument of type com.icesoft.faces.component.inputfile.InputFileProgressEvent.
  • From the InputFileProgressEvent's getComponent() or getSource() methods, developers may attain a reference to the InputFile component.
  • If the progressListener is being invoked due to the inputFile causing a form submit (refer to the submitOnUpload attribute), then the InputFile's FileInfo object's isPreUpload() or isPostUpload() method will return true, depending if the form post is from before or after the file upload.

progressRenderfalsefalsejava.lang.String

Historically, when the inputFile's current file upload was progressing, and the progressListener was invoked, the progressListener's bean would implement com.icesoft.faces.async.render.Renderable, and use the com.icesoft.faces.async.render.RenderManager in conjunction with the com.icesoft.faces.async.render.OnDemandRenderer, to do a server push, to update the view in the browser with the current progress. It could also invoke either PersistentFacesState.render() or PersistentFacesState.renderLater(), to accomplish the same thing.

As of ICEfaces 1.7.1, you can just set progressRender="true", and the server push will happen for you, without setting up all that glue code in the bean. You still have to set your outputProgress component's progress percent in the bean via the progressListener, and you have to enabled asynchronous mode, by setting the com.icesoft.faces.synchronousUpdate context parameter to false.

As of ICEfaces 1.8 DR#2, the RenderManager method is completely outdated, since now the inputFile requires a full JSF lifecycle for each progress event, meaning that now it automatically renders itself. Neither is it necessary to set progressRender="true", since it is true by default. It's possible to set progressRender="false", to disable the lifecycles, but that will also disable the progressListener and actionListener MethodBindings and the file settable ValueBinding, since these all happen within JSF lifecycles.

Note: The default value is true.

renderedfalsefalsejava.lang.String Flag indicating whether or not this component should be rendered (during Render Response Phase), or processed on any subsequent form submit.
renderedOnUserRolefalsefalsejava.lang.String If user is in given role, this component will be rendered normally. If not, nothing is rendered and the body of this tag will be skipped.
stylefalsefalsejava.lang.String CSS style(s) to be applied when this component is rendered.
styleClassfalsefalsejava.lang.String

Space-separated list of CSS style class(es) to be applied when this element is rendered. This value must be passed through as the "class" attribute on generated markup.
Default value is iceInpFile.
Style classes used, if enabled:

  • iceInpFile
  • iceInpFileBtn
  • iceInpFileTxt
if disabled
  • iceInpFile-dis
  • iceInpFileBtn-dis
  • iceInpFileTxt-dis

submitOnUploadfalsefalsejava.lang.String

Depending on the value of submitOnUpload, the inputFile may post its enclosing form, before and/or after the file upload occurs. Possible values are:

none
File uploading will not cause the inputFile's enclosing form, and any other of the form fields, to be submitted to the server.
preUpload
The inputFile's enclosing form, and any other of the form fields, will be submitted to the server, immediately before the file uploading begins.
postUpload
The inputFile's enclosing form, and any other of the form fields, will be submitted to the server, immediately after the file uploading finishes.
preAndPostUpload
The inputFile's enclosing form, and any other of the form fields, will be submitted to the server, both before and after the file uploading takes place.

This is to support two different use cases. Applications running in synchronous mode can not make use of server push, so to depict the beginning and the ending of the file upload requires browser initiated JSF lifecycles, accomplished via form submissions. As well, for some applications, it's desirable to submit other form fields when the user clicks on the file upload button, so that they may be processed together with the uploaded file.

Note: The default value is none.

tabindexfalsefalsejava.lang.String Position of this element in the tabbing order for the current document. This value must be an integer between 0 and 32767.
titlefalsefalsejava.lang.String Passed through to root element.
uniqueFolderfalsefalsejava.lang.String This uniqueFolder attribute works in conjunction with the com.icesoft.faces.uploadDirectory parameter with four possible combinations as illustrated in the table below:
com.icesoft.faces.uploadDirectory
uniqueFolderSetNot Set
True/application-context/uploadDirectory/sessionid//application-context/sessionid/
False/application-context/uploadDirectory//application-context/
Note: The default value is true.
uploadDirectoryfalsefalsejava.lang.String Describes the directory where any uploaded files should be placed. Overrides the com.icesoft.faces.uploadDirectory context-param for this specific inputFile.
uploadDirectoryAbsolutefalsefalsejava.lang.String If the uploadDirectory should be interpretted as an absolute path into the filesystem, or as a relative path from the deployment directory. Overrides the com.icesoft.faces.uploadDirectoryAbsolute context-param for this specific inputFile.
valuefalsefalsejava.lang.String The current value of this component.
widthfalsefalsejava.lang.String width of the component.

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.