Les mots-clé définis par UP

A partir de la version 3.1, UP propose une prise en charge étendue de ses traditionnels ##mots-clés## en permettant l'ajout d'un modèle, d'une condition ou d'une valeur de remplacement.

Pour rappel, le template ceci est un ##motcle##, retourne :

  • ceci est un LION, si la valeur est LION
  • ceci est un , si la valeur était vide.

Un modèle

Améliorons le rendu pour une valeur vide en ajoutant un modèle au mot-clé.
Le modèle doit être séparé du mot-clé par un unique # entre 2 espaces.
L'emplacement de la valeur est indiqué par %%.

##motcle # ceci est un %%## remplace les 2 caractères pourcentage par la valeur, comme dans la méthode simple. Si la valeur est une chaine vide, rien n'est affiché.

Si l'on veut conserver les autres éléments du modèle pour une valeur vide, il faut utiliser la méthode traditionnelle.

ceci est un ##motcle # [b style="color:red"]%%[/b]##

Le texte "ceci est un" sera toujours affiché, mais le style gras-rouge, sans intérêt pour une chaine vide, ne le sera pas.

Le modèle peut contenir du BBCode si le template est une option du shortcode.
Le BBCode et le HTML sont possibles si le contenu entre les shortcodes de l'action est utilisé comme template.

Note : si les caractères %% ne figurent pas dans le modèle, il sera ignoré. Le retour contiendra uniquement la valeur.

Les conditions

Pour attirer l'attention, il peut être souhaitable d'afficher un résultat seulement si la valeur est celle attendue.

Une condition s'exprime en ajoutant, à la suite du mot-clé, un opérateur de comparaison suivi de la valeur attendue :
= égalité, ! différent de,  > supérieur, <  inférieur ou égal.

Un exemple : pour mettre en évidence uniquement les articles qui sont non indexés pour les robots :

##index=noindex## affiche seulement noindex et aucune autre valeur.

Pour mettre en évidence un état, il suffit d'ajouter un modèle. 

##index=noindex # [span style="color:red"]%%[/span]##

Un autre exemple : on veut avoir une valeur en rouge si elle dépasse un seuil. Pour cela, nous utilisons 2 fois le mot-clé :

##size>165 # [span style="color:red"]%%[/span]## 
##size<165 # [span style="color:green"]%%[/span]## 

Les valeurs de remplacement

Pour afficher l'état d'un article, Joomla utilise des valeurs numériques difficilement compréhensives.

Un mot clé de cette forme rend tout de suite le résultat plus sympathique.

##state[-2:poubelle,0:dépublié,1:publié,2:archivé]##

Le crochet ouvrant annonce l'énumération de valeur réelle, d'un deux-points et de la valeur affichée séparée par des virgules. Le crochet fermant est optionnel.

Il est permis d'utiliser des caractères Unicode, des fonticon ou des images :

##state[-2:&#x2589;,0:&#x2705,1:&#x1F534;,2:&#x1F4CC] ##
##state[-2:trash,0:publish,1:unpublish,2:archive] # [i class="fa fa-%%"][/i]##
##state[-2:trash,0:publish,1:unpublish,2:archive] # [img src="/images/icon/%%.png"]##

Il est possible de mettre du BBcode :

##state[-2:[i class="t-grey"]&#x2589;[/i],0:[i class="t-red"]&#x2705[/i],1:[b class="t-green"]&#x1F534;[/b],2:[i class="t-orange"]&#x1F4CC[/i]] ##

On peut aussi utiliser d'autres options de UP pour préparer le shortcode

template=##state[-2:{up icon=trash},0:{up icon=play;green},1:{up icon=play;red},2:{up icon=archive}]##
template=##state{up snippet=state.html}##

Ce dernier exemple utilise une nouvelle fonction de UP qui charge un fichier modèle. Dans notre cas, il pourrait contenir  :

[-2:trash,0:publish,1:unpublish,2:archive] # [img src="/images/icon/%%.png"]

Astuces

Si la valeur n'est pas trouvée dans la liste, elle sera affichée directement.

Une valeur de zéro n'est pas considérée comme vide. Pour ne pas l'afficher, il suffit de d'utiliser : ##motcle[0:]##

Pour afficher une indication de valeur vide (''),  ##motcle[:sans argument]##

En résumé, un mot-clé est composé de :

  • 2 caractères ##
  • le mot-clé indiqué dans la documentation de l'action
  • une éventuelle condition commençant par le signe =!<>[
  • un modèle de rendu séparé du mot-clé ou de la condition par espace + signe # + espace
  • 2 caractères ##

Les champs personnalisés (CustomFields)

Les actions jcontent-xxx permettent d'afficher les custom-fields.

Pour spécifier un custom-field, il suffit de mettre son nom ou ID comme mot-clé.
Exemple pour un CF nommé couleur d'ID=3, l'appel pourra être ##couleur## ou ##3##

Custom fields simples

La valeur brute (rawvalue) du CF est retournée.

Si le CF est une liste, tous les éléments, séparés par des virgules, sont retournés.

Si le nom est suivi d'un underscore et de la position recherchée, seule cette valeur est retournée.
Une valeur négative indique une position par rapport à la fin de la liste.
Exemple pour le 2ᵉ élément d'un imagelist : ##images_2## ou pour le dernier ##images_-1##

Condition et modèle

L'ajout d'une condition ou d'une mise en forme (model) utilise la même méthode que pour les mot clés classiques.
Exemple pour afficher la valeur brute d'un CF de type color dans sa couleur :
##couleur # valeur: [span style="color:%%"]%%[/span]##

Pour forcer la donnée affichée, il suffit de mettre son nom entre les 2 signes pourcentage.
Exemple : ##couleur # %label%: %rawvalue%## affiche le label du CF interne, un signe 2 points et sa valeur brute.

Si un modèle est spécifié pour une liste, il sera appliqué à chaque élément.
Ce shortcode permet d'ajouter un filet rouge autour de chaque image :
{up jcontent-info | template=##my-imagelist # [img class="bd-red bd2" src="images/%directory%/%%"]##}

Chaque type de customField propose un ensemble de données que l'on configure dans "contenus > champs" du backend de votre site.

Son nom peut être connu avec l'inspecteur de code de votre navigateur. Exemple avec l'option "Répertoire" d'un CF de type "imagelist"

Les données courantes pour les CF de base de Joomla sont : value, rawvalue, title, type, name, label, description, required, directory, multiple, image_class

Custom fields "sous-formulaire"

Le type de champ "subform" permet de regrouper plusieurs CF dans un groupe éventuellement répétable.

Sans mention d'un CF interne, UP affichera le rendu tel que prévu par Joomla (value)
Pour afficher toutes les données d'un groupe du subform, on ajoute un underscore et la position de la ligne.
Exemple : ##subform_1## affiche toutes les données de la première ligne. (-1 pour la dernière ligne, -2 pour l'avant -dernière,...)
Pour éviter une confusion entre l'ID du CF interne et l'indice, il est permis de mettre 0 pour l'ID du CF
Exemple : ##subform_0_1## affiche toutes les données de la première ligne

Il est possible d'indiquer un CF interne en ajoutant son ID (pas son nom) séparé par un underscore.
Il est obligatoire d'ajouter la position de la ligne du subform
Exemple ##subform_3_-1## pour la valeur du CF interne couleur (id:3) de la dernière ligne du subform
Pour avoir toutes les valeurs d'un CF interne, mettre 0 comme position :
Exemple ##subform_3_0## pour toutes les valeurs du CF interne d'id 3 du subform

saisie rawvalue value simple value liste
##subform## value forcée value value tous les CF internes de toutes les lignes
##subform_X## sep virgule value ligne X value tous les CF internes de la ligne X (idem subform_0_X)
##subform_X_0## sep virgule rawvalue model repete model les valeurs du CF interne X pour toutes les lignes du subform (avec doublons éventuels)
##subform_X_Y## sep virgule rawvalue model rawvalue model la valeur du CF interne X pour la ligne Y du subform

Condition et modèle

La méthode générale est applicable, sauf pour les points suivants :

  • %value% et %rawvalue% ne sont pas disponibles pour le modèle.
    %% affiche la représentation valide, soit value pour le subform ou une de ses lignes et rawvalue pour les CF internes
  • Il n'est pas prévu de conditionner l'affichage de CF internes à la valeur de l'un d'entre eux.
    Exemple: si le CF nombre est plus grand que 100, on affiche l'image d'un autre CF interne
  • les variables  (ex: directory, label, ...) disponibles sont celles du subform. Il n'est pas possible d'accéder à celles des CF composant le subform.

Afficher la liste des champs

Les noms utilisables entre les signes pourcentages et leur valeur actuelle peuvent être connus en utilisant le nom ou id du CF suivi d'un underscore et du mot info. Exemple: ##form1_info##

En résumé, un mot-clé pour un custom field est composé de :

  • 2 caractères ##
  • son nom ou id
  • si le CF est de type subform, id du CF interne (optionnel)
  • la position de l'élément désiré pour une liste
  • une éventuelle condition commençant par le signe =!<>[
  • un modèle de rendu séparé du mot-clé ou de la condition par un signe # entre 2 espaces
    %% est remplacé par la valeur brute (rawvalue).
    %xxx% est remplacé par la valeur xxx du CF. (value, rawvalue, label, ...)
  • 2 caractères ##

Les custom-fields de base de Joomla

Sauf impossibilité évidente ou demande explicite par le modèle, la valeur brute (rawvalue) sera retournée.
Pour les listes, les valeurs brutes seront séparées par une virgule. Si un modèle est fourni, il sera répété pour chaque valeur.

Afin de faciliter la compréhension du tableau pour les valeurs multiples, j'utilise une liste de type array (1"=>"un", "2"=>"deux, etc)

La méthode qui permet de déterminer l'affichage d'un CF est générique afin de pouvoir l'utiliser pour d'autres CF (non Joomla core).

custom-field rawvalue simple rawvalue multiple value simple value multiple
calendar JJ/MM/AAAA HH:MM:SS impossible JJ/MM/AAAA impossible
checkboxes 1 1,2 un un,deux
color #rrggbb impossible #rrggbb impossible
editor HTML plugin contenu brut impossible HTML plugin contenu interprété impossible
integer 1 1,2 1 1,2
list 1 1,2 un un,deux
imagelist img1.jpg img1.jpg,img2.jpg HTML img HTML img sans sep
media chaine json impossible HTML impossible
radio 1 impossible un impossible
sql AS value impossible AS text impossible
subform JSON impossible HTML impossible
text texte  plugin contenu brut impossible texte  plugin contenu brut impossible
textarea texte  plugin contenu brut impossible texte plugin contenu interprété impossible
url URL brute impossible HTML impossible
user ID user impossible nom user impossible
usergrouplist ID group1 ID group1,ID group2 nom group1 nom group1, nom group2