Client Plugin Example

This guide walks you through how to add a custom plugin to the Weavy client library. The plugin doesn’t really do anything helpful, but in the code below you can see that is demonstrates various ways to work with the client library.

Plugin code

The functionality of the plugin basically consists of adding the CSS class widget-hello-world to the Weavy container element. When it’s finished you get a console log telling you whether setting the class was successful or not. The plugin also sets a property on, and registers a public method directly on the Weavy instance.

(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 Weavy.
    // It adds the class 'widget-hello-world' to the container element.
    // It also demonstrates various ways to work with the client library.
    console.debug("Registering Weavy plugin:", PLUGIN_NAME);
    if (typeof Weavy === 'undefined' || !Weavy.plugins) {
        throw new Error("Weavy 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 Weavy instance
    // {options} is passed to the function, which you also may access via weavy.options.plugins[PLUGIN_NAME]
    Weavy.plugins[PLUGIN_NAME] = function (options) {

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

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

        // Other options
        var weavyOptions = weavy.options; // All global options for the instance
        var pluginOptions = weavy.options.plugins[PLUGIN_NAME]; // Same as options
        
        // Set a property on the instance from options
        weavy.helloText = options.helloText;

        // Register a public method on the instance
        // Avoid prototype methods, since they cannot be disabled
        weavy.helloWorld = function (targetText) {

            // Combine the property and the provided text
            sayHello(weavy.helloText + "-" + targetText);
        };

        // Internal protected method
        function sayHello(classText) {
            if (weavy.nodes.container) {
                // Add weavy-hello-world class to the container element
                $(weavy.nodes.container).addClass("weavy-" + classText);

                // This is the last step in the flow and shows true if everything was successful
                weavy.log("Hello World done:", PLUGIN_NAME, $(weavy.nodes.container).hasClass("weavy-hello-world"));
            }
        }

        // Add a one-time load event listener
        weavy.one("load", function (e) {
            weavy.debug("Hello World oneload:", PLUGIN_NAME);
            weavy.info("Weavy version:", weavy.options.version);

            // Check if this plugin is enabled.
            // Not necessary here, but useful if you reference another plugin instead
            if (weavy.plugins.helloworld) {
                // Call the public method with the exported text as parameter
                weavy.helloWorld(weavy.plugins.helloworld.exportedText);
            }
        });

        // Export the worldText
        return { exportedText: pluginOptions.worldText };

        // END OF EXAMPLE CODE
    }

    // Set any default options here
    Weavy.plugins[PLUGIN_NAME].defaults = {
        helloText: 'hello',
        worldText: 'world'
    };

    // Non-optional dependencies
    // Dependency plugins always run prior to this plugin.
    // Unfound plugins or incorrect dependencies will result in an error.
    // The following will result in a circular reference error.
    //Weavy.plugins[PLUGIN_NAME].dependencies = [
    //    "helloworld"
    //];

})(jQuery);

Loading the plugin

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

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://{weavyurl}/javascript/weavy.js"></script>
<script src="hello-world.js"></script>
<script>var weavy = new Weavy();</script>

Setting plugin options

To configure your plugin you simply pass in any options when initializing the Weavy instance.

var weavy = new Weavy({  
   plugins: {
      helloworld: {
         helloText: 'Hello',
         worldText: 'world!',
      }
   }
});

Try it out

Try out the Hello World Plugin Example by navigating to the page in your host system where Weavy is embedded. If the plugin was loaded correctly you should see the text "Hello World done" being printed to the javascript console.