Part III - Creating Ample SDK Plugin

This tutorial provides general information that you need to now in order to create an Ample SDK plugin.

An Ample SDK plugin is something similar to what jQuery plugin is. Except for that in Ample SDK a plugin can extend not only collection object and the main object, but any other DOM object too. A plugin can also contribute a global object, for example XPath plugin adds XPathException, XPathResult and other objects to the global (window) namespace.

• Basic plugin skeleton
• A. Using private variables and functions
• Extending Ample SDK objects
  • B. Extending ample object
  • C. Extending Query class (query result collection)
• D. Guarding plugin API
• E. Contributing global objects
• Signing plugin API

Basic plugin skeleton

Let's take a look at the skeleton of a basic plugin:

(function(){
    // A. Plugin private members
    var pluginPrivateVariable = 1;
    function pluginPrivateFunction(param1, param2) {

    };

    // Plugin public members
    // B. Extending ample object
    ample.extend({
        "pluginAmpleMember": function(param1, param2) {
            // D. Guarding pluging API
            ample.guard(arguments, [
                ["param1Name", String],
                ["param2Name", Boolean, true]
            ]);

            // Plugin member implementation
        }
    });

    // C. Extending Query class (or some other core class)
    ample.extend({
        "pluginQueryMember": function(param1, param2) {
            // D. Guarding pluging API
        }
    }, ample.classes.Query.prototype);
})();

The most important thing too see in this snippet is the self-executing anonymous function wrapping entire plugin code. This is done in order to not contribute plugin-specific implementation code to the global namespace. The other points of interest will be explained below.

A. Using private variables and functions

A plugin might need to use some variables or functions to keep states or routines. A good place to put this code is in the section commented "A. Plugin private members". Note: the this keyword in a private function will point to the global window object.

Extending Ample SDK objects

The common task of a plugin - to extend Ample SDK core objects. A plugin may contribute new members to objects and their prototypes by the means of calling ample.extend() plugin authoring function.

Note: whenever a member is added to Query.prototype object or to the ample object, the later will first get checked if a member with such name already exists. If it does, a warning will be issued then in development version about member rewritten.

B. Extending ample object

A plugin may define a function on ample object. When using ample.extend() plugin authoring function to extend ample it is not necessary to specify the target - when omitted it is assumed to be ample object itself. Note: it is uncommon that one plugin contributes more than one function in this way, so please follow the recommendation. For example Cookie plugin only contributes single cookie function.

C. Extending Query class (query result object)

In Ample SDK it is possible to extend any DOM object with new members. One of the objects of interest in Query - a collection returned from ample.query() function call. When extending DOM objects you will need to extend their prototypes, this is why you see in the skeleton ample.classes.Query.prototype as the target extension object. Please be advised to keep plugin concise and also avoid populating core object prototypes with to many members. See example Form, here the plugin contributes val, submit and other functions.

D. Guarding plugin API

In Ample SDK all APIs are guarded - any call to a core public member gets validated and in case it doesn't match specification - gets rejected with runtime exception and details about the problem. We encourage you to validate API calls in your plugin too with help of ample.guard() plugin authoring function. In the skeleton above pluginAmpleMember function expects one required param1Name argument of type String and one optional param2Name of type Boolean.

Signing plugin API

Signing public members of a plugin when it gets loaded is done automaticaly by the Ample SDK so there is nothing you could or should do about. The procedure ensures that when introspecting ample or Query.prototype members, the ones contributed by a plugin will be marked with "[plugin code]" as opposite to core contributed members signed with "[ample code]".