Dans cet article, je vais décrire comment je m’y suis pris pour écrire le plugin Jquery Draggable étant parfait néophyte en la matière. Ce plugin utilise en plus le moteur de configuration de plugin CFG.
Ce script est basé tout simplement sur la librairie jQuery et tout est disponible ici.
Le but du plugin est de rendre draggable, bougeable, un élément de la page. C’est simple en soi, il suffit juste de dire à jQuey fournit en standard par Spip que l’ID tructruc ou que la class schmollschmoll sont draggables. En langue jQuery, cela donne un truc du genre : $(document).ready(function(){$("#tructruc, .schmollschmoll").draggable();});, soit, dès que le document (la page en fait) est prêt, rend les bouts de page dont les sélecteurs sont dans notre exemple tructruc et schmollschmoll, draggable.
Pour ce faire, j’ai écrit un plugin. Mais pourquoi un plugin et non un script alors que j’avais déjà écrit le script qu’il fallait et que vous pouvez retrouver sur cette page ?
L’avantage du plugin est que :
- Le script est accessible automatiquement dans toutes les pages du site ;
- Vous pouvez y inclure facilement des paramètres à faire prendre en compte par votre plugin.
Le problème est de savoir comment faire pour écrire ce fameux plugin ?
Un plugin est composé de différents fichiers contenus dans un dossier nommé du nom de votre plugin, jquery_draggable dans cet exemple.
Le fichier plugin.xml :
Vous y trouverez obligatoirement un fichier plugin.xml. Dans ce fichier, vous y trouverez toutes les informations obligatoires renseignant Spip sur le plugin. Allez regarder dans ce fichier pour remplacer les informations par celles de votre plugin.
Le début du fichier est tout à fait clair. Vous trouverez néanmoins ces lignes qui sont plus absconses :
<prefix>jquery_draggable</prefix>
<install>base/jquery_draggable_install.php</install>
<pipeline>
<nom>insert_head</nom>
<inclure>jquery_draggable_pipelines.php</inclure>
</pipeline>
<necessite id="cfg" version="[1.10;]" /><prefix>jquery_draggable</prefix> correspond au préfixe que l’on doit retrouver pour les fonctions que vous écrirez. Afin que Spip sache à qui correspond telle ou telle fonction, celles-ci doivent donc avoir un préfixe spécifique. C’est le but de cette ligne que de dire que toutes les fonctions utilisées par votre plugin contiendront ce préfixe, en l’occurrence pour mon plugin, toutes les fonctions commencent par jquery_draggable.
<install>base/jquery_draggable_install.php</install> veut dire que le plugin a une procédure d’installation spécifique. Cette procédure se retrouve placée dans un fichier nommé jquery_draggable_install.php et que ce fichier est placé dans un dossier nommé quant à lui base (base/jquery_draggable_install.php).
Nous retrouvons ensuite
<pipeline>
<nom>insert_head</nom>
<inclure>jquery_draggable_pipelines.php</inclure>
</pipeline>Pour que le plugin soit pris en compte partout dans votre site, il faut que le code du plugin soit injecté dans chaque page appelée par le navigateur du visiteur. C’est le but du jeu de la balise #INSERT_HEAD que l’on retrouve dans les squelettes. Cette balise va regarder s’il y a des trucs à ajouter à la volée aux pages du site. Les trucs à ajouter à la volée sont, entre autres choses, des bouts de code de plugin.
Ainsi, nous voulons insérer dans chaque page un petit script javascript qui va rendre draggable un élément de la page. Pour ce faire, nous définissons une information obligatoire qualifiée de pipeline.
Comme ce pipeline doit être inséré via la balise #INSERT_HEAD, son nom est insert_head. Ensuite, nous précisons à Spip qu’il doit inclure dans la fameuse balise des informations qui sont contenues dans le fichier jquery_draggable_pipelines.php.
Pour finir, nous lisons <necessite id="cfg" version="[1.10;]" /> qui veut tout simplement dire à Spip que pour fonctionner, ce plugin à besoin obligatoirement du plugin CFG avec une version au moins égale à la 1.10. Notez bien que CFG n’est pas obligatoire en soi pour faire fonctionner le plugin. Il a une importance majeure quand on veut laisser la possibilité à l’administrateur de pouvoir paramétrer certains éléments du plugin.
Dans cet exemple, j’ai besoin que l’administrateur du site puisse définir quelle partie de la page il veut rendre draggable. Nous devons donc offrir une page de configuration dans laquelle l’utilisateur pourra définir l’id ou la class de la page qui sera bougeable. C’est la fonction de CFG que de permettre cela de façon souple et homogène. Rendez vous sur le site de Spip-contrib pour tout savoir sur CFG à cette adresse : http://www.spip-contrib.net/Config-CFG.
Voilà le fichier plugin.xml complet.
La page de configuration du plugin via CFG :
Pour créer cette page de configuration, il nous faut écrire 2 fichiers :
Le fichier fonds/cfg_jquery_draggable.html :
Il n’y a rien a expliquer de particulier, remplacez simplement les occurrences « jquery_draggable » par le nom de votre plugin.
Le fichier formulaires/config_jquery_draggable.html :
C’est dans ce fichier que nous allons construire le formulaire de saisi des paramètres que vous souhaitez utiliser dans votre plugin. Dans cet exemple, je n’ai besoin de connaître que le nom des ID ou des class que l’on veut rendre bougeables. J’ai donc créé un seul champ de texte pour permettre d’entrer ces éléments.
Voici le code :
<div class="formulaire_spip formulaire_configurer formulaire_config_jquery_draggable">
[<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>]
[<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>]
<form name="formulaire_config_jquery_draggable" method="post" action="#ENV{#SELF}">
<div>
#ACTION_FORMULAIRE{#SELF}
#CONFIG{jquery_draggable/jquery_draggable_selecteur}
<ul>
<li>
<label for="jquery_draggable_selecteur"><:jquery_draggable:label_elements:></label>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{selecteur_commun})</span>]
<p class="explication"><:jquery_draggable:explication_elements:></p>
<input type="text" name="jquery_draggable_selecteur" class="text" id="jquery_draggable_selecteur"
size="80" value="#ENV{jquery_draggable_selecteur}" />
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{description})</span>]
</li>
</ul>
<p class="boutons">
<input type="submit" name="_cfg_ok" class="submit" value="<:bouton_enregistrer:>" />
</p>
</div>
</form>
</div>Il n’y a donc pas de difficulté particulière et pouvez choisir d’autre type de champ pour votre formulaire (case à cocher, menu popup...) et y mettre aussi des boucles Spip si besoin. Le tout est que chaque partie du formulaire est un : value="#ENV{le nom de l'input}".
Par contre, vous êtes peut-être interpellé par des trucs du genre <:jquery_draggable:label_elements:>. Cela correspond à des bouts de code que l’on souhaite être traduit en différentes langues. Pour ce faire, on crée des fichiers de langue qui contiendront les différentes traductions de ce code dont la syntaxe est toujours <:le nom du prefixe du fichier de langue:la phrase à traduire :>. Les fichiers de langue sont dans le dossier lang. Ainsi, dans ce plugin, nous retrouvons un fichier jquery_draggable_fr.php et un jquery_draggable_en.php.
Maintenant, l’utilisateur peut enregistrer les paramètres ad hoc.
Le fichier jquery_draggable_pipelines.php
C’est le fichier qui contient ce que fait le plugin. Vous y mettez toutes les fonctions dont vous avez besoin.
Dans notre plugin, c’est ici que vous allez mettre le petit bout de code jQuery qui va rendre draggable une partie de la page.
Ainsi, on va retrouver :
<?php
//il s'agit d'écrire une fonction qui va automatiquement insérer le bout de code
//jQuery dans l'en tête des pages.
function jquery_draggable_insert_head($flux){
//je récupère les éléments ID ou class stockées via le formulaire de configuration CFG
$conf_jquery_draggable = lire_config('jquery_draggable/jquery_draggable_selecteur');
// $les_bougeables va contenir le bout de code javascript a jouter dans l'en tete de la page
$les_bougeables="";
$les_bougeables .= "$(\"".$conf_jquery_draggable."\").draggable();";
//construction du code à mettre dans l'en tête des pages via la balise #INSERHEAD
$flux .="\n <!-- Debut de plugin draggable -->\n ".
'<script src="'.url_absolue(find_in_path('javascript/jquery.draggable.js')).'" type="text/javascript"></script>'.
'<script src="'.url_absolue(find_in_path('prive/javascript/jquery-ui-1.8-drag-drop.min.js')).'" type="text/javascript"></script>';
$flux .= '
<script type="text/javascript">/* <![CDATA[ */
$(document).ready(function(){'.$les_bougeables.'});
(jQuery)/* ]]> */</script>
';
//ajout d'un petit bout de css qui va transformer le curseur en croix pour signifier que c'est draggable
//comme j'utilise jquery, la class css des draggable est automatiquement ajoutée par jquery et est ui.draggable
$flux .= '
<style type="text/CSS">
.ui-draggable{
cursor:move;
}
</style>
';
return $flux."<!-- Fin de plugin draggable -->";
}
?>En clair, le résultat dans la page donne le code suivant (il va sans dire que chez vous l’url de l’appel à la librairie jQuery est différente ainsi que les valeurs des ID ou class que vous avez renseignés). :
Enfin...
Il ne vous reste plus qu’à dessiner de belles icones et votre plugin est terminé.
Comme vous le constatez, c’est un plugin basique qui ne prend pas en compte les paramètres possibles de jQuery draggable. À vous de jouer pour les inclure si besoin est et la page de référence pour les options est : http://jqueryui.com/demos/draggable/.
