upbtn-makefile ~ fichiers pour bouton éditeur

Up logo carre

Cette procédure génère les fichiers utilisés par le plugin editors-xtd : upbtn

Depuis la version 2.10, UP propose un bouton dans les éditeurs pour construire les shortcodes.

Pour gagner en rapidité et épargner les ressources serveur, les fichiers utilisés sont préparés à l'avance par cette action.

➠ upbtn_makefile : Création des fichiers HTML pour le plugin editors-xtd

Cliquer pour lire la documentation

syntaxe {up upbtn_makefile}
author LOMART version UP-2.1 license GNU/GPLv3 tags UP
  • upbtn_makefile: Vide pour toutes les actions, sinon liste des actions à inclure ou exclure (list-exclude=1).
  • top10: liste des actions à dupliquer dans un groupe au début de la liste
  • by-tags = 1: si 0, les actions sont dans l'ordre alpha sans notion de groupes (sauf top10)
  • list-exclude = 0: 0:uniquement les actions indiquées, 1: toutes sauf les actions indiquées

    Le plugin bouton : upbtn

    Cette action n'a aucune raison d'être en

    Ce plugin ajoute une icône dans la barre d'outils de TinyMCE et un bouton au-dessous de la zone d'édition des autres éditeurs (JCE, Rockpad, ...)

    Ce bouton ouvre une fenêtre modale.

    Il faut choisir une action dans la liste déroulante

    infos Webmaster

    Un rédacteur de contenu n'a aucune raison d'utiliser cette action.

    En tant que webmaster du site, vous l'utiliserez pour :

    • modifier le classement et la présentation de la liste des options
    • générer les écrans de saisie en tenant compte de vos jeux d'options, de vos options par défaut, de vos nouvelles actions

    Cette action propose quelques options :

    upbtn_makefile

    Vide par défaut pour inclure toutes les actions présentes dans le dossier "actions" de UP.

    Vous pouvez inclure ou exclure certaines actions en indiquant leurs noms séparés par des virgules. Voir l'option "list-mode"

    top10

    liste des actions à dupliquer dans un groupe au début de la liste. Cela permet d'avoir sous la souris les actions que vous utilisez fréquemment.

    by-tags

    si 0, les actions sont dans l'ordre alpha sans notion de groupes (sauf top10)

    list-exclude

    Par défaut, la liste contient toutes les actions ou uniquement celles indiquées dans l'option principale "upbtn-makefile".

    Cette option permet de proposer toutes les options sauf celles indiquées dans l'option principale.

    Le fichier custom/prefs.ini

    Comme pour toutes les actions, ce fichier mémorise vos choix. Il n'est pas modifié lors d'une mise à jour.

    Il vous sera utile pour 2 choses :

    • les options par défaut : section [options]
    • l'affectation des actions à des groupes : section [tags]

     

    [options]
    top10="div, span, icon, hr, flexbox"
    by-tags=1 ; classement par groupes
    
    [tags]
    div = "Editor" ; change l'action div du groupe par défaut (HTML) vers le groupe Editor span="html,editor,les actions de toto" ; affecte l'action span à 2 groupes standards et 1 nouveau groupe (crée automatiquement)

     

    Je vous conseille de faire un article, accessible uniquement au superadmin, "Maintenance de UP" avec les shortcodes permettant de régénérer les fichiers après une mise à jour de UP.

    {up upbtn_makefile}
    {up upscsscompiler | force=1 | info=1}
    {up upactionslist | make-dico=1}
    • le premier shortcode génère tous les fichiers pour le bouton éditeur en tenant compte de vos choix dans prefs.ini. Si vous n'utilisez pas la section [tags], vous pouvez mettre les options directement dans le shortcode.
    • le deuxième régénère tous les fichiers CSS à partir des SCSS de UP et toutes les actions
    • le troisième (moins usité) régénère les fichiers dico utilisés pour les synonymes

     

    Infos développeur

    Lors de la création d'une nouvelle action, il faut suivre quelques règles pour une bonne prise en compte par le bouton éditeur.

    Pour créer les fichiers utilisés par le bouton éditeur, l'action upbtn_makefile utilise

    • les commentaires présents dans le script PHP de l'action
    • les traductions xx-XX.ini du sous-dossier up de l'action. Une traduction, si elle existe, remplace toujours le commentaire dans le script.
    • les formats des options dans le fichier up/options.ini

    note : le webmaster peut modifier votre choix de groupe (@tags) dans la section [tags] du fichier prefs.ini de l'action upbtn_makefile

    Rappel : la documentation dans le script php

    UP utilise directement les commentaires présents dans votre code pour construire la documentation des actions.

    Cela impose quelques règles pour permettre une bonne interprétation.

    Si un fichier langage est disponible dans le sous-dossier up, il sera utilisé en remplacement.

    l'entête du script principal d'une action

    /**
     * DESCRIPTION COURTE 
     *
     * suite description
     *
     * syntaxe {up nomAction=argument_principal}
     *
     * @author   LOMART
     * @version  UP-1.0  <- version minimale de UP pour prise en charge
     * @license   <a href="http://www.gnu.org/licenses/gpl-3.0.html" target="_blank">GNU/GPLv3</a>
     * @credit    <a href="/" target"_blank">script xxx de xxx</a>
     * @tags    Groupe pour bouton editeur
     * 
     **/
    
    /**
     * Commentaires non repris
     **/
    

    ligne 2 : la description courte utilisée dans la liste des actions. Elle sera remplacée par la traduction correspondant au mot-clé shortdesc

    ligne 4 à 6 : la description longue. En réalité toutes les lignes jusque la première ligne commençant par @.  Elle sera remplacée par la traduction correspondant au mot-clé longdesc

    ligne 8 à 12 : ces informations sont reprises dans le bandeau bleu des démos des actions. Pour le bouton éditeur, le mot-clé @tags définit le ou les groupes de l'action. Elles ne sont jamais traduites

    ligne 16 à 18 : Pour réserver des commentaires à un usage interne, il faut créer un deuxième bloc de commentaires

    les options

    Elles sont définies dans 2 arrays : $options_def et $js_options_def. La documentation d'une option est le commentaire en fin de ligne

    Si le nom de l'option existe dans un fichier langage, sa valeur sera substituée.

    $options_def = array(
       __class__ => '', // le paramètre principal
       'id' => '', // id générée automatiquement par UP
    );
    

    La liste des actions

    Une action est décrite par son nom utilisé en programmation suivi de sa description (le texte sur fond vert). Pour faciliter la lecture, les underscores sont remplacés par des tirets. 

    Le rattachement d'une action à un ou plusieurs groupes est fait avec le mot-clé @tags dans l'entête du script

    La documentation

    Elle reprend la description courte (shortdesc) et toutes les lignes avant les mots-clés (longdesc). Les shortcodes sont automatiquement reconnus et mis en évidence. 

    Il est important de fournir les types d'utilisation (avec et sans shortcodes fermants)

    Il est possible d'utiliser du up-bbcode pour ajouter un lien ou mettre en évidence des informations.

    Les options

     

    • le texte d'aide est le commentaire présent
    • l'ordre d'affichage est celui des tableaux $options_def et $js_options_def. Prenez soin à les regrouper et les présenter de façon logique pour l'utilisateur. (Voir la classe hr-top)

    Le fichier up/options.ini

    Par défaut, toutes les options sont présentées comme un champ texte occupant la largeur de la fenêtre.

    Dans le fichier up/options.ini de chaque option, on peut définir le style et le type de champ pour le formulaire

    nom_option = "[TYPE class1 class2 ] attributs ou item liste"

    Chaque ligne est composée du nom d'une option, du signe égal, puis entre guillemets : d'un crochet ouvrant, du type de saisie (jaune), de classes pour la mise en forme (vert), d'un crochet fermant et selon le type d'attributs ou d'items de liste (bleu).

    TYPE,  le premier mot entre crochets, définit le type du champ formulaire

    • A : input type text. Les attributs autorisés sont : minlength, maxlength, size
    • N : input type number. . Les attributs autorisés sont : min, max, step et unit qui ajoute l'unité entre parenthèses devant le champ
    • B : select avec option Oui (1) et Non (0)
    • COLOR : input type color. Saisie visuelle d'une couleur au format #rrggbb
    • LIST : select avec les éléments de la liste après le crochet fermant
    • COMBO : combine un champ de saisie text avec une liste
    • FILE : COMBO dont les éléments sont le nom des fichiers correspondant au masque indiqué

    Le type est le premier mot entre crochets, les autres sont des classes CSS
    Les infos après les crochets sont les autres attributs et les éléments des listes

        option = "[A w20 important]"  ; champ text largeur 20% et mis en important (fond jaune)
        option = "[N important] min:0, max:40,step:5,unit:px"  ; champ number avec ses attributs classiques  + unit qui ajoute (pour information) l'unité entre parenthèses devant le champ
        option = "[B]" ; oui/non
        option = "[COLOR]"  ; sélecteur couleur RVB
        option = "[LIST important]item1, item2, itemN" ; select mis en important
        option = "[COMBO]item1, item2, itemN" ; champ text avec datalist
        option = "[FILE inactif]model/*.scss" ; select sur les fichiers correspondant au masque indiqué

    Note : pour les listes, le séparateur peut-être des points-virgule ou des pipes. Pour dissocier la valeur du contenu affiché, on l'indique comme ceci : valeur::affichage; valeur2::affichage2

    Pour la mise en forme, le plugin editor propose plusieurs classes :

    • w5, w10, w20, w30, w40, w50, w60, w70 : largeur du champ en pourcentage
    • important : mise en évidence par un fond de couleur jaune
    • inactif : utilisé pour indiquer que la saisie est inutile, car gérée par le script
    • attention : pour indiquer une particularité sur ce champ. Exemple : options xxx de l'action HTML
    • hr-top : ajoute une ligne verticale au-dessus du champ. Utile pour créer visuellement des groupes d'options