2 Getting Started with MAF Application Development

This chapter describes how to create a MAF application in OEPE and introduces the files and other artifacts that OEPE generates when you create the application.

This chapter includes the following sections:

2.1 Introduction to Declarative Development for MAF Applications

The Oracle Mobile Application Framework (MAF) extension in OEPE provides a number of editors and wizards to facilitate the development, testing, and deployment of MAF applications. Figure 2-1 shows the WorkBetter sample application in OEPE's MAF Application Editor where a number of the items that you use to develop MAF applications are identified:

  1. The MAF Application Editor (invoked from the assembly project), used to specify the MAF application's name, the default navigation menus (navigation bar or springboard) that the application renders, security, and device access options for the application.

  2. The MAF Features Editor (invoked from the view project), where you define the application features that your MAF application contains.

The WorkBetter sample application is one of a number of sample applications that MAF provides to demonstrate how to create mobile applications using MAF. For more information, see Appendix G, "MAF Sample Applications."

Figure 2-1 MAF Application Open in OEPE

This image is described in the surrounding text

2.2 Creating a MAF Application

You create a MAF application using the creation wizards in OEPE.

2.2.1 How to Create a Workspace for a Mobile Application

You create an application using the application creation wizard.

To create a mobile application:

  1. Choose File > New, and then select MAF Application. This opens the MAF Application wizard (see Figure 2-2).

    Figure 2-2 Creating a MAF Application

    This image is described in the surrounding text

  2. In the Application Display Name field, enter a name for the application, such as MobileApplication. This is the top-level structure of the MAF application. It is also sometimes called the assembly project, and holds all of the artifacts required for packaging and deployment of the application. Click Next.

    Figure 2-3 Specifying Application and Project Names

    This image is described in the surrounding text

  3. The next page of the wizard, shown in Figure 2-3, displays the Application Project Name and the View Project Name for the MAF application you are creating. By default, OEPE uses the name you entered on the first page, but adds Application and View, respectively, to the projects.

    For example, if you had created a MAF application called Employee, the wizard creates the names EmployeeApplication and EmployeeView. You can change the names if desired. To accept the default names of the projects, click Next.

    Figure 2-4 Choosing the Deployment Targets

    This image is described in the surrounding text

  4. The Configure Deployment Targets page of the MAF Application wizard, shown in Figure 2-4, lets you select the deployment targets you wish to use for the MAF application you are developing. The targets displayed on this page are those you specified when setting up your environment. For more information, see "Configuring Mobile Application Framework" in Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.

    By default, the wizard creates one deployment target for each SDK you have defined. Select those you want to use.

  5. Click Finish to complete the creation of the MAF application and its projects.

    A dialog is displayed asking you whether to change to the MAF perspective, as shown in Figure 2-5. Click Yes.

    Figure 2-5 Changing to MAF Perspective

    This image is described in the surrounding text

Tip:

In addition to creating an MAF application following the above-mentioned steps, you can open the HelloWorld sample application (located by selecting File > New > MAF Examples, and then selecting HelloWorld) and view the artifacts that OEPE generates after you complete the application creation wizard.

2.2.2 What Happens When You Create an MAF Application

When you create an MAF application, OEPE creates the following artifacts, which you access from the Project Explorer, as shown in Figure 2-1:

  • The top-level or assembly project. This holds all of the artifacts required for packaging and deployment of the application. In addition, the assembly project tracks the version of the MAF run time that the project uses, if you are migrating an application from an earlier version of MAF.

  • The application project. This contains a Data Control Manager which abstracts the device features and the application features.

  • The view controller-type project. This contains the source folder (src) and the ViewContent folder.

OEPE adds application-level and project-level artifacts, which you access from the Project Explorer shown in Figure 2-6. These artifacts include two MAF editors:

  • MAF Application Editor which edits maf-application.xml. It is used for configuring the MAF application itself, such as its name, the application lifecycle listener (LifeCycleListenerImpl.java), the login server connections for the embedded application features. For more information, see described in Section 2.2.2.1, "About the Assembly-Level Resources."

  • MAF Features Editor which edits maf-feature.xml. It describes which application features comprise the MAF application. For more information, see Section 2.2.2.2, "About the View Project Resources."

OEPE creates:

  • The DeviceFeatures data control. The Apache Cordova Java API is abstracted through this data control, thus enabling the application features implemented as MAF AMX to access various services embedded on the device.

  • The ApplicationFeatures data control, which enables you to build a springboard page.

By dragging and dropping the operations provided by the DeviceFeatures data control into a MAF AMX page (which is described in Section 14.10, "Using the DeviceFeatures Data Control," you add functions to manage the user contacts stored on the device, create and send both e-mail and SMS text messages, ascertain the location of the device, use the device's camera, and retrieve images stored in the device's file system.

Figure 2-6 Generated MAF Application Artifacts

This image is described in the surrounding text

By default, some files are filtered from view in the Project Explorer. In order to see the generated artifacts required for packaging and deployment of the application, click the down arrow in the explorer toolbar and choose Customize View.

In the Available Customizations dialog, shown in Figure 2-7, deselect .* resources and click OK.

Figure 2-7 Filtering Project Explorer Files

This image is described in the surrounding text

Now expand the assembly project node and .main.android or .main.ios node to view the package and deploy artifacts, as shown in Figure 2-8.

Figure 2-8 Viewing Packaging and Deployment Artifacts

This image is described in the surrounding text

To filter these files from the view in the Project Explorer, reopen the customization dialog and select .* resources and click OK.

2.2.2.1 About the Assembly-Level Resources

OEPE generates the files for the MAF application in the assembly project. These files contain configuration files for describing the metadata of the MAF application. You access these files from the res node under the assembly project in the Project Explorer, shown in Figure 2-9.

Figure 2-9 Mobile Application Artifacts

This image is described in the surrounding text

The assembly project (which is generated with the default name, application), which contains the application-wide resources, provides the presentation layer of the MAF application in that it includes metadata files for configuring how the application will display on a mobile device. This project dictates the security for the MAF application and can include the application's login page, an application-wide resource. The application controller project is essentially a consumer of the view controller project, which defines the application features and their content. For more information, see Section 2.2.2.2, "About the View Project Resources."

Tip:

Place code that supports application-wide functionality, such as an application-level lifecycle listener, in the application controller project.

Within the application project itself (which is generated with the default name, applicationApplication), shown in Figure 2-10, OEPE creates the following artifacts, listed in Table 2-0.

Figure 2-10 Application Project

This image is described in the surrounding text

2.2.2.2 About the View Project Resources

The view project (which is generated with the default name, applicationView), as illustrated in Figure 2-11) houses the resources for the application features. Unlike the application project described in Section 2.2.2.1, "About the Assembly-Level Resources," the view project's metadata files describe the resources at the application feature-level, in particular the various application features that can be aggregated into a MAF application so that they can display on a mobile device within the springboard of the MAF application itself or its navigation bar at runtime. Further, the application feature metadata files describe whether the application feature is comprised of HTML or MAF AMX pages. In addition, the view controller project can include these application pages as well as application feature-level resources, such as icon images to represent the application feature on the springboard and navigation bar defined for the MAF application.

Tip:

Store code specific to an application feature within the view controller project. Use the application controller project as the location for code shared across application features, particularly those defined in separate view controller projects.

The view controller project can be decoupled from the application controller project and deployed as an archive file for reuse in other mobile applications as described in Section 9.1, "Working with Feature Archive Files." In rare cases, an application controller project can consume more than one view controller project.

Note:

Adding a MAF view controller project as a dependency of another MAF view controller project, or as a dependency of a MAF application controller project, prevents the deployment of a MAF application.

Figure 2-11 View Project

This image is described in the surrounding text

These resources include the configuration file for application features called maf-feature.xml, which you edit using the MAF Feature Editor.

2.2.2.2.1 How to Create Multiple View Projects

Each OEPE assembly project can have more than one view project, in addition to the view project included when you first create your assembly project. The features included in this view project will be available from the application created when you build and deploy the assembly project.

To create a new view project in an existing assembly project:

  1. Click File > New > MAF View Project. This opens the MAF View Project Wizard.

  2. From the wizard, click Browse to select the assembly project to which you wish to add a new view project.

  3. OEPE automatically gives the new view project a unique name that matches the assembly project. For example, if you are creating a new view project within the CompGallery sample application, the wizard names the view project CompGalleryView1 (to distinguish it from the default CompGalleryView project initially created.

    If desired, you can edit the name of the new view project at this time.

  4. Click Finish to create the new view project.

The wizard adds view project files to the assembly project you selected in step 2.

2.2.2.3 About Deployment Configurations

OEPE uses deployment configurations to determine how applications are run or debugged. The configuration defines the way the packages into the archive that will be deployed to the target environment (such as a mobile device, an emulator, or an application marketplace, such as the iOs App Store). The deployment configuration:

  • Specifies the format and contents of the archive file that will be created

  • Lists the source files, deployment descriptors, and other auxiliary files that will be packaged

  • Describes the type and name of the archive file to be created

  • Highlights dependency information, platform-specific instructions, and other information

When you create an application, OEPE creates deployment configurations that are seeded with default settings and image files. By default, one deployment target is created for each SDK you have. Provided that you have configured the environment correctly, you can use these configurations to test an MAF application immediately after creating it by choosing Run and then Debug Configurations, as shown in Figure 2-12.

Note:

During development, use Debug Configuration. For production deployment, use the Run Configuration.

Choosing Debug Configurations rather than Run Configurations allows OEPE to use, if necessary, debug settings such as the default debug keystore.

Figure 2-12 Creating Deployment Configurations

This image is described in the surrounding text

In the Create Configuration dialog, shown in Figure 2-13, create a new configuration by clicking This image is described in the surrounding text.

Figure 2-13 Creating a New Configuration

This image is described in the surrounding text

Using the Configurations page, shown in Figure 2-14, you then select the appropriate deployment target.

Figure 2-14 Selecting a Deployment Target

This image is described in the surrounding text

Note:

iOS and Android application deployments to simulators and devices have distinct environment set up and configuration requirements. For more information, refer to the "Before You Begin" sections throughout Section 27.2.5, "Deploying an Android Application," and Section 27.2.7, "Deploying an iOS Application."

You can create a MAF Application configuration for each supported platform and device or emulator.

You can edit these configurations by selecting the configuration from the list under MAF Applications. For information on the values configured for MAF application configurations, see Section 27.2.4, "How to Create an Android Deployment Configuration" and Section 27.2.6, "How to Create an iOS Deployment Configuration."

In addition to the platform-specific deployment configurations, MAF also creates a deployment configuration that enables you to package the MAF application as a Mobile Application Archive (.maa) file. Using this file, you can create a new MAF application using a pre-existing application that has been packaged as an .maa file. For more information, see Section 27.4, "Creating a Mobile Application Archive File" and Section 27.5, "Creating Unsigned Deployment Packages."

2.2.3 What You May Need to Know About Editing MAF Applications and Application Features

Creating an application results in the generation of the maf-application.xml file, which enables you to configure the mobile application and also the maf-feature.xml file, which you use to add, remove, or edit the application features embedded within the mobile application. OEPE provides you with the MAF Application Editor for maf-application.xml and with the Mobile Features Editor for maf-feature.xml. These let you declaratively change these files. Figure 2-15 shows an example of the MAF Application Editor open in OEPE.

Figure 2-15 MAF Application Editor

This image is described in the surrounding text

As shown in Figure 2-15, the MAF Application Editor is located in the Project Explorer under the application and MAF node. The maf-application.xml file is located under the application, adf, and META-INF nodes. You open this editor by double-clicking MAF Application Editor.

As illustrated in Figure 2-16, the MAF Feature Editor is located in Explorer under the view project and MAF node. The maf-feature.xml file is located under the view project, src, and META-INF nodes. You open this editor by double-clicking MAF Feature Editor, or by double-clicking maf-feature.xml. You use this file to compose the content for the MAF application.

Figure 2-16 MAF Features Editor

This image is described in the surrounding text

Like the MAF Application Editor for editing the maf-application.xml file, OEPE presents the MAF components used for building the elements of the maf-features.xml configuration file in the MAF Feature Editor.

2.2.4 About the MAF Application Editor and MAF Feature Editor

OEPE's MAF Feature Editor and MAF Application Editor are the primary tools you use to interact with a MAF application while you are creating it. These two editors interact with each other, and with the files that comprise the application you are developing, in a way that can affect your choices while editing.

When you use the MAF Application Editor to make changes to maf-application.xml, OEPE opens not only that file, but other files related to that application. These might include any registered feature files (edited with MAF Feature Editor) and plugins. To view some of these files in the MAF Application Editor, expand the Outline and select Registered Features. In addition, files in the Features folder (if any) may also be affected. Figure 2-17 shows the MAF Application Editor open to the Registered Feature listing, which the tooltip shows is connected to the file maf-feature.xml.

Figure 2-17 maf-application.xml Showing a Related Feature File

This image is described in the surrounding text

If you double-click on maf-feature.xml in the Registered Features pane of the MAF Application Editor, OEPE opens the file in the MAF Feature Editor, as expected. The interaction between these two files (and others as applicable) while you are editing, however, deserves attention.

When you go to the MAF Application Editor and save your application file, OEPE checks to determine whether the related feature file has been changed externally in the file system. If it has, OEPE displays a confirmation dialog informing you that the related file has been changed relative to the contents of the editor. You have the chance at this point to choose one of the following options:

  • Reload the editor. This copies the changes from your file system into the MAF Application Editor, overwriting any changes you may have made to the file.

  • Not reload the editor. This saves the maf-feature.xml file and overwrites the contents of your file system.

OEPE performs a similar check if you select File > Save All. In addition, the File > Close All function checks to see whether you have files open in the MAF Application Editor and MAF Feature Editor, and checks for conflicts in those open files before closing. This helps prevent data loss.

2.2.5 Creating a MAF AMX Page

As described in Chapter 12, "Creating MAF AMX Pages," the MAF AMX components enable you to build pages that run identically to those authored in a platform-specific language. MAF AMX pages enable you to declaratively create the user interface using a rich set of components. Figure 2-18 illustrates the declarative development of an MAF AMX page, which involves selecting options in the Palette and adding them to the MAF AMX page.

Figure 2-18 Creating an MAF AMX Page

The surrounding text describes this image.

These pages may be created by the application assembler, who creates the MAF application and embeds application features within it, or they can be constructed by another developer and then incorporated into the MAF application either as an application feature or as a resource to an MAF application.

The project in which you create the MAF AMX page determines if the page is used to deliver the user interface content for a single application feature, or be used as a resource to the entire MAF application. For example, a page created within the application controller project, as shown in Figure 2-22, would be used as an application-wide resource.

Tip:

To make pages easier to maintain, you can break it down in to reusable segments known as page fragments. An MAF AMX page may be comprised one or more page fragments.

MAF enables you to arrange MAF AMX view pages and other activities into an appropriate sequence through the MAF task flow. As described in Chapter 12, "Creating Task Flows," an MAF task flow is visual representation of the flow of the application. It can be comprised of MAF AMX-authored user interface pages (illustrated by such view activities, such as the WorkBetter sample application's default List page and the Detail page in Figure 2-19) and nonvisual activities that can call methods on managed beans. The non-visual elements of a task flow can be used to evaluate an EL expression or call another task flow. As illustrated by Figure 2-19, MAF enables you to declaratively create the task flow by dragging task flow components onto a diagrammer. MAF provides two types of task flows: a bounded task flow, which has a single point of entry, such as the List page in the WorkBetter sample application, and an unbounded task flow, which may have multiple points of entry into the application flow. The WorkBetter sample application sample application is This sample application is available from File > New > MAF Examples.

Figure 2-19 MAF Task Flow

The surrounding text describes this image.

MAF provides a number of dialogs and wizards to add MAF pages, reusable portions of MAF AMX pages called MAF page fragments, and application features. Figure 2-20 shows the menu options available from the File menu.

Figure 2-20 Options for Creating Resources for Application Features

This image is described in the surrounding text

Additional options are available from File > New > Other (see Figure 2-20). In the New dialog, expand Oracle then expand Mobile Application Framework

Figure 2-21 Wizards for Creating Resources for Application Features

This image is described in the surrounding text

2.2.5.1 How to Create an MAF AMX Page

You can use the MAF Page dialog to create AMX pages used for the user interface for an application feature, or as an application-level resource (such as a login page) that can be shared by the application features that comprise the MAF application. For more information on application feature content, see Section 6.2, "How to Define the Application Feature Content as Remote URL or Local HTML."

To create an MAF AMX page as Content for an Application Feature:

  1. Choose File > New and then MAF Page.

  2. Complete the New MAF Page dialog, shown in Figure 2-22, by choosing the parent folder, for example ViewContent and entering a name in the File Name field.

    Figure 2-22 Creating an MAF AMX Page in an Application Controller Project

    This image is described in the surrounding text

  3. Select (or deselect) the Page Facets that are used to create a primary and secondary header and footer. Click OK.

    For more information, see Section 13.2.2, "How to Use a Panel Page Component."

  4. Click Finish. For more information using the AMX components, see Section 12.3.1.2, "Creating MAF AMX Pages." See also Section 6.2, "How to Define the Application Feature Content as Remote URL or Local HTML."

To create an MAF AMX page as a Resource to an MAF application:

  1. Choose File > New and then MAF Page.

  2. Complete the Create MAF AMX Page dialog, shown in Figure 2-22, by entering a name in the File Name field. In the Directory field, enter the file location, which must be within the public_html folder of the application controller project. Click OK.

  3. Build the MAF AMX page. For more information, see Section 12.3.1.2, "Creating MAF AMX Pages."

2.2.5.2 How to Create MAF Task Flows

You can deliver the content for an application feature as an MAF task flow.

To create an MAF Task Flow as content for an application feature:

  1. Choose File > New > Other.

  2. In the New dialog, expand Oracle then expand Mobile Application Framework. Select MAF Task Flow and click Next.

  3. Complete the New MAF Task Flow dialog, shown in Figure 2-23, by entering a name in File Name. Click OK.

    Figure 2-23 Creating an MAF Task Flow in a View Controller Project

    This image is described in the surrounding text

  4. Click Finish to build the task flow. See also Section 12.2, "Creating Task Flows."

2.2.5.3 What Happens When You Create MAF AMX Pages and Task Flows

OEPE places the MAF AMX pages and task flows in the ViewContent node of the view project, as shown by employeeList.amx and emp-task-flow-definition.xml in Figure 2-24. These artifacts are referenced in the maf-feature.xml file.

The task flows are also listed under the view project MAF node.

Other resources, such as customized application splash screen (or launch) images and navigation bar images, are also housed in the Web Content node.

To manage the unbound task flows, OEPE generates the adfc-mobile-config.xml file. Using this file, you can declaratively create or update a task flow by adding the various task flow components, such as a view (a user interface page), the control rules that define the transitions between various activities, and the managed beans to manage the rendering logic of the task flow.

Figure 2-24 MAF AMX Pages and Task Flows within the View Project

This image is described in the surrounding text

OEPE places the MAF AMX page and task flow as application resources to the mobile application in the Web Content node of the application controller project. As illustrated in Figure 2-24, the file for the MAF AMX page is called application_resource.amx and the task flow file is called ApplicationController-task-flow.xml (the default name).