Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1.6.0)

Part Number B31973-11
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Using Input Components and Defining Forms

This chapter describes the input components that are used to enter data, select values, edit text, and load files.

This chapter includes the following sections:

9.1 Introduction to Input Components and Forms

Input components accept user input in a variety of formats. The most common formats are text, numbers, date, and selection lists that appear inside a form and are submitted when the form is submitted. The entered values or selections may be validated and converted before they are processed further. For example, the File Explorer application contains a form that allows users to create a new file. Using input components, users enter the name, the size, select permissions, and add keywords, and a description, as shown in Figure 9-1.

Figure 9-1 Form Uses Input Components

Input form uses input components

In addition to standard input components used to input text, number, date, or color, ADF Faces includes input type components that provide additional functionality. The inputFile component allows users to browse for a file to load.

The richTextEditor component provides rich text input that can span many lines and can be formatted using different fonts, sizes, justification, and other editing features. The richTextEditor component can also be used with command components to insert given text into the component. The inserted text can be preformatted. Additionally, you can customize the buttons that appear in the editor's toolbar.

The selection components allow the user to make selections from a list of items instead of or in addition to typing in values. For example, the selectOneChoice component lets the user select input from a dropdown list and the selectOneRadio component lets a user pick from a group of radio buttons.

You can use either selection or list-of-values (LOV) components to display a list. LOV components should be used when the selection list is large. LOV components are model-driven using the ListOfValueModel class and may be configured programmatically using the API. They present their selection list inside a popup window that may also include a query panel. Selection lists simply display a static list of values. For more information about using LOV components, see Chapter 11, "Using List-of-Values Components."

The selectItem component is used within other selection components to represent the individual selectable items for that component. For example, a selectOneRadio component will have a selectItem component for each of its radio buttons. If the radio button selections are coffee, tea, and milk, there would be a selectItem component for coffee, one for tea, and one for milk.

The form components provide a container for other components. The form component represents a region where values from embedded input components can be submitted. Form components cannot be nested. However, the subform component provides additional flexibility by defining subregions whose component values can be submitted separately within a form. The resetButton component provides an easy way for the user to reset input values within a form or subform to their previous state.

All the input and selection components deliver the ValueChangeEvent and AttributeChangeEvent events. You can create valueChangeListener and attributeChangeListener methods to provide functionality in response to the corresponding events.

All input components, selection components (except selectItem), and the rich text editor component have a changed attribute that when set to true enables a change indicator icon to be displayed upon changes in the value field. This indicator allows the user to easily see which input value has changed, which can be helpful when there are multiple components on the page. By default, the change indicator usually is displayed to the left of the component. If the value in a field automatically changes due to a change in another field's value, such as an automatically generated postal code when the city is entered, the postal code field will also display a change indicator. Figure 9-2 shows changed indicators present for the checkbox and input components.

Figure 9-2 Changed indicators for two components

Indicators when value changes

Tip:

You can change the icon or the position of the icon using skins. For more information, see Chapter 20, "Customizing the Appearance Using Styles and Skins."

Most input components also have the capability of displaying only the label, and not appearing capable of changing value until the user mouses over or hovers over the component. Once the user changes the value, that new value displays as read-only. Figure 9-3 shows a selectManyChoice component configured to be editable only on access.

Figure 9-3 Input Components Can Appear Not Editable

input components can appear not editable

Input components can also display tooltips, error and validation messages, and context-sensitive help. For more information, see Chapter 17, "Displaying Tips, Messages, and Help."

All input components have JavaScript client APIs that you can use to set or get property values. For more information, see the ADF Faces JavaScript API documentation.

9.2 Defining Forms

A form is a component that serves as a container for other components. When a submit action occurs within the form, any modified input values are submitted. For example, you can create an input form that consists of input and selection components, and a submit command button, all enclosed within a form. When the user enters values into the various input fields and clicks the Submit button, those new input values will be sent for processing.

By default, when you create a JSF page in JDeveloper, it automatically inserts a form component into the page. When you add components to the page, they will be inserted inside the form component.

Tip:

If you do not already have an af:form tag on the page, and you drag and drop an ADF Faces component onto the page, JDeveloper will prompt you to enclose the component within a form component.

Example 9-1 shows two input components and a Submit button that when clicked will submit both input values for processing.

Example 9-1 ADF Faces Form as a Container for Input Components

<af:form>
  <af:panelFormLayout>
    <af:inputText value="#{myBean.firstName}"
                  label="#{First Name}"
    </af:inputText>
    <af:inputText value="#{myBean.lastName}"
                  label="#{Last Name}"
    </af:inputText>
    <f:facet name="footer">
      <af:commandButton text="Submit"/>
    </f:facet>
   </af:panelFormLayout>
</af:form>

Because there can be only one form component on a page, you can use subforms within a form to create separate regions whose input values can be submitted. Within a region, the values in the subform will be validated and processed only if a component inside the subform caused the values to be submitted. You can also nest a subform within another subform to create nested regions whose values can be submitted. For more information about subforms, see Section 4.5, "Using Subforms to Create Regions on a Page."

Example 9-2 shows a form with two subforms, each containing its own input components and Submit button. When a Submit button is clicked, only the input values within that subform will be submitted for processing.

Example 9-2 ADF Faces Subform Within a Form

<af:form>
  <af:subform>
    <af:panelFormLayout>
      <af:inputText value="#{myBean.firstName}"
      </af:inputText>
      <af:inputText value="#{myBean.lastName}"
      </af:inputText>
      <f:facet name="footer">
        <af:commandButton text="Submit"/>
      </f:facet>
    </af:panelFormLayout>
  </af:subform>
  <af:subform>
    <af:panelFormLayout>
      <af:inputText value="#{myBean.primaryPhone}"
      </af:inputText>
      <af:inputText value="#{myBean.cellPhone}"
      </af:inputText>
      <f:facet name="footer">
        <af:commandButton text="Submit"/>
      </f:facet>
    </af:panelFormLayout>
  </af:subform>
</af:form>

Aside from the basic Submit button, you can add any other command component within a form and have it operate on any field within the form. ADF Faces provides a specialized command component: the resetButton component, which when clicked, resets all the input and selection components within a form. That is, it updates all components whose values can be edited with the current values of the model. The resetButton component is different from HTML reset in that the resetButton component will reset the input components to their previous state which was partially or fully submitted successfully to the server without any validation or conversion error. For example, if a user enters value A and clicks the Submit button, and then changes the value from A to B and clicks the resetButton component, the value A will be restored.

9.2.1 How to Add a Form to a Page

In most cases, JDeveloper will add the form component for you. However, there may be cases where you must manually add a form, or configure the form with certain attribute values.

To add a form to a page:

  1. In the Component Palette, from the Common Components panel, drag and drop a Form onto the page.

  2. In the Property Inspector expand the Common section, where you can optionally set the following:

    • DefaultCommand: Specify the ID attribute of the command component whose action should be invoked when the Enter key is pressed and the focus is inside the form.

    • UsesUpload: Specify whether or not the form supports uploading files. For more information about uploading files, see Section 9.9, "Using File Upload."

    • TargetFrame: Specify where the new page should be displayed. Acceptable values are any of the valid values for the target attribute in HTML. The default is _self.

9.2.2 How to Add a Subform to a Page

You should add subform components within a form component when you need a section of the page to be capable of independently submitting values.

To add subforms to a page:

  1. In the Component Palette, from the Common Components panel, drag and drop a Subform onto the page as a child to a form component.

  2. Use the Property Inspector to set the following:

    • Default: Specify whether or not the subform should assume it has submitted its values. When set to the default value of false, this subform component will consider itself to be submitted only if no other subform component has been submitted. When set to true, this subform component assumes it has submitted its values.

      Tip:

      A subform is considered submitted if an event is queued by one of its children or facets for a phase later than Apply Request Values (that is, for later than decode()). For more information about lifecycle phases, see Chapter 4, "Using the JSF Lifecycle with ADF Faces."

    • Default Command: Specify the ID attribute of the command component whose action should be invoked when the Enter key is pressed and the focus is inside the subform.

9.2.3 How to Add a Reset Button to a Form

You can add the resetButton component inside a form or a subform. The reset button will act upon only those components within that form or subform.

To add a reset button to a page:

  1. In the Component Palette, from the Common Components panel, drag and drop a Reset Button onto the page.

  2. Use the Property Inspector to set the following:

    • Text: Specify the textual label of the button.

    • Disabled: Specify whether or not the button should be disabled. For example, you could enter an EL expression that determines certain conditions under which the button should be disabled.

9.3 Using the inputText Component

Although input components include many variations, such as pickers, sliders, and a spinbox, the inputText component is the basic input component for entering values. You can define an inputText component as a single-row input field or as a text area by setting the rows attribute to more than 1. However, if you want to create a multiple row text input, consider using the richTextEditor component as described in Section 9.8, "Using the richTextEditor Component."

You can hide the input values from being displayed, such as for passwords, by setting the secret attribute to true. Like other ADF Faces components, the inputText component supports label, text, and messages. When you want this component to be displayed without a label, you set the simple attribute to true. Figure 9-4 shows a single-row inputText component.

Figure 9-4 Single-Row inputText Component

inputText component

You can make the inputText component display more than one row of text using the rows attribute. If you set the rows attribute to be greater than one, and you set the simple attribute to true, then the inputText component can be configured to stretch to fit its container using the dimensionsFrom attribute. For more information about how components stretch, see Chapter 8, "Geometry Management and Component Stretching." Figure 9-6 shows a multi-row inputText component.

You can add multiple inputText components to create an input form. Figure 9-5 shows an input form using three inputText components and a Submit command button.

Figure 9-5 Form Created by inputText Components

Three inputText components create a form

You can also configure an insertTextBehavior tag that works with command components to insert given text into an inputText component. The text to be entered can be a simple string, or it can be the value of another component, for example the selected list item in a selectOneChoice component. For example, Figure 9-6 shows an inputText component with some text already entered by a user.

Figure 9-6 inputText Component with Entered Text

inputText with entered text

The user can then select additional text from a dropdown list, click the command button, and that text appears in the inputText component as shown in Figure 9-7.

Figure 9-7 inputText Component with Inserted Text

inputText component with inserted text

9.3.1 How to Add an inputText Component

You can use an inputText component inside any of the layout components described in Chapter 8, "Organizing Content on Web Pages."

To add an inputText component:

  1. In the Component Palette, from the Common Components panel, drag and drop an Input Text onto the page.

  2. In the Property Inspector, expand the Common section and set the following:

    • Label: Enter a value to specify the text to be used as the label.

      If the text to be used is stored in a resource bundle, use the dropdown list to select Select Text Resource. Use the Select Text Resource dialog either to search for appropriate text in an existing bundle, or to create a new entry in an existing bundle. For more information about using resource bundles, see Chapter 21, "Internationalizing and Localizing Pages."

    • Value: Specify the value of the component. If the EL binding for a value points to a bean property with a get method but no set method, and this is a component whose value can be edited, then the component will be rendered in read-only mode.

  3. Expand the Appearance section, and set the following:

    • Columns: Specify the size of the text control by entering the maximum number of characters that can be entered into the field.

    • Rows: Specify the height of the text control by entering the number of rows to be shown. The default value is 1, which generates a one-row input field. The number of rows is estimated based on the default font size of the browser. If set to more than 1, you must also set the wrap attribute.

    • Secret: Specify this boolean value that applies only to single-line text controls. When set to true, the secret attribute hides the actual value of the text from the user.

    • Wrap: Specify the type of text wrapping to be used in a multiple-row text control. This attribute is ignored for a single-row component. By default, the attribute is set to soft, which means multiple-row text wraps visually, but does not include carriage returns in the submitted value. Setting this attribute to off will disable wrapping: the multiple-row text will scroll horizontally. Setting it to hard specifies that the value of the text should include any carriage returns needed to wrap the lines.

    • ShowRequired: Specify whether or not to show a visual indication that the field is required. Note that setting the required attribute to true will also show the visual indication. You may want to use the showRequired attribute when a field is required only if another field's value is changed.

    • Changed: Specify whether or not to show a blue circle whenever the value of the field has changed. If you set this to true, you may also want to set the changedDesc attribute.

    • ChangedDesc: Specify the text to be displayed in a tooltip on a mouseover of the changed icon. By default, the text is "Changed." You can override this by providing a different value.

    • AccessKey: Specify the key to press that will access the field.

    • LabelAndAccessKey: Instead of specifying a separate label and access key, you can combine the two, so that the access key is part of the label. Simply precede the letter to be used as an access key with an ampersand (&).

      For example, if the label of a field is Description and you want the D to be the access key, you would enter &Description.

      Note:

      Because the value is being stored in the source of the page in XML, the ampersand (&) character must be escaped, so the value will actually be represented in the source of the page using the characters &amp; to represent the ampersand.

    • Simple: Set to true if you do not want the label to be displayed.

  4. Expand the Behavior section and set the following:

    • Required: Specify whether or not a value is required. If set to true, a visual indication is displayed to let the user know a value must be entered. If a value is not entered, an exception will occur and the component will fail validation.

    • ReadOnly: Specify whether the control is displayed as a field whose value can be edited, or as an output-style text control.

    • AutoSubmit: Specify whether or not the component will automatically submit when the value changes. For more information about using the autoSubmit attribute, see Section 4.3, "Using the Optimized Lifecycle."

    • AutoTab: Specify whether or not focus will automatically move to the next tab stop when the maximum length for the current component is reached.

    • MaximumLength: Specify the maximum number of characters per line that can be entered into the text control. This includes the characters representing the new line. If set to 0 or less, the maximumLength attribute is ignored. Note that in some browsers such as Internet Explorer, a new line is treated as two characters.

    • Converter: Specify a converter object. For more information, see Section 6.3, "Adding Conversion."

    • Validator: Specify a method reference to a validator method using an EL expression. For more information, see Section 6.5, "Adding Validation."

  5. Expand the Other section and set the following:

    • DimensionsFrom: Determine how you want the inputText component to handle geometry management. Set this attribute to one of the following:

      • auto: If the parent component to the inputText component allows stretching of its child, then the inputText component will stretch to fill the parent component, as long as the rows attribute is set to a number greater than one and the simple attribute is set to true. If the parent component does not allow stretching, then the inputText component gets its dimensions from the content.

      • content: The inputText component gets its dimensions from the component content. This is the default.

      • parent: The inputText component gets its dimensions from the inlineStyle attribute. If no value exists for inlineStyle, then the size is determined by the parent container.

    • Editable: Determine whether you want the component to always appear editable. If so, select always. If you want the value to appear as read-only until the user hovers over it, select onAccess. If you want the value to be inherited from an ancestor component, select inherit.

      Note:

      If you select inherit, and no ancestor components define the editable value, then the value always is used.

9.3.2 How to Add the Ability to Insert Text into an inputText Component

The insertTextBehavior tag works with command components to insert given text into an inputText component. The text to be entered can be a simple string, or it can be the value of another component, for example the selected list item in a selectOneChoice component. To allow text to be inserted into an inputText component, add the insertTextBehavior tag as a child to a command component that will be used to insert the text.

Note:

The insertTextBehavior tag cancels server-side event delivery automatically; actionListener or action attributes on the parent command component will be ignored. If you need to also trigger server-side functionality, you must add an custom client listener to deliver the server-side event. For more information, see Section 5.4, "Sending Custom Events from the Client to the Server."

Before You Begin

Before you add an insertTextBehavior tag, you need to create an inputText component as described in Section 9.3.1, "How to Add an inputText Component." Set the clientComponent attribute to true.

To add text insert behavior:

  1. Add a command component that the user will click to insert the text. For procedures, see Section 18.2.1, "How to Use Command Buttons and Command Links."

  2. In the Component Palette, from the Operations panel, drag and drop an Insert Text Behavior as a child to the command component.

  3. In the Insert Text Behavior dialog, enter the following:

    • For: Use the dropdown arrow to select Edit and then navigate to select the inputText component into which the text will be inserted.

    • Value: Enter the value for the text to be inserted. If you want to insert static text, then enter that text. If you want the user to be able to insert the value of another component (for example, the value of a selectOneChoice component), then enter an EL expression that resolves to that value. Example 9-3 shows page code for an inputText component into which either the value of a dropdown list or the value of static text can be inserted.

      Example 9-3 Using the insertTextBehavior Tag

      <af:inputText clientComponent="true" id="idInputText" label="String value"
                    value="#{demoInput.value}" rows="10" columns="60"/>
      <af:selectOneChoice id="targetChoice" autoSubmit="true"
                          value="#{demoInput.choiceInsertText}" 
                          label="Select text to insert">
        <af:selectItem label="Some Text." value="Some Text."/>
        <af:selectItem label="0123456789" value="0123456789"/>
        <af:selectItem label="~!@#$%^*" value="~!@#$%^*"/>
        <af:selectItem label="Two Lines" value="\\nLine 1\\nLine 2"/>
      </af:selectOneChoice>
      <af:commandButton text="Insert Selected Text" id="firstButton"
                        partialTriggers="targetChoice">
        <af:insertTextBehavior for="idInputText" 
                               value="#{demoInput.choiceInsertText}"/>
      </af:commandButton>
      <af:commandButton text="Insert Static Text">
        <af:insertTextBehavior for="idInputText"
                               value="Some Static Text."/>
      </commandButton>
      
  4. By default, the text will be inserted when the action event is triggered by clicking the command component. However, you can change this to another client event by choosing that event from the dropdown menu for the triggerType attribute of the insertTextBehavior component in the Property Inspector.

9.4 Using the Input Number Components

The slider components present the user with a slider with one or two markers whose position on the slider corresponds to a value. The slider values are displayed and include a minus icon at one end and a plus icon at the other. The user selects the marker and moves it along the slider to select a value. The inputNumberSlider component has one marker and allows the user to select one value from the slider, as shown in Figure 9-8 in horizontal layout, and in Figure 9-9 in vertical layout.

Figure 9-8 inputNumberSlider in Horizontal Layout

Horizontal inputSlider

Figure 9-9 InputNumberSlider in Vertical Layout

Vertical inputNumberSlider

The inputRangeSlider component has two markers and allows the user to pick the end points of a range, as shown in Figure 9-10.

Figure 9-10 inputRangeSlider in horizontal layout

Horizontal inputRangeSlider

The inputNumberSpinbox is an input component that presents the user with an input field for numerical values and a set of up- and down-arrow keys to increment or decrement the current value in the input field, as shown in Figure 9-11.

Figure 9-11 inputNumberSpinbox

Scroll through list of numbers with spinbox

9.4.1 How to Add an inputNumberSlider or an inputRangeSlider Component

When you add an inputNumberSlider or an inputRangeSlider component, you can determine the range of numbers shown and the increment of the displayed numbers.

To add an inputNumberSlider or inputRangeSlider component:

  1. In the Component Palette, from the Common Components panel, drag and drop an Input Number Slider or Input Range Slider onto the page.

  2. In the Property Inspector, expand the Common section (and for the inputRangeSlider component, also expand the Data section) and set the following attributes:

    • Label: Specify a label for the component.

    • Minimum: Specify the minimum value that can be selected. This value is the begin value of the slider.

    • Maximum: Specify the maximum value that can be selected. This value is the end value of the slider.

    • MinimumIncrement: Specify the smallest possible increment. This is the increment that will be applied when the user clicks the plus or minus icon.

    • MajorIncrement: Specify the distance between two major marks. This value causes a labeled value to be displayed. For example, the majorIncrement value of the inputRangeSlider component in Figure 9-10 is 5.0. If set to less than 0, major increments will not be shown.

    • MinorIncrement: Specify the distance between two minor marks. If less than 0, minor increments will not be shown.

    • Value: Specify the value of the component. If the EL binding for value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

  3. Expand the Appearance section and set Orientation to specify whether the component will be in horizontal or vertical layout. For information about the other attributes in this section, see Section 9.3.1, "How to Add an inputText Component."

9.4.2 How to Add an inputNumberSpinbox Component

The inputNumberSpinbox component allows the user to scroll through a set of numbers to select a value.

To add an inputNumberSpinbox component:

  1. In the Component Palette, from the Common Components panel, drag and drop an Input Number Spinbox onto the page.

  2. Expand the Data section of the Property Inspector and set the following:

    • Value: Specify the value of the component. If the EL binding for value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

    • Minimum: Specify the minimum value allowed in the input field.

    • Maximum: Specify the maximum value allowed in the input field.

    • StepSize: Specify the increment by which the spinbox will increase or decrease the number in the input field.

  3. Expand the Appearance section and set the attributes. For more information about setting these attributes, see Section 9.3.1, "How to Add an inputText Component."

  4. If you want the value of the spinbox to appear as read-only until the user hovers over it, expand the Other section and set Editable to onAccess. If you want the component to always appear editable, select always. If you want the value to be inherited from an ancestor component, select inherit.

    Note:

    If you select inherit, and no ancestor components define the editable value, then the value always is used.

9.5 Using Color and Date Choosers

The inputColor component presents a text input field for entering code for colors and a button for picking colors from a palette. The default color code format is the hexadecimal color format. However, you can override the format using a ColorConverter class.

By default, the inputColor component opens the chooseColor component that allows users to pick the color from a a palette. Figure 9-12 shows the inputColor component with the chooseColor component in a popup dialog.

Figure 9-12 inputColor Component with Popup chooseColor Component

inputColor component with chooseColor picker

The inputDate component presents a text input field for entering dates and a button for picking dates from a popup calendar, as shown in Figure 9-13. The default date format is the short date format appropriate for the current locale. For example, the default format in American English (ENU) is mm/dd/yy. However, you can override the format using a date-time converter (for more information about using converters, see Section 6.3, "Adding Conversion").

Figure 9-13 inputDate Component

Input Date component

When you add a date-time converter and configure it to show both the date and the time, the date picker is displayed as a modal dialog with additional controls for the user to enter a time. Additionally, if the converter is configured to show a time zone, a timezone dropdown list is shown in the dialog, as shown in Figure 9-14.

Figure 9-14 Modal Dialog When Date-Time Converter Is Used

Modal dialog for date and time

9.5.1 How to Add an inputColor Component

The inputColor component allows users either to enter a value in an input text field, or to select a color from a color chooser.

To add an inputColor component:

  1. In the Component Palette, from the Common Components panel, drag and drop an Input Color onto the page.

  2. In Property Inspector, expand the Common section and set the following:

    • Label: Specify a label for the component.

    • Compact: Set to true if you do not want to display the input text field, as shown in Figure 9-15.

      Figure 9-15 inputColor Component in Compact Mode

      InputColor component in compact mode
  3. Expand the Data section and set the following attributes:

    • Value: Specify the value of the component. If the EL binding for value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

    • ColorData: Specify the list of colors to be displayed in the standard color palette. The number of provided colors can be 49 (7 colors x 7 colors), 64 (8 colors x 8 colors), or 121 (11 colors x 11 colors). The number set for this attribute will determine the valid value for the width attribute. For example, if you set the colorData attribute to 49, the width must be 7. If the number does not match the width, extra color elements in the list will be ignored and missing color elements will be displayed as no-color. The color list must be an array of type TrColor on the client side.

    • CustomColorData: Specify the list of custom-defined colors. The number of colors can be 7, 8, or 11. The color list must be an array of type TrColor on the client side. On the server side, it must be a List of java.awt.Color objects, or a list of hexadecimal color strings.

    • DefaultColor: Specify the default color using hexadecimal color code, for example #000000.

  4. Expand the Appearance section and set the following attributes:

    • Width: Specify the width of the standard palette in cells. The valid values are 7, 8, and 11, which correspond to the values of the colorData and customColorData attributes.

    • CustomVisible: Specify whether or not the Custom Color button and custom color row are to be displayed. When set to true, the Custom Color button and custom color row will be rendered.

    • DefaultVisible: Specify whether or not the Default button is to be displayed. When set to true, the Default button will be rendered. The Default button allows the user to easily select the color set as the value for the defaultColor attribute.

    • LastUsedVisible: Specify whether or not the Last Used button is to be displayed. When set to true the Last Used button will be rendered, which allows the user to select the color that was most recently used.

  5. Expand the Behavior section and set the following attribute:

    • ChooseId: Specify the id of the chooseColor component which can be used to choose the color value. If not set, the inputColor component has its own default popup dialog with a chooseColor component.

  6. If you want the value of the component to appear as read-only until the user hovers over it, expand the Other section and set Editable to onAccess. If you want the component to always appear editable, select always. If you want the value to be inherited from an ancestor component, select inherit.

    Note:

    If you select inherit, and no ancestor components define the editable value, then the value always is used.

9.5.2 How to Add an InputDate Component

The inputDate component allows the user to either enter or select a date.

To add an inputDate component:

  1. In the Component Palette, from the Common Components panel, drag and drop an Input Date onto the page.

  2. In the Property Inspector, in the Common section, set the following:

    • Label: Specify a label for the component.

    • Value: Specify the value of the component. If the EL binding for value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

  3. Expand the Data section and set the following attributes:

    • MinValue: Specify the minimum value allowed for the date value. When set to a fixed value on a tag, this value will be parsed as an ISO 8601 date. ISO 8601 dates are of the form "yyyy-MM-dd" (for example: 2002-02-15). All other uses require java.util.Date objects.

    • MaxValue: Specify the maximum value allowed for the date value. When set to a fixed value on a tag, this value will be parsed as an ISO 8601 date. ISO 8601 dates are of the form "yyyy-MM-dd" (for example: 2002-02-15). All other uses require java.util.Date objects.

    • DisableDays: Specify a binding to an implementation of the org.apache.myfaces.trinidad.model.DateListProvider interface. The getDateList method should generate a List of individual java.util.Date objects which will be rendered as disabled. The dates must be in the context of the given base calendar.

      Performance Tip:

      This binding requires periodic roundtrips. If you just want to disable certain weekdays (for example, Saturday and Sunday), use the disableDaysOfWeek attribute.

    • DisableDaysOfWeek: Specify a whitespace-delimited list of weekdays that should be rendered as disabled in every week. The list should consist of one or more of the following abbreviations: sun, mon, tue, wed, thu, fri, sat. By default, all days are enabled.

    • DisableMonths: Specify a whitespace-delimited list of months that should be rendered as disabled in every year. The list should consist of one or more of the following abbreviations: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec. By default, all months are enabled.

  4. Expand the Behavior section and set ChooseId. Specify the id of the chooseDate component which can be used to choose the date value. If not set, the inputDate component has its own default popup dialog with a chooseDate component.

  5. If you want the value of the component to appear as read-only until the user hovers over it, expand the Other section and set Editable to onAccess. If you want the component to always appear editable, select always. If you want the value to be inherited from an ancestor component, select inherit.

    Note:

    If you select inherit, and no ancestor components define the editable value, then the value always is used.

9.5.3 What You May Need to Know About Selecting Time Zones Without the inputDate Component

By default, the inputDate component displays a drop down list of time zones if the associated converter is configured to do so, for example, if you include the timezone placeholder z in the converter's pattern. The end user can only modify the timezone using this list. The list is configured to display the most common time zones.

However, there may be times when you need to display the list of time zones outside of the inputDate component. For example, on a Application Preferences page, you may want to use a selectOneChoice component that allows the user to select the time zone that will be used to display all inputDates in the application. A backing bean would handle the conversion between the time zone ID and the java.util.TimeZone object. Converters for the inputDate instances in the application would then bind the time zone to that time zone object.

You can access this list using either an API on the DateTimeUtils class, or using an EL expression on a component.

Following are the methods on DateTimeUtils class:

  • getCommonTimeZoneSelectItems (): Returns a list of commonly used time zones.

  • getCommonTimeZoneSelectItems (String timeZoneId): Returns a list of commonly used time zones, including the given time zone if it is not part of the list.

To access this list using EL, use one of the following expressions:

  • af:getCommonTimeZoneSelectItems

    For example:

    <f:selectItems value="#{af:getCommonTimeZoneSelectItems()}" id="tzones2" />
    
  • af:getMergedTimeZoneSelectItems (id)

    For example:

    <f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" />
    

If you will be using an inputDate component and a selection list for its time zone on the same page, you must clear out the local value for the inputDate's timezone to ensure that the value binding for the selection takes precedence. Otherwise, a non-null local value will take precedence, and the inputDate component will not appear to be updated.In Example 9-4, the backing bean has a reference using the binding attribute to the inputDate component. When the user picks a new time zone, the id is set and the code gets the converter for the inputDate and clears out its time zone. When the page is rendered, since the local value for the converter's time zone is null, it will evaluate #{demoInput.preferredTimeZone} and obtain the updated time zone.

Example 9-4 Using an inputDate and Time Zone Selection List Together

<af:selectOneChoice label="Select a new timezone"
                    value="#{demoInput.preferredTimeZoneId}" autoSubmit="true">
  <f:selectItems
         value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" 
         id="tzones" />
</af:selectOneChoice>
<af:inputDate  label="First inputDate with timezone bound" id="bound1"
               partialTriggers="tzpick"  binding="#{demoInput.boundDate1}">
  <af:convertDateTime type="both" timeStyle="full"
                      timeZone="#{demoInput.preferredTimeZone}"/>
</af:inputDate>
 
DemoInputBean.java
public void setPreferredTimeZoneId(String _preferredTimeZoneId)
{
  TimeZone tz = TimeZone.getTimeZone(_preferredTimeZoneId);
  setPreferredTimeZone (tz);
  this._preferredTimeZoneId = _preferredTimeZoneId;
}

public void setPreferredTimeZone(TimeZone _preferredTimeZone)
{
  this._preferredTimeZone = _preferredTimeZone;
     DateTimeConverter conv1 = (DateTimeConverter)
                              _boundDate1.getConverter();
  conv1.setTimeZone(null);
}

9.6 Using Selection Components

The selection components allow the user to select single and multiple values from a list or group of items. ADF Faces provides a number of different selection components, ranging from simple boolean radio buttons to list boxes that allow the user to select multiple items. The list of items within a selection component is made up of a number of selectItem components

All the selection components except the selectItem component delivers the ValueChangeEvent and AttributeChangeEvent events. The selectItem component only delivers the AttributeChangeEvent event. You must create a valueChangeListener handler or an attributeChangeListener handler, or both for them.

The selectBooleanCheckbox component value must always be set to a boolean and not an object. It toggles between selected and unselected states, as shown in Figure 9-16.

Figure 9-16 selectBooleanCheckbox Component

selectBooleanCheckbox component

The selectBooleanRadio component displays a boolean choice, and must always be set to a boolean. Unlike the selectBooleanCheckbox component, the selectBooleanRadio component allows you to group selectBooleanRadio components together using the same group attribute.

For example, say you have one boolean that determines whether or not a user is age 10 to 18 and another boolean that determines whether a user is age 19-100. As shown in Figure 9-17, the two selectBooleanRadio components can be placed anywhere on the page, they do not have to be next to each other. As long as they share the same group value, they will have mutually exclusive selection, regardless of their physical placement on the page.

Tip:

Each selectBooleanRadio component must be bound to a unique boolean.

Figure 9-17 selectBooleanRadio Component

selectBooleanRadio component

You use the selectOneRadio component to create a list of radio buttons from which the user can select a single value, as shown in Figure 9-18.

Figure 9-18 selectOneRadio Component

selectOneRadio component

You use the selectManyCheckbox component to create a list of checkboxes from which the user can select one or more values, as shown in Figure 9-19.

Figure 9-19 selectManyCheckbox Component

selectManyCheckbox component

The selectOneListbox component creates a component which allows the user to select a single value from a list of items displayed in a shaded box, as shown in Figure 9-20.

Figure 9-20 selectOneListbox Component

selectOneListbox component

The selectManyListbox component creates a component which allows the user to select many values from a list of items. This component includes an All checkbox that is displayed at the beginning of the list of checkboxes, as shown in Figure 9-21.

Figure 9-21 selectManyListbox Component

selectManyListbox component

The selectOneChoice component creates a menu-style component, which allows the user to select a single value from a dropdown list of items. The selectOneChoice component is intended for a relatively small number of items in the dropdown list.

Best Practice:

If a large number of items is desired, use an inputComboboxListOfValues component instead. For more information, see Chapter 11, "Using List-of-Values Components."

The selectOneChoice component is shown in Figure 9-22.

Figure 9-22 selectOneChoice Component

selectOneChoice component

You can configure the selectOneChoice component to display in a compact mode, as shown in Figure 9-23. When in compact mode, the input field is replaced with a smaller icon.

Figure 9-23 selectOneChoice Component in Compact Mode

selectOneChoice in compact mode.

When the user clicks the icon, the dropdown list is displayed, as shown in Figure 9-24.

Figure 9-24 List for selectOneChoice Component in Compact Mode

List for selectOneChoice Component in Compact Mode

The selectManyChoice component creates a menu-style dropdown component, which allows the user to select multiple values from a dropdown list of items. This component can be configured to include an All selection item that is displayed at the beginning of the list of selection items. If the number of choices is greater than 15, a scrollbar will be presented, as shown in Figure 9-25.

Figure 9-25 selectManyChoice Component

selectManyChoice component

By default, all selectItem child components are built when the selectManyChoice component is built, as the page is rendered. However, if the way the list items are accessed is slow, then performance can be hampered. This delay can be especially troublesome when it is likely that the user will select the items once, and then not change them on subsequent visits. For example, suppose you have a selectManyChoice component used to filter what a user sees on a page, and that the values for the child selectItem components are accessed from a web service. Suppose also that the user is not likely to change that selection each time they visit the page. By default, each time the page is rendered, all the selectItems must be built, regardless of whether or not the user will actually need to view them. Instead, you can change the contentDelivery attribute on the selectManyChoice component from immediate (the default) to lazy. The lazy setting causes the selectItem components to be built only when the user clicks the dropdown.

For both immediate and lazy, when the user then makes a selection, the values of the selected selectItem components are displayed in the field. However when lazy content delivery is used, on subsequent visits, instead of pulling the selected values from the selectItem components (which would necessitate building these components), the values are pulled from the lazySelectedLabel attribute. This attribute is normally bound to a method that returns an array of Strings representing the selected items. The selectItem components will not be built until the user goes to view or change them, using the dropdown.

Note that there are limitations when using the lazy delivery method on the selectManyChoice component. For more information about content delivery for the selectManyChoice component and its limitations, see Section 9.6.2, "What You May Need to Know About the contentDelivery Attribute on the SelectManyChoice Component."

For the following components, if you want the label to appear above the control, you can place them in a panelFormLayout component.

For the following components, the attributes disabled, immediate, readOnly, required, requireMessageDetail, and value cannot be set from JavaScript on the client for security reasons (for more information, see Section 3.7.1, "How to Set Property Values on the Client"):

9.6.1 How to Use Selection Components

The procedures for adding selection components are the same for each of the components. First, you add the selection component and configure its attributes. Then you add any number of selectItem components for the individual items in the list, and configure those.

To use a selection component:

  1. In the Component Palette, from the Common Components panel, drag and drop the selection component onto the page.

  2. For all selection components except the selectBooleanCheckbox and selectBooleanRadio components, a dialog opens where you choose either to bind to a value in a managed bean, or to create a static list. On the second page of the dialog, you can set the following properties:

    • Label: Enter the label for the list.

    • RequiredMessageDetail: Enter the message that should be displayed if a selection is not made by the user. For more information about messages, see Section 17.3, "Displaying Hints and Error Messages for Validation and Conversion."

    • Validator: Enter an EL expression that resolves to a validation method on a managed bean (for more information, see Chapter 6, "Validating and Converting Input").

    • Value: Specify the value of the component. If the EL binding for the value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

      Note:

      If you are creating a selectBooleanRadio or selectBooleanCheckbox component, and you enter a value for the value attribute, you cannot also enter a value for the selected attribute, as it is a typesafe alias for the value attribute. You cannot use both.

    • ValueChangeListener: Enter an EL expression that resolves to a listener on a managed bean that handles value change events.

  3. Expand the Appearance section of the Property Inspector and set the attributes, as described in Table 9-1. Note that only attributes specific to the selection components are discussed here. Many of the attributes are the same as for input text components. For more information, see Section 9.3.1, "How to Add an inputText Component."

    Table 9-1 Appearance Attributes for Selection Components

    Components Attribute

    selectOneRadio, selectManyCheckbox

    Layout: Set to vertical to have the buttons or checkboxes displayed vertically. Set to horizontal to have them displayed in a single horizontal line.

    selectManyListbox

    Size: Set to the number of items that should be displayed in the list. If the number of items in the list is larger than the size attribute value, a scrollbar will be displayed.

    selectManyListbox, selectManyChoice

    SelectAllVisible: Set to true to display an All selection that allows the user to select all items in the list.

    selectOneChoice

    Mode: Set to compact to display the component only when the user clicks the dropdown icon.

    selectOneRadio, selectOneListbox, selectOneChoice

    UnselectedLabel: Enter text for the option that represents a value of null, meaning nothing is selected. If unselectedLabel is not set and if the component does not have a selected value, then an option with an empty string as the label and value is rendered as the first option in the choice box (if there is not an empty option already defined). Note that you should set the required attribute to true when defining an unselectedLabel value. If you do not, two blank options will appear in the list. Once an option has been successfully selected, and if unselectedLabel is not set, then the empty option will not be rendered.


  4. Expand the Behavior section of the Property Inspector and set the attributes, as described in Table 9-2. Note that only attributes specific to the selection components are discussed here. Many of the attributes are the same as for input text components. For more information, see Section 9.3.1, "How to Add an inputText Component."

    Table 9-2 Behavior Attributes for Selection Components

    Component Attribute

    All except the boolean selection components

    ValuePassThru: Specify whether or not the values are passed through to the client. When valuePassThru is false, the value and the options' values are converted to indexes before being sent to the client. Therefore, when valuePassThru is false, there is no need to write your own converter when you are using custom Objects as your values, options, or both. If you need to know the actual values on the client-side, then you can set valuePassThru to true. This will pass the values through to the client, using your custom converter if it is available; a custom converter is needed if you are using custom objects. The default is false.

    Note that if your selection components uses ADF Model binding, this value will be ignored.

    selectBooleanRadio

    Group: Enter a group name that will enforce mutual exclusivity for all other selectBooleanRadio components with the same group value.


  5. If you want the value of a selectOneChoice or selectManyChoice component to appear as read-only until the user hovers over it, expand the Other section and set Editable to onAccess. If you want the component to always appear editable, select always. If you want the value to be inherited from an ancestor component, select inherit.

    Note:

    If you select inherit, and no ancestor components define the editable value, then the value always is used.

  6. If you do not want the child selectItem components for the selectManyChoice to be built each time the page is rendered, do the following:

    • Create logic that can store the labels of the selected items and also return those labels as an array of strings.

    • Expand the Other section, and set ContentDelivery to lazy.

    • Bind LazySelectedLabel to the method that returns the array of the selected items.

    Note that there are limitations to using lazy content delivery. For more information about content delivery for the selectManyChoice component, see Section 9.6.2, "What You May Need to Know About the contentDelivery Attribute on the SelectManyChoice Component."

  7. For the boolean components, drag and drop any number of selectItem components as children to the boolean component. These will represent the items in the list (for other selection components, the dialog in Step 2 automatically added these for you).

  8. With the selectItem component selected, in the Property Inspector, expand the Common section, and if not set, enter a value for the value attribute. This will be the value that will be submitted.

  9. Expand the Appearance section, and if not set, enter a value for Label. This will be the text that is displayed in the list.

  10. Expand the Behavior section, and set Disabled to true if you want the item to appear disabled in the list.

9.6.2 What You May Need to Know About the contentDelivery Attribute on the SelectManyChoice Component

When the contentDelivery attribute on the selectManyChoice component is set to immediate (the default), the following happens:

  • First visit to the page:

    • The selectManyChoice and all selectItem components are built as the page is rendered. This can cause performance issues if there are many items, or if the values for the selectItem components are accessed for example, from a web service.

    • When the selectManyChoice component renders, nothing displays in the field, as there has not yet been a selection.

    • When user clicks drop down, all items are shown.

    • When user selects items, the corresponding labels for the selected selectItem components are shown in field.

    • When page is submitted, values are posted back to the model.

  • Subsequent visit: The selectManyChoice and all selectItem components are built again as the page is rendered. Labels for selected selectItem components are displayed in field. This will cause the same performance issues as on the first visit to the page.

When the contentDelivery attribute on the selectManyChoice component is set to lazy, the following happens:

  • First visit to the page:

    • The selectManyChoice is built as the page is rendered, but the selectItem components are not.

    • When the selectManyChoice component renders, nothing displays in the field, as there has not yet been a selection.

    • When user clicks drop down, the selectItem components are built. While this is happening, the user sees a "busy" spinner. Once the components are built, all items are shown.

    • When user selects items, the corresponding labels for the selected selectItem components are shown in field.

    • When page is submitted, values are posted back to the model.

  • Subsequent visit:

    • When page is first rendered, only the selectManyChoice component is built. At this point, the value of the lazySelectedLabel attribute is used to display the selected items.

    • If user clicks drop down, the selectItem components are built. While this is happening, the user sees a "busy" spinner. Once the components are built, all items are shown.

      Once the selectItem components are built, the selectManyChoice component will act as though its contentDelivery attribute is set to immediate, and use the actual value of the selectItem components to display the selected items.

Following are limitations for using lazy content delivery for the selectManyChoice component:

  • You cannot store the value of the selectManyChoice is in Request scope. On postback, the value attribute is accessed from the model, rather than decoding what was returned from the client. If the value is stored in Request scope, that value will be empty. Do not store the value in Request scope.

  • On postbacks, converters are not called. If you are relying on converters for postbacks, then you should not use lazy content delivery.

  • The contentDelivery attribute is ignored when in screen reader mode. The selectItem components will always be built when the page is rendered.

9.7 Using Shuttle Components

The selectManyShuttle and selectOrderShuttle components present the user with two list boxes and buttons to move or shuttle items from one list box to the other. The user can select a single item or multiple items to shuttle between the leading (Available values) list box and the trailing (Selected values) list box. For either component, if you want the label to appear above the control, place them in a panelFormLayout component.

The selectManyShuttle component is shown in Figure 9-26.

Figure 9-26 selectManyShuttle component

selectManyShuttle component

The selectOrderShuttle component additionally includes up and down arrow buttons that the user can use to reorder values in the Selected values list box, as shown in Figure 9-27. When the list is reordered, a ValueChangeEvent event is delivered. If you set the readOnly attribute to true, ensure the values to be reordered are selected values that will be displayed in the trailing list (Selected values).

Figure 9-27 selectOrderShuttle Component

selectOrderShuttle component

The value attribute of these components, like any other selectMany component, must be a List or an Array of values that correspond to a value of one of the contained selectItem components. If a value of one of the selectItems is in the List or Array, that item will appear in the trailing list. You can convert a selectManyListbox component directly into a selectManyShuttle; instead of the value driving which items are selected in the listbox, it affects which items appear in the trailing list of the selectOrderShuttle component.

Similar to other select components, the List or Array of items are composed of selectItem components nested within the selectManyShuttle or selectOrderShuttle component. Example 9-5 shows a sample selectOrderShuttle component that allows the user to select the top five file types from a list of file types.

Example 9-5 selectOrderShuttle JSF Page Code

<af:selectOrderShuttle value="#{helpBean.topFive}"
    leadingHeader="#{explorerBundle['help.availableFileTypes']}"
    trailingHeader="#{explorerBundle['help.top5']}"
    simple="true">
  <af:selectItem label="XLS"/>
  <af:selectItem label="DOC"/>
  <af:selectItem label="PPT"/>
  <af:selectItem label="PDF"/>
  <af:selectItem label="Java"/>
  <af:selectItem label="JWS"/>
  <af:selectItem label="TXT"/>
  <af:selectItem label="HTML"/>
  <af:selectItem label="XML"/>
  <af:selectItem label="JS"/>
  <af:selectItem label="PNG"/>
  <af:selectItem label="BMP"/>
  <af:selectItem label="GIF"/>
  <af:selectItem label="CSS"/>
  <af:selectItem label="JPR"/>
  <af:selectItem label="JSPX"/>
  <f:validator validatorId="shuttle-validator"/>
</af:selectOrderShuttle>

If you set the reorderOnly attribute of a selectOrdershuttle component to true, the shuttle function will be disabled, and only the Selected Values listbox appears. The user can only reorder the items in the listbox, as shown in Figure 9-28.

Figure 9-28 selectOrderShuttle Component in Reorder-Only Mode

selectOrderShuttle component in reorderOnly mode

9.7.1 How to Add a selectManyShuttle or selectOrderShuttle Component

The procedures for adding shuttle components are the same for both components. First you add the selection component and configure its attributes. Then you add any number of selectItem components for the individual items in the list, and configure those.

To add a selectManyShuttle or selectOrderShuttle component:

  1. In the Component Palette, from the Common Components panel, drag and drop a Select Many Shuttle or Select Order Shuttle from the Component Palette onto the page.

  2. A dialog appears where you choose either to bind to a value in a managed bean, or to create a static list. On the second page of the dialog, you can set the following:

    • Label: Enter the label for the list.

    • RequiredMessageDetail: Enter the message that should be displayed if a selection is not made by the user. For more information about messages, see Section 17.3, "Displaying Hints and Error Messages for Validation and Conversion."

    • Size: Specify the display size (number of items) of the lists. The size specified must be between 10 and 20 items. If the attribute is not set or has a value less than 10, the size would have a default or minimum value of 10. If the attribute value specified is more than 20 items, the size would have the maximum value of 20.

    • Validator: Enter an EL expression that resolves to a validation method on a managed bean.

    • Value: Specify the value of the component. If the EL binding for the value points to a bean property with a get method but no set method, the component will be rendered in read-only mode.

    • ValueChangeListener: Enter an EL expression that resolves to a listener on a managed bean that handles value change events.

  3. In the Property Inspector, expand the Appearance section and set the following:

    • Layout: Specify whether the component will be in horizontal or vertical layout. The default is horizontal, meaning the leading and trailing list boxes are displayed next to each other. When set to vertical, the leading list box is displayed above the trailing list box.

    • LeadingHeader: Specify the header text of the leading list of the shuttle component.

    • LeadingDescShown: Set to true to display a description of the selected item at the bottom of the leading list box.

    • TrailingHeader: Specify the header of the trailing list of the shuttle component.

    • TrailingDescShown: Set to true to display a description of the selected item at the bottom of the trailing list box.

  4. Expand the Behavior section and optionally set the following attributes:

    • ValuePassThru: Specify whether or not the values are passed through to the client. When valuePassThru is false, the value and the options' values are converted to indexes before being sent to the client. Therefore, when valuePassThru is false, there is no need to write your own converter when you are using custom objects as your values, options, or both. If you need to know the actual values on the client-side, then you can set valuePassThru to true. This will pass the values through to the client, using your custom converter if it is available; a custom converter is needed if you are using custom objects. The default is false.

    • ReorderOnly (selectOrderShuttle component only): Specify whether or not the shuttle component is in reorder-only mode, where the user can reorder the list of values, but cannot add or remove them.

  5. In the Structure window, select one of the selectItem components, and in the Property Inspector, set any needed attributes.

    Tip:

    If you elected to have the leading or trailing list box display a description, you must set a value for the shortDesc attribute for each selectItem component.

9.7.2 What You May Need to Know About Using a Client Listener for Selection Events

You can provide the user with information about each selected item before the user shuttles it from one list to another list by creating JavaScript code to perform processing in response to the event of selecting an item. For example, your code can obtain additional information about that item, then display it as a popup to help the user make the choice of whether to shuttle the item or not. Figure 9-29 shows a selectManyShuttle component in which the user selects Meyers and a popup provides additional information about this selection.

Figure 9-29 selectManyShuttle with selectionListener

selectManyShuttle with selectionListener

You implement this feature by adding a client listener to the selectManyShuttle or selectOrderShuttle component and then create a JavaScript method to process this event. The JavaScript code is executed when a user selects an item from the lists. For more information about using client listeners for events, see Section 3.2, "Listening for Client Events."

How to add a client listener to a shuttle component to handle a selection event:

  1. In the Component Palette, from the Operations panel, drag a Client Listener and drop it as a child to the shuttle component.

  2. In the Insert Client Listener dialog, enter a function name in the Method field (you will implement this function in the next step), and select propertyChange from the Type dropdown.

    If for example, you entered showDetails as the function, JDeveloper would enter the code shown in bold in Example 9-6.

    Example 9-6 Using a clientListener to Register a Selection

    <af:selectManyShuttle value="#{demoInput.manyListValue1}"
         valuePassThru="true" ...>
         <af:clientListener type="propertyChange" method="showDetails"/>
         <af:selectItem label="coffee" value="bean" />
          ...
    </af:selectManyShuttle>
    

    This code causes the showDetails function to be called any time the property value changes.

  3. In your JavaScript, implement the function entered in the last step. This function should do the following:

    • Get the shuttle component by getting the source of the event.

    • Use the client JavaScript API calls to get information about the selected items.

In Example 9-7, AdfShuttleUtils.getLastSelectionChange is called to get the value of the last selected item

Example 9-7 Sample JavaScript methods showDetails used to process a selection

function showDetails(event)
{
  if(AdfRichSelectManyShuttle.SELECTION == event.getPropertyName())
  {
    var shuttleComponent = event.getSource();
    var lastChangedValue =    AdfShuttleUtils.getLastSelectionChange(shuttleComponent, event.getOldValue());
    var side = AdfShuttleUtils.getSide(shuttleComponent, lastChangedValue);
    if(AdfShuttleUtils.isSelected(shuttleComponent, lastChangedValue))
    {
      //do something...
    }
    else
    {
      //do something else
    }
    if(AdfShuttleUtils.isLeading(shuttleComponent, lastChangedValue))
    {
      //queue a custom event (see serverListener) to call a java method on the server
    }
  }
}

9.8 Using the richTextEditor Component

The richTextEditor component provides an input field that can accept text with formatting. It also supports label text, and messages. It allows the user to change font name, size, and style, create ordered lists, justify text, and use a variety of other features. The richTextEditor component also can be used to edit an HTML source file. Two command buttons are used to toggle back and forth between editing standard formatted text and editing the HTML source file. Figure 9-30 shows the rich text editor component in standard rich text editing Mode.

Figure 9-30 The richTextEditor Component in Standard Editing Mode

RichTextEditor component in edit mode

Figure 9-31 shows the editor in source code editing mode.

Figure 9-31 The richTextEditor in Source Editing Mode

RichTextEditor in source mode

Other supported features include:

The value (entered text) of the rich text editor is a well-formed XHTML fragment. Parts of the value may be altered for browser-specific requirements to allow the value to be formatted. Also, for security reasons, some features such as script-related tags and attributes will be removed. There are no guarantees that this component records only the minimal changes made by the user. Because the editor is editing an XHTML document, the following elements may be changed:

The editor supports only HTML 4 tags, with the exception of:

The richTextEditor component also supports tags that pull in content (such as applet, iframe, object, img, and a). For the iframe tag, the content should not be able to interact with the rest of the page because browsers allow interactions only with content from the same domain. However, this portion of the page is not under the control of the application.

While the richTextEditor component does not support font units such as px and em, it does support font size from 1 to 7 as described in the HTML specification. It does not support embed or unknown tags (such as <foo>).

On the client, the richTextEditor component does not support getValue and setValue methods. There is no guarantee the component's value on the client is the same as the value on the server. Therefore, the richTextEditor does not support client-side converters and validators. Server-side converters and validators will still work.

The rich text editor delivers ValueChangeEvent and AttributeChangeEvent events. Create valueChangeListener and attributeChangeListener handlers for these events as required.

You can also configure the richTextEditorInsertBehavior tag, which works with command components to insert given text into the richTextEditor component. The text to be entered can be a simple string, or it can be preformatted text held, for example, in a managed bean.

By default, the toolbar in the richTextEditor component allows the user to change many aspects of the text, such as the font, font size and weight, text alignment, and view mode, as shown in Figure 9-32.

Figure 9-32 Toolbar in richTextEditor Component

Toolbar in richTextEditor

Figure 9-33 shows a toolbar that has been customized. Many of the toolbar buttons have been removed and a toolbar with a custom toolbar button and a menu have been added.

Figure 9-33 Customized Toolbar for richTextEditor

Customized Toolbar for a richTextEditor

9.8.1 How to Add a richTextEditor Component

Once you add a richTextEditor component, you can configure it so that text can be inserted at a specific place, and you can also customize the toolbar. For more information, see Section 9.8.2, "How to Add the Ability to Insert Text into a richTextEditor Component," and Section 9.8.3, "How to Customize the Toolbar."

To add a richTextEditor component:

  1. In the Component Palette, from the Common Components panel, drag and drop a Rich Text Editor onto the page.

  2. Expand the Common section of the Property Inspector and set the value attribute.

  3. Expand the Appearance section and set the following:

    • Rows: Specify the height of the edit window as an approximate number of characters shown.

    • Columns: Specify the width of the edit window as an approximate number of characters shown.

    • Label: Specify a label for the component.

  4. Expand the Behavior section and set the following:

    • EditMode: Select whether you want the editor to be displayed using the WYSIWYG or source mode.

    • ContentDelivery: Specify whether or not the data within the editor should be fetched when the component is rendered initially. When the contentDelivery attribute value is immediate, data is fetched and displayed in the component when it is rendered. If the value is set to lazy, data will be fetched and delivered to the client during a subsequent request. For more information, see Section 10.1.1, "Content Delivery."

Tip:

You can set the width of a richTextEditor component to full width or 100%. However, this works reliably only if the editor is contained in a geometry-managing parent components. It may not work reliably if it is placed in flowing layout containers such as panelFormLayout or panelGroupLayout. For more information, see Section 8.2.1, "Geometry Management and Component Stretching."

9.8.2 How to Add the Ability to Insert Text into a richTextEditor Component

To allow text to be inserted into a richTextEditor component, add the richTextEditorInsertBehavior tag as a child to a command component that will be used to insert the text.

Before you begin

You need to create a richTextEditor component as described in Section 9.3.1, "How to Add an inputText Component." Set the clientComponent attribute to true.

To add text insert behavior:

  1. Add a command component that the user will click to insert the text. For procedures, see Section 18.2.1, "How to Use Command Buttons and Command Links."

  2. In the Component Palette, from the Operations panel, drag and drop a Rich Text Editor Insert Behavior as a child to the command component.

  3. In the Rich Text Editor Insert Behavior dialog, enter the following:

    • For: Use the dropdown arrow to select Edit and then navigate to select the richTextEditor component into which the text will be inserted.

    • Value: Enter the value for the text to be inserted. If you want to insert static text, then enter that text. If you want the user to be able to insert the value of another component (for example, the value of a selectOneChoice component), then enter an EL expression that resolves to that value. If you want the user to enter preformatted text, enter an EL expression that resolves to that text. For example Example 9-8 shows preformatted text as the value for an attribute in the demoInput managed bean.

      Example 9-8 Preformatted Text in a Managed Bean

      private static final String _RICH_INSERT_VALUE =
        "<p align=\"center\" style=\"border: 1px solid gray; 
              margin: 5px; padding: 5px;\">" +
        "<font size=\"4\"><span style=\"font-family: Comic Sans MS,
          Comic Sans,cursive;\">Store Hours</span></font><br/>\n" +
        "<font size=\"1\">Monday through Friday 'til 8:00 pm</font><br/>\n" +
        "<font size=\"1\">Saturday &amp; Sunday 'til 5:00 pm</font>" +
        "</p>";
      

      Example 9-9 shows how the text is referenced from the richTextEditorInsertBehavior tag.

      Example 9-9 Using the richTextEditorInsertBehavior Tag

      <af:richTextEditor id="idRichTextEditor" label="Rich text value"
                         value="#{demoInput.richValue2}"/>
      . . .
      </af:richTextEditor>
      <af:commandButton text="Insert Template Text">
        <af:richTextEditorInsertBehavior for="idRichTextEditor"
                                         value="#{demoInput.richInsertValue}"/>
      </af:commandButton>
      
  4. By default, the text will be inserted when the action event is triggered by clicking the command component. However, you can change this to another client event by choosing that event from the dropdown menu for the triggerType attribute.

9.8.3 How to Customize the Toolbar

Place the toolbar and toolbar buttons you want to add in custom facets that you create. Then, reference the facet (or facets) from an attribute on the toolbar, along with keywords that determine how or where the contained items should be displayed.

To customize the toolbar:

  1. In the JSF page of the Component Palette, from the Core panel, drag and drop a Facet for each section of the toolbar you want to add. For example, to add the custom buttons shown in Figure 9-33, you would add two <f:facet> tags. Ensure that each facet has a unique name for the page.

    Tip:

    To ensure that there will be no conflicts with future releases of ADF Faces, start all your facet names with customToolbar.

  2. In the ADF Faces page of the Component Palette, from the Common Components panel, drag and drop a Toolbar into each facet and add toolbar buttons or other components and configure as needed. For more information about toolbars and toolbar buttons, see Section 14.3, "Using Toolbars."

  3. With the richTextEditor component selected, in the Property Inspector, in the Other section, click the dropdown icon for the toolboxLayout attribute and select Edit to open the Edit Property: ToolboxLayout dialog. The value for this attribute should be a list of the custom facet names, in the order in which you want the contents in the custom facets to appear. In addition to those facets, you can also include all, or portions, of the default toolbar, using the following keywords:

    • all: All the toolbar buttons and text in the default toolbar. If all is entered, then any keyword for noncustom buttons will be ignored.

    • font: The font selection and font size buttons.

    • history: Undo and redo buttons.

    • mode: Rich text mode and source code mode buttons.

    • color: Foreground and background color buttons.

    • formatAll: Bold, italic, underline, superscript, subscript, strikethrough buttons. If formatAll is specified, formatCommon and formatUncommon will be ignored.

    • formatCommon: Bold, italic, and underline buttons.

    • formatUncommon: Superscript, subscript, and strikethrough buttons.

    • justify: Left, center, right and full justify buttons.

    • list: Bullet and numbered list buttons.

    • indent: Outdent and indent buttons.

    • link: Add and remove Link buttons.

    For example, if you created two facets named customToolbar1 and customToolbar2, and you wanted the complete default toolbar to appear in between your custom toolbars, you would enter the following list:

    • customToolbar1

    • all

    • customToolbar2

    You can also determine the layout of the toolbars using the following keywords:

    • newline: Places the toolbar in the next named facet (or the next keyword from the list in the toolboxLayout attribute) on a new line. For example, if you wanted the toolbar in the customToolbar2 facet to appear on a new line, you would enter the following list:

      • customToolbar1

      • all

      • newline

      • customToolbar2

      If instead, you did not want to use all of the default toolbar, but only the font, color, and common formatting buttons, and you wanted those buttons to appear on a new line, you would enter the following list:

      • customToolbar1

      • customToolbar2

      • newline

      • font

      • color

      • formatCommon

    • stretch: Adds a spacer component that stretches to fill all available space so that the next named facet (or next keyword from the default toolbar) is displayed as right-aligned in the toolbar.

9.9 Using File Upload

The inputFile component provides users with file uploading and updating capabilities. This component allows the user to select a local file and upload it to a selectable location on the server. To download a file from the server to the user, see Section 18.4.1, "How to Use a Command Component to Download Files."

The inputFile component delivers the standard ValueChangeEvent event as files are being uploaded, and it manages the loading process transparently. The value property of an inputFile component is set to an instance of the org.apache.myfaces.trinidad.model.UploadedFile class when a file is uploaded.

To initiate the upload process, you can create an action component such as a command button, as shown in Figure 9-34.

Figure 9-34 inputFile Component

inputFile component

Once a file has been uploaded, and so the value of the inputFile is not null (either after the initial load is successful or it has been specified as an initial value), you can create an Update button that will be displayed instead of the Browse button, as shown in Figure 9-35. This will allow the user to modify the value of the inputFile component.

Figure 9-35 inputFile Component in Update Mode

inputFileComponent in update mode

You can also specify that the component be able to load only a specific file by setting the readOnly property to true, In this mode, only the specified file can be loaded, as shown in Figure 9-36.

Figure 9-36 inputFile Component in Read-Only Mode

inputFile component in read-only mode

For security reasons, the following attributes cannot be set from the client:

The inputFile component can be placed in either an h:form tag or an af:form tag, but in either case, you have to set the form tag to support file upload. If you use the JSF basic HTML h:form, set the enctype to multipart/form-data. This would make the request into a multipart request to support file uploading to the server. If you are using the ADF Faces af:form tag, set usesUpload to true, which performs the same function as setting enctype to multipart/form-data to support file upload.

The rich client framework performs a generic upload of the file. You should create an actionListener or action method to process the file after it has been uploaded (for example, processing xml files, pdf files, and so on).

The value of an inputFile component is an instance of the org.apache.myfaces.trinidad.model.UploadedFile interface. The API lets you get at the actual byte stream of the file, as well as the file's name, its MIME type, and its size.

Note:

The API does not allow you to get path information from the client about from where the file was uploaded.

The uploaded file may be stored as a file in the file system, but may also be stored in memory; the API hides that difference. The filter ensures that the UploadedFile content is cleaned up after the request is complete. Because of this, you cannot usefully cache UploadedFile objects across requests. If you need to keep the file, you must copy it into persistent storage before the request finishes.

For example, instead of storing the file, add a message stating the file upload was successful using a managed bean as a response to the ValueChangeEvent event, as shown in Example 9-10.

Example 9-10 Using valueChangeListener to Display Upload Message

JSF Page Code ----->
<af:form usesUpload="true">
  <af:inputFile label="Upload:"
                valueChangeListener="#{managedBean.fileUploaded}"/>
  <af:commandButton text="Begin"/>
</af:form>

Managed Bean Code ---->
import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;
import javax.faces.event.ValueChangeEvent;
import org.apache.myfaces.trinidad.model.UploadedFile;
 
public class ABackingBean
{
  ...
  public void fileUploaded(ValueChangeEvent event)
  {
    UploadedFile file = (UploadedFile) event.getNewValue();
    if (file != null)
    {
      FacesContext context = FacesContext.getCurrentInstance();
      FacesMessage message = new FacesMessage(
         "Successfully uploaded file " + file.getFilename() +
         " (" + file.getLength() + " bytes)");
      context.addMessage(event.getComponent().getClientId(context), message);
      // Here's where we could call file.getInputStream()
    }
  }
}

You can also handle the upload by binding the value directly to a managed bean, as shown in Example 9-11.

Example 9-11 Binding the Value to a Managed Bean

JSF Page Code ---->
<af:form usesUpload="true">
  <af:inputFile label="Upload:" value="#{managedBean.file}"/>
  <af:commandButton text="Begin" action="#{managedBean.doUpload}"/>
</af:form>

Managed Bean Code ---->
import org.apache.myfaces.trinidad.model.UploadedFile;public class AManagedBean
{
  public UploadedFile getFile()
  {
    return _file;
  }
  public void setFile(UploadedFile file)
  {
    _file = file;
  }

  public String doUpload()
  {
    UploadedFile file = getFile();
    // ... and process it in some way
  }
  private UploadedFile _file;

}

9.9.1 How to Use the inputFile Component

A Java class must be bound to the inputFile component. This class will be responsible for containing the value of the uploaded file.

To add an inputFile component:

  1. Create a Java class that will hold the value of the input file. It must be an instance of the org.apache.myfaces.trinidad.model.UploadedFile interface.

  2. In the Component Palette, from the Common Components panel, drag and drop an Input File onto the page.

  3. Set value to be the class created in Step 1.

  4. If you want the value of the component to appear as read-only until the user hovers over it, expand the Other section and set Editable to onAccess. If you want the component to always appear editable, select always. If you want the value to be inherited from an ancestor component, select inherit.

    Note:

    If you select inherit, and no ancestor components define the editable value, then the value always is used.

  5. From the Component Palette, drag and drop any command component onto the page. This will be used to initiate the upload process.

  6. With the command component selected, set the actionListener attribute to a listener that will process the file after it has been uploaded.

9.9.2 What You May Need to Know About Temporary File Storage

Because ADF Faces will temporarily store files being uploaded (either on disk or in memory), by default it limits the size of acceptable incoming upload requests to avoid denial-of-service attacks that might attempt to fill a hard drive or flood memory with uploaded files. By default, only the first 100 kilobytes in any one request will be stored in memory. Once that has been filled, disk space will be used. Again, by default, that is limited to 2,000 kilobytes of disk storage for any one request for all files combined. Once these limits are exceeded, the filter will throw an EOFException.

Files are, by default, stored in the temporary directory used by the java.io.File.createTempFile() method, which is usually defined by the system property java.io.tmpdir. Obviously, this will be insufficient for some applications, so you can configure these values using three servlet context initialization parameters, as shown in Example 9-12.

Example 9-12 Parameters That Define File Upload Size and Directory

<context-param>
    <!-- Maximum memory per request (in bytes) -->
    <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY</param-name>
    <!-- Use 500K -->
    <param-value>512000</param-value>
  </context-param>
  <context-param>
    <!-- Maximum disk space per request (in bytes) -->
    <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE</param-name>
    <!-- Use 5,000K -->
    <param-value>5120000</param-value>
  </context-param>
  <context-param>
    <!-- directory to store temporary files -->
    <param-name>org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR</param-name>
    <!-- Use a TrinidadUploads subdirectory of /tmp -->
    <param-value>/tmp/TrinidadUploads/</param-value>
  </context-param>
  <!-- This filter is always required;  one of its functions is 
          file upload. -->
  <filter>
    <filter-name>trinidad</filter-name>
    <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
  </filter>

You can customize the file upload process by replacing the entire org.apache.myfaces.trinidad.webapp.UploadedFileProcessor class with the <uploaded-file-processor> element in the trinidad-config.xml configuration file. Replacing the UploadedFileProcessor class makes the parameters listed in Example 9-12 irrelevant, they are processed only by the default UploadedFileProcessor class.

The <uploaded-file-processor> element must be the name of a class that implements the oracle.adf.view.rich.webapp.UploadedFileProcessor interface. This API is responsible for processing each individual uploaded file as it comes from the incoming request, and then making its contents available for the rest of the request. For most applications, the default UploadedFileProcessor class is sufficient, but applications that need to support uploading very large files may improve their performance by immediately storing files in their final destination, instead of requiring ADF Faces to handle temporary storage during the request.