Hello world plugin example

• Documentation
• Questions or comments?

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

It is where you will do all the action in order to initiate your plugin. The chalenges here is to perform the minimalist task in order to have your plugin waiting for an action. WET plugin is focused on an event base aproach where we trend to not execute a line of script if is not required at that time, that for performance reason.

At line 43-45 // Add your plugin event handler

It is where you will add a bunch of event 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 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 have initiated the plugin

At line 51 $elm.append("Hello World");

The words "Hello World" is added at the end of the content inside the elements

Step 3 - Make it configurable

As most plugins needs settings, the following code sample will show you how to support multiple way on how 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 define the defaults settings for your plugin.

At line 33 settings;

A local variable to hold the setting for the current instance of the plugin.

At line 41 settings = $.extend(

The local variable setting 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 defaults 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 working 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 are not conflicting 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?

Submit an issue on Github

Date modified:

2016-12-06