In addition to the Apache Cordova CLI utility, you can use the plugman utility in order to add or remove plugin(s) to/from your Apache Cordova projects. However, it's worth mentioning that plugman is a lower-level tool that you can use if your Apache Cordova application follows a platform-centered workflow and not a cross-platform workflow. If your application follows a cross-platform workflow, then Apache Cordova CLI should be your choice.

If you want your application to run on different mobile platforms (which is a common use case if you want to use Apache Cordova), it's recommend that you follow a cross-platform workflow. Use a platform-centered workflow if you want to develop your Apache Cordova application on a single platform and modify your application using the platform-specific SDK.

Besides adding and removing plugins to/from a platform-centered workflow, the Cordova projects plugman can also be used:

In this section, we will use the plugman utility to create the basic scaffolding of our custom SMS plugin. In order to install plugman, you need to make sure that Node.js is installed on your operating system. Then, to install plugman, execute the following command:

> npm install -g plugman

After installing plugman, we can start generating our initial custom plugin artifacts using the plugman create command as follows:

> plugman create --name sms --plugin_id  com.jsmobile.plugins.sms --plugin_version 0.0.1

It is important to note the following parameters:

The following are two parameters that the plugman create command can accept as well:

After executing the previous command, we will have initial artifacts for our custom plugin. As we will be supporting multiple platforms, we can use the plugman platform add command. The following two commands add the Android and iOS platforms to our custom plugin:

> plugman platform add --platform_name android
> plugman platform add --platform_name ios

In order to run the plugman platform add command, we need to run it from the plugin directory. Unfortunately, for Windows Phone 8 platform support, we need to add it manually later to our plugin.

Now, let's check the initial scaffolding of our custom plugin code. The following screenshot shows the hierarchy of our initial plugin code:

Hierarchy of our initial plugin code

As shown in the preceding screenshot, there is one file and two parent directories. They are as follows:

We will need to edit these generated files (and maybe, refactor and add new implementation files) in order to implement our custom SMS plugin. The details of our SMS plugin definition, JavaScript interface, and native implementations will be illustrated in detail in the upcoming sections.

First of all, we need to define our plugin structure. In order to do so, we need to define our plugin in the plugin.xml file. The following code listing shows our plugin.xml code:

<?xml version='1.0' encoding='utf-8'?>
<plugin id="com.jsmobile.plugins.sms" version="0.0.1"     
    xmlns="http://apache.org/cordova/ns/plugins/1.0" 
    xmlns:android="http://schemas.android.com/apk/res/android">

    <name>sms</name>
    <description>A plugin for sending sms messages</description>
    <license>Apache 2.0</license>
    <keywords>cordova,plugins,sms</keywords>

    <js-module name="sms" src="www/sms.js">
        <clobbers target="window.sms" />
    </js-module>

    <platform name="android">
        <config-file parent="/*" target="res/xml/config.xml">
            <feature name="Sms">
                <param name="android-package" value="com.jsmobile.plugins.sms.Sms" />
            </feature>
        </config-file>

        <config-file target="AndroidManifest.xml" parent="/manifest">
            <uses-permission android:name="android.permission.SEND_SMS" />
        </config-file>

        <source-file src="src/android/Sms.java" 
                     target-dir="src/com/jsmobile/plugins/sms" />
    </platform>

    <platform name="ios">
        <config-file parent="/*" target="config.xml">
            <feature name="Sms">
                <param name="ios-package" value="Sms" />
            </feature>
        </config-file>

        <source-file src="src/ios/Sms.h" />
        <source-file src="src/ios/Sms.m" />

        <framework src="MessageUI.framework" weak="true" />
    </platform>

    <platform name="wp8">
        <config-file target="config.xml" parent="/*">
            <feature name="Sms">
                <param name="wp-package" value="Sms" />
            </feature>
        </config-file>

        <source-file src="src/wp8/Sms.cs" />
    </platform>

</plugin>

The plugin.xml file defines the plugin structure and contains a top-level element <plugin> , which contains the following attributes:

The <plugin> element contains the following subelements:

A <plugin> element can contain one or more <platform> element(s). A <platform> element specifies a platform-specific plugin's configuration. It has mainly one attribute name that specifies the platform name (android, ios, wp8, bb10, wp7, and so on). The <platform> element can have the following sub-elements:

Given this explanation for the <platform> element and getting back to our plugin.xml file, you will notice that we have the following three <platform> elements:

This is all we need to know in order to understand the structure of our custom plugin; however, there are many more attributes and elements that are not mentioned here, as we didn't use them in our example. In order to get the complete list of attributes and elements of plugin.xml, you can check out the plugin specification page in the Apache Cordova documentation at http://cordova.apache.org/docs/en/3.4.0/plugin_ref_spec.md.html#Plugin%20Specification.

As indicated in the plugin definition file (plugin.xml), our plugin's JavaScript interface is defined in sms.js, which is located under the www directory. The following code snippet shows the sms.js file content:

var smsExport = {};

smsExport.sendMessage = function(messageInfo, successCallback, errorCallback) {
    if (messageInfo == null || typeof messageInfo !== 'object') { 
        if (errorCallback) {
            errorCallback({
                code: "INVALID_INPUT",
                message: "Invalid Input"
            });
        }
       
        return;
    }
           
    var phoneNumber = messageInfo.phoneNumber;
    var textMessage = messageInfo.textMessage || "Default Text from SMS plugin";
           
    if (! phoneNumber) {
        console.log("Missing Phone Number");
    
        if (errorCallback) {
            errorCallback({
                code: "MISSING_PHONE_NUMBER",
                message: "Missing Phone number"
            });
        }
           
        return;
    }
           
    cordova.exec(successCallback, errorCallback, "Sms", "sendMessage", [phoneNumber, textMessage]);
};

module.exports = smsExport;

The smsExport object contains a single method, sendMessage(messageInfo, successCallback, errorCallback). In the sendMessage method, phoneNumber and textMessage are extracted from the messageInfo object. If a phone number is not specified by the user, then errorCallback will be called with a JSON error object, which has a code attribute set to "MISSING_PHONE_NUMBER" and a message attribute set to "Missing Phone number". After passing this validation, a call is performed to the cordova.exec() API in order to call the native code (whether it is Android, iOS, Windows Phone 8, or any other supported platform) from Apache Cordova JavaScript.

It is important to note that the cordova.exec(successCallback, errorCallback, "service", "action", [args]) API has the following parameters:

Finally, the smsExport object is exported using module.exports. Do not forget that our JavaScript module is mapped to window.sms using the <clobbers target="window.sms" /> element inside <js-module src="www/sms.js"> element, which we discussed in the plugin.xml file. This means that in order to call the sendMessage method of the smsExport object from our plugin-client application, we use the sms.sendMessage() method.

In the upcoming sections, we will explore the implementation of our custom Cordova plugin in Android, iOS, and Windows Phone 8 platforms.