Présentation
Le plugin Porte Plume permet d’ajouter une barre d’outil sur des champs « textarea » de formulaires. Cette barre d’outil est extrêmement modulaire et extensible et permet de faciliter la rédaction de contenu pour les rédacteurs.
Possibilité de visualisation
Deux onglets dans la partie privée permettent de passer de l’espace de saisie au rendu généré.
Facilités de saisie
Le porte plume regorge de petites fonctionnalités très discrètes mais qui améliorent grandement la saisie :
- chaque bouton peut avoir un raccourci clavier,
- lorsque votre curseur est sur un mot et que vous cliquez le bouton « gras », le mot est automatiquement sélectionné ; idem si vous utilisez le raccourci Control+B,
- lorsque votre curseur est sur une ligne et que vous cliquez le bouton « intertitre », toute la ligne est automatiquement sélectionnée,
- si vous commencez une liste à puce et que vous appuyez la touche « entrée », la liste se poursuit automatiquement,
- si vous avez une liste qui n’a pas encore les caractères « -* », vous pouvez sélectionner toutes les lignes et cliquer l’icône liste. Toutes les lignes deviendront un élément de liste ; cela fonctionne aussi avec l’indentation des listes,
- shift+entrée effectue un saut simple et non un saut de paragraphe (à éviter d’utiliser !!)
Certaines fonctionnalités ne fonctionnent pas avec le navigateur Opéra.
Fonctionnement
Sur chaque page qui le souhaite et sur chaque élément ciblé, le plugin peut ajouter une barre d’outils prédéfinie. Par défaut il en existe 2 : « edition » et « forum ».
La barre « edition » est chargée sur les éléments d’édition, celle des forums uniquement sur les forums. Il est possible de créer d’autres barres d’outils ou d’appliquer celles déjà existantes sur d’autres éléments que ceux prévus par SPIP (voir Porte-plume partout). Il est aussi possible de compléter une barre existante par d’autres boutons.
Classes CSS génériques d’application
Les barres d’outils sont chargées lorsque les textarea
possèdent certaines classes CSS (et sont contenus dans une classe CSS formulaire_spip
) :
-
inserer_barre_forum
: charge la barre d’édition « forum », -
inserer_barre_edition
: charge la barre d’édition « edition », -
inserer_previsualisation
: charge les onglets de prévisualisation.
Par ailleurs, les textarea
ayant un attribut name
valant « texte » reçoivent aussi les barres d’outils.
Classes CSS de non application
Il est aussi possible de forcer l’absence de barre sur un textarea
donné en ajoutant une classe CSS :
-
no_barre
: empêchera toute barre d’outil, -
no_previsualisation
: empêchera toute prévisualisation,
API de chargement javascript
Il est possible de charger des barres ou la prévisualisation en sélectionnant en jQuery les textarea
désirés et en leur appliquant les fonctions proposées :
-
barre_outils('nom')
: charge la barre d’outils « nom », -
barre_previsualisation()
: charge les onglets de prévisualisation.
Chargement
Pour appeler une barre d’outils, il faut faire l’appel dans une fonction et appeler ensuite cette fonction à l’initialisation du script et aux rechargements AJAX des pages. Voila comment le plugin gère l’ajout de la barre dans les éléments SPIP.
;(function($){
$(document).ready(function(){
// ajoute les barres d'outils markitup
function barrebouilles(){
// fonction generique appliquee aux classes CSS :
// inserer_barre_forum, inserer_barre_edition, inserer_previsualisation
$('.formulaire_spip textarea.inserer_barre_forum').barre_outils('forum');
$('.formulaire_spip textarea.inserer_barre_edition').barre_outils('edition');
$('.formulaire_spip textarea.inserer_previsualisation').barre_previsualisation();
// fonction specifique aux formulaires de SPIP :
// barre de forum
$('textarea.textarea_forum,.formulaire_forum textarea[name=texte]').barre_outils('forum');
// barre d'edition et onglets de previsualisation
$('.formulaire_spip textarea[name=texte]').barre_outils('edition').barre_previsualisation();
}
barrebouilles();
onAjaxLoad(barrebouilles);
});
})(jQuery);
La fonction barrebouilles()
contient les différents appels des barres. Elle sélectionne les éléments cibles (textarea) et applique les fonctions de l’API de Porte Plume.
La fonction barrebouilles()
est ensuite appelée et mise dans les liste des fonctions à rappeler en cas de rechargement AJAX via la fonction onAjaxLoad
.
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é :
function barre_outils_edition_icones(){
return array(
'outil_header1' => 'intertitre.png',
'outil_bold' => 'text_bold.png',
'outil_italic' => 'text_italic.png',
'outil_liste_ul' => 'text_list_bullets.png',
'outil_liste_ol' => 'text_list_numbers.png',
// ...
);
}
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 :
function barre_outils_edition(){
$set = new Barre_outils(array(
// parametres
'cle'=>'valeur',
// nom de la barre
'nameSpace' => 'edition',
));
return $set;
}
Paramètres généraux
Déclarer simplement ce qui se passe avec la touche tabulation et des appuis sur la touche entrée :
function barre_outils_edition(){
$set = new Barre_outils(array(
'nameSpace' => 'edition',
'onShiftEnter' => array('keepDefault'=>false, 'replaceWith'=>"\n_ "),
'onCtrlEnter' => array('keepDefault'=>false, 'replaceWith'=>"\n\n"),
'onTab' => array('keepDefault'=>false, 'replaceWith'=>"\t")
));
return $set;
}
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 :
function barre_outils_edition(){
$set = new Barre_outils(array(
'markupSet' => array(
// H1 - {{{
array(
"id" => 'header1',
"name" => _T('barre_outils:barre_intertitre'),
"key" => "H",
"className" => "outil_header1",
"openWith" => "\n{{{",
"closeWith" => "}}}\n",
"display" => true,
"selectionType" => "line",
),
// Bold - {{
array(
"id" => 'bold',
"name" => _T('barre_outils:barre_gras'),
"key" => "B",
"className" => "outil_bold",
"openWith" => "{{",
"closeWith" => "}}",
"display" => true,
"selectionType" => "word",
)
)
));
return $set;
}
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
:
// guillemets de, simples
array(
"id" => 'guillemets_de_simples',
"name" => _T('barre_outils:barre_guillemets_simples'),
"className" => "outil_guillemets_de_simples",
"openWith" => "‚",
"closeWith" => "‘",
"display" => true,
"lang" => array('bg','de','pl','hr','src'),
"selectionType" => "word",
),
// guillemets autres langues
array(
"id" => 'guillemets_autres',
"name" => _T('barre_outils:barre_guillemets'),
"className" => "outil_guillemets_simples",
"openWith" => "“",
"closeWith" => "”",
"display" => true,
"lang_not" => array('fr','eo','cpf','ar','es','bg','de','pl','hr','src'),
"selectionType" => "word",
),
Fonctions JavaScript étendues
Il est possible d’appeler des fonctions dans les paramètres d’action, comme ici un bouton pour enlever toutes les balises HTML d’une sélection :
// clean
array(
"id" => 'clean',
"name" => _T('barre_outils:barre_clean'),
"className" => "outil_clean",
"replaceWith" => 'function(markitup) { return markitup.selection.replace(/<(.*?)>/g, "") }',
"display" => true,
),
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 :
// listes -*
array(
"id" => 'liste_ul',
"name" => _T('barre_outils:barre_liste_ul'),
"className" => "outil_liste_ul",
"replaceWith" => "function(h){ return outil_liste(h, '*');}",
"display" => true,
"selectionType" => "line",
"forceMultiline" => true,
),
Déclaration :
'functions' => "
// remplace ou cree -* ou -** ou -# ou -##
function outil_liste(h, c) {
if ((s = h.selection) && (r = s.match(/^-([*#]+) (.*)\$/))) {
r[1] = r[1].replace(/[#*]/g, c);
s = '-'+r[1]+' '+r[2];
} else {
s = '-' + c + ' '+s;
}
return s;
}
Compléter une barre d’outil
Des pipelines permettent de compléter une barre d’outil existante. Ils sont au nombre de 3 :
-
porte_plume_barre_pre_charger
sert à ajouter des boutons à une barre. -
porte_plume_barre_charger
sert à afficher ou masquer certains boutons -
porte_plume_porte_plume_lien_classe_vers_icone
sert à compléter les relations classes css / icone
porte_plume_barre_pre_charger
Il reçoit un tableau avec comme clé les nom de barres, et comme valeur l’instance de l’objet Barre_outils de la barre en question.
Dans ce pipeline, on récupère donc une barre d’outil comme cela en indiquant son nom :
function pp_codes_porte_plume_barre_pre_charger($barres){
$barre = &$barres['edition'];
// ...
return $barres;
}
Une fois que l’on a sélectionné la barre sur laquelle on veut agir, il suffit d’appeler les fonctions prévues. Deux seront utiles, voire 3 :
-
$barre->ajouterAvant($id, $description)
, -
$barre->ajouterApres($id, $description)
, - $description =
$barre->get($id)
.
Ca se passe de commentaire, c’est assez simple :
$barre->ajouterApres('grpCaracteres', array(
"id" => "sepCode",
"separator" => "---------------",
"display" => true,
));
$barre->ajouterApres('sepCode', array(
// groupe code et bouton <code>
"id" => 'grpCode',
"name" => _T('pp_codes:outil_inserer_code'),
"className" => 'outil_code',
"openWith" => "<code>",
"closeWith" => "</code>",
"display" => true,
));
Il est possible d’ajouter une entrée « dropmenu » dans le menu pour ajouter des boutons dans une liste déroulante.
porte_plume_barre_charger
Ce pipeline sert pour cacher ou afficher les boutons créés (pour modifier la configuration par défaut donc). Seront utiles 4 fonctions :
-
$barre->afficher($id)
, -
$barre->afficher(array($ids))
, -
$barre->afficherTout()
, -
$barre->cacher($id)
, -
$barre->cacher(array($ids))
, -
$barre->cacherTout()
.
Exemple récupéré de la barre « forum » (qui ne fait que cacher certains boutons de la barre d’édition) :
$barre->cacherTout();
$barre->afficher(array(
'bold','italic',
'sepLink','link',
'sepCitations', 'quote',
'sepCaracteres','guillemets', 'guillemets_simples',
'guillemets_de', 'guillemets_de_simples',
'guillemets_autres', 'guillemets_autres_simples',
'A_grave', 'E_aigu', 'oe', 'OE',
));
porte_plume_lien_classe_vers_icone
Ce pipeline complète les relations entre les classes CSS et les icones du répertoire icones_barre/
, comme ici dans l’extension « lorem ipsum » :
function pp_loremipsum_porte_plume_lien_classe_vers_icone($flux){
return array_merge($flux, array(
'outil_lorem_ipsum' => 'newspaper.png',
'outil_lorem_ipsum_big' => 'newspaper_add.png',
));
}
Avec SPIP 4, on a aussi une syntaxe avec un tableau pour intégrer les SVGs
function bidule_porte_plume_lien_classe_vers_icone($flux){
return array_merge($flux, array(
'bidule--nbps' => ['espace-insecable.svg', '0'],
'bidul-pp--poesie' => ['spt-v1.svg', '-2px -322px'],
));
}
Discussions par date d’activité
Une discussion
Hello
J’ai un petit souci : j’ai pu sans souci faire apparaître un bouton pour un plugin dans la barre principale avec
mais je n’arrive pas à l’insérer dans un sous-menu avec par exemple
le bouton barre_code étant présent si le plugin Enluminures typographiques est activé.
Répondre à ce message
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |