L'option css-head, présente dans la majorité des actions, permet d'ajouter des règles CSS dans le head de la page.
Cela permet des personnalisations non prévues par l'action ou la neutralisation d'un style général pour une action.
Le résultat :
Le shortcode :
1 - {up div | class=foo-1 | id=monID
2 - | css-head=
3 - body[background:#ffffe0 !important]
4 - .foo-1[background:#FFD700]
5 - #id[text-align:center; padding:1rem]
6 - \[class^="foo"\][color:var(--rouge)]
} Démo de l'option css-head {/up div}
L'argument attendu par l'option css-head est un classique code CSS.
Comme il est impossible de mettre des accolades dans les shortcodes, elles sont remplacées par des crochets. Pour saisir un crochet, échappez-le avec un antislash (voir ligne 6).
- ligne 1 : on utilise l'action div pour la démo avec la classe foo-1. Comme cette action ne génère pas automatiquement un identifiant, nous l'indiquons pour les besoins de la démo.
- ligne 2 : appel de l'option css-head. les sauts de lignes ne sont pas obligatoire, mais facilitent la lecture.
- ligne 3 : une règle pour modifier la couleur de fond de la fenêtre. L'action color est utilisée pour avoir la couleur jaune claire définie pour le site.
- ligne 4 : on donne la propriété pour la classe foo-1
- ligne 5 : #id, sera remplacé par l'identifiant de l'action (#monID).
- ligne 6 : un exemple de sélecteur utilisant les crochets.
- Détails
UP permet de donner des instructions en mode code ou wysiwyg dans un article ou un module personnalisé à l'aide de shortcodes.
- ❶ Shortcodes
- ❷ Shortcodes annexes
- ❸ Traduction
- ❹ BBcode
- ❺ Options courantes
- ❻ FAQ
{up action=paramètre principal | option=valeur de l'option}
- un shortcode "ouvrant" commence toujours par ❴up (altGr+4 suivi du mot up)
- suivi d'un espace et du nom de l'action à réaliser : action
- si l'action attend un paramètre principal, on l'indique à la suite du signe égal
- il est possible d'indiquer plusieurs options en les séparant par le caractère pipe (altGr+6).
- il se termine toujours par une accolade fermante (altGr+=)
Certaines actions permettent de saisir un contenu de façon habituelle à la suite du shortcode.
On indique la fin de ce contenu par un shortcode "fermant" où le mot up est précédé d'un antislash suivi du nom de l'action :
{/up action commentaire_optionnel}
Le tiret et trait de soulignement ont la même signification.
Shortcodes comme argument
ils sont évalués en commençant par la fin de l'article et les plus inclus en premier.
{up table-par-lignes} ❹
{up csv2table} ❸
{up jnews=8 ❷
| template=##id##;##title##
| new-html={up icon=etoile} ❶
}
{/up csv2table}
{/up table-par-lignes}
Les actions sont autonomes et indépendantes. Cela peut poser des problèmes lorsqu'une action enfant ajoute directement du code dans le head. Dans ce cas, utilisez l'option filter de l'action.
Attention Il n'est pas possible de mettre des shortcodes comme argument d'une option dans le fichier prefs.ini
Les shortcodes séparateurs
ils sont utiliser pour isoler les différentes parties du contenu situé entre le shortcode ouvrant et fermant. Cette méthode est plus visuelle et facilite la saisie dans un éditeur comme TinyMCE ou JCE
{up filter | guest}
vous êtes invité
{===}
vous êtes identifié
{/up filter}
{up flexauto=2}
bloc 1
{=== commentaire}
bloc 2
{/up flexauto}
Pour être reconnu, un séparateur doit commencer par une accolade suivi de 3 signes égal et se terminer par une accolade.
Il est permis d'ajouter un commentaire avant l'accolade fermante ❴====== commentaire❵
Shortcodes internes ou secondaires
Utilisés pour fournir des informations optionnelles, ils sont insérés entre les shortcodes ouvrant et fermant. Ils ne commencent pas par up. Voir la documentation des actions concernées.
{up osmap=48.865, 2.30}
{marker=48.8709, 2.33223 | popup-text=... }
{/up osmap}
Tous les arguments des options peuvent être fournis en plusieurs langues en utilisant une de ces 2 méthodes :
{up hr
| icon=lang[en=/images/icons/32/gb.png;fr=/images/icons/32/france.png;de=/images/icons/32/germany.png]
| icon-text=lang[en=Hello;fr=Bonjour;de=Hallo]
}
{up hr
| icon=/images/icons/32/{up lang | en=gb | fr=france | de=germany}.png}
| icon-text={up lang |en=Hello | fr=Bonjour | de=Hallo}
}
La première méthode nécessite que l'argument débute par lang[
. On peut l'utiliser dans un fichier prefs.ini
La deuxième est plus simple d'utilisation, mais son usage est limité aux shortcodes.
Si aucune langue ne correspond à celle de l'internaute, c'est la première langue qui sera utilisée.
Le bbcode permet de saisir facilement et en toute sérénité du code HTML dans un éditeur.
Le principe :
on écrit du code HTML en remplaçant certains caractères pour qu'un éditeur wysiwyg ne les interprète pas.
Exemple : un mot en <b>gras</b>
affiche le code ou le résultat, alors que un mot en [b]gras[/b]
transmet le code à UP
Vous pouvez utiliser le bbcode de 2 façons :
- comme argument des options qui l'accepte. Consulter leur documentation.
- en utilisant l'action bbcode. exemple :
{up bbcode=un mot en [b]gras[/b]}
affiche un mot en gras
Un petit résumé des règles :
- par défaut, seules les balises les plus courantes sont prises en charge :
br,p,div,span,b,i,u,img,quote,ul,ol,li,code,tt,kbd
- on utilise le nom des balises HTML en remplaçant les <> par []
- pour afficher des crochets, on ajoute un antislash devant. Exemple :
\[
- pour les actions acceptant la saisie au format CSV, il faut doubler les guillemets doubles ou utiliser des guillemets simples.
Exemple :[b class=""t-rouge""]rouge[/b]
ou[b class='t-rouge']rouge[/b]
- les entités HTML neutralisées par les éditeurs Wysiwyg sont restaurées.
Exemple :dans TynyMCE vous saisissez
, il est converti et enregistré sous la forme&nbsp;
, UP le restaure
option=1 ou option (sans argument) sont considérées comme vraie, option=0 est considérée comme fausse.
id : identifiant du bloc principal de l'action. UP le crée automatiquement, mais vous pouvez le forcer si vous avez besoin de le réutiliser pour une autre action (ex: addcsshead)
? : affiche un résumé des commandes l'action dans la langue de l'utilisateur ainsi que les prefset définis par le webmaster.
debug : affiche la liste des options avec les valeurs actuelles. Celles par défaut et celles saisies dans le shortcode. En fin de message, vous trouverez la liste des prefset définis pour votre site.
prefset : permet d'appliquer un ensemble d'options par un nom explicite et facile à retenir. Un jeu d'options (prefset) peut aussi être appelé comme argument de l'option principale. {up hr=param}
et {up hr | prefset=param}
produisent le même résultat.
style, class : propriétés CSS ou nom(s) de classe pour le bloc principal de l'action. UP accepte que l'on mélange des noms de classes et des propriétés CSS : class=color:red;bg-yellow est valide.
Les accolades sont interdites à l'intérieur du shortcode. Pour indiquer la règle CSS a[title]{color:red}
, on doit écrire a\[title\][color:red]
xxx-style, xxx-class : propriétés CSS ou nom(s) de classe pour l'élément indiqué (ex: titre-class).
xxx-style-*, xxx-class-* : style et class par défaut pour tous les éléments. exemple : col-class-*=t-bleu
toutes les colonnes de la table en bleu. : col-class-6=t-rouge
la 6è colonne en rouge. 12 éléments maximum.
css-head : ajoute des règles CSS dans le head de la page. exemple : css-head=body[background:pink] #id a[text-decoration:underline] \[class^="foo"\][color:red]
les accolades {} sont remplacées par des crochets []. #id, sera remplacé par l'identifiant de l'action. Pour saisir un crochet, échapper-le avec un antislash.
filter : n'exécute pas l'action si une des conditions est fausse. exemple : filter=motclé:condition;!motclé:condition;...
le point d'exclamation inverse le sens de la condition
Le shortcode est visible sur la page générée.
- le plugin n'est pas activé
- espace entre l'accolade et le mot up
- l'accolade est en gras. Classique après un copier-coller depuis ce site.
le shortcode ne semble pas fonctionner
- oubli du slash devant le up du shortcode fermant
- le nom de l'action dans le shortcode fermant est différent de celui dans le shortcode ouvrant
message : contenu non trouvé
- le shortcode fermant est incorrect
les options ne sont pas prises en compte
- deux-points (au lieu du signe égal) comme séparateur paramètre/valeur. UP devrait vous le signaler par un message indiquant qu'il ne connait pas l'option. En cas de doute, penser à ajouter debug dans les options pour savoir ce que UP comprend!
comportement bizarre
- peut-être un ajout involontaire de balise HTML lors d'un copier-coller ou par l'éditeur (vérifier en mode code). Normalement, UP nettoie les balises inutiles avant de transmettre les infos à l'action.
- Avec un éditeur wysiwyg, le shortcode ouvrant est dans une balise P et le fermant dans une balise DIV
UP ne reconnait pas cette option : =1
- vous avez un caractère pipe (alt-gr+6) en trop dans le shortcode
- Détails
La surcharge permet de remplacer un fichier de UP par votre version sans risque qu'il soit écrasé à la prochaine mise à jour.
Tous les fichiers d'une action sont dans un sous-dossier au nom de l'action à cet emplacement : plugins/content/up/actions
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
- Détails
L'action bbcode permet de saisir facilement et en toute sérénité du code HTML dans un éditeur.
Le principe :
on écrit du code HTML en remplaçant certains caractères pour qu'un éditeur wysiwyg ne les interprète pas.
Exemple : un mot en <b>gras</b>
affiche le code ou le résultat, alors que un mot en [b]gras[/b]
transmet le code à UP
Vous pouvez utiliser le bbcode de 2 façons :
- comme argument des options qui l'accepte. Consulter leur documentation.
- en utilisant l'action bbcode. exemple :
{up bbcode=un mot en [b]gras[/b]}
affiche un mot en gras
Un petit résumé des règles :
- par défaut, seules les balises les plus courantes sont prises en charge :
br,p,div,span,b,i,u,img,quote,ul,ol,li,code,tt,kbd
- on utilise le nom des balises HTML en remplaçant les <> par []
- pour afficher des crochets, on ajoute un antislash devant. Exemple :
\[
- pour les actions acceptant la saisie au format CSV, il faut doubler les guillemets doubles ou utiliser des guillemets simples.
Exemple :[b class=""t-rouge""]rouge[/b]
ou[b class='t-rouge']rouge[/b]
- les entités HTML neutralisées par les éditeurs Wysiwyg sont restaurées.
Exemple :dans TynyMCE vous saisissez
, il est converti et enregistré sous la forme&nbsp;
, UP le restaure
- Détails
motclé | description | type valeur |
---|---|---|
datemax | vrai jusqu'à cette date | AAAAMMJJHHMM |
datemin | vrai à partir de cette date | AAAAMMJJHHMM |
period | vrai entre ces dates. Si l'année est omise, le test est fait pour l'année en cours. Exemple: 1224,01021000 = du 24 décembre minuit au 2 janvier de l'année suivante à 10h | AAAAMMJJHHMM, AAAAMMJJHHMM |
day | liste des jours autorisés. | 1,7 -> lundi ou dimanche |
month | liste des mois autorisés | 1,2 -> janvier ou février |
hmax | vrai jusqu'à cette heure | HHMM |
hmin | vrai à partir de cette heure | HHMM |
hperiod | vrai entre ces plages horaires (liste possible) | HHMM-HHMM |
guest | vrai si l'internaute n'est pas identifié (invité) | 1|0 |
admin | vrai si un admin est connecté | 1|0 |
user | liste des userid autorisés | 8,12 |
username | liste des username autorisés | ex: admin,lomart |
group | liste des usergroup autorisés | 8,12 |
lang | liste des langages autorisés. Seule une partie du code est nécessaire | ex: fr,ca |
mobile | vrai si le site est affiché sur un mobile | 1|0 |
homepage | vrai si le shortcode est affiché sur la page d'accueil | 1|0 |
server-host | vrai si l'argument figure dans le nom du serveur hôte. exemple: server-host:.lomart.fr (un sous-domaine de lomart.fr) |
tout ou partie du nom |
server-ip | vrai si l'IP correspond à une de la liste. localhost, ::1, 192.168.0.1 pour des serveurs locaux | adresse IP |
equal | vrai si op1 = op2. Exemple: equal=1,1 est vrai, equal=!1,1 est équivalent à différent | |
smaller | vrai si op1 > op2. Exemple: smaller=2,1 est vrai. smaller=!2,1 est équivalent à plus grand ou égal | |
bigger | vrai si op1 < op2. Exemple: bigger=1,2 est vrai. bigger=!1,2 est équivalent à plus petit ou égal |
- Une condition, comme argument d'une option filter 1, s'exprime en indiquant le type de condition (mot-clé), suivi du signe 2 points et de la valeur. filter=
datemax:20191225
- Plusieurs conditions sont possibles en les séparant par des points-virgules.
filter=!day:6,7;hperiod:9-12
- >Pour inverser le sens de la condition, il suffit d'ajouter un point d'exclamation devant le type de condition.
filter=!admin
oufilter=!group:8
- Un mot-clé sans valeur est équivalent à
filter=mot-clé:1
(ou vrai). Une condition fausse s'exprime parfilter=mot-clé:0
oufilter=!mot-clé
. - Pour les dates, la partie heure (HHMM) est optionnelle.
1 L'action filter permet également d'utiliser une autre forme. Voir filter ~ afficher sous conditions
- Détails
- ❶ Options par défaut
- ❷ Jeux d'options
- ❸ CSS
- ❹ JS
- ❺ PHP
- ❻ Traduction
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
- Détails