Adding and removing plugins

To access Cordova and BlackBerry functionality, you need to add plugins to your project. Plugins represent the layer that connects JavaScript to the native C/C++ layer of the BlackBerry 10 OS. They allow you to access the native functionality of the device (for example, accessing accelerometer data, or using the camera) without the need to code in the device's native language.

When you add a plugin to your project, it is added to your project's plugins/ subfolder and packaged with your app. To keep the size of your app small, add only the plugins that you need.

When you install the BlackBerry 10 WebWorks SDK, the installation includes the BlackBerry and Cordova plugins. You can find them in the plugin/ subfolder of the BlackBerry 10 WebWorks SDK installation folder.

You can create your own plugins or access plugins created by the WebWorks community to access native APIs that are not available through the BlackBerry and Cordova plugins. For more information, see Using custom plugins.

Adding plugins using the SDK web tool

To add a plugin to your project using the BlackBerry 10 WebWorks SDK web tool:

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Navigate to your project and click Plugins.
  3. Enter the ID or URL of the plugin in the Plugin Name or URL field.
  4. Click Add Plugin.

Adding plugins from the command line

Add a plugin

You can use the plugin add command to add a plugin to your project. You can add a plugin by ID, path, or URI.

To add a plugin to your app:

  1. On the command line, navigate to your project folder.
  2. Run the following command:
    webworks plugin add <id> | <path> | <uri> 
For example, the following command adds the BlackBerry Application API to your app.
webworks plugin add com.blackberry.app

Check the table below for parameter details:

Parameter Description
<id>

The unique identifier for the plugin.

<path>

The path to the plugin on your local file system.

<uri>

The remote location for the plugin.

Remove a plugin

You can use the plugin rm command to remove a plugin from your project.

To remove a plugin from your project:

  1. On the command line, navigate to your project folder.
  2. Run the following command:
    webworks plugin rm <id>

Check the table below for parameter details:

Parameters Description
<id>

Specifies the unique identifier for the plugin.

List your installed plugins

To list the plugins you have previously added to your app:

  1. On the command line, navigate to your project folder.
  2. Run the following command:
    webworks plugin ls 

Standard WebWorks and Cordova plugins

The following plugins are installed with the BlackBerry 10 WebWorks SDK.

BlackBerry WebWorks plugins

Plugin ID Name Description
com.blackberry.app Application Provides basic app support.
com.blackberry.bbm.platform BBM Platform Lets you access the social features and functionality of BBM.

Required permission: bbm_connect

com.blackberry.connection Connection Lets you access the cellular and Wi-Fi connection information for the BlackBerry device.
com.blackberry.display Display Allows you to control whether the screen dims while the app is in the foreground.
com.blackberry.identity Identity Provides information about the user's identity and accounts.

Required permission: read_device_identitying_information

com.blackberry.ui.input Input Lets your app respond to user events on a touch-enabled keyboard. This is a new input event layer for use with touch-enabled keyboards beginning with BlackBerry 10.3. It is unrelated to DOM mouse events or HTML5 touch events on the screen.
com.blackberry.invoke Invoke Lets your app invoke and interact with other apps on the device.
com.blackberry.invoke.card Card Lets your app invoke a screen of another app on the device.
com.blackberry.invoked Invoked Lets your app be invoked by other apps on the device.
com.blackberry.io IO Provides access to the unsandboxed file systems.
com.blackberry.io.filetransfer File Transfer Lets your app upload and download files to/from a remote server.
com.blackberry.notification Notification Lets your app to provide notifications to the user.

Required permission: post_notification

com.blackberry.payment Payment Lets you sell digital goods in your app.
com.blackberry.pim.calendar Calendar Lets you access and manage entries in the Calendar application.

Required permission: access_pimdomain_calendars

com.blackberry.pim.contacts Contacts Lets you create and find contacts.

Required permission: access_pimdomain_contacts

com.blackberry.push PushPayload

PushService

Lets you access the BlackBerry push architecture to receive push content in your app.
Required permissions:
  • sys_use_consumer_push
  • run_when_backgrounded
com.blackberry.screenshot Screenshot Lets you to capture an image of the device screen.
com.blackberry.sensors Sensors Lets you get access to system level sensors and attributes of the BlackBerry device.
com.blackberry.system System Lets you access system level functions and attributes of the BlackBerry device.
com.blackberry.ui.contextmenu Context Menu Lets you control whether context menus are enabled, listen to events, add items to appear based on the context, and set the theme of the context menu.
com.blackberry.ui.cover Window Covers Lets you modify the app's window cover, which is displayed when the app is in thumbnail mode.
com.blackberry.ui.dialog Dialog Lets you manipulate system dialog boxes.
com.blackberry.ui.toast Toast Lets you display system toasts in your app.
com.blackberry.user.identity User Identity Lets you access the user's personal information stored in the identity provider's account system, and provide user authentication/authorization to access the identity provider's apps and services.

Cordova plugins installed with BlackBerry WebWorks SDK

Plugin ID Name Description
org.apache.cordova.battery-status Event (Battery Status) Provides an implementation of an old version of the Battery Status Events API.
org.apache.cordova.camera Camera Provides access to the device's default camera application.
org.apache.cordova.contacts Contacts Provides access to the device's contact database.
org.apache.cordova.device Device Describes the device's hardware and software.
org.apache.cordova.device-motion Device Motion (Accelerometer) Captures device motion in the x, y, and z directions.
org.apache.cordova.device-orientation Device Orientation (Compass) Obtains the direction that the device is pointing.
org.apache.cordova.dialogs Notification (Dialogs) Lets your app create visual, audible, and tactile notifications.
org.apache.cordova.file File System Provides the functionality to read, write, and navigate file system hierarchies.
org.apache.cordova.file-transfer File transfer Lets you upload and download files.
org.apache.cordova.geolocation Geolocation Provides access to location information based on the device's GPS sensor or inferred from network signals.
org.apache.cordova.inappbrowser InAppBrowser Provides a browser view that displays when calling window.open(), or when opening a link formed as <a target="_blank">.
org.apache.cordova.media Media Lets your app play back audio and video files on a device.
org.apache.cordova.media-capture Media Provides access to the device's audio, image, and video capture capabilities.
org.apache.cordova.network-information Network Information (Connection) Provides information about the device's cellular and Wi-Fi connection.
org.apache.cordova.splashscreen Splashscreen Lets your app hide and show the splash screen.
org.apache.cordova.vibration Notification (Vibration) Lets your app create visual, audible, and tactile notifications.

Last modified: 2014-09-29



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus