From dccc9c70015002e9eef61b5ea80437425d568cec Mon Sep 17 00:00:00 2001 From: Pierre Dubois Date: Tue, 6 Dec 2016 22:33:44 -0500 Subject: [PATCH] Hello world plugin example and fix #7788 --- .../docs/ref/helloworld/helloworld-en.hbs | 102 +++++++++ .../docs/ref/helloworld/helloworld-fr.hbs | 102 +++++++++ site/pages/docs/ref/plugins-en.hbs | 12 + site/pages/docs/ref/plugins-fr.hbs | 16 +- src/other/helloworld/demo/bonjour.js | 68 ++++++ src/other/helloworld/demo/helloworld.js | 68 ++++++ src/other/helloworld/helloworld-en.hbs | 206 +++++++++++++++++ src/other/helloworld/helloworld-fr.hbs | 207 ++++++++++++++++++ 8 files changed, 779 insertions(+), 2 deletions(-) create mode 100644 site/pages/docs/ref/helloworld/helloworld-en.hbs create mode 100644 site/pages/docs/ref/helloworld/helloworld-fr.hbs create mode 100644 src/other/helloworld/demo/bonjour.js create mode 100644 src/other/helloworld/demo/helloworld.js create mode 100644 src/other/helloworld/helloworld-en.hbs create mode 100644 src/other/helloworld/helloworld-fr.hbs diff --git a/site/pages/docs/ref/helloworld/helloworld-en.hbs b/site/pages/docs/ref/helloworld/helloworld-en.hbs new file mode 100644 index 00000000000..e8d28341b5f --- /dev/null +++ b/site/pages/docs/ref/helloworld/helloworld-en.hbs @@ -0,0 +1,102 @@ +--- +{ + "title": "Hello world", + "language": "en", + "category": "Other", + "categoryfile": "other", + "description": "A quick tutorial on how you can create your own WET plugin.", + "altLangPrefix": "helloworld", + "dateModified": "2016-12-06" +} +--- +
+ +
+

Purpose

+

Learn on how to create a simple plugin for WET

+
+ +
+

Working example

+ +
+ +
+

Source code of helloworld.js

+
/**
+ * @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,
+			settings;
+
+		if ( elm ) {
+			$elm = $( elm );
+
+			// ... Do the plugin initialisation
+
+			// Get the plugin JSON configuration set on attribute data-wb-helloworld
+			settings = 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 );
+
+ +
+

Source code

+

Hello world source code on GitHub

+
diff --git a/site/pages/docs/ref/helloworld/helloworld-fr.hbs b/site/pages/docs/ref/helloworld/helloworld-fr.hbs new file mode 100644 index 00000000000..99191695adf --- /dev/null +++ b/site/pages/docs/ref/helloworld/helloworld-fr.hbs @@ -0,0 +1,102 @@ +--- +{ + "title": "Exemple de plugiciel, Bonjour le monde", + "language": "fr", + "category": "Autre", + "categoryfile": "other", + "description": "Un tutoriel rapide sur commment créer votre plugiciel BOEW.", + "altLangPrefix": "helloworld", + "dateModified": "2016-12-06" +} +--- +
+ +
+

But

+

Apprendre à comment créer son propre plugiciel BOEW.

+
+ +
+

Exemples pratiques

+ +
+ +
+

Code source de bonjour.js

+
/**
+ * @title WET-BOEW Plugiciel bonjour le monde
+ * @overview Plugiciel démontrant un example de comment créer votre propre plugiciel BOEW personalisé
+ * @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";
+
+/*
+ * Définition de variable et de fonction.
+ * Ceux-ci sont généraux au plugiciel - cela veux dire qu'ils seront initialisé une fois par page,
+ * et non à chaque fois que le plugiciel sera instancié sur la page. Donc, ici c'est un bon endroit
+ * enfin de définir des variables qui sont communes à toutes les instance du plugiciel sur la page.
+ */
+var nomComposant = "wb-bonjour",
+	selecteur = "." + nomComposant,
+	initEvent = "wb-init" + selecteur,
+	$document = wb.doc,
+
+	/**
+	 * @method init
+	 * @param {jQuery Event} event L'object événement lors du déclanchement de la fonction
+	 */
+	init = function( event ) {
+
+		// Début de l'initialisation
+		// retourne un objet DOM = procéder avec l'initialisation
+		// retourne undefined = ne pas procéder avec l'initialisation (ex., il est déjà initialisé)
+		var elm = wb.init( event, nomComposant, selecteur ),
+			$elm,
+			parametres;
+
+		if ( elm ) {
+			$elm = $( elm );
+
+			// ... Faire l'initialisation du plugiciel
+
+			// Obtenir les paramètres JSON du plugiciel tel que définie par l'attribut data-wb-bonjour
+			parametres = wb.getData( $elm, nomComposant );
+
+			// Appel d'un événement personalisé
+			$elm.trigger( "nom.de.votre.evenement", parametres );
+
+			// Annonce que l'initialisation de l'instance a été complélté
+			wb.ready( $elm, nomComposant );
+		}
+	};
+
+// Ajouter votre code pour gérer les événement de votre plugiciel
+$document.on( "nom.de.votre.evenement", selecteur, function( evenenment, donnee ) {
+	var elm = evenenment.currentTarget,
+		$elm = $( elm );
+
+	$elm.append( "Bonjour le monde" );
+
+	if ( donnee && donnee.surpassetoi ) {
+		$elm.prepend( "Surpasse toi" );
+	}
+} );
+
+// Liaison à l'événement init du plugiciel
+$document.on( "timerpoke.wb " + initEvent, selecteur, init );
+
+// Ajouter notre poke pour que l'initialisation des instances
+wb.add( selecteur );
+
+} )( jQuery, window, wb );
+
+ +
+

Code source

+

Code source pour Bonjour le monde sur GitHub

+
diff --git a/site/pages/docs/ref/plugins-en.hbs b/site/pages/docs/ref/plugins-en.hbs index 33b0c9ff9c0..7191f9a61e4 100644 --- a/site/pages/docs/ref/plugins-en.hbs +++ b/site/pages/docs/ref/plugins-en.hbs @@ -23,6 +23,7 @@
  • Footnotes - Provides a consistent, accessible way of handling footnotes across websites.
  • Form validation - Provides generic validation and error message handling for Web forms.
  • Geomap - Displays a dynamic map over which information from additional sources can be overlaid.
    • +
  • Hello world plugin example - A quick tutorial on how you can create your own WET plugin.
  • Lightbox - Helps build a photo gallery on a web page.
  • Menu - Provides an interactive menu with optional sub-menus.
  • Multimedia player - Provides an accessible multimedia player for embedding video and audio into web pages.
    • @@ -36,3 +37,14 @@
  • Toggle - Allows a link to toggle elements between on and off states.
  • Twitter embedded timeline - Helps with implementing Twitter embedded timelines.
    • + +

    Using your own plugin

    + +

    In order to have your plugin working with WET:

    +
      +
    1. Your plugin needs to follow the WET plugin initialisation.
      2. +
    2. Your script needs to be inserted after the wet-boew.min.js script in your page.
      3. +
    3. An element in your page needs to call the plugin by having the plugin name in its class atttribute.
      4. +
    + +

    Take a look at the Hello world example.

    diff --git a/site/pages/docs/ref/plugins-fr.hbs b/site/pages/docs/ref/plugins-fr.hbs index c25462d8984..2276f1b655b 100644 --- a/site/pages/docs/ref/plugins-fr.hbs +++ b/site/pages/docs/ref/plugins-fr.hbs @@ -7,7 +7,7 @@ "dateModified": "2014-03-31" } --- -

    Needs translation A WET plugin provides various types of functionality useful to a website and provided by calling the function in the class attribute of an HTML tag.

    +

    Les plugiciels BOEW fournis divers fonctionalités utilent pour un site web et l'initialisation de ceux-ci se font l'intermédaire d'une classe CSS défénie à un élément HTML.

    + +

    Utilisation de votre plugiciel

    + +

    Pour que vous puissez utiliser votre propre plugiciel dans la BOEW, vous devez:

    +
      +
    1. Votre plugiciel doit suivre la procédure d'initialisation de la BOEW.
      2. +
    2. Votre script doit être ajouter après que le script wet-boew.min.js soit inséré dans votre page.
      3. +
    3. Un élément dans votre page doit contenir l'appel de votre plugiciel, tel que le nom du plugiciel soit existant dans l'attribut "class".
      4. +
    + +

    Prenez le temps de consulter l'example Bonjour le monde.

    diff --git a/src/other/helloworld/demo/bonjour.js b/src/other/helloworld/demo/bonjour.js new file mode 100644 index 00000000000..ee545d99ec9 --- /dev/null +++ b/src/other/helloworld/demo/bonjour.js @@ -0,0 +1,68 @@ +/** + * @title WET-BOEW Plugiciel bonjour le monde + * @overview Plugiciel démontrant un example de comment créer votre propre plugiciel BOEW personalisé + * @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"; + +/* + * Définition de variable et de fonction. + * Ceux-ci sont généraux au plugiciel - cela veux dire qu'ils seront initialisé une fois par page, + * et non à chaque fois que le plugiciel sera instancié sur la page. Donc, ici c'est un bon endroit + * enfin de définir des variables qui sont communes à toutes les instance du plugiciel sur la page. + */ +var nomComposant = "wb-bonjour", + selecteur = "." + nomComposant, + initEvent = "wb-init" + selecteur, + $document = wb.doc, + + /** + * @method init + * @param {jQuery Event} event L'object événement lors du déclanchement de la fonction + */ + init = function( event ) { + + // Début de l'initialisation + // retourne un objet DOM = procéder avec l'initialisation + // retourne undefined = ne pas procéder avec l'initialisation (ex., il est déjà initialisé) + var elm = wb.init( event, nomComposant, selecteur ), + $elm, + parametres; + + if ( elm ) { + $elm = $( elm ); + + // ... Faire l'initialisation du plugiciel + + // Obtenir les paramètres JSON du plugiciel tel que définie par l'attribut data-wb-bonjour + parametres = wb.getData( $elm, nomComposant ); + + // Appel d'un événement personalisé + $elm.trigger( "nom.de.votre.evenement", parametres ); + + // Annonce que l'initialisation de l'instance a été complélté + wb.ready( $elm, nomComposant ); + } + }; + +// Ajouter votre code pour gérer les événement de votre plugiciel +$document.on( "nom.de.votre.evenement", selecteur, function( evenenment, donnee ) { + var elm = evenenment.currentTarget, + $elm = $( elm ); + + $elm.append( "Bonjour le monde" ); + + if ( donnee && donnee.surpassetoi ) { + $elm.prepend( "Surpasse toi" ); + } +} ); + +// Liaison à l'événement init du plugiciel +$document.on( "timerpoke.wb " + initEvent, selecteur, init ); + +// Ajouter notre poke pour que l'initialisation des instances +wb.add( selecteur ); + +} )( jQuery, window, wb ); diff --git a/src/other/helloworld/demo/helloworld.js b/src/other/helloworld/demo/helloworld.js new file mode 100644 index 00000000000..2a297f7cba6 --- /dev/null +++ b/src/other/helloworld/demo/helloworld.js @@ -0,0 +1,68 @@ +/** + * @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, + settings; + + if ( elm ) { + $elm = $( elm ); + + // ... Do the plugin initialisation + + // Get the plugin JSON configuration set on attribute data-wb-helloworld + settings = 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 ); diff --git a/src/other/helloworld/helloworld-en.hbs b/src/other/helloworld/helloworld-en.hbs new file mode 100644 index 00000000000..ae762e6df80 --- /dev/null +++ b/src/other/helloworld/helloworld-en.hbs @@ -0,0 +1,206 @@ +--- +{ + "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" +} +--- + +

    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,
+			settings;
+
+		if ( elm ) {
+			$elm = $( elm );
+
+			// ... Do the plugin initialisation
+
+			// Get the plugin JSON configuration set on attribute data-wb-helloworld
+			settings = 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 16 var componentName = "wb-helloworld",
    +
    The plugin is named wb-helloworld.
    + +
    At line 40 settings = wb.getData( $elm, componentName );
    +
    It retreive and parse it into a JSON object the parameter set on the attribute data-wb-helloworld
    + +
    At line 43 $elm.trigger( "name.of.your.event", settings );
    +
    The event "name.of.your.event" is fired on the DOM element that have initiated the plugin
    + +
    At line 55 $elm.append("Hello World");
    +
    The words "Hello World" is added at the end of the content inside the elements
    + +
    At line 57-58 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 3 - 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

    \ No newline at end of file diff --git a/src/other/helloworld/helloworld-fr.hbs b/src/other/helloworld/helloworld-fr.hbs new file mode 100644 index 00000000000..6acfe10e302 --- /dev/null +++ b/src/other/helloworld/helloworld-fr.hbs @@ -0,0 +1,207 @@ +--- +{ + "title": "Exemple de plugiciel, Bonjour le monde", + "language": "fr", + "category": "Autre", + "description": "Un tutoriel rapide sur commment créer votre plugiciel BOEW.", + "tag": "helloworld", + "parentdir": "helloworld", + "altLangPrefix": "helloworld", + "js": ["demo/bonjour"], + "dateModified": "2016-12-06" +} +--- + +

    Un tutoriel rapide sur commment créer votre plugiciel BOEW.

    + +
    + +

    Étape 1 - Utiliser un plugiciel conteneur squelettique.

    + +

    Voici un plugiciel conteneur squelettique:

    + +
    /**
+ * @title WET-BOEW Plugiciel conteneur squelettique
+ * @overview Plugiciel démontrant un example de comment créer votre propre plugiciel BOEW personalisé
+ * @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";
+
+/*
+ * Définition de variable et de fonction.
+ * Ceux-ci sont généraux au plugiciel - cela veux dire qu'ils seront initialisé une fois par page,
+ * et non à chaque fois que le plugiciel sera instancié sur la page. Donc, ici c'est un bon endroit
+ * enfin de définir des variables qui sont communes à toutes les instance du plugiciel sur la page.
+ */
+var nomComposant = "wb-squelette",
+	selecteur = "." + nomComposant,
+	initEvent = "wb-init" + selecteur,
+	$document = wb.doc,
+
+	/**
+	 * @method init
+	 * @param {jQuery Event} event L'object événement lors du déclanchement de la fonction
+	 */
+	init = function( event ) {
+
+		// Début de l'initialisation
+		// retourne un objet DOM = procéder avec l'initialisation
+		// retourne undefined = ne pas procéder avec l'initialisation (ex., il est déjà initialisé)
+		var elm = wb.init( event, nomComposant, selecteur ),
+			$elm;
+
+		if ( elm ) {
+			$elm = $( elm );
+
+			// ... Faire l'initialisation du plugiciel
+
+			// Annonce que l'initialisation de l'instance a été complélté
+			wb.ready( $elm, nomComposant );
+		}
+	};
+
+// Ajouter votre code pour gérer les événement de votre plugiciel
+$document.on( "nom.de.votre.evenement", selecteur, function() {
+	//... votre code ici ...
+} );
+
+// Liaison à l'événement init du plugiciel
+$document.on( "timerpoke.wb " + initEvent, selecteur, init );
+
+// Ajouter notre poke pour que l'initialisation des instances
+wb.add( selecteur );
+
+} )( jQuery, window, wb );
    + +
    +
    À la ligne 16 var nomComposant = "wb-squelette",
    +
    La valeur donnée à nomComposant représentera le nom du plugiciel et du nom de la classe à utiliser pour initié l'instance.
    + +
    À la ligne 36 // ... Faire l'initialisation du plugiciel
    +
    C'est ici où que toute les actions d'initialisation nécessaire seront exécuté. Le défi est de faire le moins d'exécution que possible afin de rendre votre plugiel en attente d'action de l'utilisateur. Les plugiciels de la BOEW sont orienté sur une approche événementielle où qu'on essai de ne pas éxécuter des lignes de script qui n'est actuellement pas nécessaire. Ceci pour des raison de performance.
    + +
    À la ligne 43-45 // Ajouter votre code pour gérer les événement de votre plugiciel
    +
    C'est ici que vous allez déclarer une série d'événement pour votre plugiciel. Vous pouvez déclancher vos propre événéement en utilisant l'instance jQuery d'un élément. L'appel à la fonction trigger suivi de votre nom d'événement et de vos donnée s'il y lieu. Par example: $elm.trigger( "nom.de.votre.evenement", mesdonnee );. Le paramètre mesdonnee est optionel.
    +
    + +

    Étape 2 - Ajouter votre code javascript

    + +

    Cet example de plugiciel ajoute le texte "Bonjour le monde" à tout éléments qui contient la classe wb-bonjour pour la page duquel le plugiciel est chargé.

    + +
    /**
+ * @title WET-BOEW Plugiciel bonjour le monde
+ * @overview Plugiciel démontrant un example de comment créer votre propre plugiciel BOEW personalisé
+ * @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";
+
+/*
+ * Définition de variable et de fonction.
+ * Ceux-ci sont généraux au plugiciel - cela veux dire qu'ils seront initialisé une fois par page,
+ * et non à chaque fois que le plugiciel sera instancié sur la page. Donc, ici c'est un bon endroit
+ * enfin de définir des variables qui sont communes à toutes les instance du plugiciel sur la page.
+ */
+var nomComposant = "wb-bonjour",
+	selecteur = "." + nomComposant,
+	initEvent = "wb-init" + selecteur,
+	$document = wb.doc,
+
+	/**
+	 * @method init
+	 * @param {jQuery Event} event L'object événement lors du déclanchement de la fonction
+	 */
+	init = function( event ) {
+
+		// Début de l'initialisation
+		// retourne un objet DOM = procéder avec l'initialisation
+		// retourne undefined = ne pas procéder avec l'initialisation (ex., il est déjà initialisé)
+		var elm = wb.init( event, nomComposant, selecteur ),
+			$elm,
+			parametres;
+
+		if ( elm ) {
+			$elm = $( elm );
+
+			// ... Faire l'initialisation du plugiciel
+
+			// Obtenir les paramètres JSON du plugiciel tel que définie par l'attribut data-wb-bonjour
+			parametres = wb.getData( $elm, nomComposant );
+
+			// Appel d'un événement personalisé
+			$elm.trigger( "nom.de.votre.evenement", parametres );
+
+			// Annonce que l'initialisation de l'instance a été complélté
+			wb.ready( $elm, nomComposant );
+		}
+	};
+
+// Ajouter votre code pour gérer les événement de votre plugiciel
+$document.on( "nom.de.votre.evenement", selecteur, function( evenenment, donnee ) {
+	var elm = evenenment.currentTarget,
+		$elm = $( elm );
+
+	$elm.append( "Bonjour le monde" );
+
+	if ( donnee && donnee.surpassetoi ) {
+		$elm.prepend( "Surpasse toi" );
+	}
+} );
+
+// Liaison à l'événement init du plugiciel
+$document.on( "timerpoke.wb " + initEvent, selecteur, init );
+
+// Ajouter notre poke pour que l'initialisation des instances
+wb.add( selecteur );
+
+} )( jQuery, window, wb );
    + +
    +
    À la ligne 16 var nomComposant = "wb-bonjour",
    +
    Le plugiciel est nommé wb-bonjour.
    + +
    À la ligne 40 parametres = wb.getData( $elm, nomComposant );
    +
    Cela va lire les paramètres définie par l'attribut data-wb-bonjour et transforme le résultat en un objet JSON.
    + +
    À la ligne 43 $elm.trigger( "nom.de.votre.evenement", parametres );
    +
    L'événement "nom.de.votre.evenement" est déclanché pour l'élément DOM qui a initialisé cet instance de plugiciel
    + +
    À la ligne 55 $elm.append("Bonjour le monde");
    +
    Le texte "Bonjour le monde" est ajouté à la fin du contenu intérieur de l'élément.
    + +
    À la ligne 57-58 if ( donnee && donnee.surpassetoi ) {
    +
    S'il la variable donnee a été initialisé et qu'il contient une propriété nommé surpassetoi avec n'importe lequel valeur qui est vrai, alors les mots "Surpasse toi" sera ajouté au début de l'élément.
    +
    + +

    Étape 3 - Mise à l'essaie

    + +

    Exemple 1

    + +

    Exemple 2 (à l'intérieur d'un span)

    + +

    Exemple 3 avec paramètre

    + +
    <p class="wb-bonjour">Exemple 1</p>
+
+<p>Exemple 2 (<span class="wb-bonjour">à l'intérieur d'un span</span>)</p>
+
+<p class="wb-bonjour" data-wb-bonjour='{ "surpassetoi": true }'>Exemple 3 avec paramètre</p>
    + +

    Noter que pour que vous puissez utiliser votre propre plugiciel dans la BOEW, vous devriez ajouter votre script après celui de la BOEW (wet-boew.js) dans le code HTML.

    + + +

    Allez plus loin

    + +

    Le coeur non documenté de la BOEW contient plusieurs fonction utilitaire trè utile à plusieurs.

    + +

    Tel que la fonction wb.getId() permet d'obtenir un identifiant unique qui n'entrera pas en conflit avec les autres éléments sur la page. Ou le tableau disponible par wb.drawColours définie une séquence de couleur à utiliser afin de maintenir un bon contraste, tel qu'utilisé par les graphiques et le géomap. Explorer le code source du coeur de la BOEW afin de découvrir plusieurs autres fonction utilitaire.

    + +

    Le chargement de plugiciel tierce se fait à l'aide de Modernizer. Vous pouvez explorer des plugiciels qui l'utilise tel que l'amélioration de tableau de donnée.

    + + +

    Question ou besoin d'assistance?

    + +

    Soumetter une requête sur Github (en anglais seulement, mais les questions peuvent être posés en français)

    \ No newline at end of file