This chapter includes the following sections:
MAF packages a number of Cordova plugins. A MAF application uses these plugins to interact with the device on which it is deployed.
Core plugins are the plugins that MAF provides by default. View these plugins in the overview editor of
maf-application.xml. Examples include the Email and Contacts plugins that MAF applications use to access email and contact functionality from a device.
View the Cordova versions used by the Android, iOS, and Windows platforms in the overview editor of the
Select a plugin in the Core Plugins list, as shown in Figure 10-1 to view a description of the plugin. By default, a newly-created MAF application enables only one core plugin, the Network Information plugin. Enable or disable these core plugins, as described in Enabling a Core Plugin in Your MAF Application.
All applications on iOS devices have network access by default. You cannot change this behavior. If an application that is deployed to an Android device does not require network access, disable the Network Information plugin. The Network Information plugin must be enabled to facilitate remote debugging of an application running on an Android emulator or device.
You can register additional plugins if the core plugins that MAF provides by default do not meet the requirements of your MAF application. See Introduction to custom Cordova plugin development at http://blogs.oracle.com/mobile/entry/introduction_to_custom_cordova_plugin and Registering Additional Plugins in Your MAF Application. Once you have either enabled the core plugin or registered any additional plugins for your MAF application, you create content in an application feature that accesses the functionality of the plugin. See Using a Plugin in a 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 to function correctly. For more information, see Deploying Plugins with Your MAF Application. MAF applications may fail to deploy to the iOS platform if you do not provide usage descriptions when your MAF application uses plugins that access private data (contacts, photos, and so on) on the iOS device. For more information about these usage descriptions, see Providing Usage Descriptions for Plugins that Access Device Capabilities on iOS.
To migrate a MAF application created with an earlier release of MAF, see Migrating Cordova Plugins from Earlier Releases to MAF 2.3.0 in Installing Oracle Mobile Application Framework.
maf-application.xml file to manage plugins in an application results in revisions to the
maf-plugins.xml file. The ADF-META-INF node of the Application Resources pane from which both files are accessed, is shown in Figure 10-1.
Figure 10-1 Plugins in the Overview Editor of maf-application.xml
A new application enables only the core Network Information plugin. Additional plugins must be registered before they can be used.
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.
Use the procedure to enable a core plugin using the overview editor of the
mafapplication.xml file in a MAF application.
You enable a core plugin using the overview editor of the
maf-application.xml file of the MAF application.
To enable a core plugin in your MAF application:
For example, if you want your MAF application to be able to send an SMS message, select the checkbox for the SMS plugin.
JDeveloper edits the
maf-plugins.xml file of the application with entries that identify the enabled plugins in the 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 10-1 shows the entries for a MAF application where the Email and Network Information plugins have been enabled. Enabling these plugins is a prerequisite to your MAF application using the device's email client and accessing the internet.
Example 10-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="cordova-plugin-network-information"/> <core-cordova-plugin id="c2" pluginId="com.oracle.maf.email"/> </cordova-plugins> </maf-plugins>
You can use additional plugins in a MAF application after registering the plugins.
Register additional plugins in your MAF application when you require functionality in your MAF application not provided by the core plugins that MAF delivers.
Use the procedure to register plugins using the overview editor of the
maf-application.xml file of a MAF application. Registration is necessary if you want to use additional plugins.
To register an additional plugin for a MAF application, use the overview editor of the
maf-application.xml file of the application .
Before you begin, ensure that the application, and the plugin to be registered with the application, are stored on the same drive. If, for example, you store your application on the
C: drive in a Windows environment, you must also store the plugin that you want to register with the application on the
C: drive. This ensures that JDeveloper, using a relative path, successfully registers the plugin with your application.
To register an additional plugin for a MAF application:
When an additional plugin is registered, JDeveloper edits the
maf-plugins.xml file of the application with entries that identify the enabled plugin in the 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 10-2 shows the entries in a
maf-plugins.xml file where the Globalization plugin shown in Figure 10-2 has been registered with the MAF application.
Figure 10-2 Additional Plugins in the Overview Editor of maf-application.xml
Example 10-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="cordova-plugin-network-information"/> <cordova-plugin id="c2" pluginId="cordova-plugin-globalization" path="../../../../CordovaPlugins/cordova-plugin-globalization/"> <platform id="p1" name="android" enabled="true"/> <platform id="p2" name="ios" enabled="true"/> <platform id="p3" name="windows" enabled="true"/> </cordova-plugin> </cordova-plugins> </maf-plugins>
A plugin may be deployed to a FAR, or a Mobile Application Archive file. A plugin may be deployed using an Android, iOS, or Windows deployment profile.
The deployment of a plugin with your MAF application depends on the chosen method of deployment.
Deployment to a FAR
A deployment to a FAR includes a copy of the
maf-plugins.xml file of the application named
jar-maf-plugins.xml. It is identical to the
maf-plugins.xml file of the application 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
maf-plugins.xml file of the application with all
path attributes set to an empty string.
Deployment Using an Android, iOS, or Windows Deployment Profile
During deployments using an Android, iOS or Windows deployment profile, JDeveloper invokes tools that build and deploy the application. These tools, in turn, invoke the Cordova plugman tool to install the configured plugins from their source location to the deployment folder.
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
To resolve these naming conflicts, rename the resource file in the plugin that conflicts with the resource file name in the other plugin. Update the reference to the resource file in the
plugin.xml file of the first plugin. In our example, this requires you to rename the
array.xml resource file name of the first plugin to
pluginone_arrays.xml and edit the
plugin.xml file of the plugin as follows:
<source-file src="src/android/LibraryProject/res/values/pluginone_arrays.xml" target-dir="res/values"/>
Usage Descriptions for MAF Applications Deployed to iOS
Deployment to the iOS platform fails if you enable a plugin that requires your MAF application to access device features (contacts and photos, for example). Provide a usage description as described in Providing Usage Descriptions for Plugins that Access Device Capabilities on iOS.
Adding Missing Dependent Plugins
Deployment can fail if an additional plugin that your MAF application uses does not locate the plugins that it requires (dependent plugins). This scenario can arise if you work behind a firewall. At deployment time, JDeveloper invokes the tools of Apache Cordova to manage plugins dependencies. These tools may fail to download dependent plugins if their proxy settings are not configured to allow the download of dependent plugins. To work around 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. See 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 10-3.
Example 10-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>
Plugins can be imported into an application 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
maf-plugins.xml file of the consuming application. JDeveloper logs information about the merge to its Messages window.
If the plugin to import from the FAR already exists in the
maf-plugins.xml file of the consumer application, 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
maf-plugins.xml file of the consumer application, JDeveloper adds the plugin to the
maf-plugins.xml file of the application. In this scenario, you need to set the path to the newly-imported plugin, as described in Registering Additional Plugins in Your MAF Application.
A plugin that is enabled in a MAF application can be invoked to interact with device features, such as the camera, or use other applications on the device, such as email or barcode scanner applications.
See Integrating a custom Cordova plugin into a MAF app at http://blogs.oracle.com/mobile/entry/integrating_a_custom_cordova_plugin for information about how you can invoke a plugin from Java, from a MAF AMX page, and from local HTML.
BarcodeDemo sample application also demonstrates how you can accomplish this task.
Figure 10-3 Platform-Specific Content and Constraint To Access a Plugin
Figure 10-4 shows a button (Scan) in the MAF AMX page that the
Figure 10-4 Command Button Invoking Managed Bean Method to Access Plugin
Example 10-4 shows a number of code extracts from the
BarcodeDemo sample application.
Other sample applications, apart from the
BarcodeDemo sample application, that demonstrate how to use additional plugins in MAF applications are
DatePicker. See MAF Sample Applications.
Example 10-4 Using the Barcode Scanner Plugin
MAF applications that you deploy to iOS require usage descriptions if the MAF application uses hardware capabilities, such as the device camera, that allow it to access user data.
The iOS platform requires these descriptions to display in the system dialog that it uses to prompts an end user to allow an application access to the functionality and potentially sensitive user data. Figure 10-5 shows an example where the text “
This application allows the user to upload photos from their photo library” is the usage description from the MAF application.
Figure 10-5 Usage Description in the UI of a MAF Application Deployed to iOS
Basic usage of MAF does not enable functionality that requires you to provide usage descriptions. However, if you enable a core plugin that requires a usage description or use other plugins that require usage description, you need to provide a usage description to successfully deploy the application. Your application may crash or the Apple App Store may reject it if you do not provide a usage description.
The Camera, Contacts, and Geolocation core plugins require usage descriptions. MAF provides the following generic usage descriptions for these core plugins:
Camera: The camera plugin enables access to the device camera and photo libraries.
This plugin requires usage descriptions for the following Cocoa keys:
Contacts: The contacts plugin enables access to the address book on the device.
This plugin requires a usage description for the following Cocoa key:
Geolocation: The geolocation plugin uses device location services on the device.
This plugin requires a usage description for the following Cocoa key:
These generic usage descriptions meet the technical requirements of the iOS platform to successfully deploy the MAF application. We recommend that you provide a specific usage description that explains to your end users why your application needs to access the functionality and data requested by the plugin. For additional plugins that you register with your MAF application that require usage descriptions, you must provide the usage description.
You provide a usage description in your application’s resource bundle
.XLF file. The usage descriptions uses an iOS platform Cocoa key(s) as the value for the
id attribute. The following example shows a usage description that appears when a MAF application prompts an end user to grant access to the user’s photo library.
<?xml version="1.0" encoding="UTF-8" ?> <xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1"> <file source-language="en" original="mobile.ViewControllerBundle" datatype="x-oracle-adf"> <body> <trans-unit id="NSPhotoLibraryUsageDescription"> <source>This application allows the user to upload photos from their photo library.</source> ...
Also provide usage descriptions in locale-specific resource bundles if your MAF application supports more than one locale. The following example shows the corresponding usage description that renders when the locale is French.
... <file source-language="fr" original="mobile.ViewControllerBundle_fr" datatype="x-oracle-adf"> <body> <trans-unit id="NSPhotoLibraryUsageDescription"> <source>Cette application permet à l'utilisateur de télécharger des photos à partir de leur bibliothèque de photos.</source> ...
At deployment time, MAF populates the usage descriptions that you define in the resource bundle into the
info.plist file of the application that is deployed to the iOS device.
For more information about creating resource bundles in a MAF application, including how to create locale-specific resource bundles, see Localizing MAF Applications.
For a list of the Cocoa keys that identify usage descriptions, see the keys that append
UsageDescription to their key name in Apple’s Cocoa Keys documentation at https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html.