| |||||||
FRAMES NO FRAMES |
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 Class | com.icesoft.faces.component.inputfile.InputFileTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||||||||||||||
Name | Required | Request-time | Type | Description | ||||||||||||
accept | false | false | java.lang.String | Passed through to root element. | ||||||||||||
accesskey | false | false | java.lang.String | Access key that, when pressed, transfers focus to this element. | ||||||||||||
action | false | false | java.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. |
||||||||||||
actionListener | false | false | java.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. |
||||||||||||
autoUpload | false | false | java.lang.String | This attribute is false by default. It makes the inputFile component to automatically upload the file on selection. | ||||||||||||
binding | false | false | java.lang.String | The value binding expression linking this component to a property in a backing bean | ||||||||||||
buttonClass | false | false | java.lang.String | style class for the submit button. | ||||||||||||
disabled | false | false | java.lang.String | Flag indicating that this element must never receive focus or be included in a subsequent submit. | ||||||||||||
enabledOnUserRole | false | false | java.lang.String | If user is in given role, this component will be rendered normally. If not, the component will be in disabled state. | ||||||||||||
failOnEmptyFile | false | false | java.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. | ||||||||||||
file | false | false | java.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. | ||||||||||||
fileNamePattern | false | false | java.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" |
||||||||||||
height | false | false | java.lang.String | height of the component. | ||||||||||||
id | false | false | java.lang.String | The component identifier for this component. This value must be unique within the closest parent component that is a naming container. | ||||||||||||
immediate | false | false | java.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. | ||||||||||||
inputTextClass | false | false | java.lang.String | style class for the inputText. | ||||||||||||
inputTextSize | false | false | java.lang.String | size of the input text. | ||||||||||||
label | false | false | java.lang.String | Text that will appear on the submit button. | ||||||||||||
onblur | false | false | java.lang.String | Javascript code executed when this element loses focus. | ||||||||||||
onchange | false | false | java.lang.String | Javascript code executed when this element loses focus and its value has been modified since gaining focus. | ||||||||||||
onfocus | false | false | java.lang.String | Javascript code executed when this element receives focus. | ||||||||||||
progressListener | false | false | java.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.
|
||||||||||||
progressRender | false | false | java.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. |
||||||||||||
rendered | false | false | java.lang.String | Flag indicating whether or not this component should be rendered (during Render Response Phase), or processed on any subsequent form submit. | ||||||||||||
renderedOnUserRole | false | false | java.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. | ||||||||||||
style | false | false | java.lang.String | CSS style(s) to be applied when this component is rendered. | ||||||||||||
styleClass | false | false | java.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.
|
||||||||||||
submitOnUpload | false | false | java.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:
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. |
||||||||||||
tabindex | false | false | java.lang.String | Position of this element in the tabbing order for the current document. This value must be an integer between 0 and 32767. | ||||||||||||
title | false | false | java.lang.String | Passed through to root element. | ||||||||||||
uniqueFolder | false | false | java.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:
|
||||||||||||
uploadDirectory | false | false | java.lang.String | Describes the directory where any uploaded files should be placed. Overrides the com.icesoft.faces.uploadDirectory context-param for this specific inputFile. | ||||||||||||
uploadDirectoryAbsolute | false | false | java.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. | ||||||||||||
value | false | false | java.lang.String | The current value of this component. | ||||||||||||
width | false | false | java.lang.String | width of the component. |
Variables | No Variables Defined. |
| |||||||
FRAMES NO FRAMES |