| |||||||
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.
This tag can also be used to navigate and select resources other
than files. One has to implement the
com.sun.webui.jsf.model.ResourceModel
for that purpose. A default implementation of this interface for
File ojects in the local filesystem has been provided. The implementation
class is com.sun.webui.jsf.model.FileChooserModel
.
The ResourceModel supplies an array of
com.sun.webui.jsf.model.ResourecItem
objects that are
consumed by the filechooser for displaying the list of selectable files.
If the component is being used for resources other than files an
implementation of this interface should also be supplied.
In order to make the component behave as a folderchooser, where only
folders can be selected, invoke the setFolderChooser(true)
method on the model instance in your backing bean.
-->
The rendered fileChooser component is an XHTML <table> element that contains several text fields, a drop-down, a listbox, and buttons. 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.
Use the model
attribute to associate the model
with the component. By default the FileChooser model described
above will be used.
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 file chooser by selecting a sort option
from the "Sort By" dropdown menu. By default, the list is sorted
alphabetically. To specify which sort is used when the
component is initially rendered, use the sortField
attribute.
Valid sortField
attribute values are:
By default, the initial sort order is ascending: A-Z, or smallest file size
first, or oldest file first. Set the descending
attribute to true
to specify a descending sort order.
The input to the fileChooser component is the model object. The
output of this component is the list of selected files or folders.
This is the value of the component. The backing bean associated with
selected
attribute will be set with the value of the
component after each submit.
-->
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 managed bean associated with
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
content for some areas 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 |
Specify a custom label to replace the File Chooser component label. By default the label is a localized value meaning "Browse Server" in English. |
serverLabel |
Specify a custom component to replace the Server Name label. |
serverNameText |
Specify a custom component to replace the Server Name static text. |
lookinField |
Specify a custom
component for the Look In text field. The id attribute of the facet
component should be set to
the You should use the function |
lookinLabel |
Specify a custom
label for the
Look In field of the component.
|
filterField |
Specify 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 You should use the function |
filterLabel |
Specify a custom label for the File Filter or Folder Filter text field of the component. |
enterPressHelp |
Specify 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 |
Specify 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 You should use the function |
selectedLabel |
Specify
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 |
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 If you want to use the
JavaScript function associated with the default button's onClick event
use the |
sortMenu |
Specifies a custom
component to replace the Sort By drop-down menu of the
component. |
When the component is rendered, a DOM object corresponding to the
component is created. To manipulate the component on the client side,
you may invoke functions on the DOM object. With reference to the DOM
id, to obtain a list of selected option elements, invoke
document.getElementById(id).getSelectedOptions()
.
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 file chooser 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="_fc1" model="#{fileList.model}"
selected="#{fileList.fileSelected}"
sortField="size" descending="false"
multiple="false">
<f:facet name="selectedField">
<webuijsf:textField id="_fc1_selectedField"/>
</f:facet>
</webuijsf:fileChooser >
<webuijsf:fileChooser server="#{fileList.server}"
model="#{fileList.model}"
selected="#{fileList.files}"
sortfield="alphabetic"
descending="true"
toolTip="#{fileList.tooltip}" />
-->
<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}"/> </webuijsf:markup> <script type="text/javascript"> document.getElementById(form1:filechooser).setChooseButton('form1:fileChooseButton'); </script>
The example uses the following backing bean.
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. The contents of this folder will be displayed.
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 multiple to true to allow multiple files or folders to be selected from the list. The default 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 is to sort in ascending order. |
styleClass | false | false | java.lang.String | CSS style class(es) 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 the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible 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(s) to be applied to the outermost HTML element when this component is rendered. |
readOnly | false | false | java.lang.String | If readOnly 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 to use 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 | 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 |