frendeitpt

css-head

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 :

Démo de l'option css-head

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.

Les shortcodes

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 shortcode peut être sur plusieurs lignes pour faciliter la lecture
  • le nom des actions et options n'est pas sensible min/maj.
    Le tiret et trait de soulignement ont la même signification.
  • le nom des actions et options peut avoir des synonymes. Ils sont indiqués entre parenthèses dans la documentation des actions
  • une option sans argument est considérée comme égal à vrai ou 1. 0=Faux
  • l'argument d'une option et/ou le contenu peut contenir une autre action UP

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 &nbsp;, il est converti et enregistré sous la forme &amp;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

datemax vrai jusqu'à cette date (AAAAMMJJHHMM) datemin vrai à partir de cette date (AAAAMMJJHHMM) period vrai entre ces dates (si année omise, test pour année courante) (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 internaute non identifié admin vrai si admin user liste des userid autorisés (8,12) username liste des username autorisés (admin,lomart) group liste des usergroup autorisés (8,12) lang liste des langages autorisés. (fr,ca) mobile vrai si affiché sur mobile homepage vrai si page d'accueil server-host vrai si argument figure dans le nom du serveur hôte (ex: server-host:.lomart.fr (un sous-domaine de lomart.fr) server-ip vrai si IP dans la liste (localhost, ::1, 192.168.0.1)

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

 

Surcharger un fichier

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 :

  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

bbcode ~ syntaxe

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 &nbsp;, il est converti et enregistré sous la forme &amp;nbsp;, UP le restaure

Filter ~ liste des conditions

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
  • 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. datemax:20191225
  • Plusieurs conditions sont possibles en les séparant par des points-virgules. 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. !admin
  • Un mot-clé sans valeur est équivalent à mot-clé:1 (ou vrai). Une condition fausse s'exprime par mot-clé:0 ou !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

Personnaliser UP

  • ❶ 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
  1. créer un fichier prefs.ini en UTF-8 no-BOM sans un sous-dossier custom du dossier de l'action
  2. 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 :

  1. option saisie dans le shortcode
  2. argument du jeu d'option
  3. argument par défaut (section options du prefs.ini)
  4. 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 :

  1. créer un sous-dossier custom dans le dossier de l'action concernée
  2. dupliquer le fichier CSS, SCSS ou JS à personnaliser dans ce sous-dossier. Ne pas modifier son nom.
  3. 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 :

  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

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 :

  1. dupliquer le dossier de l'action originale en le renommant au nom de votre action. Exemple: mon_action
  2. renommer le fichier PHP principal. Il doit avoir le même nom que le dossier
  3. 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