What Happens When You Create Command Buttons

3-10 Java EE Developers Guide for Oracle Application Development Framework

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

3.4.2 What Happens When You Create Command Buttons

When you drop any operation as a command component, 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

3.4.2.1 Action Bindings for Built-in Navigation Operations

Action bindings execute business logic. For example, they can invoke built-in methods on the action binding object. These built-in methods operate on the iterator or on the data control itself, and are represented as operations in the Data Controls panel. JDeveloper provides navigation operations that allow users to navigate forward, backwards, to the first object in the collection, and to the last object. Like value bindings, action bindings for operations contain a reference to the iterator binding when the action binding is bound to one of the iterator-level actions, such as Next or Previous. These types of actions are performed by the iterator, which determines the current object and can therefore determine the correct object to display when a navigation button is clicked. Action bindings use the RequiresUpdateModel property, which determines whether or not the model needs to be updated before the action is executed. In the case of navigation operations, by default this property is set to true, which means that any changes made at the view layer must be moved to the model before navigation can occur. Example 3–6 shows the action bindings for the navigation operations. Example 3–6 Page Definition Code for an Operation Action Binding action IterBinding=CustomerInfoVO1Iterator id=First RequiresUpdateModel=true Action=first action IterBinding=CustomerInfoVO1Iterator id=Previous RequiresUpdateModel=true Action=previous action IterBinding=CustomerInfoVO1Iterator id=Next RequiresUpdateModel=true Action=next action IterBinding=CustomerInfoVO1Iterator id=Last RequiresUpdateModel=true Action=last

3.4.2.2 Iterator RangeSize Attribute

Iterator bindings have a rangeSize attribute that the binding uses to determine the number of data objects to make available for the page for each iteration. This attribute helps in situations when the number of objects in the data source is quite large. Instead of returning all objects, the iterator binding returns only a set number, which then become accessible to the other bindings. Once the iterator reaches the end of the range, it accesses the next set. Example 3–7 shows the default range size for the suppliersFindAll iterator. Example 3–7 RangeSize Attribute for an Iterator accessorIterator MasterBinding=SessionEJBLocalIterator Binds=suppliersFindAll RangeSize=25 Tip: You can also drop the First, Previous, Next, and Last buttons at once. To do so, drag the corresponding collection, and from the context menu, choose Navigation ADF Navigation Buttons. Creating a Basic Databound Page 3-11 DataControl=SessionEJBLocal BeanClass=model.Suppliers id=suppliersFindAllIterator ChangeEventPolicy=ppr By default, the rangeSize attribute is set to 25. This means that a user can view 25 objects, navigating back and forth between them, without needing to access the data source. The iterator keeps track of the current object. Once a user clicks a button that requires a new range for example, clicking the Next button on object number 25, the binding object executes its associated method against the iterator, and the iterator retrieves another set of 25 records. The bindings then work with that set. You can change this setting as needed. You can set it to -1 to have the full record set returned. Table 3–1 shows the built-in navigation operations provided on data controls and the result of invoking the operation or executing an event bound to the operation. For more information about action events, see the What Happens at Runtime: How Action Events and Action Listeners Work section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework.

3.4.2.3 EL Expressions Used to Bind to Navigation Operations

When you create command components using navigation operations, the command components are placed in a panelGroupLayout component. JDeveloper creates an EL expression that binds a navigational command button’s actionListener attribute to the execute property of the action binding for the given operation. At runtime an action binding will be an instance of the FacesCtrlActionBinding class, which extends the core JUCtrlActionBinding implementation class. The FacesCtrlActionBinding class adds the following methods: Note: This rangeSize attribute is not the same as the rows attribute on a table component. Note: 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. Table 3–1 Built-in Navigation Operations Operation When invoked, the associated iterator binding will... First Move its current pointer to the beginning of the result set. Last Move its current pointer to the end of the result set. Previous Move its current pointer to the preceding object in the result set. If this object is outside the current range, the range is scrolled backward a number of objects equal to the range size. Next Move its current pointer to the next object in the result set. If this object is outside the current range, the range is scrolled forward a number of objects equal to the range size. Previous Set Move the range backward a number of objects equal to the range size attribute. Next Set Move the range forward a number of objects equal to the range size attribute. 3-12 Java EE Developers Guide for Oracle Application Development Framework ■ public void executeActionEvent event : This is the method that is referenced in the actionListener property, for example {bindings.First.execute} . This expression causes the binding’s operation to be invoked on the iterator when a user clicks the button. For example, the First command button’s actionListener attribute is bound to the execute method on the First action binding. ■ public String outcome : This can be referenced in an Action property, for example {bindings.Next.outcome}. This can be used for the result of a method action binding once converted to a String as a JSF navigation outcome to determine the next page to navigate to. Every action binding for an operation has an enabled boolean property that Oracle ADF sets to false when the operation should not be invoked. By default, JDeveloper binds the UI component’s disabled attribute to this value to determine whether or not the component should be enabled. For example, the UI component for the First button has the following as the value for its disabled attribute: {bindings.First.enabled} This expression evaluates to true whenever the binding is not enabled, that is, when the operation should not be invoked, thereby disabling the button. In this example, because the framework will set the enabled property on the binding to false whenever the first record is being shown, the First button will automatically be disabled because its disabled attribute is set to be true whenever enabled is False . For more information about the enabled property, see the Oracle ADF Binding Properties appendix of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Example 3–8 shows the code generated on the JSF page for navigation operation buttons. For more information about the partialSubmit attribute on the button, see the Enabling Partial Page Rendering Declaratively section of the Oracle Fusion Middleware Web User Interface Developers Guide for Oracle Application Development Framework. For information about automatic partial page rendering for the binding, see the What You May Need to Know About Automatic Partial Page Rendering section of the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. Example 3–8 JSF Code for Navigation Buttons Bound to ADF Operations f:facet name=footer af:panelGroupLayout af:commandButton actionListener={bindings.First.execute} text=First disabled={bindings.First.enabled} partialSubmit=true id=cb1 af:commandButton actionListener={bindings.Previous.execute} text=Previous disabled={bindings.Previous.enabled} partialSubmit=true id=cb2 af:commandButton actionListener={bindings.Next.execute} Note: Using the outcome method on the action binding implies tying the view-controller layer too tightly to the model, so it should rarely be used. Creating a Basic Databound Page 3-13 text=Next disabled={bindings.Next.enabled} partialSubmit=true id=cb3 af:commandButton actionListener={bindings.Last.execute} text=Last disabled={bindings.Last.enabled} partialSubmit=true id=cb4 af:panelGroupLayoutr f:facet

3.5 Creating a Form Using a Method That Takes Parameters

There may be cases where a page needs information before it can display content. For these types of pages, you create the form using a returned collection from a method that takes parameters. The requesting page needs to supply the value of the parameters in order for the method to execute. For example, the form on the productInfo page is created using the returned collection from the findProductByIdLong method. Instead of returning all products, it returns only the product the user selected on the previous page. The toolbar button on the previous page sets the parameter Long, which provides the product’s ID. For more information about using a command component to set a parameter value, see Section 3.5.4, What You May Need to Know About Setting Parameters with Methods.

3.5.1 How to Create a Form or Table Using a Method That Takes Parameters

To create forms that require parameters, you must be able to access the values for the parameters in order to determine the records to return. You access those values by adding logic to a command button on another page that will set the parameter value on some object that the method can then access. For example, on the browse.jspx page, the Edit toolbar button sets the product ID in the pageFlow scope. To create the form showing the product information, you use the return of the findProductByIdLong method, and you have that method access the parameter on the pageFlow scope, where it is stored. Before you begin: You need to create a method on your session bean that will return the items needed to be displayed in your form. For example, the findProductByIdLong method was added to the SupplierFacadeBean.java class. To create a form or table that uses parameters: 1. From the Data Controls panel, drag a collection that is a return of a method that takes a parameter or parameters and drop it as any type of form. For example, to create the form that displays when you click the toolbar button to edit a product, you would drag and drop the Product return, as shown in Figure 3–6 . Tip: You need to refresh the Data Controls panel in order for any changes made to services to display in the panel. To refresh the panel, click the Refresh icon.