12 Creating MAF AMX Pages

This chapter describes how to create the MAF AMX application feature, including views and task flows.

This chapter includes the following sections:

12.1 Introduction to the MAF AMX Application Feature

MAF AMX is a subframework within Mobile Application Framework (MAF) that provides a set of UI components that enable you to create an application feature whose behavior is identical on all supported platforms. MAF AMX allows you to use UI components declaratively by dragging them onto a page editor. A typical MAF AMX application feature includes several interconnected pages that can be navigated through various paths.

Note:

When developing interfaces for mobile devices, always be aware of the fact that the screen space is very limited. In addition, touchscreen support is not available on some mobile devices.

For more information, see the following:

12.2 Creating Task Flows

Task flows allow you to define the navigation between MAF AMX pages. Using your application workspace in JDeveloper (see Creating a MAF Application), you can start creating the user interface for your MAF AMX application feature by designing task flows. MAF AMX uses navigation cases and rules to define the task flow. These definitions are stored in a file with the default name of ViewController-task-flow.xml (see What You May Need to Know About the ViewController-task-flow.xml File).

A MAF sample application called Navigation (located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer) demonstrates how to use various navigation techniques, such as circular navigation, routers, and so on.

MAF enables you to create MAF AMX application features that have both bounded and unbounded task flows. As described in What You May Need to Know About Bounded and Unbounded Task Flows, a bounded task flow is also known as a task flow definition and represents the reusable portion of an application. In MAF, bounded task flows have a single entry point and no exit points. They have their own collections of activities and control-flow rules, as well as their own memory scope and managed-bean life span. Other characteristics of bounded task flows include accepting input parameters (see Passing Parameters to a Bounded Task Flow) and generating return values (see Configuring a Return Value from a Bounded Task Flow).

You use the MAF AMX Task Flow Designer to create bounded task flows for your application feature. Like the overview editor for task flows, this tool includes a diagrammer (see What You May Need to Know About the MAF Task Flow Diagrammer) in which you build the task flow by dragging and dropping activities and control flows (see What You May Need to Know About Task Flow Activities and Control Flows) from the Components window. You then define these activities and the transitions between them using the Properties window.

Unless a task flow has already been created, MAF automatically generates a default unbounded task flow (adfc-mobile-config.xml file) when a new MAF AMX page is created.

You can add each task flow as an application feature to your MAF application. For more information, see Defining the Application Feature Content as a MAF AMX Page or Task Flow.

12.2.1 How to Create a Task Flow

A task flow is composed of the task flow itself and a number of activities with control flow rules between those activities (see What You May Need to Know About Task Flow Activities and Control Flows). Typically, the majority of the activities are view activities which represent different pages in the flow. When a method or operation needs to be called (for example, before a page is rendered), you use a method call activity with a control flow case from that activity to the appropriate next activity. When you want to call another task flow, you use a task flow call activity. If the flow requires branching, you use a router activity. At the end of a bounded task flow, you use a return activity which allows the flow to exit and control is sent back to the flow that called this bounded task flow.

You use the navigation diagrammer to declaratively create a bounded task flow for your MAF AMX application feature. When you use the diagrammer, JDeveloper creates the XML metadata needed for navigation to work in your MAF AMX application feature in the ViewController-task-flow.xml file (default).

Before you begin:

To design a task flow, the MAF application must include a View Controller project file (see Getting Started with MAF Application Development ).

There are two ways to create a task flow in MAF:

You can create a bounded task flow from the maf-feature.xml file. For more information, see Defining the Application Feature Content as a MAF AMX Page or Task Flow.
You can use the New Gallery in JDeveloper. For more information, refer to the following procedure.

To create a task flow from the New Gallery:

From the top-level menu in JDeveloper, click File, and then select New > From Gallery.
In the New Gallery, expand the Client Tier node, select Mobile Application Framework, and then MAF Task Flow (see Figure 12-1). Click OK.

Figure 12-1 Creating New MAF Task Flow
In the Create MAF Task Flow dialog (see Figure 12-2), specify the file name and location for your new task flow, and then click OK to open the new <Name>-flow.xml file in the navigation diagrammer that Figure 12-3 shows.

Note:

Task flows should be created within the HTML root of the View Controller project of your MAF application.

Note:

JDeveloper increments the number of the task flow according to the number of bounded task flows that already exist in the same pattern.

Figure 12-2 Create MAF Task Flow Dialog

Figure 12-3 New Blank Task Flow
In the Components window, select MAF Task Flow.

Tip:

If the Components window is not displayed, choose Window > Components from the main menu. By default, the Components window is displayed in the upper right-hand corner of JDeveloper.
From MAF Task Flow > Components, select the component you wish to use and drag it onto the diagram. JDeveloper redraws the diagram with the newly added component, as Figure 12-4 shows.

Figure 12-4 Adding Components to Task Flow

For information on how to add activities to a task flow, see How to Add and Use Task Flow Activities.

For information on how to add control flows, see How to Define Control Flows.

For information on how to define behavior of the new task flow, see What You May Need to Know About Behavior of New Bounded Task Flows.

You can also open the Overview tab and use the overview editor to create navigation rules and navigation cases. Press F1 for details on using the overview editor to create navigation.

This image is described in the surrounding text

Additionally, you can manually add elements to the task flow file by directly editing the page in the Source editor. To open the file in the Source editor, click the Source tab.

Note:

When manually editing the task flow file, keep in mind that all the document file names referring to MAF AMX pages, JavaScript files, and CSS files are case-sensitive.

If special characters (such as an underscore, for example) are used in a file name, you should consult the mobile device specification to verify whether or not the usage of this character is supported.

Once the navigation for your MAF AMX application feature is defined, you can create the pages and add the components that will execute the navigation. For more information about using navigation components on a page, see How to Define Control Flows.

After you define the task flow for the MAF AMX application feature, you can double-click a view file to access the MAF AMX view. For more information, see Creating Views .

12.2.1.1 What You May Need to Know About Behavior of New Bounded Task Flows

When a new bounded task flow is created, MAF automatically adds a page-flow-scope-behavior element to the <Name>-flow.xml file. This element is added as a child of the top-level task-flow-definition element.

Note:

The page-flow-scope-behavior element is appended to all newly created task flows, even if they are created in projects built using previous versions of MAF.

The value of the page-flow-scope-behavior element is set to push-new by default and is displayed in the Overview and Source editors for the new task flow, as well as the Properties window for the task-flow-definition element, as Figure 12-5 shows.

Figure 12-5 Page Flow Scope Behavior for Task Flows

If the Page Flow Scope Behavior is set to push-new, a new page flow scope is created and the old pageFlowScope variables are saved and pushed on to a stack. This allows for the previous page flow scope to be restored upon the execution of a task flow return. If the Page Flow Scope Behavior is set to preserve, the pageFlowScope variables are not cleared when the task flow is entered upon execution of a task flow call resulting in the new task flow variables containing old values.

In existing task flows, if the page-flow-scope-behavior element is not present, then you should define it as either push-new or preserve.

For more information about the pageFlowScope, see About the Managed Beans Category.

12.2.2 What You May Need to Know About Task Flow Activities and Control Flows

A task flow consists of activities and control flow cases that define the transitions between activities.

The MAF Task Flow designer supports activities listed in Table 12-1.

Table 12-1 Task Flow Activities

Activity	Description
View	Displays a MAF AMX page. For more information, see Adding View Activities.
Method Call	Invokes a method (typically a method on a managed bean). You can place a method call activity anywhere in the control flow of a MAF AMX application feature to invoke logic based on control flow rules. For additional information, see Adding Method Call Activities. You can also specify parameters that you pass into a method call that is included in a task flow. These include standard parameters for a method call action in a MAF AMX task flow. When you use the designer to generate a method, it adds the required arguments and type. At runtime, you can define parameters for a method call in a task flow and pass parameters into the method call itself for its usage. For more information, see How to Add and Use Task Flow Activities
Router	Evaluates an Expression Language (EL) expression and returns an outcome based on the value of the expression. These outcomes can then be used to route control to other activities in the task flow. For more information, see Adding Router Activities.
Task Flow Call	Calls a bounded task flow from either an unbounded or bounded task flow. While a task flow call activity allows you to call a bounded task flow located within the same MAF AMX application feature, you can also call a bounded task flow from a different MAF AMX application feature or from a Feature Archive file (FAR) that has been added to a library (see Reusing MAF Application Content .). The task flow call activity supports task flow input parameters and return values. For more information, see Adding Task Flow Call Activities.
Task Flow Return	Identifies the point in an application's control flow where a bounded task flow completes and sends control flow back to the caller. You can use a task flow return only within a bounded task flow. For more information, see Adding Task Flow Return Activities.

The MAF Task Flow designer supports control flows listed in Table 12-2.

Table 12-2 Control Flows

Control Flow	Description
Control Flow Case	Identifies how control passes from one activity to the next in the MAF AMX application feature. For more information, see Defining a Control Flow Case.
Wildcard Control Flow Rule	Represents a control flow case that can originate from any activities whose IDs match a wildcard expression.For more information, see Adding a Wildcard Control Flow Rule.

12.2.3 What You May Need to Know About the ViewController-task-flow.xml File

The ViewController-task-flow.xml file enables you to design the interactions between views (MAF AMX pages) by dragging and dropping MAF AMX task flow components from the Components window onto the diagrammer.

Figure 12-6 shows a sample task flow file called Products-flow.xml. In this file, the control flow is directed from the products page to the productdetails page. To return to the products page from the productdetails page, the built-in __back navigation is used (see What You May Need to Know About MAF Support for Back Navigation).

Figure 12-6 Task Flow File

12.2.4 What You May Need to Know About the MAF Task Flow Diagrammer

As illustrated in Figure 12-6, the task flow diagram and Components window display automatically after you create a task flow using the MAF Task Flow Creation utility. The task flow diagram is a visual editor onto which you can drag and drop activities and task flows from the Components window or from the Applications window. For more information, see How to Add and Use Task Flow Activities.

12.2.5 How to Add and Use Task Flow Activities

You use the task flow diagrammer to drag and drop activities, views, and control flows.

Before you begin:

You must select MAF Task Flow from the Components window, as Figure 12-7 shows.

To add an activity to a MAF task flow:

In the Applications window, double-click a task flow source file (such as ViewController-task-flow.xml) to display the task flow diagram and the Components window, as Figure 12-7 shows. The diagrammer displays the task flow editor. The Components window automatically displays the components available for a MAF task flow.
Drag an activity from the Components window onto the diagram. If you drag a view activity onto the diagram and double-click on it, you can invoke the Create MAF AMX Page wizard (see Adding View Activities).

Figure 12-7 The Diagrammer for the Task Flow Editor

Note:

There is a default activity that is associated with each bounded task flow.

12.2.5.1 Adding View Activities

One of the primary types of task flow activity is the view activity which displays a MAF AMX page.

XML metadata in the source file of the task flow associates a view activity with a physical MAF AMX page. An id attribute identifies the view activity.

You can configure view activities in your task flow to pass control to each other at runtime. For example, to pass control from one view activity (view activity A) to a second view activity (view activity B), you could configure a command component, such as a Button or a Link on the page associated with view activity A. To do so, you set the command component's Action attribute to the control flow case from-outcome that corresponds to the task flow activity that you want to invoke (for example, view activity B). At runtime, the end user initiates the control flow case by invoking the command component. It is possible to navigate from a view activity to another activity using either a constant or dynamic value on the Action attribute of the UI component:

A constant value of the component's Action attribute is an action outcome that always triggers the same control flow case. When an end user clicks the component, the activity specified in the control flow case is performed. There are no alternative control flows.
A dynamic value of the component's Action attribute is bound to a managed bean or a method. The value returned by the method binding determines the next control flow case to invoke. For example, a method might verify user input on a page and return one value if the input is valid and another value if the input is invalid. Each of these different action values trigger different navigation cases, causing the application to navigate to one of two possible target pages.

For more information, see How to Specify Action Outcomes Using UI Components.

You can also write an EL expression that must evaluate to true before control passes to the target view activity. You write the EL expression as a value for the <if> child element of the control flow case in the task flow.

The following two examples demonstrate what happens when you pass control between View activities:

This example shows a control flow case defined in the XML source file for a bounded or unbounded task flow.

<control-flow-rule>
   <from-activity-id>Start</from-activity-id>
      <control-flow-case>
         <from-outcome>toOffices</from-outcome>
         <to-activity-id>WesternOffices</to-activity-id>
      </control-flow-case>
</control-flow-rule>

In this example, a Button on a MAF AMX page associated with the Start view activity specifies toOffices as the action attribute. When the end user clicks the button, control flow passes to the WesternOffices activity specified as the to-activity-id in the control flow metadata.
```
<amx:commandButton text="Go" id="b1" action="toOffices">
```

For more information, see the following:

As previously stated, the view activity is associated in metadata with an actual MAF AMX page which it displays when added to a task flow. You add a view activity by dragging and dropping it from the Components window. You can create an actual MAF AMX page by double-clicking the View activity in the Diagram window and then define characteristics for the page through the displayed dialog (see Figure 12-30). You can also create a View activity by dragging and dropping a MAF AMX file in the Applications window onto the Overview editor's Diagram tab.

If you are creating a bounded task flow, you may want to designate a specific activity as the default activity (see What You May Need to Know About Bounded and Unbounded Task Flows). This allows the specific activity to execute first whenever the bounded task flow runs. By default, JDeveloper makes the first activity you add to the task flow the default. To change to a different activity, right-click the appropriate activity in the Diagram window and choose Mark Activity > Default Activity (see Figure 12-8).

Figure 12-8 Defining Default Activity

12.2.5.2 Adding Router Activities

Use a router activity to route control to activities based on the runtime evaluation of EL expressions.

Each control flow corresponds to a different router case. Each router case uses the following elements to choose the activity to which control is next routed:

expression: an EL expression that evaluates to true or false at runtime.

The router activity returns the outcome that corresponds to the EL expression that returns true.
outcome: a value returned by the router activity if the EL expression evaluates to true.

If the router case outcome matches a from-outcome on a control flow case, control passes to the activity that the control flow case points to. If none of the cases for the router activity evaluate to true, or if no router activity cases are specified, the outcome specified in the router Default Outcome field (if any) is used.

Consider using a router activity if your routing condition can be expressed in an EL expression: the router activity allows you to show more information about the condition on the task flow.

When you drag a Router activity onto the diagram, you can use the Properties window to create an expression whose evaluation determines which control flow rule to follow. Using the Properties window, you configure the Activity ID and Default Outcome properties of the router activity and add router cases to the router activity.

When defining the Activity ID attribute, write a value that identifies the router activity in the task flow's source file.

When defining the Default Outcome attribute, specify an activity that the router activity passes control to if no control flow cases evaluate to true or if no control flow case is specified.

For each router case that you add, specify values by clicking Add ( + ) in the Cases section that Figure 12-49 shows.

Figure 12-9 Configuring Router Activity

Expression: An EL expression that evaluates to true or false at runtime.

For example, to reference the value in an input text field of a view activity, write an EL expression similar to the following:
```
#{pageFlowScope.value=='view2'}
```
If this EL expression returns true, the router activity invokes the outcome that you specify in the Outcome field.
Outcome: The outcome the router activity invokes if the EL expression specified by Expression returns true.

Create a control flow case or a wildcard control flow rule for each outcome in the diagram of your task flow. For example, for each outcome in a control flow case, ensure that there is a corresponding from-outcome.

When you configure the control flow using a router activity, JDeveloper writes values to the source file of the task flow based on the values that you specify for the properties of the router activity.

12.2.5.3 Adding Method Call Activities

When you drag a Method Call activity onto the diagram, you can use the Properties window to configure the method to call.

Use a method call activity to call a custom or built-in method that invokes the MAF AMX application feature logic from anywhere within the application feature's control flow. You can specify methods to perform tasks such as initialization before displaying a page, cleanup after exiting a page, exception handling, and so on.

You can set an outcome for the method that specifies a control flow case to pass control to after the method finishes. You can specify the outcome as one of the following:

fixed-outcome: upon successful completion, the method always returns this single outcome, for example, success. If the method does not complete successfully, an outcome is not returned. If the method type is void, you must specify a fixed-outcome and cannot specify to-string.

You define this outcome by setting the Fixed Outcome field in the Properties window (see Figure 12-10).
to-string: if specified as true, the outcome is based on calling the toString method on the Java object returned by the method. For example, if the toString method returns editBasicInfo, navigation goes to a control flow case named editBasicInfo.

You define this outcome by setting the toString() field in the Properties window (see Figure 12-10).

You can associate the method call activity with an existing method by dropping a data control operation from the Data Controls window directly onto the method call activity in the task flow diagram. You can also drag methods and operations directly to the task flow diagram: a new method call activity is created automatically when you do so. You can specify an EL expression and other options for the method.

You configure the method call by modifying its activity identifier in the Activity ID field if you want to change the default value. If you enter a new value, the new value appears under the method call activity in the diagram.

In the Method field, enter an EL expression that identifies the method to call.

Note:

The bindings variable in the EL expression references a binding from the current binding container. In order to specify the bindings variable, you must specify a binding container definition or page definition. For more information, see What You May Need to Know About Generated Drag and Drop Artifacts.

Figure 12-10 Configuring Method Call Activity

You can also use the Expression Builder to build the EL expression for the method:

Choose Method Expression Builder from the Property Editor for the Method field.
In the Expression Builder dialog, navigate to the method that you want to invoke and select it.

If the method call activity is to invoke a managed bean method, double-click the method call activity in the diagram. This invokes a dialog where you can specify the managed bean method you want to invoke.

You can specify parameters and return values for a method by using the Parameters section of the Properties window (see Figure 12-10). If parameters have not already been created by associating the method call activity to an existing method, add the parameters by clicking Add ( + ) and setting the following:

Class: enter the parameter class. For example, java.lang.Double.
Value: enter an EL expression that retrieves the value of the parameter. For example:
```
#{pageFlowScope.shoppingCart.totalPurchasePrice}
```
Return Value: enter an EL expression that identifies where to store the method return value. For example:
```
#{pageFlowScope.Return}
```

12.2.5.4 Adding Task Flow Call Activities

You can use a task flow call activity to call a bounded task flow from either the unbounded task flow (see Unbounded Task Flows) or a bounded task flow (see Bounded Task Flows). This activity allows you to call a bounded task flow located within the same or a different MAF AMX application feature.

The called bounded task flow executes its default activity first. There is no limit to the number of bounded task flows that can be called. For example, a called bounded task flow can call another bounded task flow, which can call another, and so on resulting in the creation of chained task flows where each task flow is a link in a chain of tasks.

To pass parameters into a bounded task flow, you must specify input parameter values on the task flow call activity. These values must correspond to the input parameter definitions on the called bounded task flow. For more information, see Specifying Input Parameters on a Task Flow Call Activity.

Note:

The value on the task flow call activity input parameter specifies the location within the calling task flow from which the value is to be retrieved.

The value on the input parameter definition for the called task flow specifies where the value is to be stored within the called bounded task flow once it is passed.

Note:

When a bounded task flow is associated with a task flow call activity, input parameters are automatically inserted on the task flow call activity based on the input parameter definitions set on the bounded task flow. Therefore, you only need to assign values to the task flow call activity input parameters.

By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.

The technique for passing return values out of the bounded task flow to the caller is similar to the way that input parameters are passed. For more information, see Configuring a Return Value from a Bounded Task Flow.

To use a task flow call activity:

Call a bounded task flow using a task flow call activity (see Calling a Bounded Task Flow Using a Task Flow Call Activity)
Specify input parameters on a task flow call activity if you want to pass parameters into the bounded task flow (see Specifying Input Parameters on a Task Flow Call Activity).

12.2.5.4.1 Calling a Bounded Task Flow Using a Task Flow Call Activity

Add a task flow call activity to the calling bounded or unbounded task flow to call a bounded task flow.

To call a bounded task flow:

Open a bounded task flow file in the Diagram view.
From the Components window, select Components > Activities.
Drag and drop a Task Flow Call activity onto the diagram.
Choose one of the following options to identify the called task flow:
- Double-click the newly-dropped task flow call activity to open the Create MAF Task Flow dialog (see Figure 12-2) where you define settings for a new bounded task flow.
- Drag an existing bounded task flow from the Applications window and drop it on the task flow call activity.
- If you know the name of the bounded task flow that you want to invoke, perform the following steps:
  1. In the Diagram view, select the Task Flow Call activity.
  2. In the Properties window shown in the following illustration, expand the General section, and then select Static from the Task Flow Reference list.
  3. In the Document field, enter the name of the source file for the bounded task flow to call.
  4. In the ID field, enter the bounded task flow ID contained in the XML source file for the called bounded task flow.
  Figure 12-11 Task Flow Call Activity That Invokes a Bounded Task Flow
  
  If you do not know the name of the bounded task flow to invoke and it is dependent on an end user selection at runtime, perform the following steps:
  1. In the Diagram view, select the Task Flow Call activity.
  2. In the Properties window, expand the General section, and select Dynamic from the Task Flow Reference list.
  3. Use the Expression Builder to set the value of the Dynamic Task Flow Reference property field: write an EL expression that identifies the ID of the bounded task flow to invoke at runtime.

12.2.5.4.2 Specifying Input Parameters on a Task Flow Call Activity

The suggested method for mapping parameters between a task flow call activity and its called bounded task flow is to first specify input parameter definitions for the called bounded task flow. Then you can drag the bounded task flow from the Applications window and drop it on the task flow call activity. The task flow call activity input parameters are created automatically based on the bounded task flow's input parameter definition. For more information, see Passing Parameters to a Bounded Task Flow.

You can, of course, first specify input parameters on the task flow call activity. Even if you have defined them first, they will automatically be replaced based on the input parameter definitions of the called bounded task flow, once it is associated with the task flow call activity.

If you have not yet created the called bounded task flow, you may still find it useful to specify input parameters on the task flow call activity. Doing so at this point allows you to identify any input parameters you expect the task flow call activity to eventually map when calling a bounded task flow.

To specify input parameters:

Open a task flow file in the Diagram view and select a Task Flow Call activity.
In the Properties window, expand the Parameters section, and click Add ( + ) to specify a new input parameter in the Input Parameters list as follows:
- Name: enter a name to identify the input parameter.
- Value: enter an EL expression that identifies the parameter value. The EL expression identifies the location within the calling task flow from which the parameter value is to be retrieved. For example, enter an EL expression similar to the following:
```
#{pageFlowScope.callingTaskflowParm}
```
  By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.
After you have specified an input parameter, you can specify a corresponding input parameter definition for the called bounded task flow. For more information, see Passing Parameters to a Bounded Task Flow.

12.2.5.4.3 Specifying the Data Control Context

When one task flow calls another, the task flows can either share an instance of a data control or create separate instances of the same data control allowing the task flows to maintain independent state.

The internal object that task flows use to share their data controls or to store their own isolated data control is known as a data control context. When a task flow specifies a data-control-context value of shared, the called task flow uses the data control context of the calling task flow rather than creating its own. This allows the called task flow to share data control instances attached to the data control context. Alternatively, if a called task flow specifies a data-control-context value of isolated, a new data control context is created and a new instance of any data controls used by the task flow is attached to the newly-created data control context.

You can define a data control context for a task flow call activity as follows:

In the Diagram view, select a Task Flow Call activity.
In the Properties window, expand the General section, and then provide a value for the Data Control Context property:
- Select shared (default) from the drop-down field if the data control is to be shared with the calling task flow. For example, changes made to a called task flow are reflected when navigation back to the calling task flow occurs.
- Select isolated from the drop-down field if the task flow is to have its own set of data control instances.
- Define an EL expression that evaluates to either “shared” or “isolated”. You set this value in the Edit Property: Data Control Context dialog (see the following illustration) that you can open by clicking the Property Menu icon located to the right of the Data Control Context field in the Properties window.
Note:
To choose the correct value for the data-control-context, consider looking at your data model and decide how data should be shared across task flow boundaries.

For information on setting depth of the data control context, see How to Define the Data Control Context Depth for Task Flows.

12.2.5.5 Adding Task Flow Return Activities

A task flow return activity identifies the point in a MAF AMX application feature's control flow where a bounded task flow completes and sends control flow back to the caller. You can use a task flow return activity only within a bounded task flow.

A gray circle around a task flow return activity icon indicates that the activity is an exit point for a bounded task flow. A bounded task flow can have zero or more task flow return activities.

Each task flow return activity specifies an outcome that it returns to the calling task flow.

The outcome returned to an invoking task flow depends on the end user action. You can configure control flow cases in the invoking task flow to determine the next action by the invoking task flow. Set the From Outcome property of a control flow case to the value returned by the task flow return activity's outcome to invoke an action based on that outcome. This determines control flow upon return from the called task flow.

To add a task flow return activity:

Open a bounded task flow file in the Diagram view.
From the Components window, select Components > Activities.
Drag and drop a Task Flow Return activity onto the diagram.
In the Properties window (see Figure 12-12), expand the General section and enter an outcome in the Name field.

The task flow return activity returns this outcome to the calling task flow when the current bounded task flow exits. You can specify only one outcome per task flow return activity. The calling task flow should define control flow rules to handle control flow upon return. For more information, see How to Define Control Flows.
Expand the Behavior section and choose one of the options in the Reentry list.

If you specify reentry-not-allowed on a bounded task flow, an end user can still click the back button on the mobile device and return to a page within the bounded task flow. However, if the end user does anything on the page such as activating a button, an exception (for example, InvalidTaskFlowReentry) is thrown indicating the bounded task flow was reentered improperly.
From the End Transaction dropdown list, choose one of the following options:
- commit: select to commit the existing transaction to the database.
- rollback: select to roll back the transaction to what it was on entry of the called task flow. This has the same effect as canceling the transaction, since it rolls back a new transaction to its initial state when it was started on entry of the bounded task flow.
  
  If you do not specify commit or rollback, the transaction is left open to be closed by the calling bounded task flow.

Figure 12-12 Configuring Task Flow Return Activity

12.2.5.6 Using Task Flow Activities with Page Definition Files

Page definition files define the binding objects that populate data at runtime. They are typically used in a MAF AMX application feature to bind page UI components to data controls. The following task flow activities can also use page definition files to bind to data controls:

Method call: You can drag and drop a data control operation from the Data Controls window onto a task flow to create a method call activity or onto an existing method call activity. In both cases, the method call activity binds to the data control operation.
Router: associating a page definition file with a router activity creates a binding container. At runtime, this binding container makes sure that the router activity references the correct binding values when it evaluates the router activity cases' EL expressions. Each router activity case specifies an outcome to return if its EL expression evaluates to true. For this reason, only add data control operations to the page definition file that evaluate to true or false.
Task flow call: associating a page definition file with a task flow call activity creates a binding container. At runtime, the binding container is in context when the task flow call activity passes input parameters. The binding container makes sure that the task flow call activity references the correct values if it references binding values when passing input parameters from a calling task flow to a called task flow.
View: you cannot directly associate a view activity with a page definition file. Instead, you associate the page that the view activity references.

If you right-click any of the preceding task flow activities, except view activity, in the Diagram window for a task flow, JDeveloper displays an option on the context menu that enables you to create a page definition file if one does not yet exist. If a page definition file does exist, JDeveloper displays a context menu option for all task flow activities to go to the page definition file (see Accessing the Page Definition File). JDeveloper also displays the Edit Binding context menu option when you right-click a method call activity that is associated with a page definition file.

A task flow activity that is associated with a page definition file displays an icon in the lower-right section of the task flow activity icon.

To associate a page definition file with a task flow activity:

In the Diagram view, right-click the task flow activity for which you want to create a page definition file and select Create Page Definition from the context menu.
In the resulting page definition file, add the bindings that you want your task flow activity to reference at runtime.

For more information about page definition files, see What You May Need to Know About Generated Drag and Drop Artifacts.

When the preceding steps are completed, JDeveloper generates a page definition file for the task flow activity at design time. The file name of the page definition file comprises the originating task flow and either the name of the task flow activity or the data control operation to invoke. JDeveloper also generates an EL expression from the task flow activity to the binding in the created page definition file. At runtime, a binding container ensures that a task flow activity's EL expressions reference the correct value.

12.2.6 How to Define the Data Control Context Depth for Task Flows

Configuring the data control context depth allows you to avoid an infinite drill into a task flow by disabling certain functionality. For example, you can disable drilling into nested task flow when a particular data control context stack depth is reached.

You can modify the maximum depth of the data control context (see Specifying the Data Control Context) by setting the maximumDataControlContextDepth property in your application’s maf-config.xml file, as the following illustration shows. The default value is 10.

You can also define an EL expression of either #{feature.dataControlContextDepth} or #{feature.maximumDataControlContextDepth} using the Mobile Application Framework feature object, as the following illustration shows.

In addition, you can use methods of the EmbeddedFeatureContext class that provide access to the current data control context stack depth as well as the maximum stack depth. For more information, see Java API Reference for Oracle Mobile Application Framework.

For more information about the maf-config.xml file, see Table C-1.

For more information about EL expressions, see Creating EL Expressions.

12.2.7 How to Define Control Flows

You use the following task flow components to define the control flow in your MAF AMX application feature:

Control Flow Case (see Defining a Control Flow Case)
Wildcard Control Flow Rule (see Adding a Wildcard Control Flow Rule)

12.2.7.1 Defining a Control Flow Case

You can create navigation using the Control Flow Case component, which identifies how control passes from one activity to the next. To create a control flow, select Control Flow Case from the Components window. Next, connect the Control Flow Case to the source activity, and then to the destination activity.

JDeveloper creates the following after you connect a source and target activity:

control-flow-rule: Identifies the source activity using a from-activity-id.
control-flow-case: Identifies the destination activity using a to-activity-id.

To define a control flow case directly in the MAF task flow diagram:

Open the task flow source file in the Diagram view.
Select Control Flow Case from the Components window.
On the diagram, click a source activity and then a destination activity. JDeveloper adds the control flow case to the diagram. Each line that JDeveloper adds between an activity represents a control flow case. The from-outcome contains a value that can be matched against values specified in the action attribute of the MAF AMX UI components.
To change the from-outcome, select the text next to the control flow in the diagram. By default, this is a wildcard character.
To change the from-activity-id (the identifier of the source activity), or the to-activity-id (the identifier for the destination activity), drag either end of the arrow in the diagram to a new activity.

12.2.7.2 Adding a Wildcard Control Flow Rule

MAF task flows support the wildcard control flow rule, which represents a control flow from-activity-id that contains a trailing wildcard (foo*) or a single wildcard character. You can add a wildcard control flow rule to an unbounded or bounded task flow by dragging and dropping it from the Components window. To configure your wildcard control flow rule, use the Properties window.

To add a wildcard control flow rule:

Open the task flow source file in the Diagram view.
Select Wildcard Control Flow Rule in the Components window and drop it onto the diagram.
Select Control Flow Case in the Components window.
In the task flow diagram, drag the control flow case from the wildcard control flow rule to the target activity, which can be any activity type.
By default, the label below the wildcard control flow rule is *. This is the value for the From Activity ID element. To change this value, select the wildcard control flow rule in the diagram. In the Properties window for the wildcard control flow rule, enter a new value in the From Activity ID field. A useful convention is to cast the wildcard control flow rule in a form that describes its purpose. For example, enter project*. The wildcard must be a trailing character in the new label.

Tip:

You can also change the From Activity ID value in the Overview editor for the task flow diagram.
Optionally, in the Properties window expand the Behavior section and write an EL expression in the If field that must evaluate to true before control can pass to the activity identified by To Activity ID.

12.2.7.3 What You May Need to Know About Control Flow Rule Metadata

The following example shows the general syntax of a control flow rule element in the task flow source file.

<control-flow-rule>
   <from-activity-id>from-view-activity</from-activity-id>
   <control-flow-case>
      <from-action>actionmethod</from-action>
      <from-outcome>outcome</from-outcome>
      <to-activity-id>destinationActivity</to-activity-id>
      <if>#{myBean.someCondition}</if>
   </control-flow-case>
   <control-flow-case>
   ...
   </control_flow-case>
</control-flow-rule>

Control flow rules can consist of the following metadata:

control-flow-rule: a mandatory wrapper element for control flow case elements.
from-activity-id: the identifier of the activity where the control flow rule originates (for example, source).

A trailing wildcard ( * ) character in from-activity-id is supported. The rule applies to all activities that match the wildcard pattern. For example, login* matches any logical activity ID name beginning with the literal login. If you specify a single wildcard character in the metadata (not a trailing wildcard), the control flow automatically converts to a wildcard control flow rule activity in the diagram. For more information, see Adding a Wildcard Control Flow Rule.
control-flow-case: a mandatory wrapper element for each case in the control flow rule. Each case defines a different control flow for the same source activity. A control flow rule must have at least one control flow case.
from-action: an optional element that limits the application of the rule to outcomes from the specified action method. The action method is specified as an EL binding expression, such as, for example, #{backing_bean.cancelButton_action}.

In the preceding example, control passes to destinationActivity only if outcome is returned from actionmethod.

The value in from-action applies only to a control flow originating from a view activity, not from any other activity types. Wildcards are not supported in from-action.
from-outcome: identifies a control flow case that will be followed based on a specific originating activity outcome. All possible originating activity outcomes should be accommodated with control flow cases.

If you leave both the from-action and the from-outcome elements empty, the case applies to all outcomes not identified in any other control flow cases defined for the activity, thus creating a default case for the activity. Wildcards are not supported in from-outcome.
to-activity-id: a mandatory element that contains the complete identifier of the activity to which the navigation is routed if the control flow case is performed. Each control flow case can specify a different to-activity-id.
if: an optional element that accepts an EL expression as a value. If the EL expression evaluates to true at runtime, control flow passes to the activity identified by the to-activity-id element.

12.2.7.4 What You May Need to Know About Control Flow Rule Evaluation

At runtime, task flows evaluate control flow rules from the most specific to the least specific match to determine the next transition between activities. Evaluation is based on the following priority:

from-activity-id, from-action, from-outcome: first, searches for a match in all three elements is performed.
from-activity-id, from-outcome: the search is performed in these elements if no match in all three elements is found.
from-activity-id: if search in the preceding combinations did not result in a match, search is performed in this element only.

12.2.8 What You May Need to Know About MAF Support for Back Navigation

In the task flow example that Figure 12-13 shows, it is possible to take two separate paths to reach viewD based on the action outcome value (see How to Specify Action Outcomes Using UI Components): either from viewA to viewB to viewD, or from viewA to viewC to viewD.

Figure 12-13 Task Flow with Back Navigation

While you could theoretically keep track of which navigation paths had been followed and then directly implement the __back navigation flow, it would be tedious and error-prone, especially considering the fact that due to the limited screen space on mobile devices transitions out of the navigation sequences occur very frequently. MAF provides support for a built-in __back navigation that enables moving back through optional paths across a task flow: by applying its "knowledge" of the path taken, MAF performs the navigation back through the same path. For example, if the initial navigation occurred from viewA to viewC to viewD, on exercising the __back option on ViewD MAF would automatically take the end user back to ViewA through ViewC rather than through ViewB.

For additional information, see the following:

12.2.9 How to Enable Page Navigation by Dragging

You can enable navigation from one MAF AMX page to another through the use of the Navigation Drag Behavior operation. For more information, see How to Enable Drag Navigation.

12.2.10 How to Specify Action Outcomes Using UI Components

Using the Properties window, you can specify an action outcome by setting the action attribute of one of the following UI components to the corresponding control flow case from-outcome leading to the next task flow activity:

Command Button (see How to Use Buttons)
Command Link (see How to Use Links)
List Item

You use the UI component's Action field (see Figure 12-14) to make a selection from a list of possible action outcomes defined in one or more task flow for a specific MAF AMX page.

Figure 12-14 Setting Actions

A Back action (__back) is automatically added to every list to enable navigation to the previously visited page.

Note:

A MAF AMX page can be referenced in both bounded and unbounded task flows, in which case actions outcomes from both task flows are included in the Action selection list.

12.2.11 How to Create and Reference Managed Beans

You can create and use managed beans in your MAF application to store additional data or execute custom code. You can use JDeveloper's usual editing mechanism to reference managed beans and create references to them for applicable fields. For more information, see Creating and Using Managed Beans.

Figure 12-15 shows the Edit option for an action property in the Properties window. You click this option to invoke the Edit Property dialog that Figure 12-16 shows.

Figure 12-15 Edit Dialog

Figure 12-16 Edit Property Dialog for Action

Table 12-7 lists MAF AMX attributes for which the Edit option in the Properties window is available.

Table 12-3 Editable Attributes

Property	Element
`action`	`amx:commandButton`
`action`	`amx:commandLink`
`action`	`amx:listItem`
`action`	`amx:navigationDragBehavior`
`action`	`dvtm:chartDataItem`
`action`	`dvtm:ieDataItem`
`action`	`dvtm:timelineItem`
`action`	`dvtm:area`
`action`	`dvtm:marker`
`actionListener`	`amx:listItem`
`actionListener`	`amx:commandButton`
`actionListener`	`amx:commandLink`
`binding`	`amx:actionListener`
`mapBoundsChangeListener`	`dvtm:geographicMap`
`mapInputListener`	`dvtm:geographicMap`
`moveListener`	`amx:listView`
`rangeChangeListener`	`amx:listView`
`selectionListener`	`amx:listView`
`selectionListener`	`amx:filmStrip`
`selectionListener`	`dvtm:areaDataLayer`
`selectionListener`	`dvtm:pointDataLayer`
`selectionListener`	`dvtm:treemap`
`selectionListener`	`dvtm:sunburst`
`selectionListener`	`dvtm:timelineSeries`
`selectionListener`	`dvtm:nBox`
`selectionListener`	`dvtm:areaChart`
`selectionListener`	`dvtm:barChart`
`selectionListener`	`dvtm:bubbleChart`
`selectionListener`	`dvtm:comboChart`
`selectionListener`	`dvtm:lineChart`
`selectionListener`	`dvtm:funnelChart`
`selectionListener`	`dvtm:pieChart`
`selectionListener`	`dvtm:scatterChart`
`valueChangeListener`	`amx:inputDate`
`valueChangeListener`	`amx:inputNumberSlider`
`valueChangeListener`	`amx:inputText`
`valueChangeListener`	`amx:selectBooleanCheckbox`
`valueChangeListener`	`amx:selectBooleanSwitch`
`valueChangeListener`	`amx:selectManyCheckbox`
`valueChangeListener`	`amx:selectManyChoice`
`valueChangeListener`	`amx:selectOneButton`
`valueChangeListener`	`amx:selectOneChoice`
`valueChangeListener`	`amx:selectOneRadio`
`valueChangeListener`	`dvtm:statusMeterGauge`
`valueChangeListener`	`dvtm:dialGauge`
`valueChangeListener`	`dvtm:ratingGauge`
`viewportChangeListener`	`dvtm:areaChart`
`viewportChangeListener`	`dvtm:barChart`
`viewportChangeListener`	`dvtm:comboChart`
`viewportChangeListener`	`dvtm:lineChart`

Clicking Edit for all other properties invokes a similar dialog, but without the Action Outcome option, as Figure 12-17 shows.

Figure 12-17 Edit Property Dialog for Action Listener

The preceding dialogs demonstrate that you can either create a managed bean, or select an available action outcome for the action property.

The Action Outcome list shown in Figure 12-16 contains the action outcomes from all task flows to which a specific MAF AMX page belongs. In addition, this list contains a __back navigation outcome to go back to the previously visited page (see How to Specify Action Outcomes Using UI Components for more information). If a page is not part of any task flow, the only available outcome in the Action Outcome list is __back. When you select one of the available action outcomes and click OK, the action property value is updated with the appropriate EL expression, such as the following for a commandButton:

<amx:commandButton action="goHome"/>

The Method Binding option (see Figure 12-16) allows you to either create a new managed bean class or select an existing one.

To create a new managed bean class:

Click New next to the Managed Bean field to open the Create Managed Bean dialog that Figure 12-18 shows.

Figure 12-18 Create Managed Bean Dialog

MAF supports the following scopes:
- application
- view
- pageFlow
When you declare a managed bean to a MAF application or the MAF AMX application feature, the managed bean is instantiated and identified in the proper scope, and the bean's properties are resolved and its methods are called through EL. For more information, see Creating EL Expressions.
Provide the managed bean and class names (see Figure 12-19), and then click OK.

Figure 12-19 Setting Managed Bean Name and Class

The following example shows the newly created managed bean class. The task flow that this MAF AMX page is part of is updated to reference the bean.
```
<managed-bean id="__3">
   <managed-bean-name>MyBean</managed-bean-name>
   <managed-bean-class>mobile.MyBean</managed-bean-class>
   <managed-bean-scope>application</managed-bean-scope>
</managed-bean>
```
Note:

If a given MAF AMX page is part of bounded as well as unbounded task flows, both of these task flows are updated with the managed bean entry.
Click New next to the Method field (see Figure 12-16 and Figure 12-17) to open the Create Method dialog that Figure 12-20 shows.

Figure 12-20 Create Method Dialog

Use this dialog to provide the managed bean method name (see Figure 12-21).

Figure 12-21 Naming Managed Bean Method

Upon completion, the selected property value is updated with the appropriate EL expression, such as the following for a commandButton:
```
<amx:commandButton action="#{MyBean.getMeHome}"/>
```
The managed bean class is also updated to contain the newly created method, as the following example shows.
```
package mobile;

public class MyBean {
   public MyBean() {
   }

   public String getMeHome() {
      // Add event code here...
      return null;
   }
}
```

To select an existing managed bean:

Make a selection from the Managed Bean list that Figure 12-22 shows.

Figure 12-22 Selecting Managed Bean

Similar to the action outcomes, the Managed Bean list is populated with managed beans from all task flows that this MAF AMX page is part of.

Note:

If the MAF AMX page is not part of any task flow, you can still create a managed bean.

For more information, see the following:

About the Managed Beans Category
APIDemo, a MAF sample application located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.

12.2.12 How to Specify the Page Transition Style

By defining the page transition style on the task flow, you can specify how MAF AMX pages transition from one view to another. The behavior of your MAF AMX page at transition can be as follows:

fading in
sliding in from left
sliding in from right
sliding up from bottom
sliding down from top
sliding in from start
sliding in from end
flipping up from bottom
flipping down from top
flipping from left
flipping from right
flipping from start
flipping from end
none

Sliding in from start and end, as well as flipping from start and end are used on the iOS platform and Android 4.2 or later platform to accommodate the right-to-left (RTL) text direction. It is generally recommended to use the start and end transition style as opposed to left and right.

You set the transition style by modifying the transition attribute of the control-flow-case (Control Flow Case component), as the following example shows.

<control-flow-rule id="__1">
   <from-activity-id>products</from-activity-id>
   <control-flow-case id="__2">
      <from-outcome>details</from-outcome>
      <to-activity-id>productdetails</to-activity-id>
      <transition>fade</transition>
   </control-flow-case>
</control-flow-rule>

In the Properties window, the transition attribute is located under Behavior, as Figure 12-23 shows. The default transition style is slideLeft.

Figure 12-23 Setting Transition Style in Properties Window

Tip:

When defining the task flow, you should specify the control-flow-case's transition value such that it is logical. For example, if the transition occurs from left to right with the purpose of navigating back, then the transition should return to the previous page by sliding right.

12.2.13 What You May Need to Know About Bounded and Unbounded Task Flows

Task flows provide a modular approach for defining control flow in a MAF AMX application feature. Instead of representing an application feature as a single large page flow, you can divide it into a collection of reusable task flows. Each task flow contains a portion of the application feature's navigational graph. The nodes in the task flows represent activities. An activity node represents a simple logical operation such as displaying a page, executing application logic, or calling another task flow. The transitions between the activities are called control flow cases.

There are two types of task flows in MAF AMX:

Unbounded Task Flows: a set of activities, control flow rules, and managed beans that interact to allow the end user to complete a task. The unbounded task flow consists of all activities and control flows in a MAF AMX application feature that are not included within a bounded task flow.
Bounded Task Flows: a specialized form of task flow that, in contrast to the unbounded task flow, has a single entry point and no exit points. It contains its own collections of activities and control-flow rules, as well as their own memory scope and managed-bean life span.

For a description of the activity types that you can add to unbounded or bounded task flows, see What You May Need to Know About Task Flow Activities and Control Flows.

A typical MAF AMX application feature contains a combination of one unbounded task flow created at the time when the application feature is created and one or more bounded task flows. At runtime, the MAF application can call bounded task flows from activities that you added to the unbounded task flow.

12.2.13.1 Unbounded Task Flows

A MAF AMX application feature always contains one unbounded task flow, which provides one or more entry points to that application feature. An entry point is represented by a view activity. By default, the source file for the unbounded task flow is the adfc-mobile-config.xml file.

Figure 12-24 displays the diagram for an unbounded task flow from a MAF AMX application feature. This task flow contains a number of view activities that are all entry points to the application feature.

Figure 12-24 Unbounded Task Flow Diagram

Consider using an unbounded task flow if the following applies:

There is no need for the task flow to be called by another task flow.
The MAF AMX application feature has multiple points of entry.
There is no need for a specifically designated activity to run first in the task flow (default activity).

An unbounded task flow can call a bounded task flow, but cannot be called by another task flow.

12.2.13.2 Bounded Task Flows

By default, the IDE proposes a file name for the source file of a bounded task flow (see How to Create a Task Flow). You can modify this file name to reflect the purpose of the task to be performed.

A bounded task flow can call another bounded task flow, which can call another, and so on. There is no limit to the depth of the calls.

Figure 12-25 displays the diagram for a bounded task flow from a MAF AMX application feature.

Figure 12-25 Bounded Task Flow Diagram

The following are reasons for creating a bounded task flow:

The bounded task flow always specifies a default activity, which is a single point of entry that must execute immediately upon entry of the bounded task flow.
It is reusable within the same or other MAF AMX application features.
Any managed beans you use within a bounded task flow can be specified in a page flow scope, making them isolated from the rest of the MAF AMX application feature. These managed beans (with page flow scope) are automatically released when the task flow completes.

The following is a summary of the main characteristics of a bounded task flow:

Well-defined boundary: a bounded task flow consists of its own set of private control flow rules, activities, and managed beans. A caller requires no internal knowledge of page names, method calls, child bounded task flows, managed beans, and control flow rules within the bounded task flow boundary. Data controls can be shared between task flows.
Single point of entry: a bounded task flow has a single point of entry—a default activity that executes before all other activities in the task flow.
Page flow memory scope: you can specify page flow scope as the memory scope for passing data between activities within the bounded task flow. Page flow scope defines a unique storage area for each instance of a bounded task flow. Its lifespan is the bounded task flow, which is longer than request scope and shorter than session scope.
Addressable: you can access a bounded task flow by specifying its unique identifier within the XML source file for the bounded task flow and the file name of the XML source file.
Reusable: you can identify an entire group of activities as a single entity, a bounded task flow, and reuse the bounded task flow in another MAF AMX application feature within a MAF application.

You can also reuse an existing bounded task flow by calling it.

In addition, you can use task flow templates to capture common behaviors for reuse across different bounded task flows.
Parameters and return values: a caller can pass input parameters to a bounded task flow and accept return values from it (see Passing Parameters to a Bounded Task Flow and Configuring a Return Value from a Bounded Task Flow).

In addition, you can share data controls between bounded task flows.
On-demand loading of metadata: bounded task flow metadata is loaded on demand when entering a bounded task flow.

12.2.13.3 Using Parameters in Task Flows

A task flow´s ability to accept input parameters and return parameter values allows you to manipulate data in task flows and share data between task flows. Using these abilities, you can optimize the reuse of task flows in your MAF AMX application feature.

Figure 12-26 shows a task flow that specifies an input parameter definition to hold information about a user in a pageFlow scope.

Figure 12-26 Input Parameters in Task Flow

You can specify parameter values using standard EL expressions if you call a bounded task flow using a task flow call activity. For example, you can specify parameters using the following syntax for EL expressions:

```
#{bindings.bindingId.inputValue}
```
```
#{CustomerBean.zipCode}
```

Appending inputValue to the EL expression ensures that you assign to the parameter the value of the binding rather than the actual binding object.

12.2.13.3.1 Passing Parameters to a Bounded Task Flow

A called bounded task flow can accept input parameters from the task flow that calls it or from a task flow binding.

To pass an input parameter to a bounded task flow, you specify one or more of the following:

Input parameters on the task flow call activity in the calling task flow: input parameters specify where the calling task flow stores parameter values.
Input parameter definitions on the called bounded task flow: input parameter definitions specify where the called bounded task flow can retrieve parameter values at runtime.

Specify the same name for the input parameter that you define on the task flow call activity in the calling task flow and the input parameter definition on the called bounded task flow. Do this so you can map input parameter values to the called bounded task flow.

If you do not specify an EL expression to reference the value of the input parameter, the EL expression for value defaults to the following at runtime:

#{pageFlowScope.parmName}

where parmName is the value you entered for the input parameter name.

In an input parameter definition for a called bounded task flow, you can specify an input parameter as required. If the input parameter does not receive a value at runtime or design time, the task flow raises a warning in a log file of the MAF application that contains the task flow. An input parameter that you do not specify as required can be ignored during task flow call activity creation.

Task flow call activity input parameters can be passed by reference or passed by value when calling a task flow using a task flow call activity (see Specifying Input Parameters on a Task Flow Call Activity). By default, primitive types (for example, int, long, or boolean) are passed by value (pass-by-value).

A called task flow can return values to the task flow that called it when it exits. For more information, see Configuring a Return Value from a Bounded Task Flow.

When passing an input parameter to a bounded task flow, you define values on both the calling task flow and the called task flow.

Before you begin:

Create a calling and called task flow: the calling task flow can be bounded or unbounded. The called task flow must be bounded. For more information about creating task flows, see How to Create a Task Flow.
Add a task flow call activity to the calling task flow.

Figure 12-27 shows an example where the view activity passes control to the task flow call activity.

Figure 12-27 Calling Task Flow

To pass an input parameter to a bounded task flow:

Open a MAF AMX page that contains an input component where the end user enters a value that is passed to a bounded task flow as a parameter at runtime.

Note:

The MAF AMX page that you open should be referenced by a view activity in the calling task flow.
Select an input text component on the MAF AMX page where the end user enters a value at runtime.
In the Properties window, expand the Common section and enter a value for the input text component in the Value field.

You can specify the value as an EL expression (for example, #{pageFlowScope.inputValue}), either manually or using the Expression Builder.
Open the task flow that is to be called by double-clicking it in the Applications window, then switch the view to the Overview tab and select the Parameters navigation tab.
In the Input Parameter Definition section, click Add ( + ) to specify a new entry (see Figure 12-26):
- In the Name field, enter a name for the parameter (for example, inputParm1).
- In the Value field, enter an EL expression where the parameter value is stored and referenced (for example, #{pageFlowScope.inputValue}), either manually or using the Expression Builder.
In the Applications window, double-click the calling task flow that contains the task flow call activity to invoke the called bounded task flow.
In the Applications window, drag the called bounded task flow and drop it on top of the task flow call activity that is located in the diagram of the calling task flow. This automatically creates a task flow reference to the bounded task flow. As shown in Figure 12-28, the task flow reference contains the following:
- The bounded task flow ID (id): an attribute of the bounded task flow's task-flow-definition element.
- The document name that points to the source file for the task flow that contains the ID.
Figure 12-28 Task Flow Reference
In the Properties window for the task flow call activity, expand the Parameters section to view the Input Parameters section.
- Enter a name that identifies the input parameter: since you dropped the bounded task flow on a task flow call activity having defined input parameters, the name should already be specified. You must keep the same input parameter name.
- Enter a parameter value (for example, #{pageFlowScope.param1}): the value on the task flow call activity input parameter specifies where the calling task flow stores parameter values. The value on the input parameter definition for the called task flow specifies the location from which the value is to be retrieved for use within the called bounded task flow once it is passed.

At runtime, the called task flow can to use the input parameter. If you specified pageFlowScope as the value in the input parameter definition for the called task flow, you can use the parameter value anywhere in the called bounded task flow. For example, you can pass it to a view activity on the called bounded task flow.

Upon completion, JDeveloper writes entries to the source files for the calling task flow and called task flow based on the values that you select.

The following example shows an input parameter definition specified on a a bounded task flow.

<task-flow-definition id="sourceTaskflow">
...
   <input-parameter-definition>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.parmValue1}</value>
      <class>java.lang.String</class>
   </input-parameter-definition>
...
</task-flow-definition>

The following example shows the input parameter metadata for the task flow call activity that calls the bounded task flow shown in the preceding example.

<task-flow-call id="taskFlowCall1">
...
   <input-parameter>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.newCustomer}</value>
      <pass-by-value/>
   </input-parameter>
...
</task-flow-call>

At runtime, the task flow call activity calls the bounded task flow and passes it the value specified by its value element.

12.2.13.3.2 Configuring a Return Value from a Bounded Task Flow

You configure a return value definition on the called task flow and add a parameter to the task flow call activity in the calling task flow that retrieves the return value at runtime.

Before you begin:

Create a bounded or unbounded task flow (calling task flow) and a bounded task flow (called task flow). For more information, see How to Create a Task Flow.

To configure a return value from a called bounded task flow:

Open the task flow that is to be called by double-clicking it in the Applications window, then switch the view to the Overview tab and select the Parameters navigation tab.
In the Return Value Definitions section, click Add ( + ) to define a return value (see Figure 12-26):
- In the Name field, enter a name to identify the return value (for example, returnValue1).
- In the Class field, enter a Java class that defines the data type of the return value. The default value is java.lang.String.
- In the Value field, enter an EL expression that specifies from where to read the return value (for example, #{pageFlowScope.ReturnValueDefinition}), either manually or using the Expression Builder.
In the Applications window, double-click the calling task flow.
With the task flow page open in the Diagram view, select Components > Activities from the Components window, and then drag and drop a task flow call activity onto the diagram.
In the Properties window for the task flow call activity, expand the Parameters section, click Add ( + ) for the Return Values entry, and then add values as follows to define a return value:
- A name to identify the return value (for example, returnValue1). It must match the value you entered for the Name field when you defined the return value definition in step 2.
- A value as an EL expression that specifies where to store the return value (for example, #{pageFlowScope.ReturnValueDefinition}).

Upon completion, JDeveloper writes entries to the source files for the calling task flows that you configured.

The following example shows a sample entry that JDeveloper writes to the source file for the calling task flow.

<task-flow-call id="taskFlowCall1">
   <return-value id="__3">
      <name id="__4">returnValue1</name>
      <value id="__2">#{pageFlowScope.ReturnValueDefinition}</value>
   </return-value>
</task-flow-call>

The following example shows a sample entry that JDeveloper writes to the source file for the called task flow.

<return-value-definition id="__2">
   <name id="__3">returnValue1</name>
   <value>#{pageFlowScope.ReturnValueDefinition}/</value>
   <class>java.lang.String</class>
</return-value-definition>

At runtime, the called task flow returns a value. If configured to do so, the task flow call activity in the calling task flow retrieves this value.

12.3 Creating Views

You can start creating a MAF AMX view by doing the following:

Getting familiar with the MAF AMX page structure (see Interpreting the MAF AMX Page Structure)
Editing and previewing a MAF AMX page (see Using UI Editors)
Dragging and dropping components onto a MAF AMX page (see How to Add UI Components to a MAF AMX Page)
Adding data controls to a view (see How to Add Data Controls to a MAF AMX Page)

12.3.1 How to Work with MAF AMX Pages

A MAF AMX page is represented by an XML file whose structure consists of layered elements defining the page's presentation and functionality.

12.3.1.1 Interpreting the MAF AMX Page Structure

The following is a basic structure of the MAF AMX file:

<amx:view>
   <amx:panelPage id="pp1">
      <amx:facet name="header">
         <amx:outputText id="ot1" value="Welcome"/>
      …
      </amx:facet>
   </amx:panelPage>
</amx:view>

With the exception of data visualization components (see Providing Data Visualization), UI elements are declared under the <amx> namespace.

For more information, see What Happens When You Create a MAF AMX Page.

12.3.1.2 Creating MAF AMX Pages

MAF AMX files are contained in the View Controller project of the MAF application. You create these files using the Create MAF AMX Page dialog.

MAF offers two alternative ways of creating a MAF AMX page:

From the New Gallery
From an existing task flow

Before you begin:

To create a MAF AMX page, the MAF application must include a View Controller project file (see Getting Started with MAF Application Development ).

To create a MAF AMX page from the New Gallery:

From the top-level menu in JDeveloper, click File, and then select New > From Gallery.
In the New Gallery, expand the Client Tier node, select Mobile Application Framework, and then MAF AMX Page (see Figure 12-29). Click OK.

Figure 12-29 Creating MAF AMX Page
In the Create MAF AMX Page dialog, enter a name and, if needed, a location for your new file, as Figure 12-30 shows.
Optionally, you may select which facets your new MAF AMX page will include as a part of the page layout:
- Header
- Primary
- Secondary
- Footer
For more information, see What Happens When You Create a MAF AMX Page and How to Use a Facet Component.

Note:

When you select or deselect a facet, the image representing the page changes dynamically to reflect the changing appearance of the page.

Figure 12-30 Create MAF AMX Page Dialog

Note:

MAF persists your facet selection and applies it to each subsequent invocation of the Create MAF AMX Page dialog.
Click OK on the Create MAF AMX Page dialog.

To create a MAF AMX page from a View component of the task flow:

Open a task flow file in the diagrammer (see Figure 12-7, How to Create a Task Flow and What You May Need to Know About the MAF Task Flow Diagrammer)
Double-click a View component of the task flow to open the Create MAF AMX Page dialog that Figure 12-30 shows, and then enter a name and, if needed, a location for your new file. Click OK.

12.3.1.3 What Happens When You Create a MAF AMX Page

When you use the Create MAF AMX Page dialog to create a MAF AMX page, JDeveloper creates the physical file and adds it to the Web Content directory of the View Controller project.

In the Applications window that Figure 12-31 shows, the Web Content node contains a newly created MAF AMX file called department.amx.

Figure 12-31 MAF AMX File in Applications Window

JDeveloper also adds the code necessary to import the component libraries and display a page. This code is illustrated in the Source editor shown in Figure 12-31.

Figure 12-33 shows how the Preview pane and the generated MAF AMX code would look like if you selected all facet types listed in the Page Facet section of the Create MAF AMX Page dialog when creating the page (see Figure 12-32).

Figure 12-32 Creating MAF AMX Page with All Facets

Figure 12-33 MAF AMX Page With All Facets

In the page created with all the facets selected (see Figure 12-32 and Figure 12-33), note the following:

The header is created with an Output Text component because this component is typically used for the page title.
The primary and secondary actions are created with Button components because it is a typical pattern.
Since there is no single dominant pattern for the footer, it is created with an Output Text component by default because that component is used in some patterns and it prevents JDeveloper from generating the initial code with audit violation.
Adding either the primary or secondary action without adding the header facet still causes the header section to appear in the Page Facets section of Create MAF AMX Page dialog.

Figure 12-34 shows the Page Facet section of the Create MAF AMX Page dialog without any facets selected and Figure 12-35 shows the Preview pane with the generated MAF AMX code.

Figure 12-34 Creating MAF AMX Page Without Selected Facets

Figure 12-35 MAF AMX Page Without Facets

12.3.1.4 Using UI Editors

When the page is first displayed in JDeveloper, it is displayed in the Source editor. To view the page in a WYSIWYG environment, use the Preview pane (accessed by clicking the Preview tab).

Figure 12-36 shows the Preview tab selected for a newly created MAF AMX page called department.amx. This page is blank because it has not yet been populated with MAF AMX UI components or data controls.

Figure 12-36 The Preview Pane for Newly Created Page

Using the Preview pane's tool bar that Figure 12-36 shows, you can do the following:

Refresh the display of the MAF AMX page by clicking Refresh Page.
Stop loading of the page by clicking Stop Loading Page.
Modify the form factor for the page by selecting a different form factor from the dropdown list. For more information on form factors, see the "Configuring the Development Environment for Form Factors" section in Installing Oracle Mobile Application Framework.
Modify the scaling of the display by selecting a different percentage value from the dropdown list. Since mobile device displays can be of various sizes and densities, the Preview pane allows you to see the effect of scaling on your MAF AMX pages.

Note:

Scaling is available for both Portrait and Landscape mode.
Change orientation for the display to portrait and landscape by selecting Show Portrait Orientation or Show Landscape Orientation respectively.
Select the feature content for your MAF AMX page form the dropdown list of available application features. By default, <No Feature Content Selected> is displayed.

To view the source for the page in the Source editor, click the Source tab that Figure 12-31 shows. The Structure window, located in the lower left-hand corner of JDeveloper (shown in Figure 12-31 and Figure 12-36), provides a hierarchical view of the page. For more information, see Using the Preview.

12.3.1.5 Accessing the Page Definition File

MAF AMX supports JDeveloper's Go to Page Definition functionality that enables you to navigate to the MAF AMX page definition (see Figure 12-37 and What You May Need to Know About Generated Drag and Drop Artifacts) by using a context menu that allows you to locate and edit the binding information quickly.

Figure 12-37 Page Definition File Accessed Through Go To Page Definition

You can invoke the context menu that contains the Go to Page Definition option from the following:

Source editor, as Figure 12-38 shows.

Figure 12-38 Go to Page Definition from Source Editor
Applications window, as Figure 12-39 shows.

Figure 12-39 Go to Page Definition from Applications Window
Structure window, as Figure 12-40 shows.

Figure 12-40 Go to Page Definition from Structure Pane

In addition, you can open the Page Definition file using the Go to Page Definition shortcut key defined under Tools > Preferences on the main menu, as Figure 12-41 shows.

Figure 12-41 Opening Page Definition from Preferences

12.3.1.6 Sharing the Page Contents

You can enable sharing of contents of MAF AMX pages. Fragment (fragment) is a dynamic declarative component that allows for reusable parts of a MAF AMX page elements, including attributes and facets, to be inserted into the content represented by a template. This enables you to standardize the look and feel of your application by reusing the Fragment template across various pages within the application.

You can drag and drop a MAF AMX fragment file ( .amxf) onto a MAF AMX page or another fragment file to create a reference to the fragment and to define its attributes (see Configuring the Fragment Content). The fragment file resides inside your project and you can drop it from the Applications window.

Before you begin:

Ensure that the MAF application includes a View Controller project.

If the View Controller project does not contain a MAF AMX page or MAF AMX page task flow from which to create a page, you can invoke the Create MAF AMX Page dialog by double-clicking a view icon in a task flow diagram or by selecting Client Tier > Mobile Application Framework > MAF AMX Page from the New Gallery (see Creating MAF AMX Pages).

To create a Fragment from the New Gallery:

From the top-level menu in JDeveloper, click File, and then select New > From Gallery.
In the New Gallery, expand the Client Tier node, select Mobile Application Framework, and then MAF AMX Page Fragment (see Figure 12-42). Click OK.

Figure 12-42 Creating New Fragment
Complete the Create MAF AMX Page Fragment dialog by entering the file name and location of the new fragment, as Figure 12-43 shows. Click OK.

Figure 12-43 Create MAF AMX Page Fragment Dialog

Upon completion of the dialog, a newly created file opens in the Source editor of JDeveloper (see Figure 12-44).

Figure 12-44 Fragment File
Right-click Fragment in the Structure window and select Insert Inside Fragment. Choose elements with which to populate the new fragment (see Figure 12-45): Attribute, Attribute List, Description, Facet, or Popup.

Figure 12-45 Populating Fragment
Proceed by defining the Fragment's Attribute and other children by right-clicking that child in the Structure view and selecting appropriate values (see Figure 12-46).

Figure 12-46 Defining Fragment's Attribute

You can also define the Fragment by dragging and dropping its elements onto the MAF AMX fragment file by selecting MAF AMX Fragment in the Components window (see Figure 12-47).

Figure 12-47 Dragging and Dropping Fragment Elements

The following example shows a MAF AMX fragment file called fragment1.amxf.

<amx:fragmentDef
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
   xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <fragment xmlns="http://xmlns.oracle.com/adf/mf/amx/fragment" id="f1">
      <description id="d1">Description of the fragment</description>
      <facet id="f2">
         <description id="d4">Description of the facet</description>
         <facet-name id="f3">facet1</facet-name>
      </facet>
      <attribute id="a1">
         <description id="d2">Description of an attribute</description>
         <attribute-name id="a2">text</attribute-name>
         <attribute-type id="at1">String</attribute-type>
         <default-value id="d3">defaultValue</default-value>
      </attribute>
   </fragment>
   <amx:panelGroupLayout id="pgl1">
      <amx:facetRef facetName="facet1" id="fr1"/>
      <amx:outputText value="#{text}" id="ot1"/>
   </amx:panelGroupLayout>
</amx:fragmentDef>

To include the contents of the fragment in the MAF AMX page, you create a Fragment component (see How to Use the Fragment Component) and set its src attribute to the fragment file of your choice. The following example shows a fragment element added to a MAF AMX page. This element points to the fragment1.amxf as its page contents. At the same time, the facetRef element, which corresponds to the Facet Definition MAF AMX component, points to facet1 as its facet (MAF AMX Facet component). The facetRef element can only be specified in the .amxf file within the fragmetDef. You can pass attributes to the facetRef by specifying the MAF AMX attribute element as its child, which allows you to pass an EL variable from the Fragment to a Facet through the attribute's value.

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <amx:panelPage id="pp1">
      <amx:panelGroupLayout layout="vertical"
                            id="itemPgl"
                            styleClass="amx-style-groupbox">
         <amx:fragment id="f1" 
                       src="/simpleFragment.amxf"
            <amx:attribute id="a1"
                           name="text" 
                           value="defaultValue" />
            <amx:facet name="facet">
               <amx:outputText id="ot5" value="Fragment"/>
            </amx:facet>
         </amx:fragment>
      </amx:panelGroupLayout>
   </amx:panelPage>
</amx:view>

The Fragment receives all the information through its attributes. In addition to defining individual attributes, you can define a set of attributes to be passed to the Fragment as a list which could be iterated through in the Fragment definition. For more information, see Passing List of Attributes with Metadata to a Fragment.

Note:

EL expressions used within the Fragment file (.amxf) are not validated.

The Fragment supports the following:

Embedded popups (see How to Use a Popup Component).
Reusable user interface that can be placed on one or more other parent pages or fragments. This allows you to create a component that is composed of other components without bindings.
Definition of its own facets. This allows you to create a component such as a layout component that defines a header facet, summary facet, and detail facet, with each facet having its own style class as well as look and feel.
Data model with both attributes and collections.

MAF sample applications called FragmentDemo and CompGallery demonstrate how to create and use the fragment. These sample applications are located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.

12.3.1.6.1 Configuring the Fragment Content

When you drag and drop a MAF AMX fragment file ( .amxf) onto a MAF AMX page or another fragment file, the Configure Fragment Content dialog (see Figure 12-48) appears. This dialog displays and allows you to specify all Fragment attributes that are defined as direct children of the Fragment.

Note:

Facets, Popup components, Attribute Lists and their artifacts are not available through the Configure Fragment Content dialog.

Figure 12-48 Configure Fragment Content Dialog

Figure 12-49 demonstrates the Configure Fragment Content dialog that appears when you drag and drop the MAF AMX fragment file whose contents is shown in the following example onto a MAF AMX file.

<amx:fragmentDef
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
   xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <fragment xmlns="http://xmlns.oracle.com/adf/mf/amx/fragment" id="f1">
      <description id="d1">Description of the fragment</description>
      <facet id="f2">
         <description id="d4">Description of the facet</description>
         <facet-name id="f3">facet1</facet-name>
      </facet>
      <attribute id="a1">
         <description id="d2">Description of an attribute</description>
         <attribute-name id="a2">text</attribute-name>
         <attribute-type id="at1">String</attribute-type>
         <default-value id="d3">defaultValue</default-value>
      </attribute>
   </fragment>
   <amx:panelGroupLayout id="pgl1">
      <amx:facetRef facetName="facet1" id="fr1"/>
      <amx:outputText value="#{text}" id="ot1"/>
   </amx:panelGroupLayout>
</amx:fragmentDef>

Figure 12-49 Configure Fragment Content Dialog with Values

When completing the dialog, consider the following:

If you are configuring an attribute defined as required in the Fragment, an asterisks ( * ) is displayed at the end of the attribute name.
The OK button of the dialog is disabled until all of the required attribute values have been defined.
If the Fragment attribute's default value is specified and at the same time the required property is defined and set to true, this attribute is not treated as required (the default value takes precedence). In this case, the following occurs:
- An audit warning is displayed in the Fragment.
- The Configure Fragment Content dialog does not add the asterisk to the attribute's name and does not treat this attribute as required.
The Type column displays the value of the attribute-type element from the Fragment. It is used as a description of the attribute type (as opposed to the Java class).

Note:

Even though the attribute-type is a required element in the Fragment, it might appear unspecified in the Fragment being dropped if you failed to define its value. In this case the dialog displays String as a default value.
The Value column allows you to specify the value to pass to the Fragment's attribute. You can enter the value by typing it or clicking on the ellipsis ( … ) to invoke the EL Builder and specify an EL expression. If the default element is present for the given attribute in the Fragment, this default value is specified in the Value column for the attribute. You can override the default value.
If the description element is present in the Fragment for this attribute, the bottom portion of the dialog displays the Attribute Description field when you switch between rows of different attributes. If the description element is not defined, the Attribute Description field is blank.
You cannot add, remove, or reorder attributes using the Configure Fragment Content dialog.

12.3.1.6.2 Passing List of Attributes with Metadata to a Fragment

When defining the Fragment attributes, MAF allows you to do the following:

Pass in dynamic attributes.
Have metadata associated with each attribute (see Passing List of Attributes with Metadata to a Fragment).
Loop over attributes in the Fragment definition.
Nest dynamic attributes in an attribute.
Pass dynamic attributes from one Fragment to an embedded Fragment.

Table 12-4 lists direct and indirect child elements of the MAF AMX fragment that enable you to pass lists of attributes.

Table 12-4 Attribute-Related Child Elements of the Fragment

Child Attribute Name Description

Child Attribute Name	Description
`attributeList`	Defines an attribute list to pass to a Fragment. Can be a direct child of the MAF AMX `fragment` or `attributeSet` element. There can be any number of the child `attributeList` elements defined for a parent element. The `attributeList` element may be referenced by another `attributeList` through its `ref` attribute. An attribute list may be passed from one Fragment to another by reference, in which case both attribute lists must have the same metadata.
`attributeSet`	Can be specified as a child of the MAF AMX `attributeList`. Defines one set of attributes to be used during an iteration of the MAF AMX `attributeListIterator`. May be thought of as one item in an array. There can be any number of the child `attributeSet` elements defined for a parent `attributeList` element.
`attributeListIterator`	Consumes a MAF AMX `attributeList`. Behaves similarly to the MAF AMX Iterator in terms of stamping, but exposes attributes differently, with its `name` attribute tying the iterator to the `attributeList`. When one `attributeListIterator` is nested inside another, the `name` must point to the `attributeList` which is a child of the `attributeSet` currently being processed by the `attributeListIterator`. During the iteration, the defined attribute names are exposed as EL variables. For attributes that are not provided by the caller and in cases when the attribute has no default value, the value `adf.mf.api.OptionalFragmentArgument` is used as an EL variable. You may test for this condition by using the empty EL keyword (for example, `rendered="#{not (empty myAttribute)}"`).

attributeList

Defines an attribute list to pass to a Fragment. Can be a direct child of the MAF AMX fragment or attributeSet element.

There can be any number of the child attributeList elements defined for a parent element.

The attributeList element may be referenced by another attributeList through its ref attribute.

An attribute list may be passed from one Fragment to another by reference, in which case both attribute lists must have the same metadata.

attributeSet

Can be specified as a child of the MAF AMX attributeList.

Defines one set of attributes to be used during an iteration of the MAF AMX attributeListIterator. May be thought of as one item in an array.

There can be any number of the child attributeSet elements defined for a parent attributeList element.

attributeListIterator

Consumes a MAF AMX attributeList. Behaves similarly to the MAF AMX Iterator in terms of stamping, but exposes attributes differently, with its name attribute tying the iterator to the attributeList.

When one attributeListIterator is nested inside another, the name must point to the attributeList which is a child of the attributeSet currently being processed by the attributeListIterator.

During the iteration, the defined attribute names are exposed as EL variables. For attributes that are not provided by the caller and in cases when the attribute has no default value, the value adf.mf.api.OptionalFragmentArgument is used as an EL variable. You may test for this condition by using the empty EL keyword (for example, rendered="#{not (empty myAttribute)}").

For information on attributes and their values, see Tag Reference for Oracle Mobile Application Framework.

The following example demonstrates the basic case of passing an Attribute List to a MAF AMX Fragment.

<amx:fragment src="something.amxf">
   <amx:attributeList name="attributeToPass" ref="nameOfAnOuterAttributeList" />
</amx:fragment>

The following example shows the fragment element with the child attributeList defined in the MAF AMX file.

<amx:fragment src="summaryView.amxf">
   <amx:attributeList name="attrs">
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.firstName}"/>
         <amx:attribute name="displayType" value="string" />
      </amx:attributeSet>
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.lastName}"/>
         <amx:attribute name="displayType" value="string" />
      </amx:attributeSet>
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.homePhone}"/>
         <amx:attribute name="displayType" value="phone" />
      </amx:attributeSet>
   </amx:attributeList>
</amx:fragment>

The following example shows nested attributeList elements defined within the fragment element in the MAF AMX file.

<amx:fragment src="summaryView.amxf">
   <amx:attributeList name="attrs">
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.firstName}"/>
         <amx:attribute name="displayType" value="string" />
      </amx:attributeSet>
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.lastName}"/>
         <amx:attribute name="displayType" value="string" />
      </amx:attributeSet>
      <amx:attributeSet>
         <amx:attribute name="attribute" value="#{bindings.homePhone}"/>
         <amx:attribute name="displayType" value="phone" />
      </amx:attributeSet>
      <amx:attributeSet>
         <amx:attributeList name="subAttributes">
            <amx:attributeSet>
               <amx:attribute name="attribute"
                              value="#{bindings.spouseFirstName}"/>
               <amx:attribute name="displayType" 
                              value="string" />
            </amx:attributeSet>
            <amx:attributeSet>
               <amx:attribute name="attribute"
                              value="#{bindings.spouseLastName}"/>
               <amx:attribute name="displayType"
                              value="string" />
            </amx:attributeSet>
         </amx:attributeList>
         <amx:attribute name="label" value="Spouse"/>
      </amx:attributeSet>
   </amx:attributeList>
</amx:fragment>

The following example shows how a Fragment with defined Attribute List components is used within the Fragment Definition. The amxf:attribute-list tag defines the metadata for an Attribute List. This tag must be declared as a child of the amxf:fragment or another amxf:attribute-list tag and its valid child tags are amxf:name, amxf:description, amxf:attribute-list, and amxf:attribute. The name child is required and must be unique within the current XML node. Even though the name could be identical to the amxf:attribute that is declared on the same level, such naming practice is not recommended.

<amx:fragmentDef
   xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
   xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <fragment xmlns="http://xmlns.oracle.com/adf/mf/amx/fragment">
      <attribute-list>
         <name>attributes</name>
         <attribute>
            <attribute-name>attribute</attribute-name>
         </attribute>
         <attribute>
            <attribute-name>displayType</attribute-name>
         </attribute>
         <attribute>
            <attribute-name>label</attribute-name>
         </attribute>
         <attribute-list>
            <name>subAttributes</name>
            <attribute>
               <attribute-name>attribute</attribute-name>
            </attribute>
            <attribute>
               <attribute-name>displayType</attribute-name>
            </attribute>
         </attribute-list>
      </attribute-list>
   </fragment>
   ...
   <amx:attributeListIterator name="attributes">
      <amx:panelLabelAndMessage label="#{attribute.hints.label}"
                                id="plam1"
                                rendered="#{not (empty attribute)}">
         <amx:outputText value="#{attribute.inputValue}" id="ot1"/>
      </amx:panelLabelAndMessage>
      <amx:outputText value="#{label}"
                      id="ot2"
                      rendered="#{not (empty label)}"/>
      <amx:attributeListIterator name="subAttributes"
                                 rendered="#{not (empty subAttributes)}">
         <amx:panelLabelAndMessage label="#{attribute.hints.label}"
                                   id="plam2"
                                   rendered="#{not (empty attribute)}">
            <amx:outputText value="#{attribute.inputValue}" id="ot3"/>
         </amx:panelLabelAndMessage>
      </amx:attributeListIterator>
   </amx:attributeListIterator>
   ...
</amx:fragmentDef>

The attribute-list, attribute-set, and attribute tags could be used in the fragment node to define the following:

Attribute List components that are allowed.
The information necessary to validate the page that is calling the Fragment.

12.3.2 How to Add UI Components to a MAF AMX Page

After you create a MAF AMX page, you can start adding MAF AMX UI components to your page.

You can use the Components window to drag and drop MAF AMX components and MAF AMX data visualization components onto the page. JDeveloper then adds the necessary declarative page code and sets certain values for component attributes.

The Components window displays MAF AMX components by categories (see Figure 12-50):

General Controls
Text and Selection
Data Views
Layout, with the following subcategories:
- Interactive Containers and Headers
- Secondary Windows
- Core Structure
Operations, with the following subcategories:
- Behavior
- Listeners
- Validators and Converters

For information on adding and using specific components, see Creating and Using UI Components.

The Components window also displays MAF AMX data visualization components by categories (see Figure 12-50):

Common, with the following subcategories:
- Chart
- Gauge
- Map
- Miscellaneous
Shared Child Tags
Other Type-Specific Child Tags, with the following subcategories:
- Chart
- Gauge
- NBox
- Thematic Map
- Timeline
- Sunburst and Treemap

Before you begin:

The MAF application must include a View Controller project, which may or may not contain a MAF AMX page or MAF AMX page task flow from which to create a page.

As described in Creating MAF AMX Pages, you can invoke the Create MAF AMX Page dialog by double-clicking a view icon in a task flow diagram or by selecting Client Tier > Mobile Application Framework > MAF AMX Page from the New Gallery.

To add a UI component to a page:

Open a MAF AMX page in the Source editor (default).
In the Components window, use the menu to choose MAF AMX, as Figure 12-50 shows.

Tip:

If the Components window is not displayed, choose Window > Components from the main JDeveloper menu. By default, the Components is displayed in the upper right-hand corner of JDeveloper.

Figure 12-50 MAF AMX Components Window
Select the component you wish to use, and then drag and drop it onto the Source editor or Structure window. You cannot drop components onto the Preview pane.

Note:

When building a MAF AMX page, you can only drop UI components into UI containers such as, for example, a Panel Group Layout.

JDeveloper redraws the page in the Preview pane with the newly added component.

Alternatively, you can add UI components and data visualization components from the Structure window as follows:

On the Structure window, select an existing component that you want to use as a starting point for inserting another component.
Right-click the selected component and choose one of the options: Insert Before <component>, Insert Inside <component>, or Insert After <component>, as Figure 12-51 shows.

Figure 12-51 Inserting Components from Structure Window
From the context menu, select either MAF AMX or MAF AMX Data Visualizations:
- If you select MAF AMX, the Insert MAF AMX Item dialog opens allowing you to choose the UI component to add to the page, as Figure 12-52 shows.
  
  Figure 12-52 Inserting MAF AMX Component
- If you select MAF AMX Data Visualizations, the Insert MAF AMX Data Visualizations Item dialog opens allowing you to choose the data visualization component to add to the page, as Figure 12-53 shows.
  
  Figure 12-53 Inserting MAF AMX Data Visualization Component
  
  JDeveloper redraws the page in the Preview pane with the newly added component.

12.3.2.1 Using the Preview

JDeveloper's Preview provides WYSIWYG support for both the iOS and Android platforms when you build the user interface using MAF AMX files. As illustrated in Figure 12-54, splitting a view while adding the MAF AMX components to the MAF AMX file enables you to see both the code view through the Source editor and a UI view through the Preview pane. As a result, you can modify the source and get instant feedback in terms of the look and feel of that application on both the iOS and Android platforms.

Figure 12-54 Splitting Design and Source Views

In addition to being able to see the design and source views simultaneously, you can also open and work with multiple design views at the same time, as well as set each one to a different platform and screen size. By opening a combination of design views for different devices, you can develop applications simultaneously for different platforms and form factors using different orientation. Figure 12-55 shows a split screen with iPhone on the top and iPad with 75% scaling on the bottom. You can split the Preview pane using the default split functionality of JDeveloper.

Figure 12-55 Multiple Design Views

Note:

A MAF AMX page is rendered even for an invalid MAF AMX file. Errors are indicated by the error icon on a component. By moving the mouse over the error icon, you can view the error details.

12.3.2.2 Configuring UI Components

Once you drop UI components onto a page, you can use the Properties window (displayed by default at the bottom right of JDeveloper) to set attribute values for each component.

Tip:

If the Properties window is not displayed, choose Window > Properties from JDeveloper's main menu.

Figure 12-56 shows the Properties window displaying the attributes for an Output Text component.

Figure 12-56 The Properties Window

To set component attributes:

Select the component for which you want to set attributes. You can select the component in the Structure window or you can select its tag directly in the Source editor.
In the Properties window, expand the section that contains the attribute you wish to set.

Tip:

Some attributes are displayed in more than one section. Entering or changing the value in one section will also change it in any other sections. You can search for an attribute by entering the attribute name in the search field at the top of the Properties window.
In the Properties window, either enter values directly into the fields, or if the field contains a list, use that list to select a value. You can also use the list to the right of the field, which launches a popup containing tools you can use to set the value. These tools are either specific property editors (opened by choosing Edit) or the Expression Builder, which you can use to create EL expressions for the value (opened by choosing Expression Builder or Method Expression Builder where applicable). For more information about using the Expression Builder, see How to Create an EL Expression.

When you use the Properties window to set or change attribute values, JDeveloper automatically changes the page source for the attribute to match the entered value.

Tip:

You can always change attribute values by directly editing the page in the Source editor. To view the page in the Source editor, click the Source tab at the bottom of the page.

12.3.2.3 What You May Need to Know About Element Identifiers and Their Audit

MAF generates a unique element identifier (id) and automatically inserts it into the MAF AMX page when an element is added by dropping a component from the Components window, or by dragging and dropping a data control. This results in a valid identifier in the MAF AMX page that differentiates each component from others, possibly similar components within the same page.

MAF provides an identifier audit utility that does the following:

Checks the presence and uniqueness of identifiers in a MAF AMX page.
If the identifier is not present or not unique, an error is reported for each required id attribute of an element.
Provides an automatic fix to generate a unique id for the element when a problem with the identifier is reported.

Figure 12-57 and Figure 12-58 show the identifier error reporting in the Source editor and Structure pane respectively.

Figure 12-57 Element Identifier Audit in Source Editor

Figure 12-58 Element Identifier Audit in Structure Pane

In addition to the id, the audit utility checks the popupId and alignId attributes of the Show Popup Behavior operation (see How to Use a Popup Component).

Figure 12-59 and Figure 12-60 show the Show Popup Behavior's Popup Id and Align Id attributes error reporting in the Source Editor respectively.

Figure 12-59 Popup Id Attribute Audit in Source Editor

Figure 12-60 Align Id Attribute Audit in Source Editor

For more information, see "Auditing and Monitoring Java Projects " in Developing Applications with Oracle JDeveloper.

12.3.3 How to Add Data Controls to a MAF AMX Page

After you create a MAF AMX page, you can start adding data controls to your page.

You can create databound UI components in a MAF AMX view by dragging data control elements from the Data Controls window and dropping them into either the Structure window or the Source editor. When you drag an item from the Data Controls window to either of these places, JDeveloper invokes a context menu of default UI components available for the item that you dropped. When you select the desired UI component, JDeveloper inserts it into a MAF AMX page. In addition, JDeveloper creates the binding information in the associated page definition file. If such file does not exist, then JDeveloper creates one. MAF provides a visual indicator for dropping data controls to inform you of the location of the new data control

Note:

A data control can only be dropped at a location allowed by the underlying XML schema.

Depending on the approach you take, you can insert different types of data controls into the Structure window of a MAF AMX page.

Dropping an attribute of a collection lets you create various input and output components. You can also create Button and Link components by dropping a data control operation on a page.

The respective action listener is added in the MAF AMX Button for each of these operations.

The data control attributes and operations can be dropped as one or more of the following MAF AMX UI components (see Creating and Using UI Components):

Button
Link
Input Date
Input Date with Label
Input Text
Input Text with Label
Output Text
Output Text with Label
Iterator
List Item
List View
Select Boolean Checkbox
Select Boolean Switch
Select One Button
Select One Choice
Select One Radio
Select Many Checkbox
Select Many Choice
Convert Date Time
Convert Number
Form
Read Only Form
Parameter Form

The following Date and Number types are supported:

java.util.Date
java.sql.Timestamp
java.sql.Date
java.sql.Time
java.lang.Number
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double

For information on how to use the Data Controls window in JDeveloper, see Creating Databound UI Components from the Data Controls Panel.

12.3.3.1 Dragging and Dropping Attributes

If your MAF AMX page already contains a Panel Form Layout component or does not require to have all the fields added, you can drop individual attributes from a data control. Depending on the attributes types, different data binding menu options are provided as follows:

12.3.3.1.1 Date

This category provides options for creating MAF Input Date and MAF Input Date with Label controls. Figure 12-61 shows the context menu for adding date controls that appears when you drag an attribute from the Data Controls window onto the Source editor or Structure window of a MAF AMX page.

Figure 12-61 Context Menu for Date Controls

12.3.3.1.2 Single Selection

This category provides options for creating the following controls:

MAF Select One Button
MAF Select One Choice
MAF Select One Radio
MAF Select Boolean Checkbox
MAF Select Boolean Switch

Figure 12-62 shows the context menu for adding selection controls that appears when you drag an attribute from the Data Controls window onto the Source editor or Structure window of a MAF AMX page.

Figure 12-62 Context Menu for Selection Controls

If you are working with an existing MAF AMX page and you select MAF Select One Button or MAF Select One Choice option, an appropriate version of the Edit List Binding dialog is displayed (see Figure 12-63). If you drop a control onto a completely new MAF AMX page, the Edit Action Binding dialog opens instead. After you click OK, the Edit List Binding dialog opens.

Note:

The Edit List Binding or Edit Boolean Binding dialog appears every time you drop any data control attributes as any of the single selection or boolean selection components, respectively.

Figure 12-63 Edit List Binding Dialog for Select One Button and Choice Controls

If you select MAF Select One Radio option, another version of the Edit List Binding dialog is displayed, as shown in Figure 12-64.

Figure 12-64 Edit List Binding Dialog for Select One Radio Control

If you select MAF Select Boolean Checkbox or MAF Select Boolean Switch option, another version of the Edit List Binding dialog is displayed, as shown in Figure 12-65.

Figure 12-65 Edit List Binding Dialog for Select Boolean Checkbox and Switch Controls

12.3.3.1.3 Text

This category provides options for creating the following controls:

MAF Input Text
MAF Input Text with Label
MAF Output Text
MAF Output Text with Label

Figure 12-66 shows the context menu for adding text controls that appears when you drag an attribute from the Data Controls window onto the Source editor or Structure window of a MAF AMX page.

Figure 12-66 Context Menu for Text Controls

12.3.3.2 Dragging and Dropping Operations

In addition to attributes, you can drag and drop operations and custom methods. Depending on the type of operation or method, different data binding menu options are provided, as follows:

12.3.3.2.1 Operation

This category is for data control operations. It provides the following options (see Figure 12-67):

MAF Button
MAF Link
MAF Parameter Form

Figure 12-67 Context Menu for Operations

Note:

If you drop an operation or a method as a child of the List View control, the context menu does not appear and the List Item is created automatically because no other valid control can be dropped as a direct child of the List View control. JDeveloper creates a binding similar to the following for the generated List Item:

<amx:listItem actionListener="#{bindings.getLocation.execute}"/>

12.3.3.2.2 Method

This category is for custom methods. It provides the following options (see Figure 12-68):

MAF Button
MAF Link
MAF Parameter Form

Figure 12-68 Context Menu for Methods

The MAF Parameter Form option allows you to choose the method or operation arguments to be inserted in the form, as well as the respective controls for each of the arguments (see Figure 12-69).

Figure 12-69 Edit Form Fields Dialog

The following data bindings are generated after you select the appropriate options in the Edit Form Fields dialog:

<amx:panelFormLayout id="pfl1">
   <amx:inputText id="it1"
                  value="#{bindings.empId.inputValue}"
                  label="#{bindings.empId.hints.label}" />
</amx:panelFormLayout>
<amx:commandButton id="cb1"
                   actionListener="#{bindings.ExecuteWithParams1.execute}"
                   text="ExecuteWithParams1"
                   disabled="#{!bindings.ExecuteWithParams1.enabled}"/>

For more information about generated bindings, see What You May Need to Know About Generated Bindings.

The following are supported control types for the MAF Parameter Form:

MAF Input Date
MAF Input Date with Label
MAF Input Text
MAF Input Text with Label
MAF Output Text with Label

12.3.3.3 Dragging and Dropping Collections

You can drag and drop collections onto a MAF AMX page. Depending on the type of collection, different data binding menu options are provided, as follows:

12.3.3.3.1 Multiple Selection

This category provides options for creating multiple selection controls. The following controls can be created under this category (see Figure 12-70):

MAF Select Many Checkbox
MAF Select Many Choice

Figure 12-70 Context Menu for Multiple Selection Controls

If you select either MAF Select Many Choice or MAF Select Many Checkbox as the type of the control you want to create, the Edit List Binding dialog is displayed (see Figure 12-71).

Figure 12-71 Edit List Binding Dialog for Multiple Selection Controls

12.3.3.3.2 Form

This category is used to create the MAF AMX Panel Form controls.

The following controls can be created under the Form category (see Figure 12-72):

MAF Form
MAF Read-only Form

Figure 12-72 Context Menu for Form Controls

If you select MAF Form as the type of the form you want to create, a JDeveloper wizard is invoked that lets you choose the fields to be inserted in the form, as well as the respective controls for each of the fields (see Figure 12-73).

Figure 12-73 Edit Form Fields Dialog for MAF Form

The following data bindings are generated after you select the appropriate options in the Edit Form Fields dialog:

<amx:panelFormLayout id="pfl1">
   <amx:panelLabelAndMessage id="plam1" label="#{bindings.jobId.hints.label}">
      <amx:outputText id="ot1" value="#{bindings.jobId.inputValue}" />
   </amx:panelLabelAndMessage>
   <amx:inputText id="it4"
                  value="#{bindings.title.inputValue}"
                  label="#{bindings.title.hints.label}" />
   <amx:inputText id="it5" 
                  value="#{bindings.minSalary.inputValue}" 
                  simple="true" />
   <amx:inputText id="it3" 
                  value="#{bindings.maxSalary.inputValue}" 
                  simple="true" />
</amx:panelFormLayout>

For more information about generated bindings, see What You May Need to Know About Generated Bindings.

The following are supported controls for MAF Form:

MAF Input Date
MAF Input Date with Label
MAF Input Text
MAF Input Text with Label
MAF Output Text with Label

Note:

Since MAF Output Text is not a valid Panel Form Layout child element as defined by the MAF schema, it is not supported.

If you select MAF Read-only Form as the type of the form you want to create, a JDeveloper wizard is invoked that lets you choose the fields to be inserted in the form, as well as the respective controls for each of the fields (see Figure 12-74).

Figure 12-74 Edit Form Fields Dialog for MAF Read-only Form

The following data bindings are generated after you select the appropriate options in the Edit Form Fields dialog:

<amx:panelFormLayout id="pfl1">
   <amx:panelLabelAndMessage id="plam4" 
                             label="#{bindings.jobId.hints.label}">
      <amx:outputText id="ot4" value="#{bindings.jobId.inputValue}" />
   </amx:panelLabelAndMessage>
   <amx:panelLabelAndMessage id="plam1" 
                             label="#{bindings.title.hints.label}">
      <amx:outputText id="ot1" value="#{bindings.title.inputValue}" />
   </amx:panelLabelAndMessage>
   <amx:panelLabelAndMessage id="plam3" 
                             label="#{bindings.minSalary.hints.label}">
      <amx:outputText id="ot3" value="#{bindings.minSalary.inputValue}" />
   </amx:panelLabelAndMessage>
   <amx:panelLabelAndMessage  id="plam2"                               label="#{bindings.maxSalary.hints.label}">
      <amx:outputText id="ot2" value="#{bindings.maxSalary.inputValue}" />
   </amx:panelLabelAndMessage>
</amx:panelFormLayout>

For more information about generated bindings, see What You May Need to Know About Generated Bindings.

The MAF Read-only Form only supports the MAF Output Text with Label control.

12.3.3.3.3 Iterator

This provides an option for creating the MAF AMX Iterator with child components (see Figure 12-75).

Figure 12-75 Context Menu for Iterator Control

If you select MAF Iterator as the type of the control to create, a JDeveloper wizard is invoked that lets you choose the fields to be inserted in the iterator, as well as the respective controls for each of the fields, with MAF Output Text w/Label being a default selection (see Figure 12-76).

Figure 12-76 Edit Dialog for MAF Iterator

The following data bindings are generated after you select the appropriate options in the Edit Iterator dialog:

<amx:iterator id="i1" 
              var="row" 
              value="#{bindings.jobs.collectionModel}">
   <amx:panelLabelAndMessage id="plam6"
                             label="#{bindings.jobs.hints.jobId.label}">
      <amx:outputText id="ot6" value="#{row.jobId}" />
   </amx:panelLabelAndMessage>
   <amx:panelLabelAndMessage id="plam5"
                             label="#{bindings.jobs.hints.title.label}">
      <amx:outputText id="ot5" value="#{row.title}" />
   </amx:panelLabelAndMessage>
   <amx:inputText id="it1"
                  value="#{row.bindings.minSalary.inputValue}"
                  label="#{bindings.jobs.hints.minSalary.label}" />
   <amx:inputText id="it2"
                  value="#{row.bindings.maxSalary.inputValue}"
                  label="#{bindings.jobs.hints.maxSalary.label}" />
</amx:iterator>

For more information about generated bindings, see What You May Need to Know About Generated Bindings.

The following are supported controls for MAF Iterator:

MAF Input Text
MAF Input Text with Label
MAF Output Text
MAF Output Text with Label

12.3.3.3.4 List View

This provides an option for creating the MAF AMX List View with child components (see Figure 12-77).

Figure 12-77 Context Menu for List View Control

If you select MAF List View as the type of the control to create, the ListView Gallery opens that allows you to choose a specific layout for the List View, as Figure 12-78 shows.

Figure 12-78 ListView Gallery

Table 12-5 lists the supported List Formats that are displayed in the ListView Gallery.

Table 12-5 List Formats

Format	Element Row Values
Simple	Text
Main-Sub Text	Main Text Subordinate Text
Start-End	Start Text End Text
Quadrant	Upper Start Text Upper End Text Lower Start Text Lower End Text

The Variations presented in the ListView Gallery (see Figure 12-78) for a selected list format consist of options to add either dividers, a leading image, or both:

Selecting a variation with a leading image adds an Image row to the List Item Content table (see Figure 12-79).
Selecting a variation with a divider defaults the Divider Attribute field to the first attribute in its list rather than the default No Divider value, and populates the Divider Mode field with its default value of All.

The Styles options presented in the ListView Gallery (see Figure 12-78) allow you to suppress chevrons, use an inset style list, or both:

The selections do not modify any state in the Edit List View dialog (see Figure 12-79). They only affect the generated MAF AMX markup.
Selecting a style with the inset list sets the adfmf-listView-insetList style class on the listView element in the generated MAF AMX markup.

The following is an example of the Simple format with the inset list:

<amx:listView var="row"
              value="#{bindings.employees.collectionModel}"
              fetchSize="#{bindings.employees.rangeSize}"
              styleClass="adfmf-listView-insetList"
              showMoreStrategy="autoScroll"
              bufferStrategy="viewport"
              id="listView2">
   <amx:listItem id="li2">
      <amx:outputText value="#{row.employeename}" id="ot3"/>
   </amx:listItem>
</amx:listView>

The ListView Gallery's Description pane is updated based on the currently selected Variation. The format will include a brief description of the main style, followed by the details of the selected variation. Four list formats with four variations on each provide sixteen unique descriptions detailed in Table 12-6.

Table 12-6 List View Formats and Variations

List Format	Variation	Description
Simple	Basic	A text field appears at the start side of the list item."
Simple	Dividers	A text field appears at the start side of the list item, with items grouped by dividers."
Simple	Images	A text field appears at the start side of the list item, following a leading image.
Simple	Dividers and Images	A text field appears at the start side of the list item, following a leading image. The list items are grouped by dividers.
Main-Sub Text	Basic	A prominent main text field appears at the start side of the list item with subordinate text below.
Main-Sub Text	Dividers	A prominent main text field appears at the start side of the list item with subordinate text below. The list items are grouped by dividers.
Main-Sub Text	Images	A prominent main text field appears at the start side of the list item with subordinate text below, following a leading image.
Main-Sub Text	Dividers and Images	A prominent main text field appears at the start side of the list item with subordinate text below, following a leading image. The list items are grouped by dividers.
Start-End	Basic	Text fields appear on each side of the list item
Start-End	Dividers	Text fields appear on each side of the list item, with the items grouped by dividers.
Start-End	Images	Text fields appear on each side of the list item, following a leading image.
Start-End	Dividers and Images	Text fields appear on each side of the list item, following a leading image. The list items are grouped by dividers.
Quadrant	Basic	Text fields appear in the four corners of the list item.
Quadrant	Dividers	Text fields appear in the four corners of the list item, with items grouped by dividers.
Quadrant	Images	Text fields appear in the four corners of the list item, following a leading image.
Quadrant	Dividers and Images	Text fields appear in the four corners of the list item, following a leading image. The list items are grouped by dividers.

After you make your selection from the ListView Gallery and click OK, the Edit List View wizard is invoked that lets you create the contents of a List Item by mapping binding attributes to the elements of the selected List View format, as Figure 12-79 shows.

Figure 12-79 Edit Dialog for MAF AMX List View

When completing the dialog that Figure 12-79 shows, consider the following:

The image at the start reflects the main content elements from the selected List View format and provides a mapping from the schematic representation to the named elements in the underlying table.
The read-only cells in the Element column derive from the selected List View format.
The editable cells in the Value Binding column are based on the data control node that was dropped.
The List Item is generated as either an Output Text or Image component, depending on whichever is appropriate for the particular element.
Since the number of elements (rows) is predetermined by the selected List View format, rows cannot be added or removed.
The order of elements cannot be modified.
The List Item Selection indicates the selection mode, which can be either a single item selection (default) or no selection. The showLinkIcon attribute of the List View is updated based on the selection mode: if the selection mode is set to None, showLinkIcon attribute is set to false; otherwise showLinkIcon attribute is not modified (for example, defaulted to true).

The following attributes of the listView enable the functioning of the selection mode:
- selectionListener: defines a method reference to a selection listener.
- selectedRowKeys: indicates the selection state for this component.
If the Single Item option is chosen, the Edit List View dialog automatically sets these attributes as follows:
- selectionListener is set to "bindings.treebinding.collectionModel.makeCurrent"
- selectedRowKeys is set to "bindings.treebinding.collectionModel.selectedRow"
The selectionListener attribute has the Edit option available from the Properties window which allows you to create a managed bean class, as well as an appropriate managed bean method, similar to any other listener attributes (see Figure 12-80 and Figure 12-81).

Figure 12-80 Editing Selection Listener Attribute

Figure 12-81 Edit Selection Listener Dialog

The following example shows the selection-related attributes of the listView element in the MAF AMX file. This declaration is generated when Single Item is chosen in the Edit List View dialog (see Figure 12-79.
```
<amx:listView id="listView1"
              var="row"
              value="#{bindings.employees.collectionModel}"
              fetchSize="#{bindings.employees.rangeSize}"
              showMoreStrategy="autoScroll"
              bufferStrategy="viewport"
              selectionListener=
                  "#{bindings.employees.collectionModel.makeCurrent}"
              selectedRowKeys=
                  "#{bindings.employees.collectionModel.selectedRow}">
   <amx:listItem id="listItem1">
      ...
   </amx:listItem>
</amx:listView>
```
If None was chosen as the List Item Selection option in the Edit List View dialog, then the selectionListener and selectedRowKeys attributes are not set as they do not have default values and do not appear in the MAF AMX file. At the same time, the List Item's showLinkIcon attribute is set to false. The following example demonstrates omitting selection attributes in a List View.
```
<amx:listView id="listView1"
              var="row"
              value="#{bindings.employees.collectionModel}"
              fetchSize="#{bindings.employees.rangeSize}"
              showMoreStrategy="autoScroll"
              bufferStrategy="viewport">
   <amx:listItem id="listItem1" showLinkIcon="false">
      ...
   </amx:listItem>
</amx:listView>
```
The List View selection state is preserved when navigation occurs to or from a MAF AMX page.

Note:

The selected row is respected if there is the same iterator ID across MAF AMX pages. For example, if you drag an Employees collection onto a page as a List View with employeesIterator as its iterator and then add a Details page, the selected row will only be respected if the Details page's employees iterator has its ID set to employeesIterator.

The default value of the Divider Attribute field is No Divider, in which case the Divider Mode field is disabled. If you select value other than the default, then you need to specify Divider Mode parameters, as Figure 12-82 and Figure 12-83 show.

Figure 12-82 Specifying Divider Attribute

Figure 12-83 Specifying Divider Mode

For more information on List View dividers, see How to Use List View and List Item Components.

The following MAF AMX markup and data bindings are generated after you select the appropriate options in the Edit List View dialog:

<amx:listView id="listView1"
              var="row"
              value="#{bindings.employees.collectionModel}"
              fetchSize="#{bindings.employees.rangeSize}"
              showMoreStrategy="autoScroll" 
              bufferStrategy="viewport"
              dividerAttribute="key"
              dividerMode="firstLetter"
              selectionListener=
                "#{bindings.employees.collectionModel.makeCurrent}"
              selectedRowKeys=
                "#{bindings.employees.collectionModel.selectedRow}">
   <amx:listItem id="listItem1" >
      <amx:outputText value="#{row.key}"
                      styleClass="adfmf-listItem-subtext" 
                      id="outputText1"/>
   </amx:listItem>
</amx:listView>

For more information about generated bindings, see What You May Need to Know About Generated Bindings.

The following are supported controls for MAF List View:

MAF Output Text
MAF Image

12.3.3.4 What You May Need to Know About Generated Bindings

Table 12-7 shows sample bindings that are added to a MAF AMX page when components are dropped.

Table 12-7 Sample Data Bindings

Component	Data Bindings
Button	<amx:commandButton id="commandButton1" actionListener="#{bindings.FindContacts.execute}" text="FindContacts" disabled="#{!bindings.FindContacts.enabled}"> </amx:commandButton>
Link	<amx:commandLink id="commandLink1" actionListener="#{bindings.FindContacts.execute}" text="FindContacts" disabled="#{!bindings.FindContacts.enabled}"> </amx:commandLink>
Input Date with Label	<amx:inputDate id="inputDate1" value="#{bindings.timeStamp.inputValue}" label="#{bindings.timeStamp.hints.label}"> </amx:inputDate>
Input Date	<amx:inputDate id="inputDate1" value="#{bindings.timeStamp.inputValue}"> </amx:inputDate>
Input Text with Label	<amx:inputText id="inputText1" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.hints.label}"> </amx:inputText>
Input Text	<amx:inputText id="inputText1" value="#{bindings.contactData.inputValue}" simple="true"> </amx:inputText>
Output Text	<amx:outputText id="outputText1" value="#{bindings.contactData.inputValue}"> </amx:outputText>
Output Text with Label	<amx:panelLabelAndMessage id="panelLabelAndMessage1" label="#{bindings.contactData.hints.label}"> <amx:outputText id="outputText1" value="#{bindings.contactData.inputValue}"/> </amx:panelLabelAndMessage>
Select Boolean Checkbox	<amx:selectBooleanCheckbox id="selectBooleanCheckbox1" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.label}"> </amx:selectBooleanCheckbox>
Select Boolean Switch	<amx:selectBooleanSwitch id="selectBooleanSwitch" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.label}"> </amx:selectBooleanSwitch>
Select One Button	<amx:selectOneButton id="selectOneButton1" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.label}" required="#{bindings.contactData.hints.mandatory}"> <amx:selectItems value="#{bindings.contactData.items}"/> </amx:selectOneButton>
Select One Choice	<amx:selectOneChoice id="selectOneChoice1" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.label}"> <amx:selectItems id="selectItems1" value="#{bindings.contactData.items}"/> </amx:selectOneChoice>
Select Many Checkbox	<amx:selectManyCheckbox id="selectManyCheckbox1" value="#{bindings.AssetView.inputValue}" label="#{bindings.AssetView.label}"> <amx:selectItems id="selectItems1" value="#{bindings.AssetView.items}"/> </amx:selectManyCheckbox>
Select One Radio	<amx:selectOneRadio id="selectOneRadio1" value="#{bindings.contactData.inputValue}" label="#{bindings.contactData.label}" <amx:selectItems id="selectItems1" value="#{bindings.contactData.items}"/> </amx:selectOneRadio>
Select Many Choice	<amx:selectManyChoice id="selectManyChoice1" value="#{bindings.AssetView.inputValue}" label="#{bindings.AssetView.label}"> <amx:selectItems id="selectItems1" value="#{bindings.AssetView.items}"/> </amx:selectManyChoice>

12.3.3.5 What You May Need to Know About Generated Drag and Drop Artifacts

The first drag and drop event generates the following directories and files:

Figure 12-84 shows a sample DataBindings.cpx file generated upon drag and drop.

Figure 12-84 DataBindings.cpx File in Source View

The DataBindings.cpx files define the binding context for the entire MAF AMX application feature and provide the metadata from which the binding objects are created at runtime. A MAF AMX application feature may have more than one DataBindings.cpx file if a component was created outside of the project and then imported. These files map individual MAF AMX pages to page definition files and declare which data controls are being used by the MAF AMX application feature. At runtime, only the data controls listed in the DataBindings.cpx files are available to the current MAF AMX application feature.

JDeveloper automatically creates a DataBindings.cpx file in the default package of the ViewController project when you for the first time use the Data Controls window to add a component to a page or an operation to an activity. Once the DataBindings.cpx file is created, JDeveloper adds an entry for the first page or task flow activity. Each subsequent time you use the Data Controls window, JDeveloper adds an entry to the DataBindings.cpx for that page or activity, if one does not already exist.

Once JDeveloper creates a DataBindings.cpx file, you can open it in the Source view (see Figure 12-84) or the Overview editor.

The Page Mappings (pageMap) section of the file maps each MAF AMX page or task flow activity to its corresponding page definition file using an ID. The Page Definition Usages (pageDefinitionUsages) section maps the page definition ID to the absolute path for page definition file in the MAF AMX application feature. The Data Control Usages (dataControlUsages) section identifies the data controls being used by the binding objects defined in the page definition files. These mappings allow the binding container to be initialized when the page is invoked.

You can use the Overview editor to change the ID name for page definition files or data controls by double-clicking the current ID name and editing inline. Doing so will update all references in the MAF AMX application feature. Note, however, that JDeveloper updates only the ID name and not the file name. Ensure that you do not change a data control name to a reserved word.

You can also click the DataBindings.cpx file's element in the Structure window and then use the Properties window to change property values.

Figure 12-85 shows a sample PageDef file generated upon drag and drop.

Figure 12-85 PageDef File

Page definition files define the binding objects that populate the data in MAF AMX UI components at runtime. For every MAF AMX page that has bindings, there must be a corresponding page definition file that defines the binding objects used by that page. Page definition files provide design-time access to all the bindings. At runtime, the binding objects defined by a page definition file are instantiated in a binding container, which is the runtime instance of the page definition file.

The first time you use the Data Controls window to add a component to a page, JDeveloper automatically creates a page definition file for that page and adds definitions for each binding object referenced by the component. For each subsequent databound component you add to the page, JDeveloper automatically adds the necessary binding object definitions to the page definition file.

By default, the page definition files are located in the mobile.PageDefs package in the Application Sources node of the ViewController project. If the corresponding MAF AMX page is saved to a directory other than the default, or to a subdirectory of the default, then the page definition is also be saved to a package of the same name.

For information on how to open a page definition file, see Accessing the Page Definition File. When you open a page definition file in the Overview editor, you can view and configure bindings, contextual events, and parameters for a MAF AMX page using the following tabs:

Bindings and Executables: this tab shows three different types of objects: bindings, executables, and the associated data controls.

Note:

Data controls do not display unless you select a binding or executable.

By default, the model binding objects are named after the data control object that was used to create them. If a data control object is used more than once on a page, JDeveloper adds a number to the default binding object names to keep them unique.
Contextual Events: you can create contextual events to which artifacts in a MAF AMX application feature can subscribe.
Parameters: parameter binding objects declare the parameters that the page evaluates at the beginning of a request. You can define the value of a parameter in the page definition file using static values or EL expressions that assign a static value.

When you click an item in the Overview editor (or the associated node in the Structure window), you can use the Properties window to view and edit the attribute values for the item, or you can edit the XML source directly by clicking the Source tab.

12.3.3.6 Using the MAF AMX Editor Bindings Tab

JDeveloper's Bindings tab (see Figure 12-86) is available in the MAF AMX Editor. It displays the data bindings defined for a specific MAF AMX page. If you select a binding, its relationship to the underlying Data Control are shown and the link to the PageDef file is provided.

Figure 12-86 Bindings Tab

12.3.3.7 What You May Need to Know About Removal of Unused Bindings

When you delete or cut a MAF AMX component from the Structure window, unused bindings are automatically removed from your page.

Note:

Deleting a component from the Source editor does not trigger the removal of bindings.

Figure 12-87 demonstrates the deletion of a List View component that references bindings. Upon deletion, the related binding entry is automatically removed from the corresponding PageDef.xml file.

Figure 12-87 Deleting Bound Components from Page

Figure 12-88 demonstrates the removal of the List View component by cutting it from the page.

Figure 12-88 Cutting Bound Components from Page

After clicking Cut, you are presented with the Confirm Removal of Bindings dialog that prompts you to choose whether or not to delete the corresponding bindings, as shown in Figure 12-89.

Figure 12-89 Confirm Removal of Bindings Dialog

12.3.4 What You May Need to Know About the Server Communication

The security architecture used by MAF guarantees that the browser hosting a MAF AMX page does not have access to the security information needed to make connections to a secure server to obtain its resources. This has a direct impact on AJAX calls made from MAF AMX pages: these calls are not supported, which poses limitations on the use of JavaScript from within MAF AMX UI components. Communication with the server must occur from the embedded Java code layer.