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

La prise en compte est immédiate

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
  • du fichier actions/ACTIONS/up/options.ini ou de votre surcharge dans actions/ACTIONS/custom/options.ini
  • de vos fichiers d'aide actions/ACTIONS/up/custom/help.ini

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é