File Chooser Builder

 

In this topic ... Quick Tips Specifying Inputs An Example of Using the File Chooser Builder Related Topics ... Overview: Creating Forms

Use the File Chooser Builder when you want to give a user the ability to select a file on the server, for example, to open it. The File Chooser Builder displays a list of files and/or directories from which the user can select. The Builder generates a list of files and/or directories based on a starting directory and a filter that the user provides. The list is displayed in the Tree Builder, and the list is cached so that it does not need to be generated every time.

 

Quick Tips

• The file path selected is returned as a form input. When the user selects a file in the File Chooser, the name of the file is stored in a hidden form input whose value is available after form submission like any other input control. This input has the same name as the span name assigned to the File Chooser Builder. For example,

${Inputs/chooser}

where chooser is the name of the <span /> tag assigned to the File Chooser Builder

• Make sure the directories available to users are not confidential. Before you deploy the File Chooser Builder, make sure you have traversed the file tree to make sure there is nothing confidential hidden in subfolders.

• The HTML Event Action can intercept selection changes. To automatically submit the form and run an action as the File Chooser s selection is changed by the user, we can target an HTML Event Action builder at the File Chooser. Select "onChange" as the event, and "Submit form and invoke action" to run a model action on each change.

 

Specifying Inputs

The File Chooser Builder takes the inputs described in the table below. For help on inputs common to many or all Builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."

 

Input name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list.
Page Location	Use the Page Location Chooser to specify the page or pages on which this Builder call will act. Alternatively, we can type in the page location syntax directly. See "Locating Control Builders on Pages" for detailed documentation about the Page Location Chooser and page location syntax.
Starting Directory	This directory defaults to WEB-INF/models. Specify a fully qualified server path. If the path is relative, the path to the Factory's servable content root directory gets prepended to the value. The Factory's servable content root is the directory on the application server to which you installed the Factory. Use a "/" to signify the Factory's servable content root directory in any values you specify for this input. For example, to specify the Factory's servable root directory as the File Chooser's starting directory, enter "/' as the Starting Directory input value.
Filter Class	Defaults to com.bowstreet.webapp.methods.FileChooserMethods$FilterModel. This class enables files ending with ".model" and directories to be displayed. The class com.bowstreet.webapp.methods.FileChooserMethods$FilterDirectories enables only directories to be displayed. We can provide additional filter classes to filter any file type.
Selected Value	The name of the file or directory that should be initially selected. The selected value is now relative to the starting directory, and the builder only displays files under the starting directory. For example, factory/core/database_services.model where WEB-INF/models is specified as the starting directory You can type a value or an indirect reference to a value... ${Variables/selectedValue}
Depth	Defaults to 99. The maximum number of directory levels deep to be displayed. We can type a value or an indirect reference to a value... ${Variables/depthValue}
Refresh Interval (seconds)	Defaults to 3600 seconds. It is the amount of time that should elapse before recalculating the directory list.
Visible Root Node	Select this option if you want the root node to be shown. For example, assume you have WEB-INF/models as the starting directory. If you select this option, the models directory would appear in the tree.
Selection Rule	Choose one of the following options for selection rules: All nodes can be selected -- Enables a user to select any item in the tree. Only leaf nodes can be selected -- Disables the ability to select directories. You might want to select this option if the Web page requires that a file be selected and not a directory. No Selection - Tree does not return a value -- Disables the ability to select any items in the tree. Such a tree is often used for display purpose to indicated hierarchical relationships among items.
Node Indent (pixels)	Defaults to 40 pixels. It determines how many pixels the node is indented. On Netscape Navigator only the first level is indented using this setting. We can type a value or an indirect reference to a value... ${Variables/nodeindentValue}
Closed Node Icon	Defaults to factory/images/tree/closenode.gif. The image that appears when the node is not expanded. We can type a path to the image file or an indirect reference to the path... ${Variables/closednodeIcon}
Open Node Icon	Defaults to factory/images/tree/opennode.gif. The image that appears when the node is expanded. We can type a path to the image file or an indirect reference to the path... ${Variables/opennodeIcon}
Leaf Node Icon	Defaults to factory/images/tree/nodeleaf.gif. The image that appears next to file names in the directory. We can type a path to the image file or an indirect reference to the path... ${Variables/leafnodeIcon}
Selected Icon	Defaults to factory/images/tree/rightarrow.gif. The image that appears when the icon is selected. We can type a path to the image file or an indirect reference to the path... ${Variables/selectedIcon}
Tree Width (pixels)	Defaults to 400 pixels. It determines the width of the tree. We can type a value or an indirect reference to a value... ${Variables/treewidthValue}
Tree Height (pixels)	Defaults to 400 pixels. It determines the height of the tree. We can type a value or an indirect reference to a value... ${Variables/treeheightValue}

 

An Example of Using the File Chooser Builder

This example lets the user select a file by using the file chooser. Once the file has been selected, the user clicks the Result button. The user is then shown the relative path of the selected file.

1. Create a model. If you did not select Main_and_Page, do the following:

1. Add a Page Builder call to the model, and call it page1. This page is the first page of the model. Don't worry about adding content right now.

2. Add an Action List Builder call to the model. Type main for the name input.

3. Make page 1 the first action in the Actions list. This action loads the page.

2. In page1, create two span tags. One is for the file chooser and the other is for the Results button, as shown in the example below:

<html><body><form>

<b>An Example of Using the File Chooser Builder</b>

<p>Select a file in the file chooser. Then, click the Results button.

The relative path to the file is displayed.</p>

<hr>

<span name="chooser" />

<br><br>

<span name="resultsbutton" />

</form></body></html>

where

1. chooser is the span name assigned to the File Chooser Builder

2. results is the span name assigned to the Button Builder

3. Add another Page Builder call to the model. Call this Builder call "results". This Builder is used to display the results page.

4. In the "results" page, add two span tags: one for displaying the results in a text area and another for the Back button, as shown in the example below:

<html><body><form>

<b>An Example of Using the File Chooser Builder (Page 2)</b>

<p>The following is the relative path of the file you selected.</p>

<hr>

<span name="chooser_results" />

<br><br>

<span name="backbutton" />

</form></body></html>

where

• chooser is the span name assigned to the Text Area Builder, which displays the results

• backbutton is the span name assigned to the Button Builder

5. Add a Variable Builder call to the model, and do the following:

1. Name the Builder selectedValue.

2. Assign the Builder type String.

3. In the Initial Value field, enter the following path:

factory/samples

This variable is used to hold the value of the selected path for the file chooser.

4. Click OK.

6. Add a File Choose Builder call to the model, and add the following information:

1. For the page location, select page1 from the Page drop-down menu and the first span name listed in the Tag menu, for example, chooser. The file chooser appears in the location of the span tag.

2. In the Starting Directory, leave the default as WEB-INF/models.

3. From the Filter Class drop-down menu, select com.bowstreet.builders.webapp.methods.FileChooserMethods$FilterDirectories. See the table above for more information about this class.

4. In the Selected Value field, enter an indirect reference to the Builder call name of the Variable Builder you added to the model in Step 5...

${Variables/selectedValue}

where selectedValue is the Builder call name of the Variable Builder added in Step 5

5. Select the option Visible Root Node.

6. From the Selection Rule drop-down menu, select All nodes can be selected.

7. Click OK.

7. Add a Button Builder call to the model. This button is the Results button. Do the following:

1. From the Page drop-down menu, select page1.

2. From the Tag drop-down menu, select the span tag you created for the Results button, for example resultsbutton.

3. In the Label field, enter Results.

4. In the Action Type field, select the following option: Submit form and invoke action

5. In the Action field, type the name of the second page.

When the Results button is clicked, the user sees the page specified in the Action field.

6. Click OK.

8. Add another Button Builder call to the model. This button is the Back button on the second page. Do the following:

1. From the Page drop-down menu, select the second page, for example, results.

2. From the Tag drop-down menu, select the span tag you created for the Back button, for example backbutton.

3. In the Label field, enter Back.

4. In the Action Type field, select the following option: Submit form and invoke action

5. In the Action field, type the name of the first page, for example, page1.

When the Back button is clicked, the user sees the page specified in the Action field.

6. Click OK.

9. Add a Text Area Builder call to the model. The results appear in this text area. Do the following:

1. From the Page drop-down menu, select the second page, for example, results.

2. From the Tag drop-down menu, select the span tag you created to display the results in a text area, for example chooser_results.

3. In the Default Text field, enter an indirect reference to the variable created at run-time. For example:

${Inputs/chooser}

where chooser is the span name assigned to the File Chooser Builder.

If you are picking this indirection from the reference chooser, expand the Inputs node and then expand the page1 node to select ${inputs/chooser}.

4. Click OK.

10. Run the model.

11. Make a selection in the file chooser, then click the Results button.

The Results page displays the path of the item you selected.