frendeitpt

Personnalisation et mise à jour de UP

Cet article va vous expliquer comment adapter UP à votre image et le rendre plus facile pour vos rédacteurs.

Les dossiers et fichiers de UP

Comme il sera nécessaire d'intervenir directement dans les dossiers et fichiers de UP à cet emplacement  plugins/content/up, il est préférable de faire connaissance et d'avoir un plan pour s'y promener!

Ces adaptations nécessitent d'intervenir directement dans les fichiers de UP :

  • actions : toutes les actions
    • nom_action : une action
      • nom_action.php : le fichier principal non surchargeable
      • xxx.js : javascript surchargeable dans custom
      • xxx.scss : SCSS surchargeable dans custom
      • xxx.css : CSS surchargeable dans custom. Compilé automatiquement à partir du SCSS de même nom
      • custom : vos personnalisations (optionnel)
        • prefs.ini.dist : fichier modèle fourni par UP
        • prefs.ini : vos préférences pour l'action
        • dico.ini : vos synonymes pour le nom de l'action et ses options.
          Compilé par upactionslist avec l'option make-dico dans up/dico.json
        • upbtn-options.ini : description des options pour le bouton éditeur
        • help.txt : vos aides et conseils affichés dans le bouton éditeur de UP.
          utilisé par l'action upbtn-makefile
        • model ou autre nom : copie du dossier de même nom pour personnalisation
          • fichier SCSS
          • fichier CSS. Compilé automatiquement à partir du SCSS
          • fichier informations (voir la démo de l'action)
      • model ou autre nom : sous-dossier pour regrouper des modèles (par exemple)
        • fichier SCSS
        • fichier CSS. Compilé automatiquement à partir du SCSS
        • fichier informations (voir la démo de l'action)
      • up : fichiers utilitaires de l'action
        • en-GB.ini : traduction anglaise pour la description et les options de l'action.
          Il est possible de créer un fichier pour une nouvelle langue.
        • dico.ini : définition des synonymes pour le nom de l'action et ses options. surchargeable dans custom.
          Compilé par upactionslist avec l'option make-dico dans up/dico.json
        • en-GB.nom_action.html : version anglaise des informations pour le bouton éditeur. Crée par l'action upbtn-makefile
        • fr-FR.nom_action.html : version française des informations pour le bouton éditeur. Crée par l'action upbtn-makefile
        • upbtn-options.ini : description des options pour le bouton éditeur
  • assets : les ressources communes
    • up.css : feuille de style de UP. Générée par upscsscompiler
    • up.scss : fichier pour créer la feuille de style de UP. Non modifiable
    • colorname.ini : fichier références pour l'action color généré par upscsscompiler.
    • colorname-ref.ini : fichier références pour l'action color généré par upscsscompiler.
    • custom : vos préférences
      • _variables.scss : partiel SCSS pour définir vos préférences pour les variables SCSS. ne pas supprimer
      • _variables.scss.dist : modèle pour créer votre fichier custom/_variables.scss
      • _variables.scss.empty : fichier interne. ne pas supprimer
      • _variables.v1.0.scss.bak : sauvegarde du fichier _variables.scss avant mise à jour de UP
    • scss : partiels utilisés par up.scss
      • plusieurs fichiers non modifiables
    • js : fichiers javascript utilisés pas plusieurs actions
      • plusieurs fichiers non modifiables
    • img : images pour up.css et à disposition des actions
      • diverses images
    • overlay : images à disposition des actions pour créer des overlays
      • diverses images
  • language : le dossier des langues conforme à la norme Joomla
    • en-GB
      • en-GB.plg_content_up.ini
      • en-GB.plg_content_up.sys.ini
    • fr-FR
      • fr-FR.plg_content_up.ini
      • fr-FR.plg_content_up.sys.ini
    • xx-XX : vous pouvez créer des traductions selon les usages Joomla
  • upbtn : fichiers pour le plugin éditeur de UP
    • en-GB.actions-list.html : version anglaise de la liste des actions. générée par upactionslist
    • fr-FR.actions-list.html : version française de la liste des actions. généré par upactionslist
    • upbtn.js : script pour le plugin éditeur
    • upbtn.css : feuille de style pour le plugin éditeur
  • custom
    • dico.ini : vos synonymes pour les noms d'actions et leurs options (prioritaire)
  • up.xml : manifest du plugin
  • up.php : fichier principal du plugin
  • upAction.php : helper avec fonctions utilitaires
  • dico.ini : la définition des synonymes pour les noms d'actions et leurs options. surchargeable
  • dico.json : généré par upactionslist avec l'option make-dico à partir des fichiers dico.ini.
  • install.php : script d'installation du plugin

Les adaptations possibles

Options des shortcodes

Vous pouvez créer un fichier prefs.ini dans le dossier custom des actions.

Son contenu permet :

  • de définir la valeur par défaut des options dans la section [options]
[options]
nom_option="valeur par défaut"
  • de créer des jeux d'options pour faciliter la saisie en proposant diverses configurations
[mon-jeu-d-option]
style="border:1px dotted tan"
css-head="#id h4:before[content:'\BB']"
videoAutoPlay=1

Attention : les shortcodes UP sont interdits comme argument

pour proposer des textes en différentes langues, utiliser : lang[en=YES; fr=OUI]

La prise en compte est immédiate

Vous pouvez donner des conseils et instructions à l'aide du fichier help.txt dans le dossier custom des actions.

Elles seront affichées dans la documentation et le bouton des éditeurs (voir Bouton editor-xtd)

SCSS & CSS

UP propose 2 niveaux pour personnaliser le CSS

Les fichiers SCSS doivent être compilés avec l'action upscsscompiler

Les fichiers CSS non générés par un fichier SCSS sont opérationnels immédiatement.

Javascript

Il est possible de surcharger les fichiers Javascript utilisés par UP en créant votre version dans le sous-dossier custom de l'action

Pour surcharger un fichier, il faut :

  1. créer un sous-dossier custom, soit plugins/content/up/actions/NOM_ACTION/custom
  2. dupliquer le fichier à surcharger dans ce dossier
  3. faire les modifications désirées sur la version du fichier dans custom

Note : si le fichier est dans un sous-dossier de l'action, il faut recréer cette arborescence dans le dossier custom.

Exemple :

plugins/content/up/actions/image_gallery/lib/jqPhotoSwipe.js

Le fichier ci-dessus, doit être surchargé ici :

plugins/content/up/actions/image_gallery/custom/lib/jqPhotoSwipe.js

Note : hormis le script principal de l'action (NOM_ACTION.php), quasiment tous les fichiers peuvent être substitués

PHP

Les fichiers PHP ne peuvent pas être surchargés. Vous pouvez dupliquer et renommer une action pour créer votre version.

Dico

UP permet d'utiliser des synonymes / traductions pour le nom des actions et des options dans les shortcodes.

Cela est possible grâce :

  • au fichier up/dico.ini qui contient les synonymes généraux. Vous pouvez le surcharger dans le sous-dossier up/custom.
    Normalement ce fichier n'évoluant plus, votre version sera toujours d'actualité.
  • aux fichiers up/actions/xxx/up/dico.ini que vous pouvez surcharger dans le sous-dossier custom de l'action.

Il faut lancer l'action upactionslist avec l'option make-dico pour régénérer le fichier dico.json à partir de tous les fichiers dico.ini.

Bouton editor-xtd

L'action upbtn-makefile crée les fichiers HTML spécifiques à votre installation à partir :

  • de la liste des actions
  • des commentaires et des options du script principal des actions(et des traductions en-GB) sans possibilité de personnalisation
  • des options par défaut et jeux d'options du fichier actions/ACTIONS/custom/prefs.ini
  • du fichier actions/ACTIONS/up/upbtn-options.ini ou de votre surcharge dans actions/ACTIONS/custom/upbtn-options.ini
  • de vos fichiers d'aide actions/ACTIONS/up/custom/help.txt

Un article pour regrouper les shortcodes de mise à jour

Pour faciliter l'appel des shortcodes d'actualisation, je vous conseille de créer un article accessible par un menu réservé aux administrateurs du site.

Compilation CSS des fichiers SCSS modifiés (principal et actions)
{up upscsscompiler | info}

Intégration de tous les fichiers dico.ini
{up upactionslist | make-dico}

Prise en charge de vos valeurs par défaut, prefsets et help.txt par le plugin xtd-editor
{up upbtn-makefile}
compléter le shortcode avec des options pour inclure ou exclure des actions, définir le top10 et l'ordre d'affichage

Le code ci-dessous exécute directement toutes les mises à jour.

Vous pouvez aussi créer 3 articles pour les 3 shortcodes qui seront appelés par l'article principal
Ci-dessous une idée en mode code de cette page

<p>Compilation CSS des fichiers SCSS modifiés (principal et actions)</p>
<a href="/lien vers article" target="_blank"><b>{</b>up upscsscompiler | info<b>}</b></a>

 

Petit lexique pour bien comprendre mes annotations :

  • ne pas supprimer : le fichier doit exister sous peine d'erreur PHP, JS ou SCSS
  • généré : inutile de modifier ce fichier, il sera recréé à la prochaine compilation
  • surchargeable : il est possible de créer sa version du fichier dans le sous-dossier custom
  • non surchargeable : ce fichier ne peut être ni surchargé, ni modifié

Personnaliser les couleurs de UP

UP dispose d'une feuille de style CSS qui définit des couleurs pour les fonds, les textes, les bordures.

 

Je trouve beaucoup d'avantages à cette méthode :

  • plus besoin de mémoriser des codes
  • uniformisation des couleurs pour toutes les utilisations sur un site
  • possibilité de modifier à postériori une couleur
  • utiliser une couleur au survol sans devoir créer une règle spécifique

Les couleurs proposées par UP ne vous conviennent pas tout à fait.

Aucun souci, il est facile de les adapter à votre gout. Il faudra conserver les noms proposés (qui existent en français et en anglais), mais est-ce un problème une couleur bleue sera toujours dans les bleus.

Depuis la version 2.5, il existe les couleurs primary et secondary qui définissent les couleurs principales du site.

La modification

Il existe dans le dossier plugins/content/up/assets/custom un fichier _variables.scss qui vous permet de saisir vos préférences.

  • Il ne sera jamais écrasé lors d'une mise à jour de UP.
  • Ce fichier, même vide, doit exister pour ne pas générer une erreur lors de la compilation SCSS.

Il existe également un fichier assets/custom/_variables.scss.dist qui vous servira de modèle pour créer le vôtre.

Il contient les valeurs par défaut, mais pour faciliter la relecture, je vous conseille de copier uniquement les couleurs à modifier.


// VARIABLES WEBMASTER // ********************** // ce fichier est un modèle pour créer un fichier _variables.scss spécifique au site // Reprendre uniquement les variables modifiées. Cela évite de bloquer les mises à jours des autres. // Ne pas modifier le nom des variables et de pas en créer de nouvelles //== couleurs de base (utilisé par les fichiers SCSS, ...). On peut utiliser // - le code hexadécimal de la couleur ou les fonctions rga, rgba // - le nom d'une couleur nommée (red, navy, ...) // - des fonctions scss (darken, lighten, ...) $darkBlue : #001f3f; // bleuFonce $blue : #01457F; // bleu $lightBlue : #069; // bleuClair $paleBlue : #BCE0FF; // bleuPale $darkGreen : #006400; // vertFonce $green : #46a546; // vert $lightGreen : #98fb98; // vertClair $darkRed : #8b0000; // rougeFonce $red : #ff1111; // rouge $lightRed : #f08080; // rougeClair $pink : #f012be; // rose $purple : #9400D3; // violet $orange : #ff851b; // orange $darkYellow : #ffc40d; // jauneFonce $yellow : #ffee00; // jaune $lightYellow : #ffffe0; // jauneClair $tan : #E8DAC3; // beige $brown : #a0522d; // brun // -- les gris $black : #000; // noir $darkGrey : #333; // grisFonce $grey : #888; // gris $lightGrey : #bbb; // grisClair $paleGrey : #eee; // grisPale $white : #fff; // blanc // -- la base $primary : $blue; // c1 $secondary : $grey; // c2 //== les ombres $shadow : 0 3px 2px rgba(0, 0, 0, 0.2); $shadowMax : 0 5px 5px 0 rgba(0,0,0,0.25),0 2px 10px 0 rgba(0,0,0,0.16); $shadow-bottom:0 10px 6px -6px rgba(0, 0, 0, .8); // pour action box //== breakpoints pour mediaqueries $breakpoint-s : 480px; $breakpoint-m : 760px; //== espaces et largeurs // - espace : utilisé par ma1, pa2, ... $up-space-0: 0; $up-space-1: 10px; $up-space-2: 24px; $up-space-3: 36px; // - largeurs : utilisé par border (b1, b2, ...) $up-border-0: 0; $up-border-1: 1px; $up-border-2: 2px; $up-border-3: 6px;
 

Le principe

Vous indiquez le nom anglais de la variable SCSS et sa valeur dans un des formats admis :

  • hexadécimal (#rbg, #rrggbb)
  • couleurs nommées (aqua, gray, navy, ...)
  • rgb (rgb(255, 0, 0), rgb(100%, 0%, 0%))
  • fonction SCSS si la variable utilisée est déjà déclarée (lighten, darken, ...)
Attention : le nom de la variable ne doit pas être modifié

La compilation

Une fois les modifications effectuées, il faut recompiler tous les fichiers SCSS de UP.

Le partiel _variables.scss est également utilisé par les actions.

Je vous conseille de créer un article réservé au superadmin pour vous assister dans la mise au point des fichiers CSS. Voici un exemple :

{up color | info}
{up upscsscompiler | force | info}

Il est important que l'appel de l'action upscsscompiler soit en dernier. En effet, UP exécute les actions en commençant par la fin.

L'action color affiche une grille avec toutes les couleurs utilisées par le site avec leurs noms français et anglais ainsi que leurs valeurs.

  1. La bordure supérieure est toujours de la couleur définie à l'origine par UP. Cela vous permet de voir votre modification
  2. la couleur active sur le site
  3. La bordure inférieure est la couleur définie par votre template pour le nom anglais de la couleur.
noir
black
#000
grisFonce
darkGrey
#333
gris
grey
#888
grisClair
lightGrey
#bbb
grisPale
paleGrey
#eee
blanc
white
#fff
bleuFonce
darkBlue
#001f3f
bleu
blue
#01457F
bleuClair
lightBlue
#069
bleuPale
paleBlue
#BCE0FF
vertFonce
darkGreen
#006400
vert
green
#46a546
vertClair
lightGreen
#98fb98
brun
brown
#a0522d
beige
tan
#E8DAC3
rougeFonce
darkRed
#8b0000
rouge
red
#ff1111
rougeClair
lightRed
#f08080
jauneFonce
darkYellow
#ffc40d
jaune
yellow
#ffee00
jauneClair
lightYellow
#ffffe0
orange
orange
#ff851b
rose
pink
#f012be
violet
purple
#9400D3
c0
transparent
transparent
c1
primary
#01457F
c2
secondary
#888

Exemple de rendu de l'action color | info

Une des premières modifications à réaliser est la mise à jour des couleurs $primary et $secondary
Ces 2 couleurs, à la mode bootstrap, sont utilisées pour définir les couleurs principales du site
Il faut lire les noms français c1 et c2 comme couleur-1 et couleur-2.

Créer de nouvelles couleurs

Si vous en éprouvez la nécessité, cela est possible à condition de respecter cette procédure dans votre fichier _variables.scss:

  1. choisir le nom anglais et français de votre nouvelle couleur
  2. $nomAnglais : #rgb;
  3. $nomFrancais : $nomAnglais;
  4. copier la totalité de la définition de la variable $colorlist dans le fichier assets/_variables.scss
  5. coller cette définition dans votre fichier _variables.scss
  6. insérer votre nouvelle couleur. exemple : ("nomFrancais", "nomAnglais", $nomAnglais)

Et pas que les couleurs !

Le fichiers _variables.scss ne sert pas uniquement pour les couleurs. Vous pouvez surcharger toutes les autres variables.

  • les ombres
  • la largeur des bordures
  • l'espace pour les paddings et margins
  • les points de rupture pour les médiaqueries
Dans la terminologie SCSS, un partiel est un fichier commençant par un underscore. Il est importé par le fichier principal

Plugin bouton éditeur

Pour faciliter l'écriture des shortcodes, un plugin éditeur (editors-xtd) est disponible depuis la version 2.1 de UP.

Il doit être téléchargé et installé comme tous les plugins.

Il ajoute un bouton dans tous les éditeurs de Joomla!

UP bouton avec TinyMCE
Up bouton avec TinyMCE
UP bouton avec JCE et les autres éditeurs
Up bouton avec JCE et les autres éditeurs

Ce plugin bouton sert uniquement pour la création d'un shortcode. Les modifications sont à faire directement dans le shortcode.

Sélectionner une action

Upbtn list actions

Un clic sur le bouton, ouvre cette fenêtre popup.

La présentation standard (ci-contre) affiche la liste des options avec les options fréquemment utilisées au début.

Selon les choix du webmaster du site, les actions "top10" et le regroupement peuvent varier.

A l'ouverture, la zone active est la liste.
Cela permet de saisir les premières lettres d'une action pour la sélectionner

Action : infos et saisie des options

 

Upbtn tooltip num
  1. La sélection d'une action affiche ses informations au-dessous.
  2. Un lien permet d'ouvrir un nouvel onglet avec sa page de démo
  3. Une documentation succincte sur l'utilisation et les précautions
  4. Le webmaster du site peut également fournir des informations et conseils spécifiques à votre site
  5. La liste des options proposées par l'action.
    Sa présentation dépend de son type.
    Le survol de son libellé affiche une bulle avec des informations sur l'option.
    Le survol de la valeur affiche la valeur par défaut. Quand cela est possible, cette valeur est affichée en grisé dans le champ.
  6. Si du texte est sélectionné lors du clic sur le bouton, il est considéré comme le contenu de cette action. Il est possible de forcer la fermeture du shortcode en cochant cette case.
  7. Certaines actions utilisent des séparateurs pour les différentes parties du contenu. Indiquez ici leur nombre.
  8. Vous pouvez ajouter une option "debug" pour avoir un message avec les valeurs de l'action en frontend
  9. l'option "?" affiche une aide en frontend.
  10. Et enfin, le bouton pour insérer le shortcode dans votre article ou module personnalisé.

Les types d'options

Dans l'exemple ci-dessus, nous avons les différents types d'options

  • tooltip : l'option principale de l'action permet de saisir du texte, mais également de choisir un jeu d'options si votre webmaster en propose.
    Une liste avec saisie (combo) se reconnait grâce au petit triangle à droite.
    Cette option est sur fond jaune pour montrer son importance et la nécessité de fournir un argument.
  • position : une liste déroulante sans possibilité de saisie
  • width : saisie d'une valeur numérique entière. Il est possible d'indiquer une valeur minimale et maximale.
    notez la présence de l'unité entre parenthèses devant la zone. Il s'agit de l'unité par défaut de l'action. Elle n'est pas reprise dans le shortcode.
  • color : saisie d'une couleur au format #rrggbb. Pour utiliser un autre format, il faudra le modifier dans le shortcode
  • icon : il s'agit d'une liste contenant les fichiers d'un dossier. Utilisé pour choisir un style parmi plusieurs fichiers .css
  • open : un classique oui/non sous la forme d'une liste
  • id : sur fond gris pour indiquer la non-nécessité de saisie.
    Comme head-css, il est précédé d'une ligne pour créer des groupes visuels.

Note : un champ sur fond rouge pâle attire votre attention sur une particularité.

upbtn_makefile : action compagnon

Pour créer et mettre à jour les fichiers utilisés par le plugin upbtn, on utilise l'action upbtn_makefile

Son usage est indispensable si :

  • vous créer des jeux d'options
  • vous ajouter des modèles CSS
  • vous transmettez des conseils avec les fichiers custom/help.txt
  • vous modifiez la présentation de la liste d'action dans le plugin editor
  • vous créer des actions

Voir sa documentation

 

Créer le dossier technique du site

Tous les sites ont besoin d'un dossier technique pour transmettre les informations et bonnes pratiques aux personnes impliquées. Même et surtout si l'on est seul !