UP-LOMART - Personnaliser UP

UP définit des valeurs par défaut pour les options des actions.

Le webmaster peut indiquer ses préférences dans un fichier /custom/prefs.ini.

Cela permet d'adapter le style au site et facilite la saisie des shortcodes par les rédacteurs

En pratique

créer un fichier prefs.ini en UTF-8 no-BOM sans un sous-dossier custom du dossier de l'action
dans la section options, ajouter vos valeurs par défaut sous une forme identique à celle du shortcode. Une par ligne, pas de pipe (|).

[options]
nom_action="argument"
nom_option="argument"

Le fichier prefs.ini peut contenir d'autres informations

des clés de licence. exemple: google-map, osmap, ...
des raccourcis pour des arguments d'option. exemple: hr, icon, ...
des jeux d'options. exemple: hr, ...

Un jeu d'options (ou prefset) permet de définir plusieurs options du shortcode avec son nom.

Pour obtenir la ligne ci-dessus, on ajoute au fichier prefs.ini une section typo-feuille qui contient un ensemble d'options argumentées.

[i-love-up]
icon-text="I\2764UP"
icon-color="red"
fontname="cursive"
hr-width="80%"
hr-bg="linear-gradient(90deg, rgba(255,255,255,1) 0%, rgba(255,0,255,1) 15%, rgba(255,0,255,1) 30%, rgba(255,255,255,1) 50%, rgba(255,0,255,1) 70%, rgba(255,0,255,1) 85%, rgba(255,255,255,1) 99%, rgba(255,255,255,1) 100%)"
hr-height="2px"

Pour l'utiliser, il suffit d'indiquer le nom de la section comme argument principal

{up hr=i-love-up}

Il est aussi possible de l'utiliser avec l'option prefset. Cette méhode est obligatoire pour passer un argument à l'option principale. Voir les 2 exemples ci-dessous

{up hr | prefset=i-love-up}
{up file-download=Mon_Fichier.pdf  | prefset=Mon_Jeu_dOptions}

Si vous avez oublié le nom du jeu d'options, ajouter debug ou ? au shortcode puis appeler la page en frontend. Vous aurez la liste de toutes les sections définies pour l'action.

Si vous spécifier une option dans le shortcode, elle sera prioritaire sur la valeur définie dans le jeux d'options.

Ordre de priorité pour la prise en compte des arguments des options :

option saisie dans le shortcode
argument du jeu d'option
argument par défaut (section options du prefs.ini)
argument défini par le développeur de l'action

Si le fichier prefs.ini n'est pas reconnu, vérifiez la présence des guillemets

Vous désirez uniquement modifier le ou les fichiers CSS pour avoir un rendu différent de celui proposé par défaut.
UP propose un mécanisme très simple :

créer un sous-dossier custom dans le dossier de l'action concernée
dupliquer le fichier CSS, SCSS ou JS à personnaliser dans ce sous-dossier. Ne pas modifier son nom.
adapter le contenu selon vos envies.

Vous continuez à bénéficier des mises à jour de UP pour les fichiers 'non customisés'.
Toutefois, regarder dans le changelog si des modifications ont une incidence sur vos personnalisations. C'est le cas lors d'ajout de fonctionnalités.

Prise en charge du SCSS

Si vous préférez faire vos modifications en SCSS, il suffit de le dupliquer (ou le créer) dans le sous-dossier custom.
Il sera automatiquement compilé lors de l'appel d'une action scss-compiler.

Attention : si le fichier SCSS fait des importations de partiels, il peut être nécessaire d'adapter le chemin. Dans la majorité des cas, il suffit d'ajouter ../ au début du chemin

@import "../../assets/variables"; devient @import "../../../assets/variables";

En cas de souci, pour revenir au comportement par défaut, il suffit de modifier le nom du sous-dossier custom ou d'un fichier pour qu'il ne soit plus pris en compte.

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 :

créer un sous-dossier custom, soit plugins/content/up/actions/NOM_ACTION/custom
dupliquer le fichier à surcharger dans ce dossier
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

Vous désirez modifier le comportement d'une action en modifiant son fichier PHP ou créer une nouvelle action en utilisant une autre action comme modèle.

L'opération nécessite 3 étapes :

dupliquer le dossier de l'action originale en le renommant au nom de votre action. Exemple: mon_action
renommer le fichier PHP principal. Il doit avoir le même nom que le dossier
renommer la classe principale de ce fichier avec le nouveau nom de l'action

Ensuite, c'est à vous de jouer pour créer une action toute neuve!

N'oubliez pas de supprimer ou de mettre à jour le lien vers la page de démo.

vous ne prévoyez pas de page de démo : supprimer la ligne $this->set_demopage();
vous créez une page de démo sur votre domaine : indiquer l'url complête
$this->set_demopage('https://monsite.fr/mademo');
la démo de l'action d'origine est toujours valide : ne changer rien

N'oubliez pas de documenter votre code, pour que l'action upactionslist puisse l'afficher.

Vous ne bénéficiez plus des mises à jour de UP.

Pour traduire dans une autre langue, il suffit de dupliquer le fichier en-GB.ini du sous-dossier UP pour votre langue, puis de traduire les textes explicatifs.

Modifier le nom de l'action ou des options

Vous ne pouvez pas supprimer le nom de l'action ou de ses options, mais vous pouvez créer des synonymes dans le fichier up/dico.ini en les ajoutant (un par ligne) sous la forme mot-nouveau=mot-connu. Exemple : jnews=jcontent_by_categories

Attention ces adaptations sont globales au plugin. Si vous ajouter la correspondance breite=width pour traduire largeur en allemand, ce changement sera utilisable par toutes les autres actions

Pour regrouper ces changements, il est nécessaire de lancer l'action upactionslist avec l'option make-dico. Tous les fichiers dico.ini des actions sont regoupés en un seul fichier dico.json à la racine du plugin.

Les synonymes existants sont visibles dans la petite barre bleue de la documentation du site

Voir aussi Gestion des traductions

action color : informations sur les couleurs UP
Personnaliser les couleurs de UP