You use forms when you need to collect or display a row of data. For example, the Summit sample application for Oracle ADF contains a panel that allows users to update information about their customers as shown in Figure 31-1. This form was created by dragging and dropping the Customers collection from the Data Controls panel and then selecting the fields to display.

Figure 31-1 Customer General Information Form in the Summit ADF Sample Application

Description of "Figure 31-1 Customer General Information Form in the Summit ADF Sample Application"

When you create a form, you can also choose to add navigation, so that the user can navigate quickly between records, as shown in Figure 31-2.

Figure 31-2 Navigate Between Records in a Form

Description of "Figure 31-2 Navigate Between Records in a Form "

You can also add command buttons that invoke processing on the row displayed in the form. For example, you can change values for a record and save those changes in an edit form, or you can create an input form that allows users to create a new record. Figure 31-3 shows an input form where a user can create a new order.

Figure 31-3 Input Form

Description of "Figure 31-3 Input Form"

You may find it helpful to understand other Oracle ADF features before you implement your databound pages. Following are links to other functionality that you may find useful.

• ADF view objects: Much of how the components display and function in the form is controlled by the corresponding view objects. See Defining SQL Queries Using View Objects.

• ADF application modules: The Data Controls panel, from which you drag databound components to your pages, is populated with representations of view objects that you have added to application modules. See Implementing Business Services with Application Modules.

• Adapter-based data controls: If you are using other types of business services, such as EJB components or web services, you can create data controls for those business services as described in Creating and Configuring EJB Data Controls in Developing Applications with Oracle ADF Data Controls.

• ADF Model and data binding: When you create forms in an ADF web application, you use ADF Model and data binding. See Using ADF Model in a Fusion Web Application.

• ADF Faces: You also use ADF Faces UI components. For detailed information about developing with ADF Faces, see Introduction to ADF Faces in Developing Web User Interfaces with Oracle ADF Faces.

• Advanced UI controls: Basic forms use input and output components. You can also use more advanced components, such as lists, tables, trees, search forms, LOV components, graphs, gauges, treemaps, and more. See the remaining chapters in Creating a Databound Web User Interface .

• Task flows: If your form takes part in a transaction, for example an input form, then you may need to use an ADF task flow to invoke certain operations before or after the form is rendered. See Creating ADF Task Flows .

• Page lifecycle: For information about how forms work with the page lifecycle, see Understanding the Fusion Page Lifecycle .

• Validation: You may want certain fields to be validated before they are submitted to the data store. See Defining Validation and Business Rules Declaratively and Using Validation in the ADF Model Layer .

• Active data: If your application uses active data, then you can have the data in your UI components update automatically, whenever the data in the data source changes. See Using the Active Data Service .

1. From the Data Controls panel, select an attribute from a collection. For a description of the icons that represent attributes and other objects in the Data Controls panel, see Using the Data Controls Panel.

   For example, Figure 31-4 shows the LastName attribute under the Customers collection of the BackOfficeAppModuleDataControl data control in the Summit ADF sample application. This is the attribute to drop to display, update, or insert the customer's last name.

   Figure 31-4 Attributes Associated with a Collection in the Data Controls Panel

   
   Description of "Figure 31-4 Attributes Associated with a Collection in the Data Controls Panel"
2. Drag the attribute onto the page, and from the context menu choose the type of UI component to display or collect the attribute value, as shown in Figure 31-5.

   Figure 31-5 Context Menu When Dropping Attributes on a Page

   
   Description of "Figure 31-5 Context Menu When Dropping Attributes on a Page"

   For an attribute, you are given the following choices:

   • Text:

     • ADF Input Text w/ Label: Creates an ADF Faces inputText component in which the label attribute is populated. In addition, a nested validator component is created, which you can use to add client-side validation.

       Tip:

       For more information about the various attributes of the inputText component, see the Using Input Components and Defining Forms chapter of Developing Web User Interfaces with Oracle ADF Faces.

     • ADF Input Text: Creates an ADF Faces inputText component without a label. In addition, a nested validator component is generated, which you can use for client-side validation.

     • ADF Output Text w/ Label: Creates a panelLabelAndMessage component that holds an ADF Faces outputText component. The label attribute on the panelLabelAndMessage component is populated.

     • ADF Output Text: Creates an ADF Faces outputText component.

     • ADF Output Formatted w/Label: Same as ADF Output Text w/Label, but uses an outputFormatted component instead of an outputText component. The outputFormatted component allows you to add a limited amount of HTML formatting. For more information, see the Displaying Output Text and Formatted Output Text section of Developing Web User Interfaces with Oracle ADF Faces.

     • ADF Output Formatted: Same as ADF Output Formatted w/Label, but without the label.

     • ADF Label: An ADF Faces outputLabel component.

   • List of Values: Creates ADF LOV lists. For more information about how these lists work for Business Components, see Working with List of Values (LOV) in View Object Attributes. For more information on how these lists work for adapter-based data controls, see Creating List of Values Objects in Developing Applications with Oracle ADF Data Controls. For more information about using the lists on a JSF page, see Creating a Selection List.

   • Single selections: Creates single selection lists. For more information about creating lists on a JSF page, see Creating a Selection List.

   Note:

   These selections are your choices by default. However, the list of components available to use for an attribute can be configured as a control hint on the associated entity or view object. For more information, see Defining Attribute Control Hints for Entity Objects and Defining UI Hints for View Objects. For information on adding control hints for adapter-based data controls, see How to Set UI Hints on Attributes in Developing Applications with Oracle ADF Data Controls.

   For the purposes of this chapter, only the text components (and not the lists) will be discussed.

Among other things, when you drag an attribute onto a JSF page and drop it as a UI component, a page definition file is created for the page (if one does not already exist). For a complete account of what happens when you drag an attribute onto a page, see What Happens When You Use the Data Controls Panel. Bindings for the iterator and attributes are created and added to the page definition file. Additionally, the necessary JSPX or JSF page code for the UI component is added to the JSF page.

1. From the Data Controls panel, select the collection that represents the data you wish to display. Figure 31-6 shows the Customers collection for the BackOfficeAppModuleDataControl data control.

   Figure 31-6 CustomerVO Object in the Data Controls Panel

   
   Description of "Figure 31-6 CustomerVO Object in the Data Controls Panel"
2. Drag the collection onto the page, and from the context menu choose ADF Form.

   Figure 31-7 Context Menu When Dropping a Collection to a Page

   
   Description of "Figure 31-7 Context Menu When Dropping a Collection to a Page"
3. In the Create Form dialog, configure your form.

   • You can exclude attributes from appearing in the form.

   • If you do not select the Read-Only Form checkbox, ADF inputText components are used for most attributes. Each inputText component has the label attribute populated. By default, the label obtains its value from a binding to the label property on the associated binding object.

     Attributes that are dates use the InputDate component.

     If a control type control hint has been created for an attribute, or if the attribute has been configured to be a list, then the component set by the hint is used instead.

     InputText components contain a validator tag that allows you to set up client-side validation for the attribute. If the attribute is a number or a date, a converter is also included.

     Tip:

     For more information about the various attributes of the inputText component, see the Using Input Components and Defining Forms chapter of Developing Web User Interfaces with Oracle ADF Faces.

   • If you select the Read-Only Form checkbox, read-only outputText components are used. Since the form is meant to display data, no validator tags are added (though converters are included). Attributes of type Date use the outputText component when in a read-only form. All components are placed inside panelLabelAndMessage components, which have the label attribute populated, and are placed inside a panelFormLayout component. This ensures that the labels are aligned appropriately with the outputText components at runtime.

   • You can elect to include navigational controls that allow users to navigate through all the data objects in the collection. For more information, see Incorporating Range Navigation into Forms.

   • You can also include a Submit button to submit the HTML form and apply the data in the form to the bindings as part of the JSF/ADF page lifecycle. For additional help in using the dialog, click Help.

4. If you are building a form that allows users to update data, you now need to drag and drop an operation that will commit the changes to update the record. For more information, see Creating a Form to Edit an Existing Record.

Dropping an object as a form from the Data Controls panel has a similar effect as dropping a single attribute, except that multiple attribute bindings and associated UI components are created and all UI components are placed inside a panelFormLayout component. The attributes on the UI components (such as value) are bound to properties on that attribute's binding object (such as inputValue) or to the values of control hints set on the corresponding business object. The following example shows some of the code generated on the JSF page when you drop the Customers collection as a default ADF Form.

<af:panelFormLayout id="pfl1">
    <af:inputText value="#{bindings.Id.inputValue}" 
                  label="#{bindings.Id.hints.label}"
                  required="#{bindings.Id.hints.mandatory}"
                  columns="#{bindings.Id.hints.displayWidth}"
                  maximumLength="#{bindings.Id.hints.precision}"
                  shortDesc="#{bindings.Id.hints.tooltip}" id="it1">
        <f:validator binding="#{bindings.Id.validator}"/>
        <af:convertNumber groupingUsed="false" pattern="#{bindings.Id.format}"/>
    </af:inputText>
    <af:inputText value="#{bindings.Name.inputValue}" 
                  label="#{bindings.Name.hints.label}"
                  required="#{bindings.Name.hints.mandatory}"
                  columns="#{bindings.Name.hints.displayWidth}"
                  maximumLength="#{bindings.Name.hints.precision}"
                  shortDesc="#{bindings.Name.hints.tooltip}" id="it2">
        <f:validator binding="#{bindings.Name.validator}"/>
    </af:inputText>
    <af:inputText value="#{bindings.Phone.inputValue}" 
                  label="#{bindings.Phone.hints.label}"
                  required="#{bindings.Phone.hints.mandatory}"
                  columns="#{bindings.Phone.hints.displayWidth}"
                  maximumLength="#{bindings.Phone.hints.precision}"
                  shortDesc="#{bindings.Phone.hints.tooltip}" id="it3">
        <f:validator binding="#{bindings.Phone.validator}"/>
    </af:inputText>
. . .
</af:panelFormLayout>

For more information about the code that is generated when you drop an item from the Data Controls panel, see What Happens When You Create a Text Field .

When you choose to create an input form using an object that contains a defined list of values (LOV), then a selectOneChoice component is created instead of an inputText component. For example, the CustomerVO view object contains defined LOVs for the CountryId and CreditRatingId attributes. When you drop the Customers data control object as an ADF Form, a dropdown list showing all values is created for each LOV (instead of an empty input text field). For more information about how these lists work, see Working with List of Values (LOV) in View Object Attributes. For more information on how these lists work for adapter-based data controls, see Creating List of Values Objects in Developing Applications with Oracle ADF Data Controls. For more information about using the lists on a JSF page, see Creating a Selection List.

1. From the Data Controls panel, drag the operation onto the page.
2. From the ensuing context menu, choose either ADF Button or ADF Link.

When you drop an operation to create a command component, JDeveloper:

• Defines an action binding in the page definition file for the associated operation

• Configures the iterator binding to use partial page rendering for the collection

• Inserts code in the JSF page for the command component

When the user clicks a command component, the form is submitted and then an action event is fired. Action events might affect only the user interface (for example, a link to change the locale, causing different field prompts to display), or they might involve some logic processing in the back end (for example, a button to navigate to the next record). That event object then takes information about the current data object from the iterator and then passes it to the action binding's method, which is bound to the command component through its actionListener attribute.

For example, when the user clicks a Delete button that was created from the ADF Delete operation, an action event is fired. This event object stores currency information about the current data object, taken from the iterator. Because the component's actionListener attribute is bound to the execute method of the Delete action binding, the Delete operation is invoked when the event fires. This method takes the currency information passed in the event object to determine which data object to delete.

Typically, the actionListener property's value is in the form of an EL expression. For example, if the value of the actionListener attribute is {bindings.Delete.execute}, the execute() method of the Delete action binding is called.

When you drop an operation or method as a command button, JDeveloper binds the button to the execute method for the operation or method. However, there may be occasions when you need to add logic before or after the existing logic. JDeveloper allows you to add logic to a declarative operation by creating a new method and property on a managed bean that provides access to the binding container. By default, this generated code executes the operation or method. You can then add logic before or after this code. JDeveloper automatically binds the command component to this new method, instead of to the execute property on the original operation or method. Now when the user clicks the button, the new method is executed. For more information, see Overriding Declarative Methods.

1. From the Data Controls panel, select the operation associated with the collection of objects on which you wish the operation to execute, and drag it onto the JSF page.

   For example, if you want to navigate forward through a collection of countries, you would drag the Next operation associated with the Countries collection. Figure 31-8 shows the operations associated with the Countries collection.

2. From the ensuing context menu, choose either ADF Button or ADF Link.

When you drop a navigation operation from the Data Controls panel, JDeveloper:

• Defines an action binding in the page definition file for the associated operations

• Configures the iterator binding to use partial page rendering for the collection

• Inserts code in the JSF page for the command components

• Inserts the partialSubmit attribute for the component in the JSF page and sets it to true in order to fire a partial page request when the button is clicked. For more information, see the Using Partial Triggers section of Developing Web User Interfaces with Oracle ADF Faces.

For more information on code generated for command components, see What Happens When You Create Command Components Using Operations.

The following example shows the code generated on the JSF page for navigation operation buttons.

<f:facet name="footer">
   <af:panelGroupLayout>
     <af:button actionListener="#{bindings.First.execute}"
                       text="First"
                       disabled="#{!bindings.First.enabled}"
                       partialSubmit="true" id="cb1"/>
     <af:button actionListener="#{bindings.Previous.execute}"
                       text="Previous"
                       disabled="#{!bindings.Previous.enabled}"
                       partialSubmit="true" id="cb2"/>
     <af:button actionListener="#{bindings.Next.execute}"
                       text="Next"
                       disabled="#{!bindings.Next.enabled}"
                       partialSubmit="true" id="cb3"/>
     <af:button actionListener="#{bindings.Last.execute}"
                       text="Last"
                       disabled="#{!bindings.Last.enabled}"
                       partialSubmit="true" id="cb4"/>
   </af:panelGroupLayoutr>
 </f:facet>

When the user clicks a navigation control button, an action event is fired. That event object then takes information about the current data object from the iterator and then passes it to the operation's method, which is bound to the button through its actionListener attribute.

For more information, see What Happens at Runtime: How Action Events and Action Listeners Work .

In addition, when a user clicks a navigation button, only those components associated with the same iterator as the button's action binding are processed through the lifecycle. For more information, see What You May Need to Know About Partial Page Rendering and Iterator Bindings.

You must use the navigation buttons to navigate through the records displayed in a form; you cannot use the browser's back or forward buttons. Because navigation forms automatically use PPR, only part of the page goes through the lifecycle, meaning that when you click a navigation button, the components displaying the data are refreshed and display new data, and you actually remain on the same page. Therefore, when you click the browser's back button, you will be returned to the page that was rendered before the page with the form, instead of to the previous record displayed in the form.

For example, say you are on a page that contains a link to view all current orders. When you click the link, you navigate to a page with a form and the first order, Order #101, is displayed. You then click Next and Order #102 is displayed. You click Next again, and Order #103 is displayed. If you click the browser's back button, you will not be shown Order #102. Instead, you will be returned to the page that contained the link to view all current orders.

When you create a navigable form using the Data Controls panel, the CacheResults property on the associated iterator is set to true. This ensures that the iterator's state, including currency information, is cached between requests, allowing it to determine the current object. If this property is set to false, navigation will not work.

1. From the Data Controls panel, drag the collection for which you wish to create the form, and choose ADF Form from the context menu.

   This creates a form using inputText components, which will allow the user to edit the data in the fields.

2. In the Create Form dialog, set the fields and buttons that you would like added to the form and click OK.
3. Optionally, from the Data Controls panel, select any additional operation associated with the collection that you would like to add to the form, drag it to the page, and choose ADF Button or ADF Link from the context menu.

   For example, if you want to be able to delete a country, you would select the Delete operation associated with the Countries collection. Figure 31-10 shows the operations associated with the Countries collection.

   Figure 31-10 Operations Associated with a Collection

   
   Description of "Figure 31-10 Operations Associated with a Collection"
4. Add operations to the page to save or cancel changes.

   If the page is not part of a transaction within a bounded task flow, then you need to create buttons that allow the user either to commit or roll back the changes. From the Data Controls panel, drag the Commit and Rollback operations associated with the root-level data control, and drop them as either a command button or a command link. Figure 31-11 shows the commit and rollback operations for the BackOfficeAppModuleDataControl data control.

   Figure 31-11 Commit and Rollback Operations for a Data Control

   
   Description of "Figure 31-11 Commit and Rollback Operations for a Data Control"

   If the page is part of a transaction within a bounded task flow, then you can simply enter Commit and Rollback as the values for the transaction resolution when creating the task flow return activity. For more information, see Managing Transactions in Task Flows.

   If you are basing the form on a data control that is based on business services other than ADF Business Components, the Commit and Rollback operations might not be available. For more information, see What You May Need to Know About Working With Data Controls for Stateless Business Services.

5. Optionally, change the autoSubmit property of each editable field to true.

   Doing so enables any user changes to be submitted to the page when tabbing out of the field and thus enabling the Commit and Rollback operations, if they have not already been enabled by another sequence of events, such as a change to a field plus a button click.

   You can access the autoSubmit property for a field by selecting the field and then scrolling to the Behavior section in the Properties window.

For information on what happens when you drop a collection on to a page, see What Happens When You Create a Form Using a Data Control Collection.

Dropping any data control operation as a command button causes code generation similar to when you drop navigation operations. For more information, see What Happens When You Create Command Components Using Operations.

The only difference is that the action bindings for the Commit and Rollback operations do not require a reference to the iterator, because they execute a method on the application module (the data control itself), as opposed to the iterator. Note that the Rollback action has the RequiresUpdateModel property set to false. This is because the model should not be updated before the operation is executed, since all changes need to be discarded. The following example shows the action bindings generated in the page definition file for these operations.

<action id="Commit" RequiresUpdateModel="true" Action="commitTransaction"
        DataControl="BackOfficeAppModuleDataControl"/>
<action id="Rollback" RequiresUpdateModel="false"
        Action="rollbackTransaction"
        DataControl="BackOfficeAppModuleDataControl"/>

Table 31-2 shows the built-in non-navigation operations provided on data controls and data control objects, along with the result of invoking the operation or executing an event bound to the operation. For more information about action events, see What Happens at Runtime: How Action Events and Action Listeners Work .

When you create user interfaces based on ADF Business Components services, any data changes that a user makes are not propagated to the underlying database until the user triggers the Commit operation through a command component.

For user interfaces that are based on data controls for stateless business services, such as stateless EJB session beans or RESTful web services, the Commit and Rollback operations are not available. In such cases, you can use custom methods to handle interactions with the underlying database. In the case of EJB data controls, any persistEntity and mergeEntity methods in the session bean are exposed through the Data Controls panel, and you can create command components from them. For more information, see About Commit Models for EJB Session Beans in Developing Applications with Oracle ADF Data Controls.

1. From the Data Controls panel, drag the ExecuteWithParams operation for the collection for which you wish to create the form, and choose ADF Parameter Form from the context menu.
2. In the Create Form dialog, select the parameters on which you want users to be able to query and click OK.
3. From the Data Controls panel, drag the corresponding collection, and drop it as the type of table or form that you want to display the results of the query based on the user input.

When you drop the ExecuteWithParams operation as a parameter form, JDeveloper:

• Inserts code in the JSF page for the form using inputText components bound to the attribute bindings, and a button component bound to the ExecuteWithParams operation.

• Defines the following in the page definition file:

  • A variable iterator for the attributes to use to access the variables (as opposed to a collection's iterator which is used for other forms).

  • A variableUsage variable for each parameter to hold the data values. These variables inherit the default value and UI control hints from the view object named bind variables to which they are bound. The variables are local, meaning they live only during a single request. Though they are carried across subsequent post-backs to the same form, they are forgotten (and re-initialized) when a user navigates to some other page.

  • An action binding for the operation that contains NamedData elements for each parameter. Each NamedData element is bound to a corresponding variable. These bindings allow the operation to access the value for the parameter upon execution.

  • Attribute bindings for the associated attributes.

The following example shows the executables and bindings in the page definition file that are created by dropping the SalesPeople collection's ExecuteWithParams operation on a page.

<executables>
  <variableIterator id="variables">
    <variableUsage DataControl="BackOfficeAppModuleDataControl"
                   Binds="SalesPeople.variablesMap.TitleIdBind"
                   Name="ExecuteWithParams_TitleIdBind" IsQueriable="false"/>
  </variableIterator>
  <iterator Binds="SalesPeople" RangeSize="25"  
            DataControl="BackOfficeAppModuleDataControl" 
            id="SalesPeopleIterator"/>
</executables>
<bindings>
  <action IterBinding="SalesPeopleIterator" id="ExecuteWithParams"
          RequiresUpdateModel="true"
          Action="executeWithParams">
    <NamedData NDName="TitleIdBind" NDType="java.lang.Integer" 
               NDValue="${bindings.ExecuteWithParams_TitleIdBind}"/>
  </action>
  <attributeValues IterBinding="variables" id="TitleIdBind">
    <AttrNames>
      <Item Value="ExecuteWithParams_TitleIdBind"/>
    </AttrNames>
  </attributeValues>
</bindings>

When you drop the collection that will be used to display the results of the parameter form, code is generated for a basic form, as described in What Happens When You Create a Form Using a Data Control Collection. In addition, if you use a table to display the results, the partialTriggers property on table is set to the command button in the parameter form.

When the page is rendered, the framework checks if the page is being rendered for the first time and if the exception list has any items. If both are false, then the framework executes the ExecuteWithParams action binding. This action binding executes the query, taking the values of the named data elements as values for the needed parameters.

1. In the Data Controls panel, expand the node for the collection object on which the form is based.
2. Expand the collection's Operations node and drag the CreateInsert operation to the edit form.

When you use an ADF Form to create an input form, JDeveloper:

• Creates an iterator binding for the collection and an action binding for the CreateInsert operation in the page definition for the method activity. The CreateInsert operation is responsible for creating a row in the row set and populating the data source with the entered data. In the page definition for the page, JDeveloper creates an iterator binding for the collection and attribute bindings for each of the attributes of the object in the collection, as for any other form. If you created command buttons or links using the Commit and Rollback operations, JDeveloper also creates action bindings for those operations.

• Inserts code in the JSF page for the form using ADF Faces inputText components, and in the case of the operations, button components.

When the CreateInsert button is clicked (or a method corresponding to that operation is called), the CreateInsert action binding is invoked, which executes the CreateInsertRow action, and a new blank instance for the collection is created.

Because the Create action is executed before the page is displayed, if you are populating the primary key using sequences, the next number in the sequence will appear in the input text field, unlike the rest of the fields, which are blank. The sequence number is displayed because the associated entity class contains a method that uses an eager fetch to generate a sequence of numbers for the primary key attribute. The eager fetch populates the value as the row is created. Therefore, using sequences works as expected with input forms.

However, if instead you've configured the attribute's type to DBSequence (which uses a database trigger to generate the sequence), the number would not be populated until the object is committed to the database. In this case, the user would see a negative number as a placeholder. To avoid this, you can use the following EL expression for the Rendered attribute of the input text field:

#{bindings.EmployeeId.inputValue.value > 0}

This expression will display the component only when the value is greater than zero, which will not be the case before it is committed. Similarly, you can simply set the Rendered attribute to false. However, then the page will never display the input text field component for the primary key.

If the data control on which your input form is based is a data control for a stateless business service, there is no built-in Commit operation for you to use to save changes back to the data source.

Instead, you need to use a custom method to save to the database. For more information, see What You May Need to Know About Working With Data Controls for Stateless Business Services .

ADF Faces provides the af:dynamicComponent tag that you can use to create model-driven forms and tables where the binding metadata and the tags used to display the bound content are determined at runtime.

The dynamic building of the bindings provides the following possibilities:

• Enables you to create pages where the fields displayed and the ADF Faces components used to display them are determined by the data model. Any changes to the data model, such as additional columns or changed UI hints are reflected in the page without having to redesign the page. For more information about UI hints on view objects, see Defining UI Hints for View Objects.

• Enables you to create pages based on polymorphic view objects, in which the fields available for a given record can differ depending on the record's base entity object. Since the fields to display are determined at runtime, you do not have to include fields in the page that may not apply to certain records or do coding in the view layer to adjust the fields that are displayed for a given record. For more information about building business components that work with multiple row types, see Defining Polymorphic View Objects.

You set display information using UI hints on a view object instead of configuring the information in the Create Form or Create Table dialog when you drop the control onto the page. Then if you want to change how the data displays, you need only change it on the view object, and all dynamic components bound to that view object will change their display accordingly.

Figure 31-13 shows a dynamic form at runtime that was designed by setting UI hints for attributes on the CustomerVO view object and then dropping the Customers data control collection as a dynamic form. Among the UI hints set were LABEL and DISPLAYHINT (the latter of which can be set to Hide in order to not include the given attribute in the dynamic form).

Figure 31-13 Dynamic Form Displays Based on Hints Set on the View Object

Description of "Figure 31-13 Dynamic Form Displays Based on Hints Set on the View Object"

The following ADF Faces components can be rendered at runtime when you use af:dynamicComponent at design time:

• af:inputText

• af:inputDate

• af:inputListOfValues

• af:selectOneChoice

• af:selectManyChoice

• af:selectOneListbox

• af:selectManyListbox

• af:selectOneRadio

• af:selectBooleanRadio

• af:selectBooleanCheckbox

• af:selectManyCheckbox

1. Set UI hints on the view object or data control structure definition file that corresponds to the collection for which you are creating the dynamic form.
2. Optionally, for the Category hint on each view object attribute, specify a category or click the New Category icon to create a new category.

   Any attributes that have the same category can be grouped together in dynamic forms that you create based on that view object.

3. Optionally, for any categories that you have created set the UI hints for the category's label and tooltip. These can be set in the UI Categories tab of the view object's overview editor.
4. From the Data Controls panel, select the collection that represents the view object.
5. Drag the collection onto the page, and from the context menu, choose ADF Form.
6. In the Create Form dialog, select the Fields Generated at Runtime checkbox.
7. If you have specified any categories for attributes, select the Include Field Groups checkbox in order for the form to group the attributes according to those categories.

When you drop a collection as a dynamic form on a page, the following things happen:

• The page definition is populated with a variableIterator binding, an iterator binding to the iterator, and a tree value binding.

• The JSF page is populated with one or more af:iterator and af:dynamicComponent tags. In addition, if the Include Field Groups option is selected, af:switcher and af:group tags are added.

When a page with dynamic components is rendered, the bindings are created just as they are when items are dropped from the Data Controls panel at design time, except that they are created at runtime.

At runtime, the iterator iterates over the set of attributes and instantiates a dynamicComponent for each attribute. The dynamic component uses its attributeModel property to obtain information from the iterator about the current attribute, such as label and control type. Each dynamicComponent then renders a component based on the metadata that is returned for the attribute.

If the DISPLAYHINT UI hint for an attribute is set to Hide, no component for the attribute is rendered.

If the dynamic form is created from a data control object that is based on a polymorphic view object, the rendered components depend on the row type for the currently selected record.

1. Open the page containing the dynamic component in the source editor.
2. Within the af:dynamicComponent tag, insert any validator and converter components that you want to use.
3. Within the each validator and converter tag, insert the disabled attribute and bind it to an EL expression that disables the tag for all attributes except for those to which you want to apply it.

   For example, the following expression would enable a validator only for the Hiredate attribute:

   #{attr.name == 'Hiredate' ? false : true}
   

<af:panelFormLayout id="pfl1">
  <af:iterator id="i1" value="#{bindings.EmpVO1.attributesModel.attributes}" 
                       var="attr">
    <af:dynamicComponent 
                  value="#{bindings[attr.containerName][attr.name].inputValue}" 
                  attributeModel="#{attr}" id="dc1"/>
      <af:convertDateTime disabled="#{attr.name == 'Hiredate' ? false : true}"
                          pattern="yyyy/MM/dd"/>
      <af:convertNumber disabled="#{attr.name == 'Sal' ? false : true}" 
                        pattern="#,###,###" />
      <af:validateLength disabled="#{attr.name == 'Job' ? false : true}"
                         maximum="10" hintMaximum="maxmum length is 10"/>
      <af:validateLongRange disabled="#{attr.name == 'Sal' ? false : true}" 
                            minimum="1000"/>
    </af:dynamicComponent>
  </af:iterator>
</af:panelFormLayout>

When you create a dynamic form, you essentially create a block of components that are rendered dynamically. It is possible place static components before and after that block of components, but you can not intersperse static components within that block.

The following example illustrates the granularity of mixing static and dynamic components that is possible. It consists of three af:group tags, the first and third of which contain static content and the second of which contains an af:iterator tag with a nested af:dynamicComponent tag.

<af:group title="static before dynamic" id="g1">
    <af:separator id="sp2"/>
    <af:inputText value="#{bindings.Empno.inputValue}" label="Static Empno"
                  required="#{bindings.Empno.hints.mandatory}"
                  columns="#{bindings.Empno.hints.displayWidth}"
                  maximumLength="#{bindings.Empno.hints.precision}"
                  shortDesc="#{bindings.Empno.hints.tooltip}" id="it1">
        <f:validator binding="#{bindings.Empno.validator}"/>
        <af:convertNumber groupingUsed="false" 
                          pattern="#{bindings.Empno.format}"/>
    </af:inputText>
</af:group>
<af:group title="dynamic part" id="g2">
    <af:separator id="sp3"/>
    <af:panelFormLayout id="pfl1">
        <af:iterator id="i1" value="#{bindings.EmpVO1.attributesModel.attributes}"
                     var="attr">
            <af:dynamicComponent 
                     value="#{bindings[attr.containerName][attr.name].inputValue}" 
                     id="dc1" attributeModel="#{attr}"/>
        </af:iterator>
    </af:panelFormLayout>
</af:group>
<af:group title="static after dynamic" id="g3">
    <af:separator id="sp4"/>
    <af:inputText value="#{bindings.Ename.inputValue}" label="Static Ename"
                  required="#{bindings.Ename.hints.mandatory}"
                  columns="#{bindings.Ename.hints.displayWidth}"
                  maximumLength="#{bindings.Ename.hints.precision}"
                  shortDesc="#{bindings.Ename.hints.tooltip}" id="it2">
        <f:validator binding="#{bindings.Ename.validator}"/>
    </af:inputText>
</af:group>
<af:button text="Back" id="cbb1" action="back"/>

1. In the UI project that contains the dynamic component, create a Java class that extends the oracle.adf.view.rich.model.BaseAttributeDescriptor class.

   As the following example shows a sample class that adds a method to apply a custom style to the label for the Sal attribute.

   public class CustomizedDescriptor extends BaseAttributeDescriptor
   {
     public CustomizedDescriptor(BaseAttributeDescriptor base)
     {
       _base = base;
     }
    
     public Object getLabelStyle()
     {
       if (getName().equals("Sal"))
         return "color:red; font-weight:bold";
       else
         return null;
     }
   

2. Create a managed bean for the page.
3. In the managed bean, create a method that returns an instance of the custom descriptor. As the following example shows such a method.

   public CustomizedDescriptor getCustomizedAttributes(String attrName)
     {
     // create value expression for "#{attrName}" and evaluate it to get object
     // of "attr"
       BaseAttributeDescriptor attrMetadata = null;
       Class klass = null;
    
       try
       {
         klass = ClassLoaderUtils.loadClass("oracle.adf.view.rich.model.BaseAttributeDescriptor");
       }
       catch (ClassNotFoundException e)
       {
         throw new RuntimeException("Can not find class oracle.adf.view.rich.model.BaseAttributeDescriptor");
       }
    
       FacesContext facesContext = FacesContext.getCurrentInstance();
       ELContext elContext = facesContext.getELContext();
       ValueExpression valueExpression = createValueExpression(attrName, klass);
    
       if (valueExpression != null)
         attrMetadata = (BaseAttributeDescriptor)valueExpression.getValue(elContext);
    
       return new CustomizedDescriptor(attrMetadata);
     }
   

4. In the source editor for the page containing the dynamic component, bind the dynamic component's attributeModel property to the managed bean method that returns the customized attribute descriptor.

   As the following example shows an af:dynamicComponent tag where its attributeModel attribute has been set to an EL expression that references the getCustomizedAttributes method of the attributeCustomBean managed bean.

   <af:panelFormLayout id="pfl1">
     <af:iterator id="i1" value="#{bindings.EmpVO1.attributesModel.attributes}"
                  var="attr">
       <af:dynamicComponent value="#{bindings[attr.containerName][attr.name].inputValue}" attributeModel="#{attributeCustomBean.getCustomizedAttributes('attr')}" />
     </af:iterator>
   </af:panelFormLayout>
   

1. Create a managed bean method that identifies dynamic component, casts the component to RichDynamicComponent, and then applies any changes.

   For more information, see Using a Managed Bean in a Fusion Web Application.

2. In the page containing the dynamic component, add a command component to the page and bind its actionListener property to the managed bean method.

public void changeLabelColor (ActionEvent event)
  {
    UIComponent component = event.getComponent().getParent();
    component = component.findComponent("pfl1");
 
    while(component != null)
    {
      if(component.getId().equals("it1"))
      {
        RichDynamicComponent rdc = (RichDynamicComponent)component;
        rdc.setLabelStyle("color:red");
        break;
      }
      else
        component = component.getChildren().get(0);
    }
  }

1. Create a managed bean method that accesses the binding container through the FacesContext, gets the AttributesModel, and then applies the desired business logic.

   For more information, see Using a Managed Bean in a Fusion Web Application.

2. In the page containing the dynamic component, add a command component to the page and bind its actionListener property to the managed bean method.

public void setValueThroughBinding(ActionEvent event)
  {
    // get binding container
    FacesContext facesContext = FacesContext.getCurrentInstance();
    ELContext elContext = facesContext.getELContext();
    ValueExpression valueExpression = createValueExpression("bindings", 
                                      DCBindingContainer.class);
    DCBindingContainer binding = (DCBindingContainer) 
                                 valueExpression.getValue(elContext);
 
    // get AttributesModel and attribute metadata list
    valueExpression = createValueExpression("bindings.EmpVO1.attributesModel", 
                      AttributesModel.class);
    AttributesModel attributesModel = (AttributesModel) 
                                      valueExpression.getValue(elContext);
    List<BaseAttributeDescriptor> attrList = attributesModel.getAttributes();
 
    // get AttributeMetadata for "Empno"
    BaseAttributeDescriptor deptNoAttributeBase = null;
    FacesAttributeDescriptor deptNoAttribute = null;
    for (BaseAttributeDescriptor attrDescriptor: attrList)
    {
      if ("Comm".equals(attrDescriptor.getName()))
      {
        deptNoAttributeBase = attrDescriptor;
        break;
      }
    }
 
    deptNoAttribute = (FacesAttributeDescriptor)deptNoAttributeBase;
    if (deptNoAttribute == null || deptNoAttribute.getContainerName() == null)
    {
      System.out.println("AttributesModel of Empno or its model name"); 
      System.out.println("can not be found.");
      return;
    }
 
    // get Deptno attribute value binding, set input value
    JUFormBinding fb = (JUFormBinding) binding.findExecutableBinding((String)
                                        deptNoAttribute.getContainerName());
    JUCtrlValueBinding valueBinding = (JUCtrlValueBinding)
                                  fb.getControlBinding(deptNoAttribute.getName());
    valueBinding.setInputValue(Integer.valueOf(9999));
 
    System.out.println("Found JUCtrlValueBinding " + deptNoAttribute.getName()");
    System.out.println("set its value to 9999.");
  }

1. Use the Structure window to do the following:

   • Change the order of the UI components by dragging them up or down the tree. A black line with an arrowhead denotes where the UI component will be placed.

   • Add a UI component. Right-click an existing UI component in the Structure window and choose to place the new component before, after, or inside the selected component. You then choose from a list of UI components.

   • Bind a UI component. Right-click an existing UI component in the Structure window and choose Bind to ADF Control. You can then select the object to which you want your component bound.

   • Rebind a UI component. Right-click an existing UI component in the Structure window and choose Rebind to another ADF Control. You can then select the new control object to which you want your component bound.

   • Delete a UI component. Right-click the component and choose Delete. If you wish to keep the component, but delete the binding, you need to use the Properties window. See the second bullet point in Step 2.

2. With the UI component selected in the Structure window, you can then do the following in the Properties window:

   • Add a non-ADF binding for the UI component. Enter an EL expression in the Value field, or use the dropdown menu and choose Edit.

   • Delete a binding for the UI component by deleting the EL expression.

   • Change the label for the UI component. By default, the label is bound to the binding's label property of its hint. This property allows your page to use the UI control hints for labels that you have defined for your entity object attributes or view object attributes. The UI hints allow you to change the value once and have it appear the same on all pages that display the label.

     You can change the label just for the current page. To do so, select the label attribute. You can enter text or an EL expression to bind the label value to something else, for example, a key in a properties or resource file.

     For example, the inputText component used to display the name of a product might have the following for its Label attribute:

     #{bindings.ProductName.hints.label}
     

     However, you could change the expression to instead bind to a key in a properties file, for example:

     #{properties['productName']}
     

     In this example, properties is a variable defined in the JSF page used to load a properties file.

When you modify how an attribute is displayed by moving or changing the UI component, JDeveloper changes the corresponding code on the JSF page. When you use the binding editors to add or change a binding, JDeveloper adds the code to the JSF page, and also adds the appropriate elements to the page definition file.