Marcimat’s Docs

Accueil du site > Extensions > Porte Plume > Description d’une barre d’outil

Description d’une barre d’outil

Les barres d’outil sont décrites dans des fichiers placés dans le répertoire barre_outils/. Chaque plugin peut créer ce répertoire pour y placer une barre d’outil éventuelle.

Deux barres sont présentes par défaut : « edition » et « forum », dans des fichiers PHP homonymes. Ces fichiers doivent contenir une fonction barre_outils_$nom() qui renvoie une instance de l’objet PHP Barre_outils décrivant la barre et les différents boutons.

Ces fichiers peuvent posséder aussi une fonction barre_outils_$nom_icones() permettant d’associer à un nom de classe CSS un nom d’icone contenu dans le dossier icones_barre/.

Exemple de déclaration classe CSS/icone

Commençons par le plus simple, c’est un simple tableau associatif qui est retourné :

  1. function barre_outils_edition_icones(){
  2.     return array(
  3.         'outil_header1' => 'intertitre.png',
  4.         'outil_bold' => 'text_bold.png',
  5.         'outil_italic' => 'text_italic.png',
  6.         'outil_liste_ul' => 'text_list_bullets.png',
  7.         'outil_liste_ol' => 'text_list_numbers.png',
  8.         // ...
  9.     );
  10. }
Télécharger

Exemple de déclaration d’une barre

Cette déclaration est plus complexe, elle permet de définir essentiellement 3 choses : des actions générales, des boutons, et des menus pour les boutons.

Voyons deja le premier paramètre, pour indiquer le nom de la barre :

  1. function barre_outils_edition(){
  2.     $set = new Barre_outils(array(
  3.         // parametres
  4.         'cle'=>'valeur',
  5.         // nom de la barre
  6.         'nameSpace'         => 'edition',
  7.     ));
  8.     return $set;
  9. }
Télécharger

Paramètres généraux

Déclarer simplement ce qui se passe avec la touche tabulation et des appuis sur la touche entrée :

  1. function barre_outils_edition(){
  2. $set = new Barre_outils(array(
  3.     'nameSpace' => 'edition',
  4.     'onShiftEnter' => array('keepDefault'=>false, 'replaceWith'=>"\n_ "),
  5.     'onCtrlEnter' => array('keepDefault'=>false, 'replaceWith'=>"\n\n"),
  6.     'onTab' => array('keepDefault'=>false, 'replaceWith'=>"\t")
  7. ));
  8. return $set;
  9. }
Télécharger

Un certain nombre d’évènements sont connus de MarkItUp, comme onEnter, ou onShifEnter, auxquels il est possible d’affecter des actions tel que openWith, closeWith, replaceWith...

Déclarer un bouton

Les boutons se déclarent dans un paramètre markupSet qui est un tableau associatif :

  1. function barre_outils_edition(){
  2.     $set = new Barre_outils(array(
  3.         'markupSet'         => array(
  4.             // H1 - {{{
  5.             array(
  6.                 "id"        => 'header1',
  7.                 "name"      => _T('barre_outils:barre_intertitre'),
  8.                 "key"       => "H",
  9.                 "className" => "outil_header1",
  10.                 "openWith" => "\n{{{",
  11.                 "closeWith" => "}}}\n",
  12.                 "display"   => true,
  13.                 "selectionType" => "line",
  14.             ),
  15.             // Bold - {{
  16.             array(
  17.                 "id"        => 'bold',
  18.                 "name"      => _T('barre_outils:barre_gras'),
  19.                 "key"       => "B",
  20.                 "className" => "outil_bold",
  21.                 "openWith" => "{{",
  22.                 "closeWith" => "}}",
  23.                 "display"   => true,
  24.                 "selectionType" => "word",
  25.             )
  26.         )
  27.     ));
  28.     return $set;
  29. }
Télécharger

Chaque bouton est un tableau de paramètres. Un bouton possède

  • un identifiant unique (id),
  • un titre (name),
  • parfois un raccourcis clavier (key) avec la touche contrôle
  • une classe CSS (qui sert entre autre à afficher l’icône correspondante)
  • des actions à réaliser (openWith, closeWith, replaceWith)
  • si le bouton est affiché (display)
  • un type de sélection éventuel (rien, ou "word" ou "line") pour sélectionner automatiquement un mot ou une ligne si rien n’est encore sélectionné au moment de l’appel du bouton.

Sous menu

Chaque bouton peut recevoir un sous menu de boutons, pour cela, il faut renseigner le paramètre dropMenu d’un bouton, qui contient un tableau associatif de déclarations de boutons (comme markupSet donc)

Jouer avec la langue

Un cas particulier concerne les boutons que l’on souhaite uniquement dans certaines langues. deux paramètres indiquent cela : lang et lang_not :

  1. // guillemets de, simples
  2. array(
  3.     "id"          => 'guillemets_de_simples',
  4.     "name"        => _T('barre_outils:barre_guillemets_simples'),
  5.     "className"   => "outil_guillemets_de_simples",
  6.     "openWith"    => "‚",
  7.     "closeWith"   => "‘",
  8.     "display"     => true,
  9.     "lang"        => array('bg','de','pl','hr','src'),
  10.     "selectionType" => "word",
  11. ),
  12. // guillemets autres langues
  13. array(
  14.     "id"          => 'guillemets_autres',
  15.     "name"        => _T('barre_outils:barre_guillemets'),
  16.     "className"   => "outil_guillemets_simples",
  17.     "openWith"    => "“",
  18.     "closeWith"   => "”",
  19.     "display"     => true,
  20.     "lang_not"    => array('fr','eo','cpf','ar','es','bg','de','pl','hr','src'),
  21.     "selectionType" => "word",
  22. ),
Télécharger

Fonctions JavaScript étendues

Il est pssible d’appeler des fonctions dans les paramètres d’action, comme ici un bouton pour enlever toutes les balises HTML d’une sélection :

  1. // clean
  2. array(
  3.     "id"          => 'clean',
  4.     "name"        => _T('barre_outils:barre_clean'),
  5.     "className"   => "outil_clean",
  6.     "replaceWith" => 'function(markitup) { return markitup.selection.replace(/<(.*?)>/g, "") }',
  7.     "display"     => true,
  8. ),
Télécharger

Il est même possible de créer des fonctions en écrivant le javascript de la fonction dans le paramètre général functions :

Exemple avec les listes :

Les listes appellent une fonction "outil_liste" déclarée dans le paramètre général de la barre :

  1. // listes -*
  2. array(
  3.     "id"        => 'liste_ul',
  4.     "name"      => _T('barre_outils:barre_liste_ul'),
  5.     "className" => "outil_liste_ul",
  6.     "replaceWith" => "function(h){ return outil_liste(h, '*');}",
  7.     "display"   => true,
  8.     "selectionType" => "line",
  9.     "forceMultiline" => true,
  10. ),
Télécharger

Déclaration :

  1.    
  2. 'functions'         => "
  3.     // remplace ou cree -* ou -** ou -# ou -##
  4.     function outil_liste(h, c) {
  5.         if ((s = h.selection) && (r = s.match(/^-([*#]+) (.*)\$/)))  {
  6.             r[1] = r[1].replace(/[#*]/g, c);
  7.             s = '-'+r[1]+' '+r[2];
  8.         } else {
  9.             s = '-' + c + ' '+s;
  10.         }
  11.         return s;
  12.     }
Télécharger
SPIP | | Suivi | Plan du site | Mentions légales | Suivre la vie du site RSS 2.0