SPIP-Contrib

SPIP-Contrib

عربي | Deutsch | English | Español | français | italiano | Nederlands

286 Plugins, 197 contribs sur SPIP-Zone, 185 visiteurs en ce moment

Accueil > Rédaction > Assistants de rédaction > Porte Plume > Porte Plume : documentation technique

Porte Plume : documentation technique

1er novembre 2011 – par Matthieu Marcillaud – 20 commentaires

12 votes

Le « Porte Plume » est l’extension donnant accès à des barres d’outils sur certains champs d’édition des formulaires. Cette extension s’appuie sur jQuery et utilise une adaptation de la librairie Markitup de Jay Salvat.

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.

PNG - 18.9 ko

Possibilité de visualisation

Deux onglets dans la partie privée permettent de passer de l’espace de saisie au rendu généré.

PNG - 250.4 ko

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 raccourcis 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. 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.

  1. ;(function($){
  2. $(document).ready(function(){
  3. // ajoute les barres d'outils markitup
  4. function barrebouilles(){
  5. // fonction generique appliquee aux classes CSS :
  6. // inserer_barre_forum, inserer_barre_edition, inserer_previsualisation
  7. $('.formulaire_spip textarea.inserer_barre_forum').barre_outils('forum');
  8. $('.formulaire_spip textarea.inserer_barre_edition').barre_outils('edition');
  9. $('.formulaire_spip textarea.inserer_previsualisation').barre_previsualisation();
  10. // fonction specifique aux formulaires de SPIP :
  11. // barre de forum
  12. $('textarea.textarea_forum,.formulaire_forum textarea[name=texte]').barre_outils('forum');
  13. // barre d'edition et onglets de previsualisation
  14. $('.formulaire_spip textarea[name=texte]').barre_outils('edition').barre_previsualisation();
  15. }
  16. barrebouilles();
  17. onAjaxLoad(barrebouilles);
  18. });
  19. })(jQuery);

Télécharger

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é :

  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. "id" => 'header1',
  6. "name" => _T('barre_outils:barre_intertitre'),
  7. "key" => "H",
  8. "className" => "outil_header1",
  9. "openWith" => "\n{{{",
  10. "closeWith" => "}}}\n",
  11. "display" => true,
  12. "selectionType" => "line",
  13. ),
  14. // Bold - {{
  15. "id" => 'bold',
  16. "name" => _T('barre_outils:barre_gras'),
  17. "key" => "B",
  18. "className" => "outil_bold",
  19. "openWith" => "{{",
  20. "closeWith" => "}}",
  21. "display" => true,
  22. "selectionType" => "word",
  23. )
  24. )
  25. ));
  26. return $set;
  27. }

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

Télécharger

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 :

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

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. "id" => 'liste_ul',
  3. "name" => _T('barre_outils:barre_liste_ul'),
  4. "className" => "outil_liste_ul",
  5. "replaceWith" => "function(h){ return outil_liste(h, '*');}",
  6. "display" => true,
  7. "selectionType" => "line",
  8. "forceMultiline" => true,
  9. ),

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

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_outils_pre_charger sert à ajouter des boutons à une barre.
  • porte_plume_barre_outils_charger sert à afficher ou masquer certains boutons
  • porte_plume_porte_plume_lien_classe_vers_icone sert à compléter les relations classes css / icone

barre_outils_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 :

  1. function pp_codes_porte_plume_barre_pre_charger($barres){
  2. $barre = &$barres['edition'];
  3. // ...
  4. return $barres;
  5. }

Télécharger

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 :

  1. $barre->ajouterApres('grpCaracteres', array(
  2. "id" => "sepCode",
  3. "separator" => "---------------",
  4. "display" => true,
  5. ));
  6. $barre->ajouterApres('sepCode', array(
  7. // groupe code et bouton <code>
  8. "id" => 'grpCode',
  9. "name" => _T('pp_codes:outil_inserer_code'),
  10. "className" => 'outil_code',
  11. "openWith" => "<code>",
  12. "closeWith" => "</code>",
  13. "display" => true,
  14. ));

Télécharger

barre_outils_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) :

  1. $barre->cacherTout();
  2. $barre->afficher(array(
  3. 'bold','italic',
  4. 'sepLink','link',
  5. 'sepCitations', 'quote',
  6. 'sepCaracteres','guillemets', 'guillemets_simples',
  7. 'guillemets_de', 'guillemets_de_simples',
  8. 'guillemets_autres', 'guillemets_autres_simples',
  9. 'A_grave', 'E_aigu', 'oe', 'OE',
  10. ));

Télécharger

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 » :

  1. function pp_loremipsum_porte_plume_lien_classe_vers_icone($flux){
  2. return array_merge($flux, array(
  3. 'outil_lorem_ipsum' => 'newspaper.png',
  4. 'outil_lorem_ipsum_big' => 'newspaper_add.png',
  5. ));
  6. }

Télécharger

Dernière modification de cette page le 19 septembre 2016

Retour en haut de la page

Vos commentaires

  • Le 27 juillet 2015 à 17:40, par RealET En réponse à : Porte Plume : documentation technique

    Bonjour,

    Avec http://zone.spip.org/trac/spip-zone/changeset/91096 j’ai rajouté une entrée de menu dans le porte-plume pour afficher des frimousses.

    Mais cette entrée n’est pas visible dans le public pour les forums.

    Comment la rajouter ?

    Merci d’avance.

    Répondre à ce message

  • Le 29 février à 11:58, par Jean Christophe Villeneuve En réponse à : Porte Plume : documentation technique

    Bonjour

    Comment surcharger la barre ’edition’ ET la barre ’forum’ de façon différente ?

    • Le 18 juillet à 17:38, par Mist. GraphX En réponse à : Porte Plume : documentation technique

      hello Jean Christophe ,

      en spécifiant la barre que tu souhaite surcharger au début de la déclaration de la pipeline

      1. prefix_porte_plume_barre_pre_charger($barres) {
      2. $barre_edition = &$barres['edition'];
      3. $barre_forum = &$barres['forum'];
      4.  
      5. $barre_edition->set('header1', array(
      6. ...
      7. ));
      8.  
      9. $barre_forum->set('header1', array(
      10. ...
      11. ));
      12.  
      13. return $barres;
      14. }

      Télécharger

      bonne journée
      Mist. GraphX

    • Le 18 juillet à 19:47, par Jean Christophe Villeneuve En réponse à : Porte Plume : documentation technique

      Cool !
      Je regarde ça de près dès que je rentre de vacances...
      Merci

    • Le 4 août à 20:22, par Jean Christophe Villeneuve En réponse à : Porte Plume : documentation technique

      Bon pour un ignare en php comme moi, ce n’est pas si simple.
      Voici le code actuel que j’utilise pour surcharger la barre d’édition des articles :

      if (!defined("_ECRIRE_INC_VERSION")) return;
      function escal_porte_plume_barre_pre_charger($barres){
              $barre = &$barres['edition'];

              $module_barre = "barre_outils";
              if (intval($GLOBALS['spip_version_branche'])>2)
                      $module_barre = "barreoutils";
             

              // Ajouts Escal       
              $barre->ajouterApres
      ...
              ));       
                     
              return $barres;
      }

      Que dois-je changer ?

    • Le 5 août à 11:54, par Jean Christophe Villeneuve En réponse à : Porte Plume : documentation technique

      C’est bon j’ai trouvé.
      Merci beaucoup pour le solution.

    Répondre à ce message

  • Le 5 février à 10:37, par Rainer Müller En réponse à : Porte Plume : documentation technique

    Juste pour signaler que dans la docc apparament les pipelines ne sont pas correct, il faut remplacer

    porte_plume_barre_outils_pre_charger

    par

    porte_plume_barre_pre_charger au lieu de 
    

    et

    porte_plume_porte_plume_lien_classe_vers_icone

    par

    porte_plume_lien_classe_vers_icone

    Répondre à ce message

  • Le 1er novembre 2013 à 18:53, par mmmx En réponse à : Porte Plume : documentation technique

    Bonjour
    I have a problem with extensions of porte-plume with spip 2.1 and spip 3.
    Can’t see anymore extension buttons for « Bouton Changement de langue pour le Porte-Plume » and my plugin Porte Plume Equation.
    Bouton pour spip code still is visible.
    Nobody has the same problem ?
    Any idea ?

    • Le 15 novembre 2013 à 12:02, par mmmx En réponse à : Porte Plume : documentation technique

      il est necessaire de vider la cache apres la installation du plugin !

      Is there a way to make this automatic during the installation of the plugin ?

    Répondre à ce message

  • Le 8 juin 2012 à 20:06, par mmmx En réponse à : Porte Plume : documentation technique

    dear Marcimat
    another question :
    how to make a button of the bar just open a link (in new browser window) ?
    (i need to open an help page)

    Répondre à ce message

  • Le 8 juin 2012 à 13:38, par Matthieu Marcillaud En réponse à : Porte Plume : documentation technique

    Hi mmmx

    The best for you is to look at new plugin named « Relecture » witch do exactly what you want.
    http://zone.spip.org/trac/spip-zone/browser/_plugins_/relecture/

    Look at directory "barre_outils"
    And also on the little script that plug it on a textarea here
    http://zone.spip.org/trac/spip-zone/browser/_plugins_/relecture/formulaires/commenter_relecture.html#L4

    Hope that helps you.

    • Le 8 juin 2012 à 15:16, par mmmx En réponse à : Porte Plume : documentation technique

      thanks for your instant answer !!!

      And also on the little script that plug it on a textarea here

      yes, maybe this is the point : so I have to insert a jQuery function to append the barre to the textarea.

      But in the example it does for a new textarea in a new formularie.

      Have I to use pipeline insert_head to add this function to the saisie texarea in the espace privé ?
      Or what ?
      Isn’t it a pipeline that do that for me in porte plume ?

    • Le 8 juin 2012 à 15:47, par Matthieu Marcillaud En réponse à : Porte Plume : documentation technique

      You can use pipeline header_prive yes to run a js on all private page. (http://programmer.spip.org/header_prive)

      There is no pipeline in porte_plume.

    • Le 8 juin 2012 à 16:01, par mmmx En réponse à : Porte Plume : documentation technique

      So, i have this script,

      $(document).ready(function(){
             function barreeq(){
                     $('.formulaire_spip textarea.inserer_barre_edition').barre_outils('spip_super');
              }
             barreeq();
             onAjaxLoad(barreeq);
      });

      I charge it, i have the file spip_super.php in outils_barre/ but I cant get it visualized.

      The script is called correctly, as if i write .barre_outils('foo'); i get a javascript error.

      Any suggestion ?

    • Le 8 juin 2012 à 16:31, par mmmx En réponse à : Porte Plume : documentation technique

      So,
      I am actually able to charge my barre, modifing the class selector in javascript, but not toghether with porteplume :
      $('.formulaire_spip textarea').barre_outils('spip_super');
      The problems seems to be that porte plume changes the class of the textarea, and so at the next call of barre_outils it cant find any textarea.inserer_barre_edition ;
      if i just call it on textarea it clear edition barre and append only my one ;

      So the question is how to write de javascript to just add the barre, i think.

    • Le 8 juin 2012 à 16:34, par Matthieu Marcillaud En réponse à : Porte Plume : documentation technique

      You can’t load 2 bars on 1 textarea. What do you expect in fact ?

    • Le 8 juin 2012 à 16:50, par mmmx En réponse à : Porte Plume : documentation technique

      When editing equations is useful to have all buttons in front of you, without searching them in a submenu.

      So I would like to add a button to the edition bar that make show all the maths button (about to rows) under the edition bar itself and at the top of textarea, and hide it after clicking again the button, as in the original project ;
      What do you think is the correct approach to achieve this ?

    Répondre à ce message

  • Le 8 juin 2012 à 13:26, par mmmx En réponse à : Porte Plume : documentation technique

    Dear marcimat

    I would like to understand how to add a barre to porteplume

    I can add a button to the barre edition, but I would like to add a whole barre pour le project spip equation)

    I tried adding the pipeline plume_barre_declarer as you stated here but I cant make it appear.

    Could you please tell me step by step the procedure to follow ?
    Can’t write french but I can read it so you can answer me in french. thanks

    Répondre à ce message

Répondre à cet article

Qui êtes-vous ?

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici Les choses à faire avant de poser une question (Prolégomènes aux rapports de bugs. )
Ajouter un document

Retour en haut de la page

Ça discute par ici

  • Import ICS 2 (agenda distant)

    2 août – 35 commentaires

    La version 2 du plugin « import ICS » en reprend la principale fonctionnalité, à savoir l’ajout automatique d’évènements distants dans la liste des évènements d’un site. À la différence de la première version, elle ne dépend pas du plugin « Séminaire » et est (...)

  • Newsletters

    16 janvier 2013 – 374 commentaires

    Ce plugin permet de composer des Info-lettres. Par info-lettre, on désigne ici le contenu éditorial qui va être composé et envoyé par courriel à une liste d’inscrits. Le plugin permet de composer une info-lettre à partir d’un modèle pré-composé, (...)

  • CKeditor 3.0

    4 octobre 2009 – 1217 commentaires

    CKeditor est l’évolution de l’éditeur WYSIWYG : FCKeditor, avec ce plugin vous pourrez utiliser cet éditeur à la place de l’éditeur de spip tout en laissant le choix à vos auteurs de l’éditeur qu’ils préfèrent utiliser. Attention : cet éditeur WYSIWYG (...)

  • GIS 4

    11 août 2012 – 1284 commentaires

    Présentation et nouveautés La version 4 de GIS abandonne la libraire Mapstraction au profit de Leaflet. Cette librairie permet de s’affranchir des librairies propriétaires tout en gardant les mêmes fonctionnalités, elle propose même de nouvelles (...)

  • SPIPr

    23 mars 2015 – 75 commentaires

    SPIPr est à la fois une famille de squelettes et un framework pour le développement front avec SPIP. Prêt à l’emploi, thémable, responsive, et conçu dans une approche d’industrialisation et de développement rapide. Documentation source : (...)

Ça spipe par là