| |||||||
FRAMES NO FRAMES |
Use the webuijsf:fileChooser
tag to display a component
that shows files and folders in a local file system hierachy,
and allows the web application user to select files and folders.
The list of displayed files is determined by the filesystem access rules that are in place in the given environment.
The fileChooser component is rendered as an XHTML <table>
element that contains several TextField
, DropDown
,
Listbox
, and Button
components.
The layout is similar to the following:
Browse Server | |||
Server Name: SomeServer (static text) | |||
Look In: | /some/directory (text field) | ||
File Filter: | * (text field) | ||
To apply a new field value, press Enter in that field | |||
Sort By: | (dropDown) | ||
List of files/folders (list box)
|
|||
Up One Level (button) |
Open Folder (button) |
||
Selected File: | some filename (text field) |
The fileChooser component can be used to render a file chooser or a folder chooser. A file chooser displays files and folders, and allows you to select files and open folders, but not to select folders. A folder chooser also displays files and folders, but the files are displayed as disabled and cannot be selected. A folder chooser allows only folders to be selected. With both types of choosers, you can open folders by selecting a folder and clicking the Open Folder button, or by double-clicking the folder name.
The fileChooser component displays files in the local filesystem only.
The directory whose files and folders should be displayed is specified with a
webuijsf:fileChooser
tag's lookin
attribute. The list of displayed files is determined by the filesystem
access rules that are in effect in the given environment.
By default, the component is rendered as a file chooser. To specify a
folder chooser, set the webuijsf:fileChooser
tag's
folderChooser
attribute to true. The folder chooser
displays the labels Folder Filter and Selected Folders
instead of the file chooser's File Filter and Selected Files.
Use the multiple
attribute to specify whether
multiple resources (files or folders) can be selected.
By default the multiple
attribute is set to false.
The web app user can sort the list of files and folders shown in the
fileChooser by selecting a sort option from the "Sort By" drop down menu.
The list is sorted alphabetically by default. Use the sortField
attribute to configure the initial sort. Valid sortField
attribute values are:
alphabetic
to sort alphabetically
size
to sort by file size
date
to sort by last modified date
The initial sort order is ascending; A-Z, smallest file size first,
oldest file first respectively. Set the descending
attribute to true to specify a descending sort order.
The input to the fileChooser is the value of the lookin
attribute. This attribute sets the initial value of the "Look In" text field
which determines the initial contents of the chooser's list.
The output of the fileChooser component is the list of selected files or
folders. This is the value of the component. The selected
attribute is updated with the value when the setChooseButton
JavaScript function causes the form to be submitted or the form is
submitted in a non "immediate" manner. See the sections
Client-side JavaScript functions
and Form Submit Behavior for more details.
The webuijsf:fileChooser
tag supports several facets that
you can use to replace the default component rendered for some
functionality of the component. The facets are listed in the
Facets section.
The fileChooser's form submit behavior conforms to the JSF lifecycle, with
respect to the fileChooser's value (assigned to the selected
attribute), and the values of the fileChooser facets. This means that
the fileChooser's value and its facets' values are only updated if the
form is submitted with the intent of updating the application's model values.
In other words, the fileChooser elements that submit the form do so in an "immediate" JSF fashion, so that the submitted values of the fileChooser and facets are validated, but the values are not updated. Only the local values are set.
The fileChooser's selected
value and the value of the facet
components are updated only when the following actions occur on a page
that uses the fileChooser component:
setChooserButton
function is clicked or otherwise submits the page.
The fileChooser component supports the following facets.
Note Specifying facets to replace the default components rendered by the file chooser for facet roles, is an advanced use of this tag. This is especially true for the TextField and Button facets such as lookinField, selectedField, filterField, upButton, and openButton. The component specified for a given facet role must take on the responsibilities expected by the fileChooser. Not satisifying those responsibilities can cause the fileChooser to function incorrectly.
fileChooserLabel |
Specifies a custom label to replace the File Chooser component label. By default the label is a localized value meaning "Browse Server" in English. |
serverLabel |
Specifies a custom component to replace the "Server Name" label. |
serverNameText
|
Specifies a custom component to replace the "Server Name" static text. |
lookinField |
Specifies a custom component for the
"Look In" text field. The id attribute of the facet
component should be set to the webuijsf:fileChooser
tag's id attribute with _lookinField appended
to the ID. For example, if thewebuijsf:fileChooser ID is
fc1 , the facet component's ID should be
fc1_lookinField .You should use the function enterKeyPressed(this)
as the value of the onKeyPress attribute of the facet
component. See Client-side JavaScript functions
for details. |
lookinLabel |
Specifies a custom label for the Look In field of the component. |
filterField |
Specifies a custom
component to replace the "File Filter" or "Folder Filter" text
field. The id attribute of the facet's component should
be set to the webuijsf:fileChooser tag's id
attribute, with _filterField appended to the ID. For
example, if the webuijsf:fileChooser ID is fc1 ,
the facet component's id should be fc1_filterField .You should use the function enterKeyPressed(this)
as the value of the onKeyPress attribute of the facet
component. See Client-side JavaScript functions
for details. |
filterLabel |
Specifies a custom label for the "File Filter" or "Folder Filter" text field of the component. |
enterPressHelp |
Specifies a custom inline help message to describe the
effect of pressing the Enter key after entering data in the "Look In"
and "Filter On" fields. By default the following inline help message is
displayed: "To apply a new field value, press Enter in that field." |
multiSelectHelp |
Specifies a custom inline help message about choosing
multiple files. By default the following inline help message is
displayed: "To select multiple items, use Shift-click or Control-click." |
selectedField |
Specifies a custom
component to replace the "Selected Files" or "Selected Folders"
field. The id attribute of the facet component should
be set to the webuijsf:fileChooser tag's id
attribute, with _selectedField appended to the ID. For
example, if the webuijsf:fileChooser ID is fc1 ,
the facet component's ID should be fc1_selectedField .You should use the function enterKeyPressed(this)
as the value of the onKeyPress attribute of the facet
component. See Client-side JavaScript functions for
details. |
selectedLabel |
Specifies a custom label for the "Selected Files" or "Selected Folders" field of the component. |
upButton |
Specifies a custom
component to replace the "Up One Level" button. When clicked,
this button causes the list of files from a level above the
currently displayed directory to be displayed. The id
attribute of the custom component should be set to the
webuijsf:fileChooser tag's id attribute with
_upButton appended to the ID. For example, if the
webuijsf:fileChooser ID is fc1 , the facet
component's ID should be fc1_upButton .If you want to use the JavaScript function associated with the default button's onClick event use the moveUpButtonClicked()
function with the custom component's onClick attribute. See
Client-side JavaScript functions below for details. |
openButton |
Specifies a custom component to replace
the "Open Folder" button. When clicked, this button causes the currently
selected folder's contents to be displayed. The id attribute
of the custom component should be set to the webuijsf:fileChooser
tag's id attribute with _openButton appended to the
id. For example, if the webuijsf:fileChooser ID is
fc1 , the custom component's ID should be
fc1_openButton .If you want to use the JavaScript function associated with the default button's onClick event use the openFolderClicked() function
with the custom component's onClick attribute. See
Client-side JavaScript functions below for details. |
sortMenu |
Specifies a custom component to replace the "Sort By" drop down menu of the component. |
When the fileChooser is rendered, a DOM object corresponding to the
component is created. To manipulate the component on the client,
you may invoke functions on the DOM object. Assume the ID of the
fileChooser is "fc1". Invoke document.getELementById("fc1")
to obtain a reference the fileChooser's DOM object. The following
functions can be invoked on that instance, for example
document.getElementById("fc1").openFolderClicked()
.
openFolderClicked() |
Displays the list of files and/or folders in the currently selected folder. |
handleOnChange() |
Handles all activities when the onChange event occurs for the listbox that lists the files and folders. |
handleDblClick() |
Invoked when the user double clicks on a file or folder in the list. |
enterKeyPressed(userAction) |
Invoked when the user changes the value of any of the text fields in the file chooser and hits the Enter key. |
setChooseButton() |
Use this function to assign a DOM element
ID of the element that submits the form to update the file chooser's
selections. The state of this element will be controlled by the state
of the file chooser. For example if there are no selections, the element
will be disabled. Note:Any action in the fileChooser that submits the form with the intent of updating the file chooser value, will call the "click" function of this element. |
getCurrentDirectory() |
Convenience function to get the current directory without going to the server. |
getOptionElements() |
Convenience function to get the list of option elements. |
getSelectedOptions() |
Convenience function to get the list of selected option elements. |
This example shows a simple fileChooser. The page includes a separate button
that is used with the fileChooser's setChooseButton
function.
<webuijsf:fileChooser id="filechooser" lookin="#{fileList.lookin}" selected="#{fileList.selected}" sortField="alphabetic" descending="true" /> <webuijsf:button id="fileChooseButton" primary="true" text="Choose File" actionListener="#{fileList.chooseFile}"/> <script type="text/javascript"> var fc = document.getElementById(form1:filechooser); fc.setChooseButton('form1:fileChooseButton'); </script>
The example uses the following ManagedBean class
import java.io.File; import javax.faces.event.ActionEvent; // Mapped to managed bean "fileList" in faces-config.xml // This managed bean is session scoped. // public class FileList { public static final String WINDOWS_OS = "WINDOW"; private File lookin = null; // Creates a new instance of FileList public FileList() { String osName = System.getProperty("os.name").toUpperCase(); if (osName.startsWith(WINDOWS_OS)) { lookin = new File("c:\\\\windows"); } else { lookin = new File("/usr"); } } public File getLookin() { return lookin; { private File selected; public File getSelected() { return fileSelected; } public void setSelected(File selected) { this.selected = selected; } public void chooseFile(ActionEvent event) { // do something useful with the selected files // when the "Choose File" button is clicked. } }
Tag Information | |
Tag Class | com.sun.webui.jsf.component.FileChooserTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.lang.String | A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children. |
lookin | false | false | java.lang.String | Use this attribute to specify the initial folder to display in the
Look In text field and display the contents of the lookin folder.
Only |
rows | false | false | java.lang.String | The number of items to display in the listbox. The value must be greater than or equal to one. The default value is 12. Invalid values are ignored and the value is set to 12. |
multiple | false | false | java.lang.String | Set this attribute to true to allow multiple files or folders to be selected from the list. The default for this attribute is false, which allows only one item to be selected. |
disabled | false | false | java.lang.String | Indicates that activation of this component by the user is not currently permitted. |
descending | false | false | java.lang.String | Set this attribute to true to sort from the highest value to lowest value, such as Z-A for alphabetic, or largest file to smallest for sorting on file size. The default of this attribute to sort in ascending order. |
styleClass | false | false | java.lang.String | CSS style class or classes to be applied to the outermost HTML element when this component is rendered. |
selected | false | false | java.lang.String | This attribute represents the value of the fileChooser. Depending on
the value of the If the
If the
If a type other than these is contained in a list type or bound
directly to the |
folderChooser | false | false | java.lang.String | Use this attribute to configure the file chooser as a folder chooser. Set the value to true for a folder chooser or false for a file chooser. The default value is false. |
visible | false | false | java.lang.String | Use this attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If this attribute is set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, this attribute is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present. |
style | false | false | java.lang.String | CSS style properties to be applied to the outermost HTML element when this component is rendered. |
readOnly | false | false | java.lang.String | If this attribute is set to true, the value of the component is rendered as text, preceded by the label if one was defined. |
sortField | false | false | java.lang.String | Field used to sort the list of files. Valid values are:
Note that these values are case sensitive. By default, the list is sorted alphabetically. |
tabIndex | false | false | java.lang.String | Describes the position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767. |
converter | false | false | java.lang.String | Specifies a method to translate native
property values to String and back for this component. The converter
attribute value must be one of the following:
|
immediate | false | false | java.lang.String | Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase. |
validatorExpression | false | false | java.lang.String | Used to specify a method in a backing bean to validate input
to the component. The value must be a JavaServer Faces
EL expression that resolves to a public method with
return type void. The method must take three parameters:
The backing bean where the method is defined must implement
The method is invoked during the Process Validations Phase. |
rendered | false | false | java.lang.String | Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission. |
valueChangeListenerExpression | false | false | java.lang.String | Specifies a method to handle a value-change event that is triggered
when the user enters data in the input component. The
attribute value must be a JavaServer Faces EL expression that
resolves to a backing bean method. The method must take a single
parameter of type javax.faces.event.ValueChangeEvent ,
and its return type must be void. The backing bean where the
method is defined must implement java.io.Serializable
or javax.faces.component.StateHolder .
|
id | false | true | java.lang.String | No Description |
Variables | No Variables Defined. |
| |||||||
FRAMES NO FRAMES |