Adding and Managing Plugins

Contents:
  Exploring and Adding Cordova Plugins with the Plugin Manager
  Managing Plugins: Viewing Details, Versions, Variables, ...
  Your Project Directory and Plugin Sources
  How to Fix intelxdk.config.additions.xml Plugin Tag Problems
  Resources

NOTE: If you are not sure what a Cordova plugin is, or are new to developing hybrid cross-platform mobile apps, please read the Plugins Overview page first, and then return to this page.

The Intel XDK Projects tab includes a Plugin Management tool that simplifies finding, adding and managing the Apache Cordova* plugins in your project. Plugins are stored as a part of your project on your development system after they are retrieved by the Intel XDK and copied to your plugins directory. This approach documents the components that make up your Cordova app, because the plugins are part of your project folder. This is consistent with the way a standard Cordova CLI project works.

Do not try to modify the structure of non-source files in the plugins folder inside any of your Intel XDK projects while the Intel XDK is running. When the Intel XDK is running, do not edit or delete non-source files, such as the plugin.xml file; also, do not change or remove the plugins folder nor its immediate subfolders. The entire plugins folder and all the plugins stored therein must conform to the Cordova CLI plugin specification at all times (the Intel XDK uses the Cordova command line interface (Cordova CLI), under the hood, to manage this directory and the plugins contained within it).

Exploring and Adding Cordova Plugins with the Plugin Manager

To display Cordova plugin information and explore available plugins for the active project:

  1. Click the word PROJECTS in the upper-left corner of the Intel XDK window.
  2. Open the Plugin Management section of the Projects tab,
  3. Click Add Plugins to this Project to begin exploring plugins to add to your project.

Intel XDK Projects tab, Plugin Management of Cordova plugins

As shown above, those plugins that are already part of your project are listed below the Add Plugins to this Project link. On the left, choose a category of plugins to explore. You can view available plugins within a category and select one (such as the Core Plugin named Camera shown below) for closer inspection:

Intel XDK Projects tab, exploring the Camera Core Plugin

You can select from these categories:

  • Core Plugins that are maintained by the Apache Cordova project team members.
  • Featured Plugins that are maintained by third-party plugin authors.
  • Third-Party Plugins lets you import any Cordova plugin, including plugins stored in git* repositories. Use this category to add plugins that are not listed in other categories.

Except for the Third-Party Plugins category, when exploring plugins, you can:

  • Read a short description of each plugin.
  • See a plugin's name, ID, and recommended version. You can also view its available version numbers (shown above).
  • View a plugin's README or main documentation page by clicking the icon.
  • Change a plugin version before adding it by clicking the icon. You can also change the version of a plugin that is already part of your project from within the Plugin Management section of the Projects tab.

After you read about a plugin and choose its version and variables, add it to the active project by clicking Add Plugin.

NOTE: Plugins are maintained and supported by third-party organizations that may or may not have an affiliation with Intel Corporation. It is important that you read and understand each plugin's documentation and license terms and restrictions before you include it as a part of your project. Support for the Core Plugins, Featured Plugins and Third-Party Plugins are provided by their respective third-party plugin authors. Support for third-party plugins must be obtained directly from the third-party plugin authors.

Intel Corporation cannot guarantee the reliability or usability of third-party plugins and has no authority over their license terms and restrictions.

Importing Third-Party Plugins

The contents and functionality of Third-Party Plugins are completely unknown to the Intel XDK. You can import third-party Cordova plugins into your project but you need to specify where to retrieve each plugin from. The Intel XDK can obtain Cordova plugins from these sources that you specify:

  • Cordova plugins registry by specifying a Plugin ID.
  • Git repositories by specifying a Git repo URL.
  • Import local plugins by specifying a local directory on your file system that is outside the source directory (usually named www) and outside the plugins directory in your project folder (e.g., do not copy or clone local plugins into the www folder or the plugins folder, otherwise your local plugin sources will become part of the package built for the application, unnecessarily consuming extra space in your final app).

NOTE: With the retirement of the Intel XDK build system, importing local plugins is no longer a feature we recommend you use. Instead, if you have a private plugin or have customized a third-party plugin, you should publish your unique plugin to a git repo and add your plugin using the git repository add feature described below.

Use the following dialog to import a Third-Party Plugin. Specifying the plugin origin (registry, git repo or local file system) will result in prompts to provide a plugin ID or location, version number, variables (if needed), and other relevant information.

Intel XDK, importing third-party Cordova plugins

Plugin Variables

Some plugins require variables. For example, an application that interacts with a web service usually needs access to an API key or other unique identifier that you obtained by registering with that web service. Those plugins that expect such information typically receive it via “plugin variables” that are filled when the plugin is added to your project. This eliminates the need to store and pass these variables in your application source when the plugin is initialized and used by your application.

If a plugin uses variables, you must provide their values when you add that plugin to your project. You will be prompted for the values of those variables when you add one of those plugins to your project.

If you omit a required variable the “plugin add” operation will fail. If you do not know the required values yet, you can use dummy values as a placeholder. You can always use the Plugin Manager to change the variable values after you add a selected plugin to the project. To determine the correct plugin variable data you must read the plugin's documentation and examples, where you will find the information regarding what format and type of data is required by a specific plugin.

Managing Plugins: Viewing Details, Versions, Variables, ...

Once you have selected a plugin, you can expand it to see more details about that plugin. For example, clicking the line containing Device cordova-plugin-device in the image below.

Intel XDK, examining Cordova plugin details

This provides information regarding the plugin's ID, the version that is installed in your project, a link to the main documentation page for that plugin and an icon to modify the version of that plugin. Changing a plugin version or variables will result in a "cordova plugin remove" operation followed by a "cordova plugin add" operation -- removing the copy of the plugin that is stored in your project directory and replacing it with a new copy that corresponds to the changes you requested (note: any variables required by that plugin may need to be provided again when you perform any such operation).

Viewing Plugin Details

Depending upon the information provided by the plugin, you can view the following information when you select the plugin in the Plugin Manager list:

  • The name of the plugin and its Cordova ID.
  • The plugin's version. Once fetched, the plugin version does not change. (See the plugin's repo or registry entry to see what versions are currently available.)
  • The primary documentation for the plugin (by clicking the icon).
  • Which plugins this plugin depends on and what other plugins depend on this plugin, if any.
  • If available, which versions of Cordova are compatible with this plugin.
  • If relevant, any Android permissions that the plugin will set.
  • If available, the name of the author(s) who created the plugin.

All of the data above is provided within the plugin.xml file that is included with each Cordova plugin. Only the information that is available in the plugin.xml file can be provided; if the author of the plugin does not provide that information the Plugin Manager in the Intel XDK cannot display the information.

For example, the core File plugin (cordova-plugin-file, formerly named org.apache.cordova.file) displays the following information when selected:

NOTE: Before you do extensive testing/debugging of your app, check the versions of your selected plugins using Projects tab > Plugin Management. Also check the plugin versions after you change the Cordova CLI version in the Projects tab > Build Settings. After you change a plugin version, recheck that plugin's associated dependencies (read its documentation). A main cause of build failures is related to plugin use, such as referencing a plugin that is no longer available or mismatched versions between dependent plugins.

Checking Plugin Versions and Variables

You can use the Plugin Manager at any time to view a plugin's details. You can also change its version or variables by selecting the pencil icon ().

Changing either a plugin's version or variables causes a "cordova plugin remove" operation followed by a "cordova plugin add" operation; the plugin is removed from your project's plugins directory and then re-added to match your requested changes. If you changed the plugin sources located in the plugins directory inside your project directory, those changes will be overwritten by these operations. If you need to modify a plugin it is recommended that you fork or clone the plugin, make your changes to that fork or clone and then import your modified plugin using the Third-Party Plugin Import local plugins option.

Deleting a Plugin

If you decide you no longer need a plugin, click the button to the right of the plugin's name.

When a plugin is a dependency of another plugin (another plugin requires this plugin), the locked icon appears instead of a button. You cannot delete a plugin identified by the locked icon (locked plugin) unless you first remove the plugin(s) that require the plugin. To determine which plugin(s) depend on a locked plugin, expand the locked plugin to view its details. For example, the Cordova File Transfer plugin depends on the Cordova File plugin; so if you want to remove the File plugin you must first remove the File Transfer plugin that requires it.

A locked plugin can be required by more than one plugin. All of the plugins that require that locked plugin will be displayed in the locked plugin's expanded details.

Your Project Directory and Plugin Sources

The Plugin Manager stores your included plugins in a directory named plugins inside the project directory on your development system. This means that when you add a plugin, the plugin is fetched and added to your project's plugins directory.

Data flow for the project plugins directory

Each plugin is stored in a subdirectory named after its plugin ID, within the project's plugins directory; for example, plugin/cordova-plugin-device. You can view the contents of your plugins directory using the file tree in the Develop tab or with your development system's file explorer tool.

Including the plugin sources has advantages for debugging your app. Sometimes it is useful to look at the plugin sources to clarify some usage detail that isn’t specified in the plugin documentation. Also, when debugging you can set breakpoints in plugin sources and then look back to see who called that plugin function.

To learn more about your project and how it is organized on your development machine's file system see the Projects Overview.

The Plugins Directory: Synchronizing and Editing Plugin Sources

The Intel XDK attempts to maintain a record of the state of each plugin and its plugin version within the project file settings (in the <project-name>.xdk and <project-name>.xdke files that are stored in your project's root directory). Each time you open a project the Intel XDK compares the contents of the plugins directory with the state information stored in your project file settings. Normally they will match; however, there are some instances when they might not match:

  • You modified the project file settings outside of the Intel XDK. For example, if you do not keep your plugins directory under source control and you pulled down a new version of your project from your source code control system (perhaps updated by a co-worker). Your pull resulted in updated project file settings but because your plugins directory was not under source code control, the changes came without any corresponding updates to the plugins directory contents.

  • You modified the contents of the plugins directory outside of the Intel XDK. For example, you modified, added or deleted your project plugins using the Cordova command line tools (Cordova CLI). You could also have simply deleted the plugins directory or any subdirectory therein.

When the project file settings and the plugins directory do not match, the Intel XDK must synchronize them to a consistent state. If the plugins directory does not exist the Intel XDK will attempt to create it and populate it with your project plugins, based on your project file settings. If you import an existing HTML5 code base into the Intel XDK and that imported project has a plugins directory, the Intel XDK will attempt to update the project file to match the contents of the plugins directory. Otherwise, the Intel XDK displays a dialog box that lists the inconsistencies and asks you to choose how the Intel XDK should proceed. In this case, your choices are:

  • Update the project plugins directory to match the project file settings.
  • Modify the project file settings to match the plugins directory.
  • Leave things as they are and abandon any attempt to open the project (so you can try again later).

Usually you will remember what you did to cause the mismatch. For example, if you deliberately modified the plugins directory, then you will probably want the Intel XDK to update the project file settings. If you need more time to investigate further, before you decide which route to take, you can abandon the project open and try again later when you are prepared to resolve the inconsistency.

Modifying Plugin Sources

There are a few cases where you may want to modify plugin code. For example, you may want to fix a bug in a plugin, or you might need to add tracing output (e.g., console.log messages) to a plugin's sources to help debug your application's interaction with the plugin. To accomplish these goals you can edit and import a modified copy of the plugin. 

NOTE: With the retirement of the Intel XDK build system, importing local plugins is no longer a feature we recommend you use. Instead, if you must fix or customize a third-party plugin, you should publish your unique plugin to a git repo and add your plugin to your project using the git repository add feature described above.

Interoperability with PhoneGap Build

There are a few features of Cordova CLI that are not supported by PhoneGap Build. These include the “merges” folder and the “hooks” feature. Merges are platform-specific source variations. It is possible, for example, to say that you want to substitute some file in your application with an alternative version when you build on a specific platform. Hooks are scripts are special plugin-specific scripts that are executed at various points during the build process. 

If you receive a message similar to...

Warning: Plugin <plugin-name> contains hooks scripts.

...it means you have included a plugin that contains Cordova plugin "hooks" scripts. Those "hooks" scripts were ignored by the PhoneGap Build system, resulting in a partial installation of the plugin in your app. The part of your app that depends on the problem plugin may not work properly. For this reason, plugins that contain "hooks" scripts will only work if you use Cordova CLI to build your app.

How to Fix intelxdk.config.additions.xml Plugin Tag Problems

The Intel XDK no longer supports adding plugins via the intelxdk.config.additions.xml file. All project plugins must be added using the Plugin Management tool, described in the paragraphs above. This change improves build system security, increases your control over the code that is included with your app, and ensures greater consistency between builds. It also provides better documentation regarding the components that make up your Cordova app, because all plugins must be a part of your project directory. This is also consistent with the way a standard Cordova CLI project works.

The Intel XDK Plugin Management tool simplifies finding, adding and managing Apache Cordova plugins in your project. Plugins you add with the Plugin Management tool are stored as a part of your project in your project's plugins directory.

If you have plugin tags included in your intelxdk.config.additions.xml file, your build will fail with an error message similar to the following (Error: Unable to build; intelxdk.config.additions.xml file includes plugin tags, which are no longer supported.):

 Unable to build; intelxdk.config.additions.xml file includes plugin tags, which are no longer supported.

Migrating Plugins from the Additions File

In the Develop Tab, open your project's intelxdk.config.additions.xml file for editing. You can find it in the tree hierarchy on the left-hand side of the Develop tab; it will not be in a folder but at the top level, in the "root" of your project folder. The plugin XML tags in this file begin with intelxdk:plugin.

Migrating Plugins from the Additions File.

In this example, we have two plugins, a plugin named by its plugin ID (cordova-plugin-battery-status) and a plugin located by a URL (https://github.com/cranberrygame/cordova-plugin-game). You must add each plugin you find in the intelxdk.config.additions.xml file to your project using the plugin management system and then delete the references to those plugins in your project's additions file.

It is a good idea to save a copy of your original intelxdk.config.additions.xml file before you delete the plugin tags from it. For example, save it as intelxdk.config.additions.xml.bak. Do this in case you have difficulties with moving your plugins to the plugin management tool in order to keep a reference of the plugins that were in your additions file.

If you do not delete the plugin references in your intelxdk.config.additions.xml file, it will result in problems. Note that plugin tags may be located anywhere in your additions file, they are not guaranteed to be grouped together near the top, as shown in this example. Be sure to find all plugin tags within the additions file, even those buried inside of any platform tags.

To add a plugin using the plugin management tool, click PROJECTS in the top left corner of the Intel XDK UI. This will take you to the Project tab. Then, find the “Plugin Management” section and expand it by clicking on the plus sign (“+”). Finally, click “Add Plugins to this Project” to open the plugin management tool.

Adding a plugin to the plugin management system.

If a Plugin is Specified as a URL in the Additions File

Use the technique below to add a plugin that is specified as a URL in the additions file, via the plugin management tool.

Click on “Third-Party Plugin” and change the Plugin Source radio button to “Git repo.” Copy the URL into the Repo URL field. If your plugin had a commit tag (like the one in the example) or a git ref tag, copy and paste that information into the Git Ref field. Be sure to also include any Plugin Variables that are required by your plugin (not depicted in the example). Finally, make sure you delete the plugin from the intelxdk.config.additions.xml file!

If the Plugin value is a URL.

If a Plugin is NOT Specified as a URL in the Additions File

Use the technique below to add a plugin that is specified as a "plugin ID," using the plugin management tool.

Click on “Third-Party Plugin” and make sure the Plugin Source radio button is set to “npm.” Set Plugin ID to the name of the plugin. If your plugin includes a version tag, like the one in the example, copy and paste it into the Version Number field. Be sure to add any Plugin Variables that are required by your plugin (not depicted in the example). Finally, make sure you delete the plugin from the intelxdk.config.additions.xml file!

If the Plugin value is a not a URL.

For more complete information about compiler optimizations, see our Optimization Notice.