Exemple de plugiciel, Bonjour le monde

• Documentation
• Questions ou commentaires?

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,
	initEvenement = "wb-init" + selecteur,
	$document = wb.doc,

	/**
	 * @method init
	 * @param {jQuery Evenement} Evenement L'object événement lors du déclanchement de la fonction
	 */
	init = function( Evenement ) {

		// 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( Evenement, 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 " + initEvenement, 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,
	initEvenement = "wb-init" + selecteur,
	$document = wb.doc,

	/**
	 * @method init
	 * @param {jQuery Evenement} Evenement L'object événement lors du déclanchement de la fonction
	 */
	init = function( Evenement ) {

		// 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( Evenement, nomComposant, selecteur ),
			$elm;

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

			// ... Faire l'initialisation du plugiciel

			// Appel d'un événement personalisé
			$elm.trigger( "nom.de.votre.evenement" );

			// 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 ) {
	var elm = evenenment.currentTarget,
		$elm = $( elm );

	$elm.append( "Bonjour le monde" );

} );

// Liaison à l'événement init du plugiciel
$document.on( "timerpoke.wb " + initEvenement, 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 39 $elm.trigger( "nom.de.votre.evenement" );

L'événement "nom.de.votre.evenement" est déclanché pour l'élément DOM qui a initialisé cet instance de plugiciel

À la ligne 51 $elm.append("Bonjour le monde");

Le texte "Bonjour le monde" est ajouté à la fin du contenu intérieur de l'élément.

Étape 3 - Permettre le paramétrage

La pluspars des plugiciels ont besoin de paramétrage, l'exemple de code suivant démontre comment supporté plusieurs avenue différente afin de géré des paramètrages définie par l'éditeur et le développeur.

/**
 * @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,
	initEvenement = "wb-init" + selecteur,
	$document = wb.doc,
	defauts = {},

	/**
	 * @method init
	 * @param {jQuery Evenement} Evenement L'object événement lors du déclanchement de la fonction
	 */
	init = function( Evenement ) {

		// 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( Evenement, 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 = $.extend(
				true,
				{},
				defauts,
				window[ nomComposant ],
				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 " + initEvenement, selecteur, init );

// Ajouter notre poke pour que l'initialisation des instances
wb.add( selecteur );

} )( jQuery, window, wb );

À la ligne 20 defauts = {}

Un objet JSON qui définie les paramètres par défaut du plugiciel.

À la ligne 33 parametres;

Une variable local qui contiendra les paramètres de l'instance courrante du plugiciel.

À la ligne 41 parametres = $.extend(

La valeur de la variable local, parametres, sera une copie clonné créé en combinant l'ensemble des paramètres.

À la ligne 42 true,

Cela va faire une copie en profondeur des objects JSON.

À la ligne 43 {},

L'extension débute avec un objet vide.

À la ligne 44 defauts,

Applique les paramètres par défaut.

À la ligne 45 window[ nomComposant ],

Obtient les paramètres définie via javascript qui est souvant directement codé dans la même page qui utilise le plugiciel. Par example : window['wb-bonjour'] = {};

À la ligne 46 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 50 $elm.trigger( "nom.de.votre.evenement", parametres );

Ici, le second paramètre est la configuration de l'instance en cours et qui sera utilisé par l'événement.

À la ligne 58 function( evenenment, donnee ) {

Ajoute un second paramètre, donnee, à la fonction afin d'être en mesure de recevoir les données lorsque l'évélement est déclanché.

À la ligne 64-66 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 4 - 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)

Date de modification :

2016-12-06