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

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?

Submit an issue on Github

Date modified:

2016-12-06