webuijsf
Tag fileChooser


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.

HTML Elements and Layout

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.

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 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.

Form Submit Behavior

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:

Facets

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 webuijsf:fileChooser tag's id attribute with _lookinField appended to the id. For example, if the webuijsf: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 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 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 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 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

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 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.

Client-side JavaScript Functions

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.

Examples

Example 1: Simple FileChooser

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}"/>
     </webuijsf:markup>
     <script type="text/javascript">
         document.getElementById(form1:filechooser).setChooseButton('form1:fileChooseButton');
     </script>
 

Backing Bean for fileList Managed Bean

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 Classcom.sun.webui.jsf.component.FileChooserTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.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.
lookinfalsefalsejava.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 java.io.File or java.lang.String objects can be bound to this attribute.

rowsfalsefalsejava.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.

multiplefalsefalsejava.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.

disabledfalsefalsejava.lang.String

Indicates that activation of this component by the user is not currently permitted.

descendingfalsefalsejava.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.

styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

selectedfalsefalsejava.lang.String

This attribute represents the value of the fileChooser. Depending on the value of the folderChooser attribute, the value of the selected attribute can consist of selected files or folders from the listbox and/or paths to files or folders entered into the Selected File field.

If the multiple attribute is true, the selected attribute must be bound to one of the following:

  • java.io.File[]
  • java.lang.String[]
  • a java.util.List[] such as java.util.ArrayList, or java.util.LinkedList, or java.util.Vector containing instances of java.io.File or java.lang.String.

If the multiple attribute is false, the selected attribute must be bound to one of the following:

  • java.io.File
  • java.lang.String

If a type other than these is contained in a list type or bound directly to the selected attribute, then you must specify a converter with the converter attribute.

folderChooserfalsefalsejava.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.

visiblefalsefalsejava.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.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

readOnlyfalsefalsejava.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.

sortFieldfalsefalsejava.lang.String

Field to use to sort the list of files. Valid values are:

  • alphabetic - sort alphabetically
  • size - sort by file size
  • time - sort by last modified date

Note that these values are case sensitive. By default, the list is sorted alphabetically.

tabIndexfalsefalsejava.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.

converterfalsefalsejava.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:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
immediatefalsefalsejava.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.
validatorExpressionfalsefalsejava.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:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

renderedfalsefalsejava.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.
valueChangeListenerExpressionfalsefalsejava.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.
idfalsetruejava.lang.StringNo Description

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.