10 Using Plugins in MAF Applications

This chapter describes how to enable the core plugins that MAF provides for use in MAF applications, how to register additional plugins, how to import a plugin from a FAR, how to package plugins in your MAF application for deployment, and how to use plugins in a team working environment.

This chapter includes the following sections:

10.1 Introduction to Integrating Plugins in MAF Applications

MAF packages a number of Cordova plugins that enable your MAF application to interact with the device on which you deploy the application. We refer to the plugins that MAF provides by default as core plugins. You can view these plugins in the MAF Application Editor as shown in Figure 10-1. Examples include the Email and Contacts plugins that MAF applications use to access email and contact functionality from a device.

MAF includes the following versions of Apache Cordova for MAF applications that use plugins:

  • Apache Cordova 3.6.3 for MAF applications on the Android platform

  • Apache Cordova 3.7.0 for MAF applications on the iOS platform

Select a plugin in the Core Plugins list, as shown in Figure 10-1, to view a description of the individual plugins. By default, a newly-created MAF application enables only one core plugin (Network Information plugin). You enable these core plugins, as described in Section 10.2, "Enabling Core Plugins in Your MAF Application."

Note:

All applications on iOS devices have network access by default. You cannot change this behavior. For applications that you intend to deploy on Android devices, disable the Network Information plugin if you do not want the application to have network access on the Android device.

You can register additional plugins that you or others develop if the core plugins that MAF provides by default do not meet your MAF application's requirements. For more information, see Section 10.3, "Registering Additional Plugins in Your MAF Application."

You can register Cordova plugins from a Cordova registry. For more information, see Section 10.3, "Registering Additional Plugins in Your MAF Application."

You can use Cordova-enabled shared projects to work with plugins in team environments. For more information, see Section 10.5, "Using External Plugins in a Team Environment."

If your MAF application fails to deploy after you register a additional plugins, it may be due to filename conflicts between plugins that your MAF application uses. For more information, see Section 10.7, "Deploying Plugins with Your MAF Application."

If you want to migrate a MAF application created with an earlier release of MAF, you need to register any plugins your application uses in the MAF Application Editor. For more information, refer to "Migrating Plugins from Earlier Releases." section in Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.

The BarcodeDemo sample application, described in Appendix G, "MAF Sample Applications" provides an examples of using plugins, including an external plugin.

Figure 10-1 Plugins in the MAF Application Editor

This image is described in the surrounding text

10.2 Enabling Core Plugins in Your MAF Application

By default, newly-created MAF applications enable only one core plugin (Network Information plugin). Enable or disable additional core plugins so that your MAF application can access the associated device functionality.

Only enabled plugins are deployed, which keeps the size of the deployed application to a minimum.

10.2.1 How to Enable a Core Plugin in Your MAF Application

You enable a core plugin using the MAF Application Editor.

To enable a core plugin in your MAF application:

  1. From the Project Explorer, expand the assembly project folder, then expand MAF and double-click MAF Application Editor.

  2. In the editor under Outline, expand Core plugins and then select Plugin Enablement. The Plug -ins already enabled for the application are listed.

  3. Click This images is described in the surrounding text to open the Mobile Plugin Selection dialog and select the core plugin you want to use. Click OK.

    For example, if you want your MAF application to be able to send an SMS message, select the SMS plugin.

  4. With the core plugin selected in the Plugin Enablement area of the MAF Application Editor, choose whether the plugin is to be available for Android, iOS, or both. Save your changes.

    You can also add notes, for example, if there are plugins which are enabled but which do not have features associated with them.

10.2.2 What Happens When You Enable a Core Plugin in Your MAF Application

Once you enable a core plugin in the MAF Application Editor the plugin is listed in Plugin Enablement in the editor. You can see which features in the application use the selected plugin in the Registered Features Declaring Usage in the Plugin Enablement area.

The plugin is available to use with features and listed in Plugin Usage in the MAF Features Editor.

10.3 Registering Additional Plugins in Your MAF Application

Register additional plugins in your MAF application when you require functionality in your MAF application not provided by the core plugins that MAF delivers. You access the additional plugin from a file location or relative to a workspace, so the external plugin can be an external file, for example a zipped file, or a location relative to the workspace.

When you register additional plugins you are making that plugin available to be used and deployed in your MAF application. It is the first step to using third party plugins in an application.

10.3.1 How to Register an Additional Plugin

You use the MAF Application Editor to register the additional plugin you want your MAF application to use.

You can either use an plugin that is stored in an accessible file location, for example a zip you have downloaded, or you can enter a location which references an external plugin relative to a workspace.

To register an external plugin for your MAF application:

  1. From the Project Explorer, expand the assembly project folder, then expand MAF and double-click MAF Application Editor.

  2. In the editor under Outline, right-click External plugins and choose New > External Cordova Plugin.

  3. Enter the location of the plugin in URI. Click This images is described in the surrounding text to open the Mobile Plugin location dialog. Enter either an Eclipse workspace container, or navigate to an external folder containing the plugin.

  4. To re-inspect the plugin and update the information if the content of the URI has changed, click This images is described in the surrounding text. This gets the information available from the metadata of the current plugin. This can include:

    • Id

    • Name

    • Description

    • Version

    • Platform support. This can be edited so you can override the platform availability if you need to.

    • Notes. You can add information that may be useful to understand the history of this registration in the application, or for any other purpose.

10.3.2 What Happens When You Register an External Plugin for Your MAF Application

Once you enable an external plugin in the MAF Application Editor the plugin is listed in Plugin Enablement in the editor. You can see which features in the application use the selected plugin in the Registered Features Declaring Usage in the Plugin Enablement area.

The plugin is available to use with features and listed in Plugin Usage in the MAF Features Editor.

Figure 10-2 Additional Plugin in the MAF Application Editor

This image is described in the surrounding text

10.4 Using Plugins From a Cordova Registry

You can create an Apache Cordova project which allows you to use Cordova plugins from a Cordova registry.

There are a number of steps:

  1. Create a project that is configured for Apache Cordova in a location that can be shared by a team.

  2. Add plugins from the repository.

  3. Add the shared project to the assembly project of the MAF application.

  4. Add the external plugin in the shared project in the MAF Application Editor.

10.4.1 How to Use Plugins From a Cordova Registry

Before you begin, get either the plugin ID or repository URI for the plugins you want from the registry, which is at http://plugins.cordova.io. For example, for the Cordova Geolocation plugin, the Plug ID is org.apache.cordova.geolocation and the Repository URI is https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git.

Also, in order to configure a project for Apache Cordova you must have Cordova CLI installed and on your path. For more information, refer to http://cordova.apache.org

To set up a shared project for plugins:

  1. Create a new Cordova project for the plugins. Right-click one of the projects in the Project Explorer and choose New > Apache Cordova Project. This creates a empty set of files and folders in the Project Explorer.

  2. In the New Apache Cordova Project dialog, enter a name for the project and give it a suitable location. Click Finish.

  3. In the Project Explorer, right-click the new project and choose Cordova > Add Plugin from Registry.

  4. In the Add Cordova Plugin dialog, shown in Figure 10-3, specify the plugin.

    Figure 10-3 Using Plugins from a Registry

    This image is described in the surrounding text

    You can use either:

    • The Plugin ID of the plugin on the Apache Cordova registry.

    • The repository URI for the plugin.

    The Add Cordova Plugin dialog has a link that will open the registry in an external browser. You can search for plugins, and copy the plugin id or repository URI.

    Click Execute. The results are listed in the dialog. Once it has succeeded, click Close.

  5. To use the plugin in a MAF application, right-click the assembly project in the Project Explorer and choose Properties.

  6. In the Properties dialog, select Mobile Application Framework and choose the Projects tab. Add the Apache Cordova project to the list of projects. Click OK.

    If you registered external plug-ins using the Eclipse Workspace container option, this step is done for you automatically.

  7. In the assembly project of the MAF application, right-click External plugins and choose New >External Cordova Plugin. Navigate to the Apache Cordova project and choose the plugin you want to enable in the MAF application.

10.4.2 What Happens When You Use Plugins From a Cordova Registry

Once you enable a plugin from a registry in the MAF Application Editor the plugin is listed in Plugin Enablement in the editor. You can see which features in the application use the selected plugin in the Registered Features Declaring Usage in the Plugin Enablement area.

The plugin is available to use with features and listed in Plugin Usage in the MAF Features Editor.

10.5 Using External Plugins in a Team Environment

If you are working in a team environment and want to access external plugins from the Apache Cordova registry from a shared location, depending on how your workstations are configured you do this from an Apache Cordova project that is available to all users.

This allows for the separation of roles in a team environment, where one developer may work on specifying the plugins enabled in the application using a shared folder, and other developers work on feature development described in Section 10.6, "Using Plugins in your MAF Application."

10.5.1 How to Use External Plugins in a Team Environment

Follow the instructions in Section 10.4.1, "How to Use Plugins From a Cordova Registry.". You can create the project in a shared location under source control so that it is available to all users.

10.6 Using Plugins in your MAF Application

You use plugins in your MAF application by associating them with application features using the MAF Feature Editor, as shown in Figure 10-4. After that, you ensure that the plugins are enabled for the application in the MAF Application Editor.

Figure 10-4 Using Plugins with Features

This images is described in the surrounding text

10.6.1 How to Specify plugins for Registered Features

You associate plugins with features using the MAF Feature Editor.

Plugin usage in the MAF Features Editor is useful in a team environment where different people work on specifying the plugins enabled in the application, and using plugins in features.

To specify the plugins a features uses:

  1. From the Project Explorer, expand the view project folder, then expand MAF and double-click MAF Feature Editor.

  2. In the editor under Outline, select the feature you want to use a plugin and choose plugin Usage.

  3. In the Plugin Usage area of the page, click This images is described in the surrounding text to open the Mobile Plugin Selection dialog.

  4. From the list of plugins registered for the application, choose the ones you want and click OK.

  5. Select whether Android or iOS or both are available as platforms for the plugin. If the registered plugin disallows a particular platform, then you will not be able to select it. Save your changes.

  6. Return to the MAF Application Editor. In the Project Explorer, expand the assembly project folder, then expand MAF and double-click MAF Application Editor.

  7. In the editor under Outline, select Plugin Enablement and click This images is described in the surrounding text. This ensures that all plugins that are declared to be used by registered features are enabled by the application.

10.7 Deploying Plugins with Your MAF Application

The deployment of a plugin with your MAF application depends on the deployment method you choose.

Deployment to a FAR

A deployment to a FAR includes a copy of the application's plugins information named jar-maf-plugins.xml. This allows for portability between OEPE and JDeveloper.

Deployment to a Mobile Application Archive File

A deployment to a Mobile Application Archive File includes a copy of the application's maf-plugins.xml file generated from the oepe-maf-plugins.xml file with all path attributes set to an empty string.

Deployment Using an Android or iOS Deployment Profile

When deploying using an Android or iOS deployment profile, OEPE invokes the maf-helper command-line tool to deploy the configured plugins. The maf-helper command-line tool deploys the plugin artifacts from their source location to the Android or iOS deployment folder. Once the command-line tool deploys the plugins, deployment incorporates the plugin(s) into the platform-specific application.

10.8 Importing Plugins from a FAR

When you import a FAR you can choose which plugins should be imported and whether any plugins should be ignored. In this way you can merge the imported plugins with the consuming application's list of plugins. For more information, see Section 9.1, "Working with Feature Archive Files."

10.8.1 How to Import Plugins from a FAR

You do this in the MAF Features Editor.

To import plugins from a FAR:

  1. In the MAF Features Editor, import the FAR as described in Section 9.1.1, "Importing a FAR as an Application Library."

  2. When you expand the node for the imported FAR and select Plugins, the plugins that the archive declares are listed, as shown in Figure 10-5.

    Figure 10-5 Plugins in Imported FAR

    This image is described in the surrounding text

    External plug-ins are listed under three nodes:

    • New These are plugins that are defined by the FAR but have no equivalency in the consuming application.

    • Equivalent An equivalent plug-in is one where the plugin id matches one that is registered in the application already. Core plug-ins for a particular runtime will always have equivalents.

    • Ignored These are plugins that you have chosen to ignore.

    Validation errors will appear on FAR plugins if both these conditions are met:

    • There is at least one FAR feature being used by the application.

    • All plugins are not either equivalent or ignored.

  3. To ignore a plugin, select it and click This image is described in the surrounding text. The plugin will no longer be available to use in the application.

    If a FAR feature in use relies on the ignored plug-in, then the application will probably fail at runtime.

  4. To import a new plugin, click This image is described in the surrounding text. This opens the Select Cordova Plugin dialog where you can browse to the source URI for the plugin. OEPE will warn you if you choose a plugin that is potentially not valid so that you can decide whether to proceed, for example, when the Cordova version is earlier than the expected version.

    The plugin is now available for you to use in your application, as described in Section 10.3, "Registering Additional Plugins in Your MAF Application."