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.
In addition to standard input components used to input text, number, date, or color, ADF Faces includes input type components that provide additional functionality. The inputFile
component allows users to browse for a file to load.
The richTextEditor
component provides rich text input that can span many lines and can be formatted using different fonts, sizes, justification, and other editing features. The richTextEditor
component can also be used with command components to insert given text into the component. The inserted text can be preformatted. Additionally, you can customize the buttons that appear in the editor's toolbar.
The selection components allow the user to make selections from a list of items instead of or in addition to typing in values. For example, the selectOneChoice
component lets the user select input from a dropdown list and the selectOneRadio
component lets a user pick from a group of radio buttons.
You can use either selection or list-of-values (LOV) components to display a list. LOV components should be used when the selection list is large. LOV components are model-driven using the ListOfValueModel
class and may be configured programmatically using the API. They present their selection list inside a popup window that may also include a query panel. Selection lists simply display a static list of values. For more information about using LOV components, see Chapter 11, "Using List-of-Values Components."
The selectItem
component is used within other selection components to represent the individual selectable items for that component. For example, a selectOneRadio
component will have a selectItem
component for each of its radio buttons. If the radio button selections are coffee, tea, and milk, there would be a selectItem
component for coffee, one for tea, and one for milk.
The form components provide a container for other components. The form
component represents a region where values from embedded input components can be submitted. Form components cannot be nested. However, the subform
component provides additional flexibility by defining subregions whose component values can be submitted separately within a form. The resetButton
component provides an easy way for the user to reset input values within a form or subform to their previous state.
All the input and selection components deliver the ValueChangeEvent
and AttributeChangeEvent
events. You can create valueChangeListener
and attributeChangeListener
methods to provide functionality in response to the corresponding events.
All input components, selection components (except selectItem
), and the rich text editor component have a changed
attribute that when set to true
enables a change indicator icon to be displayed upon changes in the value
field. This indicator allows the user to easily see which input value has changed, which can be helpful when there are multiple components on the page. By default, the change indicator usually is displayed to the left of the component. If the value in a field automatically changes due to a change in another field's value, such as an automatically generated postal code when the city is entered, the postal code field will also display a change indicator. Figure 9-2 shows changed indicators present for the checkbox and input components.
Tip:
You can change the icon or the position of the icon using skins. For more information, see Chapter 20, "Customizing the Appearance Using Styles and Skins."Most input components also have the capability of displaying only the label, and not appearing capable of changing value until the user mouses over or hovers over the component. Once the user changes the value, that new value displays as read-only. Figure 9-3 shows a selectManyChoice
component configured to be editable only on access.
Input components can also display tooltips, error and validation messages, and context-sensitive help. For more information, see Chapter 17, "Displaying Tips, Messages, and Help."
All input components have JavaScript client APIs that you can use to set or get property values. For more information, see Oracle Fusion Middleware Javascript API Reference for Oracle ADF Faces.
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 anaf:form
tag on the page, and you drag and drop an ADF Faces component onto the page, JDeveloper will prompt you to enclose the component within a form component.Example 9-1 shows two input components and a Submit button that when clicked will submit both input values for processing.
Example 9-1 ADF Faces Form as a Container for Input Components
<af:form> <af:panelFormLayout> <af:inputText value="#{myBean.firstName}" label="#{First Name}" </af:inputText> <af:inputText value="#{myBean.lastName}" label="#{Last Name}" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> </f:facet> </af:panelFormLayout> </af:form>
Because there can be only one form
component on a page, you can use subforms within a form to create separate regions whose input values can be submitted. Within a region, the values in the subform will be validated and processed only if a component inside the subform caused the values to be submitted. You can also nest a subform within another subform to create nested regions whose values can be submitted. For more information about subforms, see Section 4.5, "Using Subforms to Create Regions on a Page."
Example 9-2 shows a form with two subforms, each containing its own input components and Submit button. When a Submit button is clicked, only the input values within that subform will be submitted for processing.
Example 9-2 ADF Faces Subform Within a Form
<af:form> <af:subform> <af:panelFormLayout> <af:inputText value="#{myBean.firstName}" </af:inputText> <af:inputText value="#{myBean.lastName}" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> </f:facet> </af:panelFormLayout> </af:subform> <af:subform> <af:panelFormLayout> <af:inputText value="#{myBean.primaryPhone}" </af:inputText> <af:inputText value="#{myBean.cellPhone}" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> </f:facet> </af:panelFormLayout> </af:subform> </af:form>
Aside from the basic Submit button, you can add any other command component within a form and have it operate on any field within the form. ADF Faces provides a specialized command component: the resetButton
component, which when clicked, resets all the input and selection components within a form. That is, it updates all components whose values can be edited with the current values of the model. The resetButton
component is different from HTML reset in that the resetButton
component will reset the input components to their previous state which was partially or fully submitted successfully to the server without any validation or conversion error. For example, if a user enters value A
and clicks the Submit button, and then changes the value from A
to B
and clicks the resetButton
component, the value A
will be restored.
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.
In the Component Palette, from the Common Components panel, drag and drop a Form 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.
In the Component Palette, from the Common Components panel, drag and drop a Subform onto the page as a child to a form
component.
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:
Asubform
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.
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:
In the Component Palette, from the Common Components panel, drag and drop a Reset Button onto the page.
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.
Although input components include many variations, such as pickers, sliders, and a spinbox, the inputText
component is the basic input component for entering values. You can define an inputText
component as a single-row input field or as a text area by setting the rows
attribute to more than 1. However, if you want to create a multiple row text input, consider using the richTextEditor
component as described in Section 9.8, "Using the richTextEditor Component."
You can hide the input values from being displayed, such as for passwords, by setting the secret
attribute to true
. Like other ADF Faces components, the inputText
component supports label, text, and messages. When you want this component to be displayed without a label, you set the simple
attribute to true
. Figure 9-4 shows a single-row inputText
component.
You can make the inputText
component display more than one row of text using the rows
attribute. If you set the rows
attribute to be greater than one, and you set the simple
attribute to true, then the inputText
component can be configured to stretch to fit its container using the dimensionsFrom
attribute. For more information about how components stretch, see Chapter 8, "Geometry Management and Component Stretching." Figure 9-6 shows a multi-row inputText
component.
You can add multiple inputText
components to create an input form. Figure 9-5 shows an input form using two inputText
components.
You can also configure an insertTextBehavior
tag that works with command components to insert given text into an inputText
component. The text to be entered can be a simple string, or it can be the value of another component, for example the selected list item in a selectOneChoice
component. For example, Figure 9-6 shows an inputText
component with some text already entered by a user.
The user can then select additional text from a dropdown list, click the command button, and that text appears in the inputText
component as shown in Figure 9-7.
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:
In the Component Palette, from the Common Components panel, drag and drop an Input Text onto the page.
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.
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.
Note:
The placeholder value will only work on browsers that fully support HTML5.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."
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 selectinherit
, and no ancestor components define the editable
value, then the value always
is used.The insertTextBehavior
tag works with command components to insert given text into an inputText
component. The text to be entered can be a simple string, or it can be the value of another component, for example the selected list item in a selectOneChoice
component. To allow text to be inserted into an inputText
component, add the insertTextBehavior
tag as a child to a command component that will be used to insert the text.
Note:
TheinsertTextBehavior
tag cancels server-side event delivery automatically; actionListener
or action
attributes on the parent command component will be ignored. If you need to also trigger server-side functionality, you must add an custom client listener to deliver the server-side event. For more information, see Section 5.4, "Sending Custom Events from the Client to the Server."Before you 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
.
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."
In the Component Palette, from the Operations panel, 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 of the insertTextBehavior
component 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-8 in horizontal layout, and in Figure 9-9 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-10.
You can also configure the inputNumberSlider
and inputRangeSlider
components to add a play/pause button that animates the slider across the component's increment values, as shown in Figure 9-11.
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-12.
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:
In the Component Palette, from the Common Components panel, drag and drop an Input Number Slider or Input Range Slider 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:
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.
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."
Expand the Other section and set AnimationInterval to a value in milliseconds. Default value is zero.
If the value is greater than zero, a play button appears below the component. When clicked, it animates the slider across its increment values, stopping at each increment for the specified number of milliseconds. While animation is playing, the play button changes to a pause button that stops the animation at the current increment value.
For example, the animationInterval
value of the inputRangeSlider
component in Figure 9-11 is 999
.
The inputNumberSpinbox
component allows the user to scroll through a set of numbers to select a value.
To add an inputNumberSpinbox component:
In the Component Palette, from the Common Components panel, drag and drop an Input Number Spinbox onto the page.
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.
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."
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 selectinherit
, and no ancestor components define the editable
value, then the value always
is used.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-13 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-14. 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, as shown in Figure 9-15.
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:
In the Component Palette, from the Common Components panel, drag and drop an Input Color onto the page.
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-16.
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
.
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.
Note:
The placeholder value will only work on browsers that fully support HTML5.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.
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 selectinherit
, and no ancestor components define the editable
value, then the value always
is used.The inputDate
component allows the user to either enter or select a date.
To add an inputDate component:
In the Component Palette, from the Common Components panel, drag and drop an Input Date onto the page.
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.
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 thedisableDaysOfWeek
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.
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.
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 selectinherit
, 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.
Note:
The placeholder value will only work on browsers that fully support HTML5.By default, the inputDate
component displays a drop down list of time zones if the associated converter is configured to do so, for example, if you include the timezone placeholder z
in the converter's pattern. The end user can only modify the timezone using this list. The list is configured to display the most common time zones.
However, there may be times when you need to display the list of time zones outside of the inputDate
component. For example, on a Application Preferences page, you may want to use a selectOneChoice
component that allows the user to select the time zone that will be used to display all inputDates
in the application. A backing bean would handle the conversion between the time zone ID and the java.util.TimeZone object
. Converters for the inputDate
instances in the application would then bind the time zone to that time zone object.
You can access this list using either an API on the DateTimeUtils
class, or using an EL expression on a component.
Following are the methods on DateTimeUtils
class:
getCommonTimeZoneSelectItems ()
: Returns a list of commonly used time zones.
getCommonTimeZoneSelectItems (String timeZoneId)
: Returns a list of commonly used time zones, including the given time zone if it is not part of the list.
To access this list using EL, use one of the following expressions:
af:getCommonTimeZoneSelectItems
For example:
<f:selectItems value="#{af:getCommonTimeZoneSelectItems()}" id="tzones2" />
af:getMergedTimeZoneSelectItems (id)
For example:
<f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" />
If you will be using an inputDate
component and a selection list for its time zone on the same page, you must clear out the local value for the inputDate
's timezone to ensure that the value binding for the selection takes precedence. Otherwise, a non-null local value will take precedence, and the inputDate
component will not appear to be updated.In Example 9-4, the backing bean has a reference using the binding attribute to the inputDate
component. When the user picks a new time zone, the id is set and the code gets the converter for the inputDate
and clears out its time zone. When the page is rendered, since the local value for the converter's time zone is null, it will evaluate #{demoInput.preferredTimeZone}
and obtain the updated time zone.
Example 9-4 Using an inputDate and Time Zone Selection List Together
<af:selectOneChoice label="Select a new timezone" value="#{demoInput.preferredTimeZoneId}" autoSubmit="true"> <f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" /> </af:selectOneChoice> <af:inputDate label="First inputDate with timezone bound" id="bound1" partialTriggers="tzpick" binding="#{demoInput.boundDate1}"> <af:convertDateTime type="both" timeStyle="full" timeZone="#{demoInput.preferredTimeZone}"/> </af:inputDate> DemoInputBean.java public void setPreferredTimeZoneId(String _preferredTimeZoneId) { TimeZone tz = TimeZone.getTimeZone(_preferredTimeZoneId); setPreferredTimeZone (tz); this._preferredTimeZoneId = _preferredTimeZoneId; } public void setPreferredTimeZone(TimeZone _preferredTimeZone) { this._preferredTimeZone = _preferredTimeZone; DateTimeConverter conv1 = (DateTimeConverter) _boundDate1.getConverter(); conv1.setTimeZone(null); }
The selection components allow the user to select single and multiple values from a list or group of items. ADF Faces provides a number of different selection components, ranging from simple boolean radio buttons to list boxes that allow the user to select multiple items. The list of items within a selection component is made up of a number of selectItem
components
All the selection components except the selectItem
component delivers the ValueChangeEvent
and AttributeChangeEvent
events. The selectItem
component only delivers the AttributeChangeEvent
event. You must create a valueChangeListener
handler or an attributeChangeListener
handler, or both for them.
The selectBooleanCheckbox
component value must always be set to a boolean and not an object. It toggles between selected and unselected states, as shown in Figure 9-17.
The selectBooleanCheckbox
component also provides a third mixed state that indicates that the component is neither selected or cleared, as shown in Figure 9-18. Clicking a mixed state checkbox makes it selected. It toggles between the selected and cleared states, but it does not return to the mixed state by clicking, or any other click action.
The selectBooleanRadio
component displays a boolean choice, and must always be set to a boolean. Unlike the selectBooleanCheckbox
component, the selectBooleanRadio
component allows you to group selectBooleanRadio
components together using the same group
attribute.
For example, say you have one boolean that determines whether or not a user is age 10 to 18 and another boolean that determines whether a user is age 19-100. As shown in Figure 9-19, the two selectBooleanRadio
components can be placed anywhere on the page, they do not have to be next to each other. As long as they share the same group
value, they will have mutually exclusive selection, regardless of their physical placement on the page.
Tip:
EachselectBooleanRadio
component must be bound to a unique boolean.You use the selectOneRadio
component to create a list of radio buttons from which the user can select a single value, as shown in Figure 9-20.
You use the selectManyCheckbox
component to create a list of checkboxes from which the user can select one or more values, as shown in Figure 9-21.
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-22.
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-23.
The selectOneChoice
component creates a menu-style component, which allows the user to select a single value from a dropdown list of items. The selectOneChoice
component is intended for a relatively small number of items in the dropdown list.
Best Practice:
If a large number of items is desired, use aninputComboboxListOfValues
component instead. For more information, see Chapter 11, "Using List-of-Values Components."The selectOneChoice
component is shown in Figure 9-24.
You can configure the selectOneChoice
component to display in a compact mode, as shown in Figure 9-25. 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-26.
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-27.
By default, all selectItem
child components are built when the selectManyChoice
component is built, as the page is rendered. However, if the way the list items are accessed is slow, then performance can be hampered. This delay can be especially troublesome when it is likely that the user will select the items once, and then not change them on subsequent visits. For example, suppose you have a selectManyChoice
component used to filter what a user sees on a page, and that the values for the child selectItem
components are accessed from a web service. Suppose also that the user is not likely to change that selection each time they visit the page. By default, each time the page is rendered, all the selectItems
must be built, regardless of whether or not the user will actually need to view them. Instead, you can change the contentDelivery
attribute on the selectManyChoice
component from immediate
(the default) to lazy
. The lazy
setting causes the selectItem
components to be built only when the user clicks the dropdown.
For both immediate
and lazy
, when the user then makes a selection, the values of the selected selectItem
components are displayed in the field. However when lazy content delivery is used, on subsequent visits, instead of pulling the selected values from the selectItem
components (which would necessitate building these components), the values are pulled from the lazySelectedLabel
attribute. This attribute is normally bound to a method that returns an array of Strings
representing the selected items. The selectItem
components will not be built until the user goes to view or change them, using the dropdown.
Note that there are limitations when using the lazy
delivery method on the selectManyChoice
component. For more information about content delivery for the selectManyChoice
component and its limitations, see Section 9.6.2, "What You May Need to Know About the contentDelivery Attribute on the SelectManyChoice Component."
For the following components, if you want the label to appear above the control, you can place them in a panelFormLayout
component.
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.7.1, "How to Set Property Values on the Client"):
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.
In the Component Palette, from the Common Components panel, drag and drop the selection component onto the page.
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 aselectBooleanRadio
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.
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 |
---|---|
|
Layout: Set to |
|
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 |
|
SelectAllVisible: Set to |
|
Mode: Set to |
|
UnselectedLabel: Enter text for the option that represents a value of |
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 Note that if your selection components uses ADF Model binding, this value will be ignored. |
|
Group: Enter a group name that will enforce mutual exclusivity for all other |
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 selectinherit
, and no ancestor components define the editable
value, then the value always
is used.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."
If you want the af:selectBooleanCheckbox
component to show the indeterminate (or mixed) state that indicates that the component is neither selected or cleared, expand the Advanced section, and set the nullValueMeans attribute to mixed
.
The user cannot make the selectBooleanCheckbox
component into the mixed state with a single click. For example, a checkbox can be used to show the mixed state when some, not all, children options of the checkbox are enabled or disabled. The mixed state changes to the selected state when all its children options are enabled, and it changes to the unselected state when all the children options under it are disabled. This behavior is not automatic and needs to be managed by backend application code.
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 Label. This will be the text that is displayed in the list.
Expand the Behavior section, and set Disabled to true
if you want the item to appear disabled in the list.
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.
By default, the selectOneChoice
component passes the index value of the selected component to its list binding. If the first value of the selectOneChoice
component is blank or a label (such as "<select a value>"), it passes 0
(an integer value) instead of an empty value, or a null
value. If the selectOneChoice
component is a required component with its default selected item set to an empty value and the user submits the data without changing the selected item in the selectOneChoice
component, this behavior might cause a validation error at the client-side as it could not map the passed value of 0
to an actual value or a no-selection item.
To make the no-selection item of selectOneChoice
to a null
value, set the oracle.adf.view.PASS_NULL_FOR_NO_SELECTION_ITEM
parameter to true
in adf-settings.xml
.
Example 9-5 shows sample code of adf-settings.xml
where oracle.adf.view.PASS_NULL_FOR_NO_SELECTION_ITEM
is set to true
.
Example 9-5 Setting passNullForNoSelectionItem parameter in adf-settings.xml
<?xml version="1.0" encoding="UTF-8" ?> <adf-settings xmlns="http://xmlns.oracle.com/adf/settings"> <adf-properties-settings xmlns="http://xmlns.oracle.com/adf/proeprties/settings"> <default-values> <property-default name= "oracle.adf.view.PASS_NULL_FOR_NO_SELECTION_ITEM" value="true" /> </default-values> </adf-properties-settings> </adf-settings>
When passNullForNoSelectionItem
is set to true
, Faces List Binding builds the item list to use null
value for no-selection item.
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-28.
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-29. 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-6 shows a sample selectOrderShuttle
component that allows the user to select the top five file types from a list of file types.
Example 9-6 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-30.
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:
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.
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.
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.
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 theshortDesc
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-31 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:
In the Component Palette, from the Operations panel, drag a Client Listener 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-7.
Example 9-7 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-8, AdfShuttleUtils.getLastSelectionChange
is called to get the value of the last selected item
Example 9-8 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-32 shows the rich text editor component in standard rich text editing Mode.
Figure 9-33 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 provides a footer facet that you can use to display additional information, or to add user interface elements. For example, Figure 9-34 shows the richTextEditor
component with a character counter in its footer facet
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>
). The richTextEditor
component also does not support links at design-time.
On the client, the richTextEditor
component does not support getValue
and setValue
methods. There is no guarantee the component's value on the client is the same as the value on the server. Therefore, the richTextEditor
does not support client-side converters and validators. Server-side converters and validators will still work.
The rich text editor delivers ValueChangeEvent
and AttributeChangeEvent
events. Create valueChangeListener
and attributeChangeListener
handlers for these events as required.
You can also configure the richTextEditorInsertBehavior
tag, which works with command components to insert given text into the richTextEditor
component. The text to be entered can be a simple string, or it can be preformatted text held, for example, in a managed bean.
By default, the toolbar in the richTextEditor
component allows the user to change many aspects of the text, such as the font, font size and weight, text alignment, and view mode, as shown in Figure 9-35.
Figure 9-36 shows a toolbar that has been customized. Many of the toolbar buttons have been removed and a toolbar with a custom toolbar button and a menu have been added.
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:
In the Component Palette, from the Common Components panel, drag and drop a Rich Text Editor onto the page.
Expand the Common section of the Property Inspector and set the value
attribute.
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.
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."
Expand the Other section and set the DimensionsFrom property to one of the following:
auto
: Resize the richTextEditor
component and get dimensions from its container component, or its own content.
If the parent component to richTextEditor
component allows stretching of its child, then the richTextEditor
component will stretch to fill the parent component. If the parent component does not allow stretching, then the richTextEditor
component gets its dimensions from the content.
If the richTextEditor
component is inside a container component, it gets its dimensions from its parent component. If there is no parent component, the richTextEditor
component gets resized as per its content.
content
: Resize the richTextEditor
component and get dimensions from its own content. This is the default value.
parent
: Resize the richTextEditor
component and get its dimensions from inlineStyle
.
If inlineStyle
is not specified, it automatically gets its dimensions from the container component. If there is no container component and inlineStyle
is not specified, the richTextEdito
r component gets its dimensions from the specified skin.
For more information about how components stretch, see Chapter 8, "Geometry Management and Component Stretching."
Note:
You can also specify an EL expression that evaluates to a String value ofauto
, content,
or parent
.Tip:
You can set the width of arichTextEditor
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.
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
.
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."
In the Component Palette, from the Operations panel, 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-9 shows preformatted text as the value for an attribute in the demoInput
managed bean.
Example 9-9 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-10 shows how the text is referenced from the richTextEditorInsertBehavior
tag.
Example 9-10 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.
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.
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-36, 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 withcustomToolbar
.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."
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.
UIWebView
is a user interface control used in iOS applications. It allows a developer to embed a web browser within the ADF application, allowing access to web pages without leaving the application.
ADF Faces now supports the default UIWebView
user-agent for richTextEditor
in ADF Faces applications. The UIWebView
user-agent is a short string that applications send to identify themselves to web servers when accessing different HTML pages.
When your ADF application connects to a website, it includes a User-Agent
field in its HTTP header. The contents of the user-agent field vary from application to application. Each application has its own, distinctive user-agent. Essentially, a user-agent identifies the browser version and the operating system of the device.
The web server can use this information to serve different web pages to different web browsers and different operating systems. For example, a website could send mobile pages to mobile browsers or send a Please upgrade your browser message
to supported browsers. The following example shows a typical UIWebView
user-agent for an application:
Mozilla/5.0 (iPhone; CPU iPhone OS 8_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12D508
Note:
Oracle ADF supports different browsers for desktop and mobile devices. For the list of supported browsers, click the Certification Information link that appears for your release on the OTN Documentation page athttp://www.oracle.com/technetwork/developer-tools/jdev/documentation/index.html
.The inputFile
component provides users with file uploading and updating capabilities. This component allows the user to select a local file and upload it to a selectable location on the server. To download a file from the server to the user, see Section 18.4.1, "How to Use a Command Component to Download Files."
The inputFile
component delivers the standard ValueChangeEvent
event as files are being uploaded, and it manages the loading process transparently. The value
property of an inputFile
component is set to an instance of the org.apache.myfaces.trinidad.model.UploadedFile
class when a file is uploaded.
To initiate the upload process, you can create an action component such as a command button, as shown in Figure 9-37.
Once a file has been uploaded, and so the value of the inputFile
is not null (either after the initial load is successful or it has been specified as an initial value), you can create an Update button that will be displayed instead of the Browse button, as shown in Figure 9-38. This will allow the user to modify the value of the inputFile
component.
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-39.
By default, the inputFile
component allows upload of one file, but it can be configured to upload multiple files. Figure 9-40 shows the inputFile
component configured to upload multiple files.
The user can select multiple files in the File Upload dialog that opens through the Browse button, or drag-and-drop multiple files in the drop section of the component. When files appear in the drop section, the user clicks Upload to upload the files, as shown in Figure 9-42.
Using Javascript APIs, you can configure the inputFile
component to utilize custom user interface elements. For example, Figure 9-41 shows the inputFile
component with a description field that the user may use to enter a brief description of the selected file.
For more information about Javascript APIs that you can use to configure the inputFile
component, see the documentation of class AdfFileUploadManager
in Oracle Fusion Middleware Javascript API Reference for Oracle ADF Faces.
For security reasons, the following attributes cannot be set from the client:
disabled
(unless the unsecure
property is set. For more information, see Section 3.7.2, "How to Unsecure the disabled Property.")
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 ADF Faces 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-11.
Example 9-11 Using valueChangeListener to Display Upload Message
JSF Page Code -----> <af:form usesUpload="true" id="f1"> <af:inputFile label="Upload:" valueChangeListener="#{managedBean.fileUploaded}" id="if1"/> <af:commandButton text="Begin" id="b1"/> </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-12.
Example 9-12 Binding the Value to a Managed Bean
JSF Page Code ----> <af:form usesUpload="true"> <af:inputFile label="Upload:" value="#{managedBean.file}" id="if1"/> <af:commandButton text="Begin" action="#{managedBean.doUpload}" id="b1"/> </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; }
Note:
If you are using theinputFile
component to upload multiple files, note that the return type of event.getNewValue()
is List<UploadedFile>
, instead of UploadedFile
. The value binding for the managed bean is also List<UploadedFile>
, not UploadedFile
.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.
In the Component Palette, from the Common Components panel, drag and drop an Input File onto the page.
Set value to be the class created in Step 1.
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 selectinherit
, and no ancestor components define the editable
value, then the value always
is used.From the Component Palette, drag and drop any 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.
Use the uploadType
and maximumFiles
attributes to configure the inputFile
component to upload multiple files.
To configure an inputFile component to upload multiple files:
In the form, select the inputFile
component.
In the Property Inspector, expand the Appearance section and set the following:
autoHeightRows
: Specify the number of rows used to size the height of the inputFile
component. The value must be equal to, or lower than, the value of rows
.
rows
: Specify the number of files that will appear in the drop section. By default, it is set to 5.
Expand the Advanced section and set the maximumFiles
attribute to specify the number of maximum files the user can upload. By default, it is set to 1 and allows upload of one file only.
Expand the Behavior section and set the uploadType
attribute to specify whether the files would be uploaded automatically, or the user would have to click Upload button to upload files.
Table 9-3 lists the possible values of the uploadType
attribute.
Table 9-3 uploadType Values for the inputFile Component
Value | Description |
---|---|
|
Upload one file only. The drop section, where the user can drag-and-drop files, is not displayed. |
|
Show the drop section and enable upload of multiple files. The upload starts immediately when the files appear in drop section. If |
|
Show the drop section and enable upload of multiple files. The upload starts when the Upload button is clicked. If |
|
Upload multiple files. The upload starts immediately when the files appear in the drop section. By default, If |
|
Upload multiple files. The upload starts when the Upload button is clicked. If |
To remove an uploaded file from the drop section, or cancel upload of a file that is being uploaded, click the Cancel icon next to the file name and the progress bar. To cancel upload of all files, click the Stop Uploading button, as shown in Figure 9-43.
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-13.
Example 9-13 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> <context-param> <!-- Maximum file size that can be uploaded.--> <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE</param-name> <!-- Use 5,000K --> <param-value>5120000</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-13 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.
The inputFile
component uses HTML 5 to support the drag-and-drop functionality and upload of multiple files. In browsers that do not support HTML 5, a Java applet is used for drag-and-drop functionality and upload of multiple files, as shown in Figure 9-44.
If the browser does not support HTML5 and Java is also not available, then the drop section in the inputFile
component is not displayed.
Note:
If you are using OracleAS Single Sign-On (SSO), you might need to configure themod_osso.conf
file that enables single sign-on for Oracle HTTP Server. The file is located at ORACLEOHS_HOME
/ohs/conf/
, where ORACLEOHS_HOME
refers to the home directory of the Oracle HTTP server installation. The configuration is required for the upload applet to function properly in non-HTML5 browsers.
Update the mod_osso.conf
file with the following parameters:
OssoSecureCookies off
OssoHTTPOnly Off
Header unset Pragma
OssoSendCacheHeaders off
For more information about OracleAS Single Sign-On, see the chapter on configuring Single Sign-On using OracleAS SSO in the Oracle Fusion Middleware Application Security Guide.
The inputFile
component can only upload files that are smaller than 2 GB when in single file upload mode. In multiple file upload mode, the inputFile
component can upload files greater than 2 GB, by default, by splitting them into chunks of 2 GB in size. The chunk size can be controlled by the parameter org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE
in web.xml
whose default and maximum value is 2 GB. For example:
<context-param> <!-- Maximum file chunk size that can be uploaded.--> <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE</param-name> <!-- Use 1,000 MB as chunk size --> <param-value>1000000000</param-value> </context-param>
Note that not all browsers support the uploading of large files using the chunk functionality. For more information, see Oracle JDeveloper Release Notes on Oracle Technology Network.
After uploading all files, you must ensure that the form is submitted, else the inputFile
component data will not be uploaded to the server. If autoSubmit
is set to true
on the inputFile
component, then the form is submitted automatically after all the files have finished uploading. After the form has been submitted, the inputFile
component is refreshed and the file list of the drop section becomes empty so that more files can be uploaded. To show the list of uploaded files, add ValueChangeListener
or bind the value to a managed bean, as described in Example 9-11.
The af:codeEditor
component provides an in-browser code editing solution and enables the user to display and edit program code at runtime in the Fusion web application. The input field of the code editor component accepts text, and provides some common code editing functionalities such as a toolbar, syntactical color coding of keywords, code completion, basic validation, highlighting errors, and a message pane for logs. Using the code editor, the user won't need to run a separate IDE to test program code for errors or warnings.
The code editor component supports Javascript, XML, and Groovy languages, as shown in Figure 9-45.
The code editor component provides the following functionalities:
Line numbering
Undo and redo operations (also possible using keyboard shortcuts Ctrl+Z and Ctrl+Y)
Jump to a specific line
Find and replace
Color-coded text
Highlighting syntaxes and search terms
Code completion
Auto-indent
Auto-format
Message pane for error messages
Support for large files with more than thousand lines of code
To add or edit code in code editor, the user can simply click in the editor area and start typing. Ctrl+Spacebar displays a contextual list of hints for code completion. To use other editing features, press F2 to enable edit mode. Once in edit mode, the user can Tab to indent and Shift+Tab to backward-indent a line of code. With edit mode disabled, Tab and Shift+Tab provide navigation to the next and previous components.
The user can use the toolbar (shown in Figure 9-46) to undo and redo changes, search and replace text, and jump to a specific line number.
To search for a string, enter the search term in the Find field, and click Find Next or Find Previous icons to locate the search string in the code editor. Figure 9-47 shows the Find field of the toolbar used to search a string in the code editor.
To search a case sensitive string, or replace a search term, open the Find and Replace dialog from the Find and Replace icon and perform the operations from the dialog, as shown in Figure 9-48.
To jump to a specific line number, enter the number in the Go to Line field and click Jump to line, as shown in Figure 9-49.
The code editor component can be configured to list all warnings and errors in a message pane that is also provided with the code editor component. Figure 9-50 shows the message pane listing all XML errors noticed by the XML parser running on the server.
The message pane is a non-editable region that resides below the text area of the code editor. It is used to display code-related status information, such as validation support for code compilation, and any error or warning messages. Clicking a message in the message pane navigates you to the respective code line in the code editor.
You can also configure the code editor to programmatically add various types of markers. Figure 9-51 shows the code editor with error, critical, warning, and information markers.
When you add a codeEditor
component, use the language
attribute to configure the programming language used by the code editor.
To add a codeEditor component:
In the Component Palette, from the Common Components panel, drag and drop a Code Editor component onto the page.
In the Property Inspector, expand the Common section, and set Language. The valid values are javascript
, groovy
, and xml
.
Expand the Appearance section, and set the following:
LineNumbers: Specify whether line numbers should be visible in the code editor.
The valid values are yes
and no
.
Simple: Set to true
if you do not want the label to be displayed.
Expand the Behavior section, and set the following
ReadOnly: Specify whether the code in the code editor can be edited or displayed as output-style text.
Disabled: Specify whether or not the code editor should be disabled.