Monday Sep 07, 2015

Quick Tip: Multi Line Labels on Command Button

By default, command button labels in MAF AMX display as a single line. But what if you need to reduce the width of a command component while still going with a longer label on it? In this case Cascading Style Sheet (CSS) comes in handy. You can create a quick test case yourself and copy & paste the page code below

<amx:commandButton id="c1" text="one two three four five six seven eight nine ten eleven twelve thirteen"
     inlineStyle="word-break:break-word; white-space: normal; width:100px; 
                  height:150px; max-height:0%; max-width:100px;">

Note the inlineStyle property setting, which not only determines where and how to break the label string but also sets the max width and height for the component. If you like this CSS setting to be more central, you can add it to a MAF skin file so it is applied to all buttons, or just to buttons that reference a specific style class

Friday Sep 04, 2015

Quick Tip: Changing Button Icon in Response to Button Action

A question on the Oracle MAF forum on the Oracle Technology Network  was about how to change the icon displayed on a command button in response to a button action. The solution to this challenge is to think Java and managed bean. Below is a quick outline to the solution of this problem.

AMX page content

The AMX page content shows a command button with an icon attribute that points to a managed bean in view scope (no need for a larger scope).

  <amx:commandButton text="commandButton1" id="cb3" inlineStyle="height:150px; width:150px;"

Managed Bean

The managed bean that you configure either in the adfc-mobile-config.xml file or a task flow specific configuration file contains a property for setting the image ("imageName" in the example) along with its setter/getter methods and two final variables that hold the two image icon names and locations.

import oracle.adfmf.amx.event.ActionEvent;

public class SampleBean {
  private static final String IMAGE1 = "/img/4.png";
  private static final String IMAGE2 = "/img/5.png";
  String imageName = IMAGE1;
  private PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport(this);

  public SampleBean() {

  public void setImageName(String imageName) {
     String oldImageName = this.imageName;
     this.imageName = imageName;
     propertyChangeSupport.firePropertyChange("imageName", oldImageName, imageName);

  public String getImageName() {
     return imageName;

  public void addPropertyChangeListener(PropertyChangeListener l) {

  public void removePropertyChangeListener(PropertyChangeListener l) {

  public void onButtonPressed(ActionEvent actionEvent) {
    if (imageName.equalsIgnoreCase(IMAGE1)){

Important for this to work is that the property change support is added to the managed bean and the image name setter methods. This can be generated for you by Oracle JDeveloper and also in OEPE (Eclipse). With the property change event fired MAF will be notified about a data change and then refreshes the UI of the component the Java code is bound to.

The "onButtonPressed" method is invoked by the command button's action listener attribute and compares the current icon with the two images names in the bean to determine which one to set.

Friday Aug 28, 2015

MAF MCS Utility: Accessing Oracle MCS from MAF Made Simple

With the recent release of Oracle MAF 2.1.3 a new utility becomes available that simplifies access to Oracle Mobile Cloud Services (MCS) from Oracle MAF applications. Oracle MAF MCS Utility (MAF MCS Utility in short) is a Java library for Oracle MAF applications and exposes  MCS client platform REST API calls as native Java calls. This blog post introduces Oracle MAF MCS Utility, explains what it does, how it works and where to find it.

Oracle Mobile Cloud Service client API

Oracle MCS is all about REST! Any mobile client that is capable of sending REST requests and to handle JSON responses can invoke MCS mobile platform functionality exposed on a mobile backend (MBE). This includes calls to Analytics, Notification, Storage, User Information and Custom API.

About MCS client SDK

REST is a good choice for Oracle MCS and ensures an understandable and very easy to use application development interface.

From the perspective of mobile application developers however, accessing REST interfaces from mobile applications is a mental mismatch. To access REST APIs from a mobile application developers need to "think REST" though their comfort zone is within their favorite programming language, which for mobile usually means Objective-C, Java or scripting.

To address this lack of developer comfort and to improve developer productivity, Oracle MCS provides development language specific client SDKs. The MCS client SDK provides a native language abstraction to the underlying REST calls (for Android and Objective-C at current, as well as Xamarin), plus handy infrastructure functionality like offline synchronization and support for push notification registration and handling.

The image below shows the basic architecture pattern implemented by all Oracle MCS SDKs. All in all, using the MCS SDK makes developers more productive, requiring them to write less code.

MCS SDK Architecture

A MBE Manager object, a singleton, is configured with information required to access mobile backend(s) exposed on an Oracle Mobile Cloud Service instance. Mobile applications access the MBE Manager to obtain an instance of an MBE object representing a specific mobile backend in MCS.

The MBE object itself exposes Service Proxy objects that abstract the MCS platform API access. When using the service proxy objects to read and write to the remote mobile backend on the remote MCS instance, the MCS SDK takes care for all required request headers to be added (e.g. Oracle-Mobile-Backend-Id, Authorization, etc.), thus reducing the error surface for application developers. 

You can tell from the above description and image that the MCS client SDK is a simple but effective solution for mobile application developers to stay in their comfort zone.

About MAF MCS Utility

Oracle MAF is a Java based framework that uses Apache Cordova to deploy mobile applications to the Android and iOS platform (and Windows in a future release). MAF uses Java as a shared language across mobile platforms. The use of Java and the cross platform nature of MAF don't allow the use of one of the existing MCS client SDKs. This is where MAF MCS Utility comes in.

MAF MCS Utility provides functionality similar to those of the Oracle MCS client SDKs with some minor differences explained in the following with the help of the image below.

MAF MCS Utility Architecture

MAF MCS Utility needs to be added as a JAR file to MAF applications and is deployed to the mobile device as part of the application.  For this, MAF application developers add the mafmcsutility.jar file to the ApplicationController and/or ViewController project.

The MBE Manager, a singleton, manages MBE object instances that are created from a MBE configuration object. A copy of the MBE configuration object is stored and updated within the MBE instance. MAF application developers can access the MBE configuration object at runtime to e.g. dynamically enable or disable MBE specific logging or to enable or disable collecting analytic events. Service Proxy objects in MAF MCS Utility expose MCS platform REST API calls as typed native Java method calls.

To issue REST requests and handle JSON reponses, MAF MCS Utility wraps the MAF framework RestServiceAdapter class to benefits from MAF features like the security framework and the declarative REST connection framework.

MAF MCS Utility example

The code snippet below creates a MBE configuration object to then obtain a MBE instance from the MBE Manager to showcase how easy MCS integration becomes with MAF MCS Utility
MBEConfiguration mbeConfiguration = 
    new MBEConfiguration(
          <mbe rest connection>,<mobileBackendId>,
          <anonymous key string>,<application key string>, 
MBE mobileBackend = MBEManager.getManager().
         createOrRenewMobileBackend(<mobile backend Id>, mbeConfiguration);

As you can see, the majority of the code lines above are to define the mobile backend specific information like the MCS MBE id, its base URL, as well as the anonymous key (for public access) and the application client key, which allows MAF MCS Utility to register a MAF application with MCS to receive push notifications from MCS. Once you have a handle to the MBE object you call service proxy objects for a specific MCS platform interface as shown below.

UserInfo userInfo = mobileBackend.getServiceProxyUserInfo();
Analytics analyticsProxy = mobileBackend.getServiceProxyAnalytics();
Storage storageProxy = mobileBackend.getServiceProxyStorage();
CustomAPI customApiProxy = mbe.getServiceProxyCustomApi();

Where to get MAF MCS Utility

MAF MCS Utility ships as part of the MAF 2.1.3 public samples. The sample contains the MAF MCS Utility source code, a compiled ready-to-use mafmcsutility.jar library file and a MAF application that demonstrate how to use MAF MCS Utility.

The MAF MCS Utility sample application (shown in the image below) is a generic Oracle MCS tester that can be configured to run against any MCS public cloud instance.

MAF MCS Utility public sample application

MAF MCS Utility Positioning

MAF MCS Utility provides MCS SDK functionality for Oracle MAF application developers to easily integrate calls to Oracle Mobile Cloud Services in their mobile applications. It improves developer productivity by shifting the "think REST" development style to "think Java" when accessing Oracle MCS platform APIs from MAF applications, which also means less code to write.

Because MAF MCS Utility implements the same architecture access pattern as the existing (and future) MCS SDK there is no extra learning curve to it. If you can do it in Android and iOS, you can do it in MAF as well (and vice versa).

MAF MCS Utility in the SDK Architecture

MAF MCS Utility Developer Guide

MAF MCS Utility is further explained in a developer guide, which also covers the MAF MCS Utility public sample application. For each service proxy, the developer guide points you to where in the public sample you find sample code to study and reuse.

MAF MCS Utility Support

As other samples that are distributed with the Oracle MAF public samples, we do our best to provide end user support on the MCS forum on OTN and the MAF forum on OTN.

Thursday Feb 19, 2015

Integrating a custom Cordova plugin into a MAF app

In this earlier post, I demonstrated how to create a simple Cordova plugin for each of Android and iOS.  In this post, I’ll describe how to include that plugin into a MAF 2.1.0 app and how to invoke it from Java, from AMX and from local HTML.

You can follow these same instructions to integrate any 3rd party or custom Cordova plugin into your MAF app.

How do I include a custom Cordova plugin into my MAF app?

To include a custom Cordova plugin into a MAF app, you specify the location of the plugin’s top-level folder (on your local hard drive) in the app’s maf-application.xml > Plugins UI in JDeveloper, as described in the MAF 2.1.0 Documentation.

The path to the plugin will be stored in maf-plugins.xml and will be relative to that file’s location. To avoid any deploy-time issues, make sure the plugin’s top-level folder is on the same drive as your app and that there are no spaces in its path. If your plugin is specific to your MAF app, you probably want to include it within the app’s source tree.

The plugin will appear in the maf-application.xml > Plugins UI as follows:

Note: If you want to use a 3rd party plugin, you must first download it (as a zip file) and extract it to your local hard drive as described in Step 7 of this blog post.

How do I invoke the plugin’s methods?

As described in the earlier post, a Cordova plugin includes a JavaScript interface that defines its available functions. You must write your own JavaScript in your MAF application to call the plugin’s JavaScript interface so your MAF application can interact with the plugin.

In the example “Alert” plugin created in the earlier post, we defined the following JavaScript interface in the alert.js file:

module.exports = {
  alert: function(title, message, buttonLabel, successCallback) {
                 null, // No failure callback
                 [title, message, buttonLabel]);

Our plugin’s manifest file, plugin.xml, defined the JavaScript module as follows:

  <js-module src="www/alert.js" name="Alert">
target="Alert" />

This means that the alert function will be exported as part of the Alert JavaScript module within the consuming MAF application, which enables you to call this function from JavaScript as follows:

  Alert.alert(“My title”, “My message”, “My button label”, myCallbackFunction);

As per the plugin design, this code would cause a native popup dialog to be displayed with “My title” as the title, “My message” as the message and a single button with the label “My button label”. When the user taps the button to dismiss the dialog, the JavaScript callback function myCallbackFunction will be executed with an input parameter of 0.

For more information on using JavaScript callback functions, refer to this helpful blog post by Michael Vollmer.

Note: If you want to use a 3rd party plugin, the JavaScript interface and how to call it should be described in the plugin’s file, typically found in the plugin’s top-level folder.

How do I invoke the plugin from a Local HTML page?

You could invoke the plugin’s JavaScript interface methods directly from your HTML code, but it’s more common to provide a wrapper function that simplifies your code and abstracts you from possible changes to the plugin’s interface.

Let’s take a look at a local HTML page that calls our “Alert” plugin:

<!DOCTYPE html>
    <meta name="viewport"

          content="width=device-width, initial-scale=1, maximum-scale=1"/>
    <title>Plugin Demo</title>
    <script type="text/javascript">if (!window.adf) window.adf = {};
                                   adf.wwwPath = 
    <script type="text/javascript" src="../../../../www/js/base.js"></script>
    <script type="text/javascript">
      function showAlert(frm) {
                    function(button) {
                      console.log("User tapped button:" + button);
      <br>Title: <input type="text" name="title" value="Title">
      <br>Message: <input type="text" name="message" value="Message">
      <br>Button Label: <input type="text" name="buttonLabel" value="Button">
      <br><input type="button" value="Alert" onclick="showAlert(this.form);">

The <meta> tag is included here to avoid the user seeing the components on the page increase or decrease in size as she interacts with it.

You must include the two lines of JavaScript that define the window.adf object and include base.js. There is no need to explicitly include the plugin’s JavaScript file here, since at deploy-time it will be injected into base.js.

A simple showAlert function has been defined to wrap the call to Alert.alert, which in turn simplifies the calling code within the HTML form.

The showAlert function is called when the user taps on the “Alert” button. The “title”, “message” and “button label” input text values are read from the form and passed to Alert.alert, along with an anonymous callback function that will be called when the user taps on the dialog’s button. This callback function will be passed a value for the input parameter button, which we know will be 0, since that was hard-coded in our plugin’s native code.

How do I invoke the plugin from an AMX page?

AMX components cannot call JavaScript methods directly, so you must implement a Java method that is called from an AMX component, which in turn executes some JavaScript that calls the plugin’s JavaScript interface.

Let’s take a look at an AMX page that is similar to the local HTML page described above:

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi=""
  <amx:panelPage id="pp1">
    <amx:facet name="header">
      <amx:outputText value="Plugin Demo" id="ot1"/>
    <amx:inputText label="Title" id="it1"
    <amx:inputText label="Message" id="it2"
    <amx:inputText label="Button Label" id="it3"
    <amx:commandButton text="Alert" id="cb1"

The three inputText components store their values in three attributes of an bean called PluginBean. When the user taps the commandButton component, it calls the popupAlertDialog method of PluginBean.

Let’s take a look at the PluginBean:

package mobile;

import oracle.adfmf.amx.event.ActionEvent;
import oracle.adfmf.framework.api.AdfmfContainerUtilities;
import oracle.adfmf.framework.api.AdfmfJavaUtilities;

public class PluginBean {
  private String alertTitle"Title";
  private String alertMessage"Message";
  private String alertButtonLabel"Button";

  public PluginBean() {

  public void popupAlertDialog(ActionEvent actionEvent) {
      new Object[] {

  public void setAlertTitle(String alertTitle) {
    this.alertTitle = alertTitle;

  public String getAlertTitle() {
    return alertTitle;

  public void setAlertMessage(String alertMessage) {
    this.alertMessage = alertMessage;

  public String getAlertMessage() {
    return alertMessage;

  public void setAlertButtonLabel(String alertButtonLabel) {
    this.alertButtonLabel = alertButtonLabel;

  public String getAlertButtonLabel() {
    return alertButtonLabel;

The popupAlertDialog method calls AdfmfContainerUtilities.invokeContainerJavaScriptFunction to invoke a JavaScript function called showAlert, passing the alertTitle, alertMessage and alertButtonLabel attributes as input parameters to the JavaScript function.

You may wonder why the plugin’s alert JavaScript method is not invoked directly and we call the showAlert function instead. The reason is that the plugin’s alert method requires a JavaScript function callback to be passed as an input parameter and there is no way to do this from Java. Passing a null value may have unwanted side effects, so that is not recommended.

For this reason, we need to write a JavaScript function that wraps the call to the plugin’s alert method. There are two options for this.

One option is to create a JavaScript file and include it into each feature that wishes to invoke the plugin via the app’s maf-feature.xml UI as follows:

The JavaScript file would look similar to the following:

showAlert = function(title, message, buttonLabel) {
              function(button) {
                console.log("User tapped button: " + button);

This JavaScript file defines a global function variable called showAlert, which accepts 3 input parameters and calls the plugin’s alert method with those 3 parameters, along with an anonymous callback function that will be executed when the user taps on the dialog’s button. The native code will pass a return value of 0 to the anonymous callback function as the input parameter button.

The other option, if the plugin is to be invoked from a single AMX page, is to include the wrapper function as verbatim JavaScript within the AMX page, similar to the following:

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi=""
  <amx:panelPage id="pp1">
    <amx:verbatim id="v1">
        <script type="text/javascript">
          function showAlert(title, message, buttonLabel) {
                        function(button) {
                          console.log("User tapped button: " + button);
    <amx:facet name="header">
      <amx:outputText value="Plugin Demo" id="ot1"/>
    <amx:inputText label="Title" id="it1"
    <amx:inputText label="Message" id="it2"
    <amx:inputText label="Button Label" id="it3"
    <amx:commandButton text="Alert" id="cb1"

In either case, there is no need to include the plugin’s JavaScript file in the calling feature(s), since at deploy-time it will be injected into base.js.


You now have the knowledge required to create your own custom Cordova plugin and integrate it into your MAF 2.1.0 app, invoking it from local HTML, an AMX page, or from Java code.

Once you’ve tested your code successfully, you might consider publishing the plugin to make it available to the greater Cordova community. This can be achieved by calling plugman as follows:

$ plugman publish path-to-plugin-top-level-folder

Thursday Feb 12, 2015

Introduction to custom Cordova plugin development

Oracle Mobile Application Framework (MAF) v2.1.0 uses Cordova version 3.6.3 on Android and 3.7.0 on iOS to provide access to native device functionality.  The MAF 2.1.0 extension to JDeveloper 12.1.3 enables you to easily include any of the hundreds of published 3rd party Cordova plugins into your MAF app.

But what if you can’t find a suitable 3rd party plugin? You could elect to write your own, which, depending on the functionality required, may not be as difficult as you think.

In this post I’ll provide an introduction to developing a Cordova plugin by creating a very simple plugin for each of Android and iOS.

How does a Cordova plugin work?

In a nutshell, Cordova provides a bridge between JavaScript and native code, enabling you to write native code that gets exposed to your app via a common JavaScript interface.

Each method exposed by a plugin’s JavaScript interface is mapped to a method in the plugin’s native code via the Cordova bridge, which also enables you to pass parameters back and forth between the JavaScript and native methods.

What comprises a Cordova plugin?

A Cordova plugin typically consists of:

  • Native code for each supported platform
  • A common JavaScript interface
  • A manifest file called plugin.xml

The conventional structure for a Cordova plugin supporting both Android and iOS is:

  - Plugin top-level folder
     - plugin.xml
     - src/
        - android/
           - <Java source code>
        - ios/
           - <Objective-C source code>
     - www/
        - <JavaScript interface>

Ideally, community-published plugins also include release notes, author and license information, and a README file.  

A plugin may also include additional native resources and these are identified in the plugin.xml manifest file. This manifest file is read by the plugman command-line tool, which is used by the Cordova command-line interface and also by the MAF extension for JDeveloper.

In some rare cases, a plugin may be created that simply executes some native code on initialization and requires no JavaScript interface.

For more detailed information about the plugin.xml manifest file, refer to the Cordova Plugin Specification.

How do I create my own custom Cordova plugin?

To create your own custom Cordova plugin, you must write:

  • JavaScript that provides the interface for calling your plugin from within a Cordova-based app, such as a MAF app.
  • Native code that provides the functionality you need.  Since MAF supports both Android and iOS, you should write native code for both platforms.
  • A plugin.xml manifest file that defines your plugin and how plugman should incorporate it into a MAF app (or any Cordova-based app).

What tools do I need to create my own custom Cordova plugin?

You really only need a text editor to create your own custom Cordova plugin, which is all I’ve used to create the custom plugin described in this post.

For more complex plugins, you may wish to develop and test the plugin’s native code in each platform’s native IDE, which means downloading and installing the Android Studio and/or Apple’s Xcode.

You don’t need Cordova installed to develop a Cordova plugin.  Once you have developed your Cordova plugin, you can incorporate it directly into your MAF app for testing. However, if you wish to test your plugin within a Cordova app, you must download and install Cordova using the Cordova Command-Line Interface.

How do I write the plugin’s JavaScript interface?

We start with the JavaScript interface since it provides a common interface to both the Android and iOS native code.  This interface effectively defines what is required in the native code.

The JavaScript interface must call the cordova.exec method to invoke a native plugin method, as follows: 

cordova.exec(successCallback, failureCallback, service, action, [args]);

This call invokes the action method on the service class on the native side, passing the arguments in the optional args array.  If the native code completes successfully, the successCallback function is executed, along with any return parameters.  If the native code fails, the failureCallback function is executed, with an optional error parameter.  For more information on JavaScript callback functions, refer to this helpful blog post by Michael Vollmer.

Let’s create a very simple plugin that displays a native popup dialog.  Thus plugin shall present one method that takes 3 parameters – title, message and button label – and shall return the result in the ‘success’ callback. No ‘failure’ callback will be implemented. The service class shall be named “Alert” and we shall call the sole method “alert”. 

The following JavaScript defines the interface:

module.exports = {
  alert: function(title, message, buttonLabel, successCallback) {
                 null, // No failure callback
                 [title, message, buttonLabel]);

The call to module.exports exports the JavaScript function alert as part of the JavaScript module that will be defined in the plugin manifest file, plugin.xml

Your app will call this alert JavaScript function, which will invoke the alert method on the Alert class in the plugin’s native code.

Save this JavaScript into a file called alert.js, within a www subfolder of your plugin’s top-level folder.

How do I write the plugin’s native code?


Based on the JavaScript interface, we must define a class called Alert in a Java source file called  Let’s take a look at the source file:

package com.acme.plugin.alert;

import android.content.DialogInterface;
import org.apache.cordova.CallbackContext;
import org.apache.cordova.CordovaInterface;
import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CordovaWebView;
import org.apache.cordova.PluginResult;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class Alert extends CordovaPlugin {
  protected void pluginInitialize() {

  public boolean execute(String action, JSONArray args, CallbackContext callbackContext)
      throws JSONException {
    if (action.equals("alert")) {
0), args.getString(1), args.getString(2), callbackContext);
      return true;
    return false;

  private synchronized void alert(final String title,
                                  final String message,
                                  final String buttonLabel,
                                  final CallbackContext callbackContext) {
    new AlertDialog.Builder(cordova.getActivity())
new AlertDialog.OnClickListener() {
      public void onClick(DialogInterface dialogInterface, int which) {
new PluginResult(PluginResult.Status.OK, 0));

The Alert class should be part of a package that will be referenced in the manifest file, plugin.xml.

The Alert class must extend the CordovaPlugin class, the definition of which you can find here.

The Alert class must override the execute method, since this will be called each time the JavaScript cordova.exec method is called, providing the name of the plugin method, the input parameters and a callback context.  The execute method should return true if a valid action was passed in, otherwise false.

Once the code has completed, it should return a result and optional return parameters to the calling JavaScript by invoking the sendPluginResult method on the callbackContext object.   Returning a result of PluginResult.Status.OK will cause the JavaScript ‘success’ callback to be executed.  Any other result (apart from PluginResult.Status.NO_RESULT) will cause the JavaScript ‘failure’ callback to be executed.

In our plugin, a ‘success’ result is returned when the user taps the button on the popup dialog and a value of 0 is returned.

The Alert class may override the pluginInitialize method if any initialization logic is required when the plugin is first constructed.

Save this code into a file called, within a src/android subfolder of your plugin’s top-level folder.

For more detailed information on aspects such a threading and event handling, refer to the Cordova page Android Plugins.


For our example, we must define a class called Alert in an Objective-C source file called Alert.m and corresponding header file Alert.h

Let’s take a look at the Alert.h header file:

#import <Cordova/CDV.h>

@interface Alert : CDVPlugin <UIAlertViewDelegate> {}
- (void)alert:(CDVInvokedUrlCommand*)command;

MyAlertView : UIAlertView {}
@property (nonatomic, copy) NSString* callbackId;

The Alert class must be a sub-class of CDVPlugin, the definition of which you can find here.

The Alert class must provide an alert method, since this will be called each time the plugin’s JavaScript alert method executes the cordova.exec method.

Save this code into a file called Alert.h, within a src/ios subfolder of your plugin’s top-level folder.

Let’s take a look at the Alert.m source file:

#import "Alert.h"

@implementation Alert
- (void)pluginInitialize

- (void)alert:(CDVInvokedUrlCommand*)command
  NSString* callbackId = command.callbackId;
  NSString* title = [command argumentAtIndex:
  NSString* message = [command argumentAtIndex:
  NSString* button = [command argumentAtIndex:

  MyAlertView *alert = [[MyAlertView alloc]
                        alert.callbackId = callbackId;
  [alert show];

- (void)alertView:(UIAlertView*)alertView clickedButtonAtIndex:(NSInteger)buttonIndex
  MyAlertView* myAlertView = (MyAlertView*)alertView;
  CDVPluginResult* result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
self.commandDelegate sendPluginResult:result callbackId:myAlertView.callbackId];

@synthesize callbackId;

The alert method receives the input parameters and a callback id.

Once the code has completed, it should return a result and optional return parameters to the calling JavaScript by invoking the sendPluginResult method on the commandDelegate object. Returning a result of CDVCommandStatus_OK will cause the JavaScript ‘success’ callback to be executed. Any other result will cause the JavaScript ‘failure’ callback to be executed.

In our plugin, a ‘success’ result is returned when the user taps the button on the popup dialog and a value of 0 is returned.

The Alert class may implement the pluginInitialize method if any initialization logic is required when the plugin is first constructed.

Save this code into a file called Alert.m, within a src/ios subfolder of your plugin’s top-level folder.

For more detailed information on aspects such a threading and event handling, refer to the Cordova page iOS Plugins.

How do I write the plugin’s manifest file (plugin.xml)?

The manifest file, called plugin.xml, is an XML document that defines the plugin and tells plugman how to incorporate the plugin into your MAF app (or any Cordova-based app) for each platform it supports.

The Cordova Plugin Specification is comprehensive, but we will focus on the manifest file used for our “Alert” plugin:

<?xml version="1.0" encoding="UTF-8"?>

A Cordova plugin that displays an alert popup dialog</description>

name="cordova" version=">=3.6.0" />

src="www/alert.js" name="Alert">
target="Alert" />

  <!-- android -->
  <platform name="android">
      <feature name="Alert">
        <param name="android-package" value="com.acme.plugin.alert.Alert" />
    <source-file src="src/android/" target-dir="src/com/acme/plugin/alert" />

  <!-- ios -->
  <platform name="ios">
    <config-file target="config.xml" parent="/*">
      <feature name="Alert">
        <param name="ios-package" value="Alert" />
    <header-file src="src/ios/Alert.h" />
    <source-file src="src/ios/Alert.m" />


The plugin element must contain the plugin’s XML namespace (xmlns), id and version.

The name and description elements should always be defined.  If you intend to publish your plugin for public use, you should include additional elements such as those identifying the author, license, keywords and repository.

The child elements of the engines element define which version(s) of the Cordova framework the plugin supports.  Since this plugin has been developed based on Cordova 3.6.0 documentation and will be tested within a MAF 2.1.0 app, we should set the minimum required Cordova version to 3.6.0.

The JavaScript interface is defined by including a js-module tag for each JavaScript file.  Any file defined here is automatically copied into your MAF app and injected into any HTML using a <script> tag so that you don’t have to specifically add this tag yourself, or include the JavaScript as content in your AMX features.  The clobbers tag indicates that the module shall be inserted into the window object as Alert, so your MAF app code should call the JavaScript method Alert.alert to execute the plugin’s alert method.

If your plugin has a dependency on another Cordova plugin, you can define this using a dependency tag.  Since our plugin does not have any dependencies, there is no such tag defined.

The platform tag is used to define the platforms that are supported by the plugin.  Within each platform tag, you specify the native source files, changes required to configuration files, any additional native resources or frameworks and any platform-specific JavaScript files.

For Android, it is important to specify the full package name of the plugin as the value for the android-package parameter, for example “com.acme.plugin.alert.Alert”, and to specify the target-dir for any source files (since this indicates the location to which the source file should be copied and it must match the package name), for example “src/com/acme/plugin/alert”.

Save this XML into a file called plugin.xml, within your plugin’s top-level folder.


We have now developed a custom Cordova plugin that can be incorporated into a MAF 2.1.0 app, or any app based on Cordova 3.6.0 or above.  In a follow-up post [Edit: here], I’ll describe how to integrate this plugin into a MAF app.

For developers looking for more detailed information about how to create a Cordova plugin, refer to the Cordova Plugin Development Guide, which contains specific guides for each native platform.

Monday Oct 13, 2014

Updated MAF Academy Course

Now available! The FREE online Oracle Developer Academy course, Developing Applications with Oracle Mobile Application Framework (MAF) has just been re-released to include all you need to know about securing a MAF application. Carve out two hours of time in your day* with this interactive, engaging online course and get a comprehensive education on Oracle MAF. You'll master the nuts and bolts of the architecture, be able to design and develop a MAF application with web services, integrate with native device capabilities, and secure the app and the services it accesses.

*or multiple days – the course player remembers where you were so you can easily pick up where you left off if necessary

Note: The course requires the following:

Flash Player 10 or later, and one of the following browsers:

Internet Explorer 6 and later, Firefox 1.x and later, Google Chrome, Opera 9.5 and later, Safari 3 and later.


This blog is is dedicated to announcements,tips and tricks and other items related to developing, integrating, securing, and managing mobile applications using Oracle's Mobile Platform. It is created and maintained by the Oracle Mobile product development team.

Archive of past entries

Even More Mobile Development Blogs

Oracle A-Team Site - Mobile Related Entries

Code samples from the Community

Fusion Middleware Blogs


« October 2015