---
{
	"title": "Hello world plugin example",
	"language": "en",
	"category": "Other",
	"description": "A quick tutorial on how you can create your own WET plugin.",
	"tag": "helloworld",
	"parentdir": "helloworld",
	"altLangPrefix": "helloworld",
	"js": ["demo/helloworld"],
	"dateModified": "2016-12-06"
}
---

<p>A quick tutorial on how you can create your own WET plugin.</p>

<div class="wb-prettify all-pre linenums"></div>

<h2>Step 1 - Use a barebone plugin container</h2>

<p>Use a barbone plugin container like:</p>

<pre><code>/**
 * @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 ) {
&quot;use strict&quot;;

/*
 * 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.
 */
<strong>var componentName = &quot;wb-barebone&quot;,</strong>
	selector = &quot;.&quot; + componentName,
	initEvent = &quot;wb-init&quot; + 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 );

			<strong>// ... Do the plugin initialisation</strong>

			// Identify that initialization has completed
			wb.ready( $elm, componentName );
		}
	};

<strong>// Add your plugin event handler</strong>
$document.on( &quot;name.of.your.event&quot;, selector, function() {
	<strong>//... your code here ...</strong>
} );

// Bind the init event of the plugin
$document.on( &quot;timerpoke.wb &quot; + initEvent, selector, init );

// Add the timer poke to initialize the plugin
wb.add( selector );

} )( jQuery, window, wb );</code></pre>

<dl>
	<dt>At line 16 <code>var componentName = &quot;wb-barebone&quot;,</code></dt>
	<dd>The value of <var>componentName</var> define the name of your plugin and the class name to use in order to initiate it</dd>

	<dt>At line 36 <code>// ... Do the plugin initialisation</code></dt>
	<dd>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.</dd>

	<dt>At line 43-45 <code>// Add your plugin event handler</code></dt>
	<dd>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 <code>$elm.trigger( "name.of.your.event", mydata );</code>. The mydata parameter is optional.</dd>
</dl>

<h2>Step 2 - Add your javascript code</h2>

<p>Here a plugin sample that append the word "Hello World" to any element that contain the class <code>wb-helloworld</code> on the page the plugin is loaded.</p>

<pre><code>/**
 * @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 ) {
&quot;use strict&quot;;

/*
 * 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.
 */
<strong>var componentName = &quot;wb-helloworld&quot;,</strong>
	selector = &quot;.&quot; + componentName,
	initEvent = &quot;wb-init&quot; + 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
			<strong>$elm.trigger( &quot;name.of.your.event&quot; );</strong>

			// Identify that initialization has completed
			wb.ready( $elm, componentName );
		}
	};

// Add your plugin event handler
$document.on( &quot;name.of.your.event&quot;, selector, function( event ) {
	var elm = event.currentTarget,
		$elm = $( elm );

	<strong>$elm.append( &quot;Hello World&quot; );</strong>

} );

// Bind the init event of the plugin
$document.on( &quot;timerpoke.wb &quot; + initEvent, selector, init );

// Add the timer poke to initialize the plugin
wb.add( selector );

} )( jQuery, window, wb );</code></pre>

<dl>
	<dt>At line 16 <code>var componentName = &quot;wb-helloworld&quot;,</code></dt>
	<dd>The plugin is named <strong>wb-helloworld</strong>.</dd>

	<dt>At line 39 <code>$elm.trigger( &quot;name.of.your.event&quot; );</code></dt>
	<dd>The event &quot;name.of.your.event&quot; is fired on the DOM element that has initiated the plugin</dd>

	<dt>At line 51 <code>$elm.append(&quot;Hello World&quot;);</code></dt>
	<dd>The words &quot;Hello World&quot; are added at the end of the content inside the element</dd>
</dl>

<h2>Step 3 - Make it configurable</h2>

<p>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.</p>

<pre><code>/**
 * @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 ) {
&quot;use strict&quot;;

/*
 * 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 = &quot;wb-helloworld&quot;,
	selector = &quot;.&quot; + componentName,
	initEvent = &quot;wb-init&quot; + selector,
	$document = wb.doc,
	<strong>defaults = {}</strong>,

	/**
	 * @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,
			<strong>settings;</strong>

		if ( elm ) {
			$elm = $( elm );

			// ... Do the plugin initialisation

			// Get the plugin JSON configuration set on attribute data-wb-helloworld
			<strong>settings = $.extend(
				true,
				{},
				defaults,
				window[ componentName ],
				wb.getData( $elm, componentName )
			);</strong>

			// Call my custom event
			<strong>$elm.trigger( &quot;name.of.your.event&quot;, settings );</strong>

			// Identify that initialization has completed
			wb.ready( $elm, componentName );
		}
	};

// Add your plugin event handler
$document.on( &quot;name.of.your.event&quot;, selector, <strong>function( event, data ) {</strong>
	var elm = event.currentTarget,
		$elm = $( elm );

	$elm.append( &quot;Hello World&quot; );

	<strong>if ( data &amp;&amp; data.domore ) {</strong>
		$elm.prepend( &quot;Do more&quot; );
	}
} );

// Bind the init event of the plugin
$document.on( &quot;timerpoke.wb &quot; + initEvent, selector, init );

// Add the timer poke to initialize the plugin
wb.add( selector );

} )( jQuery, window, wb );</code></pre>

<dl>
	<dt>At line 20 <code>defaults = {}</code></dt>
	<dd>JSON object that defines the default settings for your plugin.</dd>

	<dt>At line 33 <code>settings;</code></dt>
	<dd>A local variable to hold the settings for the current instance of the plugin.</dd>

	<dt>At line 41 <code>settings = $.extend(</code></dt>
	<dd>The local variable settings will have a cloned copy of all the combined settings.</dd>

	<dt>At line 42 <code>true,</code></dt>
	<dd>It will perform a deep copy</dd>

	<dt>At line 43 <code>{},</code></dt>
	<dd>Start extending with an empty new object.</dd>

	<dt>At line 44 <code>defaults,</code></dt>
	<dd>Apply the default settings.</dd>

	<dt>At line 45 <code>window[ componentName ],</code></dt>
	<dd>Retreive setting directly set via javascript harde coded in the page for example like: <code>window['wb-helloworld'] = {};</code></dd>

	<dt>At line 46 <code>wb.getData( $elm, componentName )</code></dt>
	<dd>Retreive and parse into a JSON object the setting set through the attribute <code>data-wb-helloworld</code></dd>

	<dt>At line 50 <code>$elm.trigger( &quot;name.of.your.event&quot;, settings );</code></dt>
	<dd>Now, the second parameter contains the instance settings that will be used by the event.</dd>

	<dt>At line 58 <code>function( event, data ) {</code></dt>
	<dd>Add a second parameter, <var>data</var>, in order to receive data when the event is trigger.</dd>

	<dt>At line 64-66 <code>if ( data &amp;&amp; data.domore ) {</code></dt>
	<dd>If a <var>data</var> has been set and the property <var>domore</var> is true or is positive or contain something then prepend the words &quot;Do more&quot; to the element</dd>
</dl>

<h2>Step 4 - Test it out</h2>

<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>

<pre><code>&lt;p class=&quot;wb-helloworld&quot;&gt;Example 1&lt;/p&gt;

&lt;p&gt;Example 2 (&lt;span class=&quot;wb-helloworld&quot;&gt;inside a span&lt;/span&gt;)&lt;/p&gt;

&lt;p class=&quot;wb-helloworld&quot; data-wb-helloworld='{ &quot;domore&quot;: true }'&gt;Example 3 with configuration&lt;/p&gt;</code></pre>

<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.</p>

<h2>Going beyond</h2>

<p>The non-documented WET core includes a lot of utilities function re-used by several plugins.</p>

<p>Such as the function <code>wb.getId()</code> from which we can get an unique id that does not conflict with any other elements. Or the array defined at <code>wb.drawColours</code> 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 <a href="https://github.com/wet-boew/wet-boew/tree/master/src/core">WET core source code</a> to find others useful function.</p>

<p>The loading of third party plugin is done by using Modernizer. You can explorer other plugin that implement is like the <a href="https://github.com/wet-boew/wet-boew/blob/master/src/plugins/tables/tables.js#L80">tables plugins</a>.</p>

<h2>Question or need help?</h2>

<p><a href="https://github.com/wet-boew/wet-boew/issues/new">Submit an issue on Github</a></p>
