Verify that your custom plugin contains a plugin.xml file that meets the requirements of the Apache Cordova Plugman specification.

This procedure shows how to create the most basic markup of plugin.xml. Depending on the plugin, you might need to make a number of additional declarations in the markup, modify the code of your JAVA, JS and Objective-C files or change your target Apache Cordova version. For more information, see Plugin.xml Manifest Format and Requirements for Custom Plugins.

Prerequisites

  • Verify that you have saved the custom plugin on your disk.
  • If archived, verify that you have extracted the custom plugin files.
  • (Optional) Verify that you have modified the directory structure to meet the recommendations of the Apache Cordova Plugman specification.
  • Verify that the custom plugin contains plugin.xml. If needed, use a text or a code editor to create an empty plugin.xml in the root of the custom plugin.

Procedure

  1. Open plugin.xml in a text or a code editor.
  2. In the markup, verify that the following line is present at the top.

    <?xml version="1.0" encoding="UTF-8"?>
    
  3. Declare the plugin, including namespaces, id and version.

    <?xml version="1.0" encoding="UTF-8"?>
    <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
        xmlns:android="http://schemas.android.com/apk/res/android"
    
        <!-- Sets the ID for the custom plugin. It consists of 
            the package declaration made in the JAVA file
            and the plugin name. For example, com.custom.plugin.CustomCordovaPlugin. -->
    
        id="com.custom.plugin.CustomCordovaPlugin"
        version="1.0.0">
    </plugin>
    
  4. (Optional) Declare the name of the plugin.

    <plugin xmlns...
        ...
        version="1.0.0">
    
        <!-- Sets the name for the custom plugin. -->
    
        <name>CustomCordovaPlugin</name>
    
    </plugin>
    
  5. Declare the JS file that contains the plugin functionality.

    • Declare the JavaScript script file as an asset. The asset will be copied to the specified target folder in your application package. You need to add references to the plugin file in your code.

      • If the plugin targets both Android and iOS, declare the asset as non-platform specific.

        <plugin xmlins...
            ...
            </name>
        
            <!-- Declares the plugin asset as non-platform specific. Typically, this is the JS file
                that contains the plugin functionality and is located in the www directory.
                For example, CustomCordovaPlugin.js. -->
        
            <asset src="www/CustomCordovaPlugin.js" target="CustomCordovaPlugin.js" />
        
            <!-- The target file path declared in the asset element is relative to the root directory
                of the installed app. You need to add a script include for the target in index.html. -->
        
        </plugin>
        
      • If the plugin targets only Android or iOS, declare the asset as platform-specific.

        <plugin xmlins...
            ...
            </name>
        
            <!-- Declares the plugin asset as platform-specific. Typically, this is the JS file
                that contains the plugin functionality and is located in the www directory.
                For example, CustomCordovaPlugin.js. -->
        
            <!-- ios -->
            <platform name="ios">       
                <asset src="www/CustomCordovaPlugin.js" target="CustomCordovaPlugin.js" />
                ...
            </platform>
        
            <!-- The target file path declared in the asset element is relative to the root directory
                of the installed app. You need to add a script include for the target in index.html. -->
        
        </plugin>
        
    • Declare the script file as a JavaScript module. You do not need to add <script> references to the script file in your code. The JavaScript file must be in the CommonJS module format.

      • If the plugin targets both Android and iOS, declare the JavaScript module as non-platform specific.

        <plugin xmlins...
            ...
            </name>
        
            <!-- Declares the plugin script file as a non-platform specific JavaScript module. 
                Typically, this is the JS file that contains the plugin functionality
                and is located in the www directory and is in the CommonJS module format.
                For example, CustomCordovaPlugin.js. -->
        
            <js-module src="www/CustomCordovaPlugin.js" name="CustomCordovaPlugin">
                <clobbers target="custom.cordovaPlugin" />
            </js-module>
        
            <!-- You do not need to add a script include for the target in index.html.
                To access the plugin functionality with `window.custom.cordovaPlugin`,
                declare the <clobbers> element.
                To access the plugin functionality with `cordova.require.CustomCordovaPlugin`,
                do not declare the <clobbers> element. -->
        
        </plugin>
        
      • If the plugin targets only Android or iOS, declare the JavaScript module as platform-specific.

        <plugin xmlins...
            ...
            </name>
        
            <!-- Declares the plugin script file as a platform-specific JavaScript module.
                Typically, this is the JS file that contains the plugin functionality
                and is located in the www directory and is in the CommonJS module format.
                For example, CustomCordovaPlugin.js. -->
        
            <!-- ios -->
            <platform name="ios">       
                <js-module src="www/CustomCordovaPlugin.js" name="CustomCordovaPlugin">
                    <clobbers target="custom.cordovaPlugin" />
                </js-module>
                ...
            </platform>
        
            <!-- You do not need to add a script include for the target in index.html.
                To access the plugin functionality with `window.custom.cordovaPlugin`,
                declare the <clobbers> element.
                To access the plugin functionality with `cordova.require.CustomCordovaPlugin`,
                do not declare the <clobbers> element. -->
        
        </plugin>
        
  6. Declare the supported mobile platforms.

    <plugin xmlins...
        ...
    
        <!-- Android -->
        <platform name="android">
    
            <!--  Sets the changes that need to be made to AndroidManifest.xml
                    in the selected parent element. For separate parents, make sure
                    to use separate <config-file> elements with the proper parent.
                    These changes are applied by AppBuilder during the build process.-->
    
            <config-file target="AndroidManifest.xml" parent="/manifest/application">
                <activity android:name="com.custom.plugin.CustomCordovaPlugin"
                    android:label="@string/app_name">
                    <intent-filter>
                    </intent-filter>
                </activity>
            </config-file>
    
            <!--  Sets the changes that need to be made to config.xml for Android
                    in the selected parent element. For separate parents, make sure
                    to use separate <config-file> elements with the proper parent.
                    These changes are applied by AppBuilder during the build process. -->
    
            <!-- If your app targets Apache Cordova 2.x,
                    use the following block. -->        
            <config-file target="res/xml/config.xml" parent="plugins"> 
                <plugin name="Custom Cordova Plugin"
                    value="com.custom.plugin.CustomCordovaPlugin"/>
            </config-file>        
    
            <!-- If your app targets Apache Cordova 3.x,
                    use the following block. -->
            <config-file target="res/xml/config.xml" parent="widget">
                <feature name="CustomCordovaPlugin">
                    <param name="android-package" value="com.custom.plugin.CustomCordovaPlugin" />
                </feature>
            </config-file>
    
            <!-- Declares the source JAVA file that contains the plugin functionality for Android. 
                    For example, CustomCordovaPlugin.java. -->
    
            <source-file src="src/android/com/custom/plugin/CustomCordovaPlugin.java" 
                    target-dir="src/com/custom/plugin"/> 
    
        </platform>
    
        <!-- ios -->
        <platform name="ios">
    
            <!--  Sets the changes that need to be made to config.xml for iOS
                    in the selected parent element. For separate parents, make sure
                    to use separate <config-file> elements with the proper parent.
                    These changes are applied by AppBuilder during the build process. -->
    
            <!-- If your app targets Apache Cordova 2.x,
                    use the following block. -->        
            <config-file target="res/xml/config.xml" parent="plugins"> 
                <plugin name="Custom Cordova Plugin"
                    value="com.custom.plugin.CustomCordovaPlugin"/>
            </config-file>        
    
            <!-- If your app targets Apache Cordova 3.x,
                    use the following block. -->
            <config-file target="res/xml/config.xml" parent="widget">
                <feature name="CustomCordovaPlugin">
                    <param name="ios-package" value="com.custom.plugin.CustomCordovaPlugin" />
                </feature>
            </config-file>
    
            <!-- Sets the header H file. You need to declare 
                    resource XLIB and BUNDLE files, if any, within separate <resource-file /> elements. -->
    
            <header-file src="src/ios/CustomCordovaPlugin.h" /> 
    
            <!-- Sets the source M file that contains the plugin functionality for iOS. -->
    
            <source-file src="src/ios/CustomCordovaPlugin.m" /> 
    
        </platform>
    
    </plugin>
    
  7. Save all changes.

Example

Plugin.xml for a non-platform specific custom plugin

The custom plugin named Custom Cordova Plugin targets Apache Cordova 3.0.0 and both iOS and Android. The package declaration for the plugin is com.custom.plugin.

If you declare the plugin script in an <asset> element, the valid plugin.xml file for the plugin contains the following markup.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
        xmlns:android="http://schemas.android.com/apk/res/android"
        id="com.custom.plugin.CustomCordovaPlugin"
        version="1.0.0">

    <name>CustomCordovaPlugin</name>

    <asset src="www/CustomCordovaPlugin.js" target="CustomCordovaPlugin.js" />

    <!-- Android -->
    <platform name="android">
        <config-file target="AndroidManifest.xml" parent="/manifest/application">
            <activity android:name="com.custom.plugin.CustomCordovaPlugin"
                      android:label="@string/app_name">
                <intent-filter></intent-filter>
            </activity>
        </config-file>

        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="android-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <source-file src="src/android/com/custom/plugin/CustomCordovaPlugin.java"
            target-dir="src/com/custom/plugin"/>
    </platform>

    <!-- ios -->
    <platform name="ios">
        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="ios-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <header-file src="src/ios/CustomCordovaPlugin.h" />
        <source-file src="src/ios/CustomCordovaPlugin.m" />
    </platform>
</plugin>

If you declare the plugin script in a <js-module> element, the valid plugin.xml file for the plugin contains the following markup.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
        xmlns:android="http://schemas.android.com/apk/res/android"
        id="com.custom.plugin.CustomCordovaPlugin"
        version="1.0.0">

    <name>CustomCordovaPlugin</name>

    <js-module src="www/CustomCordovaPlugin.js" name="CustomCordovaPlugin">
        <clobbers target="custom.cordovaPlugin" />
    </js-module>

    <!-- Android -->
    <platform name="android">
        <config-file target="AndroidManifest.xml" parent="/manifest/application">
            <activity android:name="com.custom.plugin.CustomCordovaPlugin"
                      android:label="@string/app_name">
                <intent-filter></intent-filter>
            </activity>
        </config-file>

        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="android-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <source-file src="src/android/com/custom/plugin/CustomCordovaPlugin.java"
            target-dir="src/com/custom/plugin"/>
    </platform>

    <!-- ios -->
    <platform name="ios">
        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="ios-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <header-file src="src/ios/CustomCordovaPlugin.h" />
        <source-file src="src/ios/CustomCordovaPlugin.m" />
    </platform>
</plugin>

Plugin.xml for a platform-specific custom plugin

The custom plugin named Custom Cordova Plugin targets Apache Cordova 3.0.0 and iOS. The package declaration for the plugin is com.custom.plugin.

If you declare the plugin script in an <asset> element, the valid plugin.xml file for the plugin contains the following markup.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
        id="com.custom.plugin.CustomCordovaPlugin"
        version="1.0.0">

    <name>CustomCordovaPlugin</name>

    <!-- ios -->
    <platform name="ios">

        <asset src="www/CustomCordovaPlugin.js" target="CustomCordovaPlugin.js" />

        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="ios-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <header-file src="src/ios/CustomCordovaPlugin.h" />
        <source-file src="src/ios/CustomCordovaPlugin.m" />
    </platform>
</plugin>

If you declare the plugin script in a <js-module> element, the valid plugin.xml file for the plugin contains the following markup.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
        id="com.custom.plugin.CustomCordovaPlugin"
        version="1.0.0">

    <name>CustomCordovaPlugin</name>

    <!-- ios -->
    <platform name="ios">

        <js-module src="www/CustomCordovaPlugin.js" name="CustomCordovaPlugin">
            <clobbers target="custom.cordovaPlugin" />
        </js-module>

        <config-file target="res/xml/config.xml" parent="widget">
            <feature name="CustomCordovaPlugin">
                <param name="ios-package" value="com.custom.plugin.CustomCordovaPlugin" />
            </feature>
        </config-file>

        <header-file src="src/ios/CustomCordovaPlugin.h" />
        <source-file src="src/ios/CustomCordovaPlugin.m" />
    </platform>
</plugin>

Next Steps

Archive the folder that contains the custom plugin and import it into AppBuilder.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.