Adding Plugins to Your Intel® XDK Cordova App

Apache* Cordova* plugins are a very important tool for enhancing the features and functionality of your Intel® XDK HTML5 mobile application. They provide a way to extend your app's JavaScript API, resulting in a much tighter integration of your app with a mobile device's software and hardware. There are hundreds of Cordova (and Adobe* PhoneGap*) plugins available for use with your app. They can be found in the Apache Cordova Plugins Registry and similar plugin registries, as well as many open source github repos. If you work for a large company your IT department might even maintain a set of Cordova plugins they've developed for mobile apps used by your company's employees, for example.

The Intel XDK references and uses Cordova plugins in a variety of locations throughout the development cycle of your HTML5 mobile application. The most apparent usage is in the Projects and Build tabs. In the Projects tab (described below) you select which Cordova plugins will be included as a part of your app. The Build tab will then automatically add those plugins to your app package when it builds your app, in order to include the "JavaScript extension API" provided by that plugin and used by your application. Less obvious is their use in the Brackets editor (the text editor in the Develop tab) and the Emulate tab.

In the Develop tab, the plugins are used to implement code hinting (a common editor feature that is frequently referred to as "intelli-sense" or "auto-hinting"). The editor automatically provides API method and property hints for the core Cordova and Intel XDK APIs. At this time code hinting is provided for ALL core plugins, regardless of which you've actually selected to be part of your application on the Projects tab.

The Emulate and Test tabs (App Preview) make note of which core Cordova plugins you've selected on the Projects tab and will only present to your application those APIs that correspond to the selected core Cordova plugins, when your app runs inside the emulator or App Preview. The complete set of APIs provided by the Intel XDK plugins are always presented to your app by the emulator, regardless of which have been selected on the Projects tab.

NOTE: at this time the Debug and Profile tabs are not affected by the plugins you choose on the Projects tab.

Only the Build tab actually uses third-party (non-core) plugins. Future editions of the Intel XDK will expand the use of third-party plugins throughout the development cycle. However, at this time the only way you can test and debug any code in your app that accesses third-party plugins is to build an application and run it on a real device.

See Debug & Test Overview for recommendations on how to debug your Intel XDK apps, especially those that incorporate third-party plugins.

What is a Cordova Plugin?

Paraphrasing the Cordova Plugin Development Guide:

A plugin is a package of code that allows your Cordova HTML5 app to communicate with the native platform on which it runs. Plugins provide access to platform functionality that is ordinarily unavailable to browser-based apps. The core Cordova (and Intel XDK) APIs are implemented as plugins. Many other plugins are available that enable features such as barcode scanners, NFC communication and access to local phone and tablet software databases (such as phone contacts and calendar entries).

Plugins consist of a JavaScript API and native code modules (for each platform supported by the plugin) that support the plugin's JavaScript API. In essence, when your app calls the plugin's JavaScript API, it is redirected to the underlying plugin native code that implements that API on the device. For example, the JavaScript API is redirected to Java code on an Android device or to Objective C code on an iOS device. Plugins can be complex or simple: providing APIs as complex as a persistent database engine or as simple as a method to turn on the camera's flash LED.

Do I Need to Learn How to Write Native Code in Java and Objective C and C# and ???

Absolutely not. Most plugins can be pulled directly from a plugin registry or github repo and used as-is, without learning how the plugin operates internally. You do not need to "compile" anything to use a properly structured plugin, most are ready to use without any configuration or internal programming required.

You will need to learn how to use the plugin's JavaScript API in order to use it within your app; but that is to be expected. You can think of a Cordova plugin as a JavaScript library that extends the device-specific features your app can access, features that you typically are not able to access from a standard browser or webview (the embedded browser that interprets your HTML5 hybrid app). Plugins provide the extra features that distinguish a mobile app from a browser-based web app.

Including a Cordova Plugin in Your Intel XDK App

Including any of the "core" Cordova plugins and the Intel XDK plugins in your app is very easy. The Projects tab for your app contains a list of "core" plugins that can be added to or removed from your app by simply selecting or clearing the respective check box next to the plugin name. See the following screenshot for an example application.

Details about which APIs are included with each core Cordova plugin can be found in the API Reference section of the Apache Cordova Documentation pages. See the Intel XDK API Reference Documentation for API and platform details regarding the Intel XDK API plugins.

About the Core Plugins

The core Cordova plugins and Intel XDK plugins are included with the Intel XDK; because these plugins are included as part of the Intel XDK, they have a "default version" associated with them. These are the versions that the plugin specifications are reset to when you push the ">Reset versions" link (see image above).

You can change a plugin's version number by selecting the edit button (hover over a plugin as shown in the image below):

and then entering the desired version number of the plugin (as shown below):

See the Apache Cordova Documentation pages for details regarding the core Cordova plugins. The git repo where each core Cordova plugin is maintained includes details about plugin versions, etc. You can quickly determine which versions are available for a particular plugin by inspecting it in the Apache Cordova Plugins Registry or by clicking the (i) link next to each plugin. At this time, only the Build tab uses the plugin version number, other Intel XDK components use a fixed set of core Cordova plugins.

In the September, 2014 release of the Intel XDK we added a list of featured plugins as part of the Projects tab. These plugins are third-party plugins that may include tighter integration with the Intel XDK than other third-party plugins. For example, if parameters are required by a plugin the Intel XDK will prompt you for those parameters. Some featured plugins may include access to the plugin source via a github repo, and some may incorporate proprietary code. One example of a featured plugin is the APP Security API, which enables non-security experts to take advantage of the security properties and capabilities available on your target mobile platforms.

Including Third-Party Plugins

There are two ways third-party plugins can be included as part of your application: via a public repo or a local directory. You select the specific method by selecting "Import Local Plugin" or "Get Plugin from the Web" in the "Third-Party Plugins" section of the "Plugins and Permissions" panel on the Project tab.

Two public repos are supported: a git repo (such as github) or the Apache Cordova Plugins Registry. When using the Cordova registry you only need the plugin ID, which can be found in the Cordova registry entry (see the image below for an example of referencing the Cordova registry with just a plugin ID). You can also optionally provide a plugin version number (more info below) as part of the Plugin ID field in the "Get Plugin from the Web" dialog box.

If your third-party plugin is being retrieved from the Cordova registry the Name and Plugin ID are sufficient. In that case, check the "Plugin is located in the Apache Cordova Plugins Registry" box and select the "Import" button.

Otherwise, if your third-party plugin is located in a git repo you must also include the address of that git repo. The git repo must be publicly accessible on the Internet because the "git pull" used to retrieve the plugin is performed by the cloud-based build server, not the Intel XDK; thus, it must reside in a publicly accessible git repo.

If you are familiar with the Cordova CLI plugin add command you can use that syntax to include a specific plugin version based on either the version numbers stored in the Cordova registry or a git reference ID. Details can be found in the Advanced Plugin Options section of the Cordova CLI doc pages (about three-quarters down the page). If you do not specify a plugin version or reference ID your app will be built using the most recent version available in the Cordova registry or the default branch when retrieved from a public git repo.

Importing a third-party plugin that resides in a local directory requires that the plugin be located within your project's "source directory." Normally this source directory is named "www" and is located inside your application's project directory (see the "Project Info" section of the Project tab for the name and location of your project's "source directory"). A local plugin will be included with the source bundle that is uploaded to the cloud-based build server; the entire contents of your project's "source directory" are included as part of that uploaded bundle.

HINT: in some rare cases you may need to modify a third-party plugin before it can be used with the build system. In this case, download a copy of the third-party plugin you wish to use into your "source directory"; make the necessary modifications to the plugin sources; and use the "Import Local Plugin" mechanism to include that plugin as part of your project.

References to your third-party plugins, whether imported from a local directory or a public repo, are listed in the "Third-Party Plugins" section of the Projects tab (see the image below for an example). The Name field you specified above is arbitrary and is used strictly as an identifier here and in the build message log. The Plugin ID must match that specified inside the plugin.xml file (see the registry or the plugin's git repo). At this time there is no way to edit or inspect the data you provided during the plugin import process; if you need to change the Name or Plugin ID or other fields you must delete the plugin reference (click the (X) icon) and re-import the plugin with the revised Name, Plugin ID and other fields.

The following screenshot is typical of what you will find when you inspect a plugin that is located in the Apache Cordova Plugins Registry. Note the plugin ID field, supported platforms, plugin version and supported Cordova CLI version number (aka "Engine Number").

Building Your Cordova App

To build an app package, based on the Cordova container and your selected Cordova plugins, go to the Build tab and select the platform for which you want to generate an installable package under the "Cordova 3.x Hybrid Mobile App Platforms" heading.

The Crosswalk for Android and Android platforms both generate APKs for Android devices. See Using the Intel XDK “Crosswalk for Android” Build Option and the Crosswalk Overview for more details.

When you initiate a build you'll be asked if you want to "Upload to the build server?" Normally you should choose to "Upload Code" when this question is asked. The usual exception is when you have previously uploaded your code and successfully built for one platform and are now building for a second platform without any changes to your application between builds. In that case there is no need to upload your code to the build server a second time.

A successful upload of your application source bundle will result in a screen similar to the following. To initiate a build click the "Build App Now" button. Unlike the "legacy" build system, there are no options associated with this step; your options are stored in an intelxdk.config.platform.xml file in your project file. See Adding Build Options to Your Intel® XDK Cordova App Using intelxdk.config.additions.xml for information on how to add build options that are not accessible via the Project tab's user interface.

iOS builds include an option for supplying your Apple developer certificate. This certificate is stored in the build system under your Intel XDK userid; it is only necessary to provide it once for all applications you build under your login.

A successful build results in a screen similar to the following. If the build system encounters issues the build log will include an error message indicating the nature of the problem that is preventing a successful build and a link to a detailed error log. If you consistently get build errors visit the Intel XDK forum for help (a link to the forum can be found under the (?) pulldown of the Intel XDK).

A Simple Example Using Cordova Plugins

The device screenshots below show a simple HTML5 hybrid app running on a real Android device. This application was built by selecting the "Device,""Media,""Accelerometer" and "Compass" plugins from the "Core Cordova Plugins" column of the "Included Plugins" section on the Projects tab and the Intel XDK "Base" plugin from the "Intel XDK Plugins" section under the "Featured and Custom Cordova Plugins" column. Finally, the "Cordova StatusBar" third-party plugin was included using the "Get Plugin from the Web" feature.

This sample app generates a list of included plugins dynamically, at runtime, by inspecting a special Cordova 3.x JavaScript property. The results are then printed into a <textarea> element at the bottom of the app's index.html page.

The only difference between the two device screenshots above is the visibility of the status bar at the top of the screen. Touching the "Toggle Status Bar" button calls the StatusBar plugin's StatusBar.hide() or StatusBar.show() method, depending on the visible state of the status bar, which is determined by checking the plugin's StatusBar.isVisible property. Had the plugin not been included these methods and this property would not be available to the app and references to them would result in JavaScript undefined errors.

Real Devices vs Simulated Devices

The following screenshot shows the same app running in the Emulate tab of the Intel XDK (not on a real device). There are several differences that are worthy of note and help to illustrate some key differences between running your plugin-enabled app in the emulator (or in App Preview or when using the Debug tab) compared to running your app on a real device.

The screenshots shown above were taken on a real device that was running the built app installed on that device. The app was built using the Android Cordova build tile on the Intel XDK Build tab.

What's different?

• The Cordova versions do not match: the Emulate tab is using Cordova 3.4, whereas the built app running on the real device (shown above) is using Cordova 3.3.
• The core Cordova "Device" plugin is using the default plugin version (0.2.5), whereas the built app running on the real device is using a later version that was specified manually on the Projects tab (0.2.10).
• The third-party "StatusBar" plugin does not show up in the list of included plugins when the app runs on the Emulate tab. As a result, touching the "Toggle Status Bar" button results in no change to the device status bar when it runs inside the Emulate tab, because the StatusBar API is not present in that runtime environment.

Running this app inside of App Preview (either via the Test tab or from the App Preview menu) or on the Debug tab (which runs the app in a special version of Crosswalk for Android) will show yet another set of results. If you run this app in those environments you will see a very long list of "included" plugins listed, as if you had selected all the plugins on the "Included Plugins" list of the Projects tab. This is normal and is due to the way these preview applications work. You will also not see any third-party plugins listed. Likewise, those third-party (non-core or not included) plugin APIs will not be accessible from within these app test environments.

A version of the above app can be retrieved from this Github repo: https://github.com/xmnboy/test-third-party-plugin.