Hello world plugin example
A quick tutorial on how you can create your own WET plugin.
Step 1 - Use a barebone plugin container
Use a barbone plugin container like:
/**
* @title WET-BOEW Barebone plugin container
* @overview Plugin contained to show an example of how to create your custom WET plugin
* @license wet-boew.github.io/wet-boew/License-en.html / wet-boew.github.io/wet-boew/Licence-fr.html
* @author @duboisp
*/
( function( $, window, wb ) {
"use strict";
/*
* Variable and function definitions.
* These are global to the plugin - meaning that they will be initialized once per page,
* not once per instance of plugin on the page. So, this is a good place to define
* variables that are common to all instances of the plugin on a page.
*/
var componentName = "wb-barebone",
selector = "." + componentName,
initEvent = "wb-init" + selector,
$document = wb.doc,
/**
* @method init
* @param {jQuery Event} event Event that triggered the function call
*/
init = function( event ) {
// Start initialization
// returns DOM object = proceed with init
// returns undefined = do not proceed with init (e.g., already initialized)
var elm = wb.init( event, componentName, selector ),
$elm;
if ( elm ) {
$elm = $( elm );
// ... Do the plugin initialisation
// Identify that initialization has completed
wb.ready( $elm, componentName );
}
};
// Add your plugin event handler
$document.on( "name.of.your.event", selector, function() {
//... your code here ...
} );
// Bind the init event of the plugin
$document.on( "timerpoke.wb " + initEvent, selector, init );
// Add the timer poke to initialize the plugin
wb.add( selector );
} )( jQuery, window, wb );
- At line 16
var componentName = "wb-barebone",
- The value of componentName define the name of your plugin and the class name to use in order to initiate it
- At line 36
// ... Do the plugin initialisation
- Is where you will do all the actions in order to initiate your plugin. The challenge here is to perform the minimal amount of tasks in order to have your plugin waiting for an action. WET plugins are focused on an event base aproach where we trend to not execute a line of code if is not required at that time for performance reasons.
- At line 43-45
// Add your plugin event handler
- Is where you will add a number of events that your plugin will deal with. You can trigger your own event by using the jQuery instance of an element, then call the function trigger with your custom event name in the first parameter followed by an object if you want to transfers some data. Like
$elm.trigger( "name.of.your.event", mydata );
. The mydata parameter is optional.
Step 2 - Add your javascript code
Here a plugin sample that append the word "Hello World" to any element that contain the class wb-helloworld
on the page the plugin is loaded.
/**
* @title WET-BOEW Hello world plugin
* @overview Plugin contained to show an example of how to create your custom WET plugin
* @license wet-boew.github.io/wet-boew/License-en.html / wet-boew.github.io/wet-boew/Licence-fr.html
* @author @duboisp
*/
( function( $, window, wb ) {
"use strict";
/*
* Variable and function definitions.
* These are global to the plugin - meaning that they will be initialized once per page,
* not once per instance of plugin on the page. So, this is a good place to define
* variables that are common to all instances of the plugin on a page.
*/
var componentName = "wb-helloworld",
selector = "." + componentName,
initEvent = "wb-init" + selector,
$document = wb.doc,
/**
* @method init
* @param {jQuery Event} event Event that triggered the function call
*/
init = function( event ) {
// Start initialization
// returns DOM object = proceed with init
// returns undefined = do not proceed with init (e.g., already initialized)
var elm = wb.init( event, componentName, selector ),
$elm;
if ( elm ) {
$elm = $( elm );
// ... Do the plugin initialisation
// Call my custom event
$elm.trigger( "name.of.your.event" );
// Identify that initialization has completed
wb.ready( $elm, componentName );
}
};
// Add your plugin event handler
$document.on( "name.of.your.event", selector, function( event ) {
var elm = event.currentTarget,
$elm = $( elm );
$elm.append( "Hello World" );
} );
// Bind the init event of the plugin
$document.on( "timerpoke.wb " + initEvent, selector, init );
// Add the timer poke to initialize the plugin
wb.add( selector );
} )( jQuery, window, wb );
- At line 16
var componentName = "wb-helloworld",
- The plugin is named wb-helloworld.
- At line 39
$elm.trigger( "name.of.your.event" );
- The event "name.of.your.event" is fired on the DOM element that has initiated the plugin
- At line 51
$elm.append("Hello World");
- The words "Hello World" are added at the end of the content inside the element
Step 3 - Make it configurable
As most plugins needs settings, the following code sample will show you how to support multiple ways in which an editor and developer will be able to configure your plugin.
/**
* @title WET-BOEW Hello world plugin
* @overview Plugin contained to show an example of how to create your custom WET plugin
* @license wet-boew.github.io/wet-boew/License-en.html / wet-boew.github.io/wet-boew/Licence-fr.html
* @author @duboisp
*/
( function( $, window, wb ) {
"use strict";
/*
* Variable and function definitions.
* These are global to the plugin - meaning that they will be initialized once per page,
* not once per instance of plugin on the page. So, this is a good place to define
* variables that are common to all instances of the plugin on a page.
*/
var componentName = "wb-helloworld",
selector = "." + componentName,
initEvent = "wb-init" + selector,
$document = wb.doc,
defaults = {},
/**
* @method init
* @param {jQuery Event} event Event that triggered the function call
*/
init = function( event ) {
// Start initialization
// returns DOM object = proceed with init
// returns undefined = do not proceed with init (e.g., already initialized)
var elm = wb.init( event, componentName, selector ),
$elm,
settings;
if ( elm ) {
$elm = $( elm );
// ... Do the plugin initialisation
// Get the plugin JSON configuration set on attribute data-wb-helloworld
settings = $.extend(
true,
{},
defaults,
window[ componentName ],
wb.getData( $elm, componentName )
);
// Call my custom event
$elm.trigger( "name.of.your.event", settings );
// Identify that initialization has completed
wb.ready( $elm, componentName );
}
};
// Add your plugin event handler
$document.on( "name.of.your.event", selector, function( event, data ) {
var elm = event.currentTarget,
$elm = $( elm );
$elm.append( "Hello World" );
if ( data && data.domore ) {
$elm.prepend( "Do more" );
}
} );
// Bind the init event of the plugin
$document.on( "timerpoke.wb " + initEvent, selector, init );
// Add the timer poke to initialize the plugin
wb.add( selector );
} )( jQuery, window, wb );
- At line 20
defaults = {}
- JSON object that defines the default settings for your plugin.
- At line 33
settings;
- A local variable to hold the settings for the current instance of the plugin.
- At line 41
settings = $.extend(
- The local variable settings will have a cloned copy of all the combined settings.
- At line 42
true,
- It will perform a deep copy
- At line 43
{},
- Start extending with an empty new object.
- At line 44
defaults,
- Apply the default settings.
- At line 45
window[ componentName ],
- Retreive setting directly set via javascript harde coded in the page for example like:
window['wb-helloworld'] = {};
- At line 46
wb.getData( $elm, componentName )
- Retreive and parse into a JSON object the setting set through the attribute
data-wb-helloworld
- At line 50
$elm.trigger( "name.of.your.event", settings );
- Now, the second parameter contains the instance settings that will be used by the event.
- At line 58
function( event, data ) {
- Add a second parameter, data, in order to receive data when the event is trigger.
- At line 64-66
if ( data && data.domore ) {
- If a data has been set and the property domore is true or is positive or contain something then prepend the words "Do more" to the element
Step 4 - Test it out
Example 1
Example 2 (inside a span)
Example 3 with configuration
<p class="wb-helloworld">Example 1</p>
<p>Example 2 (<span class="wb-helloworld">inside a span</span>)</p>
<p class="wb-helloworld" data-wb-helloworld='{ "domore": true }'>Example 3 with configuration</p>
Please note to have your plugin work with WET you will needs to add your script after WET (wet-boew.js) in the HTML.
Going beyond
The non-documented WET core includes a lot of utilities function re-used by several plugins.
Such as the function wb.getId()
from which we can get an unique id that does not conflict with any other elements. Or the array defined at wb.drawColours
that is about a color sequence to use in order to maintain a good contrast, as used by the chart and graph and the geomap. Take a look at the WET core source code to find others useful function.
The loading of third party plugin is done by using Modernizer. You can explorer other plugin that implement is like the tables plugins.
Question or need help?
- Date modified: