upbtn-makefile ~ fichiers pour bouton éditeur

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.

Le plugin bouton : upbtn

Le plugin s'installe comme toutes les extensions Joomla. Il 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
• afficher le contenu du fichier custom/help.txt (v2.8)
• afficher un résumé des prefsets pour le site (v2.8)

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)

{up upbtn_makefile}
{up upscsscompiler | force=1 | info=1}
{up upactionslist | make-dico=1}

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/upbtn-options.ini (surchargeable dans le dossier custom)
  

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.

Elle est disponible :

• en ajoutant une option ? ou debug au shortcode d'une action
• avec l'action {up upactionslist=nom_action}
• dans l'aide au format PDF téléchargeable sur ce site
• dans le tableau CSV généré avec {up upactionslist=nom_action | csv}
• dans le plugin editor-xtd : upbtn

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
   /* [MOTCLE] SOUS-TITRE SUR UNE LIGNE */
   'id' => '', // id générée automatiquement par UP
);

Pour faciliter la lecture, il est possible d'intercaler des sous-titres.

• Ils doivent impérativement être sur une seule ligne encadré par /* ... */
• un mot-clé (optionnel) entre crochet permet de faire un lien vers le fichier langage 
• le texte du sous-titre qui sera remplacé par sa traduction éventuelle  

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-virgules 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

Mise à jour

Version 2.2

Ajout option export-folder qui reçoit en argument le nom d'un sous-dossier de tmp. Une copie de tous les fichiers html sera créée en respectant l'arborescence des dossiers du plugin. Son usage est principalement interne. Il permet de mettre à jour la version à partir de laquelle est généré le ZIP proposé au téléchargement.