| Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) Part Number B31973-03 |
|
|
View PDF |
| Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) Part Number B31973-03 |
|
|
View PDF |
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:
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.
You can also configure the 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.
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.
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.
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".
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.6, "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.
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:
To create a form, drag and drop the Form component from the Component Palette onto the page.
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.
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:
To add a subform, drag and drop a Subform from the Component Palette onto the page, as a child to a form component.
Use the Property Inspector to set the following attributes:
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.
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.
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:
Drag and drop the Reset Button component from the Component Palette onto the page.
Use the Property Inspector to set the following attributes:
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.
text: Specify the textual label of the button.
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 a 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-3 shows a single-row inputText component.
You can add multiple inputText components to create an input form. Figure 9-4 shows an input form using three inputText components and a Submit command button.
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-5 shows an inputText component with some text already entered by a user.
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-6.
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:
Drag and drop an Input Text component from the Component Palette onto the page.
In the Property Inspector, expand the Common section and set the following attributes:
label: Enter a value to specify the text to be used as the label.
If the text to be used for a label is held in a resource bundle, use the field's dropdown menu to choose Select Text Resource. Use the Select Text Resource dialog to create an expression that evaluates to the text item within the resource bundle, for example:
"#{res['home.description']}"
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, the component will be rendered in read-only mode.
Expand the Appearance section, and set the following attributes:
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 1-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.
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.
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.
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.
Expand the Behavior section and set the following attributes:
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 or not the control is displayed as 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 autoSubmit attribute, see Section 4.4, "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 like Internet Explorer, a new line is treated as 2 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".
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.
To add text insert behavior:
Create an inputText component as described in Section 9.3.1, "How to Add an inputText Component". Set the clientComponent attribute to true.
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".
Expand the Operations section of the Component Palette and drag and drop an Insert Text Behavior as a child to the command component.
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>
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 in the Property Inspector.
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-7 in horizontal layout, and in Figure 9-8 in vertical layout.
The inputRangeSlider component has two markers and allows the user to pick the end points of a range, as shown in Figure 9-9.
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-10.
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:
Drag and drop the Input Number Slider or Input Range Slider component from the Component Palette onto the page.
In the Property Inspector, expand the Common section (and for the inputRangeSlider component, also expand the Data section) and set the following attributes:
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, and causes a labeled value to be displayed. For example, the majorIncrement value of the inputRangeSlider component in Figure 9-9 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.
Expand the Appearance section and set the following attributes:
orientation: 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".
The inputNumberSpinbox component allows the user to scroll through a set of numbers to select a value.
To add an inputNumberSpinbox component:
Drag and drop the Input Number Spinbox component from the Component Palette onto the page.
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.
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.
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"
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-11 shows the inputColor component with the chooseColor component in a popup dialog.
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-12. 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").
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 and the inputDate component will display the selected time zone above the input box, as shown in Figure 9-13.
The inputColor component allows users to either enter a value in an input text field, or select a color from a color chooser.
To add an inputColor component:
Drag and drop the Input Color component from the Component Palette onto the page.
In Property Inspector, expand the Common section and set the following attributes:
compact: Set to true if you do not want to display the input text field, as shown in Figure 9-14.
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) and 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 or 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.
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, and corresponds 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.
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.
The inputDate component allows the user to either enter or select a date.
To add an inputDate component:
Drag and drop the Input Date component from the Component Palette onto the page.
In the Property Inspector, in the Common section, set the following attributes:
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.
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 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 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.
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.
Expand the Behavior section and set the chooseId attribute. 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.
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 selectOneRadio component creates a component which allows the user to select a single value from a set of items displayed as a series of radio buttons, as shown in Figure 9-15.
The selectBooleanRadio component allows you to group selectBooleanRadio buttons together using the same group attribute. As shown in Figure 9-16, radio buttons can be placed anywhere on the page, and do not have to be placed together with other radio buttons that share the same group value. Radio buttons with the same group value will have mutually exclusive selection, regardless of their physical placement on the page.
As with selectOneRadio, the selectBooleanCheckbox component toggles between selected and unselected states, as shown in Figure 9-17.
The selectManyCheckbox component creates a component which allows the user to select many values from a series of checkboxes, as shown in Figure 9-18.
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-19.
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-20.
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. If a large number of items is desired, it is recommended to use an inputComboboxListOfValues component instead. For more information, see Chapter 11, "Using List-of-Values Components".
The selectOneChoice component is shown in Figure 9-21.
You can configure the selectOneChoice component to display in a compact mode, as shown in Figure 9-22. When in compact mode, the input field is replaced with a smaller icon.
When the user clicks the icon, the dropdown list is displayed, as shown in Figure 9-23.
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-24.
For the following components, if you want the label to appear above the control, you can place them in a panelFormLayout component.
selectOneChoice
selectOneRadio
selectOneListbox
selectManyChoice
selectManyCheckbox
selectManyListbox
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.6.3, "What You May Need to Know About Secured and Disconnected Properties"):
selectOneChoice
selectOneRadio
selectOneListbox
selectBooleanRadio
selectBooleanCheckbox
selectManyChoice
selectManyCheckbox
selectManyListbox
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.
Drag and drop the selection component from the Component Palette onto the page.
For all selection components except the selectBooleanCheckbox and selectBooleanRadio components, a dialog opens where you choose to either bind to a value in a managed bean, or 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.
valueChangeListener: Enter an EL expression that resolves to a listener on a managed bean that handles value change events.
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
Note that if your selection components uses ADF Model binding, this value will be ignored. |
|
|
|
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).
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.
Expand the Appearance section, and if not set, enter a value for the label attribute. This will be the text that is displayed in the list.
Expand the Behavior section, and set the disabled attribute to true if you want the item to appear disabled in the list.
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-25.
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-26. 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).
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-4 shows a sample selectOrderShuttle component that allows the user to select the top five file types from a list of file types.
Example 9-4 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-27.
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:
Drag and drop the shuttle component from the Component Palette onto the page.
A dialog appears where you choose to either bind to a value in a managed bean, or create a static list. On the second page of the dialog, you can set the following properties:
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.
Expand the Appearance section and set the following properties:
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.
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.
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.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-28 shows a selectManyShuttle component in which the user selects Meyers and a popup provides additional information about this selection.
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:
Drag a Client Listener from the Operations section of the Component Palette, and drop it as a child to the shuttle component.
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-5.
Example 9-5 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.
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-6, AdfShuttleUtils.getLastSelectionChange is called to get the value of the last selected item
Example 9-6 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
}
}
}
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-29 shows the rich text editor component in standard Rich Text Editing Mode.
Figure 9-30 shows the editor in Source Code Editing Mode.
Other supported features include:
Font type
Font size
Link/unlink
Clear styling
Undo/redo
Bold/italics/underline
Subscript/superscript
Justify (left, middle, right, full)
Ordered/unordered lists
Indentation
Text color/background color
Rich text editing mode/source code editing mode
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:
Nonmeaningful whitespace
Element minimization
Element types
Order of attributes
Use of character entities
The editor supports only HTML 4 tags, with the exception of:
Script, noscript
Frame, frameset, noframes
Form-related elements (input, select, optgroup, option, textarea, form, button, label, isindex)
Document-related elements (html, head, body, meta, title, base, link)
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 richTextEditorInsertBehavior tag that 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.
To add a richTextEditor component:
Drag and drop the Rich Text Editor component from the Component Palette onto the page.
Expand the Common section of the Property Inspector and set the value attribute.
Expand the Appearance section of the Property Inspector 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.
Expand the Behavior section and set the following:
editMode: Select whether or not 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".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.
To add text insert behavior:
Create a richTextEditor component as described in Section 9.3.1, "How to Add an inputText Component". Set the clientComponent attribute to true.
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".
Expand the Operations section of the Component Palette and drag and drop a Rich Text Editor Insert Behavior as a child to the command component.
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-7 shows preformatted text as the value for an attribute in the demoInput managed bean.
Example 9-7 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 & Sunday 'til 5:00 pm</font>" +
"</p>";
Example 9-8 shows how the text is referenced from the richTextEditorInsertBehavior tag.
Example 9-8 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>
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.
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.3.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-31.
If the value of the input field 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-32.
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-33.
For security reasons, the following attributes cannot be set from the client:
disabled
immediate
readOnly
requiredMessageDetail
value
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-9.
Example 9-9 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-10.
Example 9-10 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;
}
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:
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.
From the Component Palette, drag and drop the Input File component onto the page.
Set the value attribute to be the class created in Step 1.
Drag and drop a command component onto the page. This will be used to initiate the upload process.
With the command component selected, set the actionListener attribute to a listener that will process the file after it has been uploaded.
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-11.
Example 9-11 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-11 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.
|
 Copyright © 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|