Porte Plume : créer une nouvelle barre

This is an « educational contribution » which shows, with concrete example, how to develop a new functionality for SPIP.

Ceci est un tutoriel pour créer ex nihilo une nouvelle barre d’outils d’aide à la rédaction.
Il est également question de voir comment charger cette nouvelle barre sur les champs de votre choix, et gérer les traitements typographiques liés aux nouveaux boutons.

1- Créer une nouvelle barre

Pour cela, vous devez créer deux répertoires dans le dossier /squelettes de votre site ou à la racine de votre plugin.

/barre_outils
Il contiendra le fichier ma_barre.php.

Pour la constitution de ce fichier, voir le paragraphe “Exemple de déclaration d’une barre” dans la documentation technique du Porte Plume.

/icones_barre
Il contiendra les fichiers images correspondants aux boutons de votre barre.
Ex : noisette.png, noix.png, etc.

Ces images ont une dimension de 16x16 pixels.
L’idéal est de faire le symbole en 14x14 px et de le centrer dans un fond transparent de 16x16 px.

2- Charger votre nouvelle barre

Cet appel se fait via un javascript. En fonction de votre besoin, il existe deux méthodes pour intégrer ce script.

1ère méthode : chargement directement depuis le fichier mon_formulaire.html
Cette méthode est la plus rapide à mettre en place, mais il est conseillé de ne l’utiliser que si vous compter charger votre nouvelle barre dans un seul formulaire.
Sinon, privilégiez la seconde méthode décrite plus loin.

Avec cette méthode, il vous suffit d’intégrer le code suivant dans le fichier .html de votre formulaire :

;(function($) {
$(document).ready(function() {
	function appel_barre() {
		$('.formulaire_mon_formulaire textarea[name=mon_champ]').barre_outils('ma_barre');
	}
	appel_barre();
	onAjaxLoad(appel_barre);
});
})(jQuery);
  • function appel_barre : le nom appel_barre est ici arbitraire. Donnez lui le nom que vous voulez;
  • .formulaire_mon_formulaire : remplacer ici la partie mon_formulaire par le nom de votre formulaire;
  • mon_champ : à remplacer par le nom (attribut name) de votre champ;
  • ma_barre : à remplacer par le nom que vous avez donné à votre barre.

Dans le même formulaire, vous pourrez charger votre barre sur autant de champ que vous voulez, à condition de rajouter une déclaration pour chaque champ.

$('.formulaire_mon_formulaire textarea[name=deuxieme_champ]').barre_outils('ma_barre');
$('.formulaire_mon_formulaire textarea[name=troisieme_champ]').barre_outils('ma_barre');

2e méthode : chargement depuis n’importe quel formulaire...
...grâce à la création de classes CSS génériques d’application [1].

Pour cela, vous devez créer un fichier barre_ma_barre.js dans le dossier /squelettes/javascript de votre site ou dans le dossier /mon_plugin/javascript de votre plugin.

;(function($){
$(document).ready(function(){
	function charger_barre(){ 
		$('.formulaire_spip textarea.inserer_ma_barre').barre_outils('ma_barre');		
	}
	charger_barre();
	onAjaxLoad(charger_barre);
});
})(jQuery);

Enfin vous devez charger ce fichier JS dans l’espace privé. Là aussi deux méthodes sont possibles :
-  Pour les version de antérieures à 3.1, vous devez utiliser le pipeline header_prive
-  Depuis SPIP 3.1, vous pouvez déclarer l’appel de ce fichier en utilisant la balise <script> décrite dans Rédaction du paquet.xml
exemple :

  1. <script source="javascript/barre_ma_barre.js" type="prive" />

Une fois que tout ceci est fait, vous pouvez charger votre nouvelle barre dans n’importe quel champ de n’importe quel formulaire, en ajoutant simplement la classe .inserer_ma_barre dans le champ voulu.

Exemple :

<textarea name="infos" class="inserer_ma_barre"  id="champ_infos" rows="4" cols="40" >

Exemple en utilisant le plugin Saisies

[(#SAISIE{textarea, infos, obligatoire=oui,
label=<:prefixe:champ_infos_label:>,
class=inserer_ma_barre, rows=4})]

3- Traitements typographiques des nouveaux boutons

Il s’agit maintenant de créer et d’activer le rendu des traitements typographiques liés à vos nouveaux boutons aussi bien dans la partie publique que dans les vues Voir et Plein écran de l’interface de rédaction du back-office de votre formulaire.

Vous faites ainsi d’une pierre deux coups : un seul code pour la partie publique et privé.
Et vous améliorez surtout l’expérience utilisateur de vos rédacteurs.

Explications par l’exemple

Imaginons une nouvelle barre intégrant un bouton ’buste’.
L’objet de ce bouton est de rajouter un picto ’buste’ à la suite de votre texte.

La barre chargée

Nouvelle barre de typo
Nouvelle barre de typo

petite note : Le tag <buste> est choisi pour sa valeur WYSIWYM (What You See Is What You Mean).

Le champ de saisie en mode ’Voir’

Rendu dans l'espace privé
Rendu dans l’espace privé

Note : pour le rendu dans l’espace privé, vous devez penser à intégrer les styles correspondants dans l’espace privé.

Le rendu dans l’espace publique

Rendu dans l'espace public
Rendu dans l’espace public

Le code HTML attendu est celui-ci :

<p>1-2<i class="icon-user"></i></p>

On va donc créer la fonction suivante et la placer mes_options.php, :

function typo_nom_de_mon_champ($texte) {
	$texte = preg_replace('/<\/buste>/i', "&nbsp;<i class='icon-user'></i></p>", $texte);
	$texte = preg_replace('/<buste>/i', '<p>', $texte);
	return $texte;
}

Puis, appliquer ce traitement typo sur le champ qui charge ma nouvelle barre, en l’occurrence ci-dessous, le champ INFOS.

  1. $interfaces['table_des_traitements']['INFOS'][] = 'typo_nom_de_mon_champ(%s)';

Ce code sera intégré le plus souvent via le pipeline declarer_tables_interfaces

Pour plus d’explication sur ce dernier point reportez-vous à la documentation sur les Traitements automatiques des balises

Footnotes

[1Cette méthode reprend d’une façon simplifiée les explications données dans le paragraphe Fonctionnement dans la documentation technique du Porte Plume.

updated on 13 June 2019

Discussion

Aucune discussion

Comment on this article

Who are you?
  • [Log in]

To show your avatar with your message, register it first on gravatar.com (free et painless) and don’t forget to indicate your Email addresse here.

Enter your comment here

This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.

Add a document

Follow the comments: RSS 2.0 | Atom