Integrating IBM MobileFirst Platform Foundation SDK in Cordova applications
You can use the IBM MobileFirst Platform Command Line Interface (CLI) to leverage MobileFirst features in Cordova applications. This is made possible by packaging the MobileFirst SDK as a plug-in for Cordova named
Use this tutorial as a guide to create Cordova applications by using the MobileFirst CLI, add supported platforms to the application, and add MobileFirst features and 3rd-party Cordova plug-ins.
The tutorial also explains the initialization flow of IBM MobileFirst Platform Foundation in a Cordova application, and how to register the application to MobileFirst Server.
- MobileFirst CLI contains an instance of Cordova CLI v5.0.0, Android platform version 3.6.4, and iOS platform version 3.7.0. It is not possible to upgrade or replace these embedded versions. Therefore, it is not a requirement for you to install Cordova on your developer workstation.
- Only Android and iOS are supported for creating Cordova apps by using the MobileFirst CLI.
- Cordova CLI commands
- Creating a Cordova project
- Cordova project structure
- MobileFirst Platform initialization flow
- Previewing the application web resources
- Testing an application on an emulator or device
- Managing Cordova platforms
- Managing Cordova plug-ins
- Registering applications
- Supported MobileFirst features
- Sample application
Cordova CLI commands
You can create a Cordova-based project with the MobileFirst plug-in by using the MobileFirst CLI. For more information about downloading and using the MobileFirst CLI, see the Using CLI to create, build, and manage MobileFirst project artifacts tutorial.
To see a list of the available Cordova commands, open Terminal and run the following command:
Creating a Cordova project
To create a Cordova application, run the command:
mfp cordova create.
You can use either the Interactive Mode as detailed below, or the Direct Mode (see
mfp help cordova create).
- Enter the application name, package ID, application version, and desired platforms:
- A default set of Cordova plug-ins, including
cordova-plugin-mfp, are automatically added to the application. You can also add additional standard Cordova plug-ins.
- You can use an application template for your project. The CLI provides the default template cordova-hello-world-mfp. You can create your own repository of app templates to speed up your development process and point the path to the application template that you want to use.
- The Cordova project is generated with the selected platforms and plug-ins.
To learn more about Cordova application templates, see the topic about developing Cordova client apps, in the user documentation.
Cordova project structure
After the Cordova project is created, the following files and folders are generated. This project structure follows the standard Cordova project structure:
- application-descriptor.xml - Application metadata for MobileFirst
- config.xml - The Cordova configuration file with extended MobileFirst-related preferences
- hooks - The Cordova hooks folder
- mobilefirst - The folder that contains MobileFirst artifacts:
.wlappfiles that MobileFirst Server needs to recognize applications, as explained below
- platforms - The folder that contains Cordova platforms support
- plugins - The folder that contains Cordova plug-ins
- www - The folder that contains the application web resources
MobileFirst Platform initialization flow
The initialization flow is similar to the flow of a MobileFirst Hybrid app. During initialization, the MobileFirst Cordova Plugin runs
WL.Client.init(wlInitOptions). After initialization completes, the function
wlCommonInit() is called.
wlInitOptions object and the
wlCommonInit function are available inside the
index.js file, which is part of the cordova-hello-world-mfp template. You can use the standard Cordova
deviceready event to handle Cordova initialization, but the function
wlCommonInit is the recommended way to identify that MobileFirst features are ready to be used.
Previewing the applications web resources
Before you can preview application web resources, you must have a MobileFirst Development Server running. If a MobileFirst Server instance is not yet available, use the
mfp create command to setup a new MobileFirst back-end project, followed by the
mfp start command to initialize MobileFirst Server.
When previewing the Cordova app, you can make selections by using either the MobileFirst Operations Console Simple Browser Rendering, or Mobile Browser Simulator.
After MobileFirst Server is started, navigate to the Cordova application folder and use the
mfp cordova preview command to preview the application:
Testing an application on an emulator or device
To run the application by using the Android Emulator or the iOS Simulator, use the
Alternately, you can plug a device into your computer and test the app directly on it by using the
Note: If you do not have a device plugged and execute the
run command, this command starts an emulator/simulator, so that the behavior is the same as that of the
Managing Cordova platforms
You can manage the available platforms in the Cordova project by using the
mfp cordova platform [option].
- Add a new platform to Cordova app:
mfp cordova platform add
- List available platforms in Cordova app:
mfp cordova platform list
- Remove a platform:
mfp cordova platform remove
- Update Cordova assets for each platform in Cordova app:
mfp cordova platform update
Managing Cordova plug-ins
You can manage the plug-ins used in the Cordova project by running the command:
Registering applications to a local development server
mfp push command is used to register client applications and deploy required application and adapter assets to MobileFirst Server.
If you are previewing an app in the Browser, you can refresh the browser after the
push command to preview the new version pushed.
Registering applications to a remote development server
It is also possible to register an application to an existing remote MobileFirst Server, such as a QA, UAT, preproduction or production server. The
mfp push command can be used with the remote server name specified.
Create a remote server definition by using the command:
mfp server add.
You are prompted to provide a name, a fully qualified server address (
protocol://host-or-ip-address:port), admin username and password, and additional details.
To push to the newly defined remote server, run the command:
mfp push myserver.
push command connects to the server and retrieves the list of available back-end projects to be selected.
After pushing an application to the remote server, the application configuration (w
config.xml files) are updated to point to the remote server as the back-end server for the app.
By default, the
mfp push command points to a local development server. Use
mfp server info to list all defined servers and default servers.
To learn more, see the Using CLI to create, build, and manage MobileFirst project artifacts tutorial.
Supported MobileFirst features
Not all MobileFirst features are currently supported by the MobileFirst SDK in Pure Cordova applications.
- Direct Update
- Push Notifications
- 3rd-party Cordova plug-ins
Note: 3rd-party plug-ins are plug-ins that are developed outside the Apache Cordova core plugins.
IBM provides customer support for the core plug-ins provided by Apache Cordova.
IBM does not provide customer support for 3rd-party Cordova plug-ins. Support for these plug-ins is provided by their developers.
- FIPS 140-2
- Shell applications
- Swappable Cordova CLI and platform versions
- Swappable WebViews (CrossWalk)
For more details about what features are supported by MobileFirst Cordova plug-in, see the product user documentation.
Click to download the MobileFirst project.
The provided Cordova application contains a single screen with three buttons which exemplify possible uses of Cordova plug-ins and MobileFirst features:
- The VIBRATE button uses the Cordova plug-in
org.apache.cordova.vibrationto make the device vibrate.
- The CAMERA button opens the device camera and presents the picture taken.
- The RSS FEED button uses a MobileFirst adapter to retrieve data from a RSS feed and presents an alert message with the total of topics obtained from the feed.
Running the sample
- Download and extract the sample
- From the command line, navigate to the
RSSAdapterfolder and run the command
mfp startto start the MobileFirst Server.
- Navigate to the
CordovaAppfolder and run the following commands:
mfp cordova platform add, then follow the interactive instructions to add the iOS and Android platforms
mfp cordova plugin add
, then select the
cordova-plugin-mfp, org.apache.cordova.camera and org.apache.cordova.vibration plugins
- Run the application by using the command
mfp cordova runand follow the interactive instructions to select the device to run. If no device is present, an emulator is used instead.
to register the Cordova application in the MobileFirst Server
Building the sample step by step
Follow these instructions to implement the sample application.
Create the Cordova application
Add the Vibration and Camera Plug-ins
Edit the index.html file
Edit the index.css file
Edit the file
your-app-name/www/css/index.cssto update the visual of the app.
Edit the index.js file
Create a Cordova project by running the
mfp cordova create command. Provide a name for it, and accept all the other default values. The application folder is created, with the default application template.
To add the Cordova Vibration and Camera plug-ins to the Cordova project, run the following commands:
Optionally, you can run the interactive command
mfp cordova plugin add and select the vibration and camera plugins from the list presented.
your-app-name/www/index.html file to add the three buttons: VIBRATE, CAMERA, and RSS FEED, a list to present the results from RSS FEED, and an image to present the result from the camera plug-in:
Edit the file
your-app-name/www/js/index.js to implement the behavior of the buttons.
- For the VIBRATE button, use the function
navigator.vibrate(time)to trigger the vibration.
- For the CAMERA button, use the function
navigator.camera.getPicture(onSuccess,onFailure,options)to open the camera.
- For the RSS FEED button, use the
WLResourceRequestAPI method to call the adapter procedure
getStories, as described in the Invoking adapter procedures from hybrid client applications tutorial.
Create a MobileFirst Project and adapter
For the RSS feed, it is necessary to create a MobileFirst adapter procedure that returns a JSON object containing a retrieved data.
- Change to a different folder (outside of the Cordova project) and create a MobileFirst back-end project by using the
mfp create MFPServercommand.
This command creates a MobileFirst project inside the
- Navigate into the
MFPServerfolder and create the new HTTP adapter by runnin the
mfp add adapter RSSAdapter -t httpcommand. This command creates the RSS adapter inside the
MFPServer/adapters/RSSAdapterfolder. The HTTP adapter contains a sample procedure named
getStorieswhich retrieves data from the CNN RSS feed.
- Start the MobileFirst Server with the
mfp startcommand. The new adapter is pushed to the server during the server initialization.
You can test the
getStories procedure with the
mfp adapter call RSSAdapter/getStories command.
Run the app
- Navigate back to the application folder.
- Register the Cordova application to the MobileFirst Server with the command
- Execute the application with the command
mfp cordova run.
- Follow the interactive instructions to select the device or emulator to run.
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.