Weavy widget plugins

You can create your own plugins. This way you can include code, events and communication into the Weavy Widget. This is a good way to package code that extends the widget. You can specify options or enable/disable plugins directly in the widget options.

Loading plugins

You just have to load the javascript file of your plugin to get it registered. Make sure to load any custom plugins after widget.js is loaded and before you make a new WeavyWidget() instance.

Default plugins

There is currently one built-in plugin called position. It’s for handling positioning of the widget dock. You may disable this plugin or override it with your own custom plugin.

Options and Widget API

While you get possibilities to use built in options you may also use anything exposed in the Widget API in your plugin.

Plugin template

This is the minimal structure you need in your plugin for it to be registered and executed. Have a look at the hello world example below to get more explanation of the various parts of the plugin.

(function ($) {
    // Set you plugin name here. This name will be used for registration and options etc.
    var PLUGIN_NAME = "myplugin";

    console.debug("Registering WeavyWidget plugin:", PLUGIN_NAME);

    if (typeof WeavyWidget === 'undefined' || !WeavyWidget.plugins) {
        throw new Error("WeavyWidget must be loaded before registering plugin: " + PLUGIN_NAME);
    }

    WeavyWidget.plugins[PLUGIN_NAME] = function (options) {
        var widget = this;

        // MY CUSTOM CODE
        // ...
    };

    // Default plugin options
    WeavyWidget.plugins[PLUGIN_NAME].defaults = {
    };

})(jQuery);

Hello World Plugin Example

This is a maximal example of a plugin setting the widget-hello-world class to the widget container. It uses various methods and events just to show an example of what you can do. When it’s finished you get a console log telling you whether setting the class was successful or not.

(function ($) {
    // Set you plugin name here. This name will be used for registration and options etc.
    var PLUGIN_NAME = "helloworld";

    // This is an example hello-world plugin for the Weavy widget.
    // It adds the class 'widget-hello-world' to the widget container.
    // It demonstrates various ways to work with the widget.

    console.debug("Registering WeavyWidget plugin:", PLUGIN_NAME);

    if (typeof WeavyWidget === 'undefined' || !WeavyWidget.plugins) {
        throw new Error("WeavyWidget must be loaded before registering plugin: " + PLUGIN_NAME);
    }

    // Register the plugin the same way you would define a prototype
    // {this} is passed as a reference to the widget instance
    // {options} is passed to the function, which you also may access via this.options
    WeavyWidget.plugins[PLUGIN_NAME] = function (options) {

        // Best practice is to use 'widget' instead of 'this' to avoid confusion
        var widget = this;

        // EXAMPLE CODE BELOW, REPLACE IT WITH ANY CUSTOM CODE

        // Set a common widget property from options
        widget.helloWorldText = options.hello_world;

        // Register a public prototype method on the widget
        WeavyWidget.prototype.helloWorld = function () {
            if (widget.container) {
                sayHello();
            }
        };

        // Internal protected method
        function sayHello() {
            // Add weavy-hello-world class to the main widget container
            $(widget.container).addClass("weavy-" + widget.helloWorldText);
        }

        // Add a one-time load event listener
        widget.one("load", function (e) {
            console.debug("WeavyWidget plugin oneload:", PLUGIN_NAME);
            console.info("WeavyWidget version:", widget.version);
            console.info("Weavy version:", widget.options.version);
            widget.helloWorld();
        });

        // END OF EXAMPLE CODE
    }

    // Set any default options here
    WeavyWidget.plugins[PLUGIN_NAME].defaults = {
        hello_world: 'hello-world'
    };

})(jQuery);