9 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, and how to package plugins in your MAF application for deployment.

This chapter includes the following sections:

Section 9.1, "Introduction to Using Plugins in MAF Applications"
Section 9.2, "Enabling a Core Plugin in Your MAF Application"
Section 9.3, "Registering Additional Plugins in Your MAF Application"
Section 9.4, "Deploying Plugins with Your MAF Application"
Section 9.5, "Importing Plugins from a Feature Archive File"

9.1 Introduction to Using 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.xml file's overview editor. 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 9-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 or disable these core plugins, as described in Section 9.2, "Enabling a Core Plugin 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 plugin 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 9.3, "Registering Additional Plugins in Your MAF Application."

If your MAF application fails to deploy after you register additional plugins, it may be due to filename conflicts between plugins that your MAF application uses. Alternatively, it may be due to the absence of dependent plugin that additional plugins you registered require in order to function correctly. For more information, see Section 9.4, "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-plugins.xml file. For more information, see the "Migrating Cordova Plugins from Earlier Releases to MAF" section in Oracle Mobile Application Framework Installing Oracle Mobile Application Framework.

Note:

Although you edit the maf-application.xml file to manage plugins in your application, any changes you make result in revisions to the maf-plugins.xml file. You access both files from the ADF-META-INF node of the Application Resources pane, as shown in Figure 9-1.

Figure 9-1 Plugins in maf-application.xml File's Overview Editor

This image is described in the surrounding text

9.2 Enabling a Core Plugin in Your MAF Application

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

9.2.1 How to Enable a Core Plugin in Your MAF Application

You enable a core plugin using the overview editor for your MAF application's maf-application.xml file.

To enable a core plugin in your MAF application:

In the Applications window, expand the Application Resources panel.
In the Application Resources panel, expand Descriptors and then ADF META-INF.
Double-click the maf-application.xml file and in the overview editor that appears, click the Plugins navigation tab
Expand the Core Plugins section and select the plugin that allows your application access features.

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

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

Once you enable a plugin in the overview editor, JDeveloper edits the application's maf-plugins.xml file with entries that identify the enabled plugins in your MAF application. Example 9-1 shows the entries for a MAF application where the Email, PushPlugin, and Network Information plugins have been enabled. Enabling these plugins is a prerequisite to your MAF application using the device's email client, accessing the internet and receiving push notifications from the device.

Example 9-1 Enabled Core Plugins in maf-plugins.xml File

<?xml version="1.0" encoding="UTF-8" ?>
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/adf/mf">
  <cordova-plugins>
    <core-cordova-plugin id="c1" pluginId="org.apache.cordova.network-information"/>
    <core-cordova-plugin id="c2" pluginId="com.oracle.maf.email"/>
    <core-cordova-plugin id="c3" pluginId="com.phonegap.plugins.PushPlugin"/>
  </cordova-plugins>
</maf-plugins>

9.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.

9.3.1 How to Register an Additional Plugin

You use the overview editor for your MAF application's maf-application.xml file to register the additional plugin you want your MAF application to use.

Before you begin, make sure to store the plugin that you want to register with your application on the same drive as the application with which you want to register it. If, for example, you store your application in the C: drive on a Windows environment, you must also store the plugin that you want to register with the application on the C: drive. This makes sure that JDeveloper successfully registers the plugin with your application using a relative path.

To register an additional plugin for your MAF application:

In the Applications window, expand the Application Resources panel.
In the Application Resources panel, expand Descriptors and then ADF META-INF.
Double-click the maf-application.xml file and in the overview editor that appears, click the Plugins navigation tab.
Expand the Additional Plugins section and click the Add icon to display a dialog where you browse to and select the directory that stores the plugin that you want to register with your application.

9.3.2 What Happens When You Register an Additional Plugin for Your MAF Application

Once you select the source files for the plugin you want your MAF application to use, JDeveloper edits the application's maf-plugins.xml file with entries that identify the enabled plugins in your MAF application. Example 9-2 shows the entries in a maf-plugins.xml file where the Calendar plugin shown in Figure 9-2 has been registered with the MAF application.

Figure 9-2 Additional Plugin in maf-application.xml File's Overview Editor

Example 9-2 Additional Plugin in maf-plugins.xml File

<?xml version="1.0" encoding="UTF-8" ?>
<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://xmlns.oracle.com/adf/mf">
   <cordova-plugins>
     <core-cordova-plugin id="c1" pluginId="org.apache.cordova.network-information"/>
    <cordova-plugin id="c2" pluginId="nl.x-services.plugins.calendar"
                    path="../../../../../z_plugins/Calendar-PhoneGap-Plugin-master/">
      <platform id="p1" name="android" enabled="true"/>
      <platform id="p2" name="ios" enabled="true"/>
    </cordova-plugin>
   </cordova-plugins>
</maf-plugins>

9.4 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 maf-plugins.xml file named jar-maf-plugins.xml. It is identical to the application's maf-plugins.xml file with the exception that the path attribute value of each plugin is an empty string. A FAR deployment does not include the source files for the plugin.

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 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, JDeveloper 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.

Resolving Naming Conflicts Between Plugins

Deployment can fail due to naming conflicts if more than one plugin used by your MAF application contains resource files with the same name. For example, deployment fails if a MAF application uses two plugins that both have a resource file name arrays.xml.

To resolve these naming conflicts, rename the resource file name in one plugin that conflicts with the resource file name in the second plugin. Update the reference to the resource file in the first plugin's plugin.xml file. In our example, this requires you to rename the first plugin's array.xml resource file name to pluginone_arrays.xml and edit the plugin's plugin.xml file as follows:

<source-file src="src/android/LibraryProject/res/values/pluginone_arrays.xml"
                                                         target-dir="res/values"/>

Adding Missing Dependent Plugins

Deployment can fail if an additional plugin that your MAF application uses does not locate plugins that it requires (dependent plugins). This scenario can arise if you work behind a firewall because, at deployment time, JDeveloper invokes Apache Cordova's tools to manage plugins dependencies. These latter tools may fail to download dependent plugins if their proxy settings are not configured to allow the download of dependent plugins. To workaround this scenario, download the missing dependent plugin and add it to your MAF application. You add the missing dependent plugin the same way as other plugins that you want to add to your MAF application. For more information, see Section 9.3, "Registering Additional Plugins in Your MAF Application." After you add the dependent plugin, make sure that it appears before the plugin that requires it in the maf-plugins.xml file, as demonstrated in Example 9-3.

Example 9-3 Adding Dependent Plugins to the MAF Application

<maf-plugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://xmlns.oracle.com/adf/mf">
   <cordova-plugins>
     ....
    <cordova-plugin id="c2" pluginId="com.example.dependent.dependentPlugin"
                    path="../../../../../plugins/Dependent-Plugin-Required-By-PluginWithID_c3/">
      ...
    <cordova-plugin id="c3" pluginId="com.example.plugin"
                    path="../../../../../plugins/AdditionalPlugin/">
      ...
   </cordova-plugins>
</maf-plugins>

9.5 Importing Plugins from a Feature Archive File

When you import a FAR that contains a jar-maf-plugins.xml file to your application, the content in the jar-maf-plugins.xml file merges with the consuming application's maf-plugins.xml file. JDeveloper logs information about the merge to its Messages window. If the plugin to import from the FAR exists already in the consumer application's maf-plugins.xml file, JDeveloper logs a message that the plugin exists in the application and will not be merged. If the plugin to import from the FAR does not exist in the consumer application's maf-plugins.xml file, JDeveloper adds the plugin to the application's maf-plugins.xml file. In this scenario, you need to set the path to the newly-imported plugin, as described Section 9.3, "Registering Additional Plugins in Your MAF Application."