9 Using Input Components and Defining Forms

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.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 & to represent the ampersand.

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

   • Placeholder: Specify the text that appears in the input component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.

     The placeholder text is used to inform the user what should be entered in the input component.

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.

   • Usage: Specify how the input component will be rendered in HTML 5 browser. The valid values are auto, text, and search. Default is auto.

     If the usage type is search, the input component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.

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

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

     
     

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.

   • Placeholder: Specify the text that appears in the input component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.

     The placeholder text is used to inform the user what should be entered in the input component.

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

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

   • Usage: Specify how the input component will be rendered in HTML 5 browser. The valid values are auto, text, and search. Default is auto.

     If the usage type is search, the input component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.

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 the following attributes:

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

   • Usage: Specify how the input component will be rendered in HTML 5 browser. The valid values are auto, text, and search. Default is auto.

     If the usage type is search, the input component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.

5. Expand the Appearance section and set the following:

   • Editable: Set to onAccess if you want the value of the component to appear as read-only until the user hovers over it. 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.

   • Placeholder: Specify the text that appears in the input component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.

     The placeholder text is used to inform the user what should be entered in the input component.

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.

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

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

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

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

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