Composition des shortcodes

Le shortcode vous permet de donner des instructions à UP.
Quelle que soit l'action, la manière de le rédiger suit les mêmes règles.
Les comprendre vous fera gagner beaucoup de temps dans votre apprentissage de UP.

Le principe

  • {up   l'identifiant du plugin pour la recherche du shortcode dans les articles et modules.
    On peut indiquer des alternatives à up dans les paramètres du plugin, même si je n'en vois plus trop l'utilité.
  • une suite d'option=argument séparés par des caractères pipes (AltGr+6).
  • la première option est le nom de l'action
  • une option sans argument est considérée comme égal à vrai ou 1. 0=Faux; exemple: admin=0 signifie n'est pas admin
  • le shortcode peut être sur plusieurs lignes pour faciliter la lecture
  • on peut saisir le nom des options sans se soucier de la case, ils sont évalués en minuscules.
  • le programmeur de l'action peut définir des alternatives pour le nom de l'action et des options.
    Par exemple: table-par-lignes crée une instance de la classe table_by_rows

Des shortcodes entourant un contenu.

Dans les démonstrations, j'utilise l'expression shortcode ouvrant pour le premier qui contient les options.
Celui après le contenu est nommé shortcode fermant. Le nom de l'action doit être le même que celui du shortcode ouvrant.

Exemple {up table-par-lignes} <table> ...</table> {/up table-par-lignes}

Ce contenu peut-être un autre shortcode

{up table-par-lignes}
   {up csv2table}
      {up jnews=8 | pref=list}
   {/up csv2table}
{/up table-par-lignes}

Shortcode séparateur

Pour certaines actions, le contenu entre les shortcodes peut contenir plusieurs parties comme les éléments pour les panneaux d'une boîte à onglets (tab) ou les des textes alternatifs selon le résultat d'un test (filter).

{up filter | admin} je suis un admin {=====} je ne suis pas un admin {/up filter}

Cela permet une saisie entièrement en wysiwyg.

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 comme dans cet exemple: {======= commentaire}

Les shortcodes secondaires.

Une action peut avoir besoin qu'on lui fournisse des informations optionnelles dont la quantité est indéfinie. C'est le cas pour OSMap qui utilise le shortcode marker pour avoir la liste des marqueurs a afficher sur la carte. Ces sous-shortcodes 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=[b]Opéra de Paris[/b][br]Place de l'Opéra}
{/up osmap}

Des shortcodes comme argument

Il est possible de mettre le shortcode d'une action comme argument pour l'option d'une autre action.

{up readmore={up icon=plus} lire la suite}

Dans cet exemple, on ajoute une icône devant le texte du bouton à l'aide de l'action icon.

Attention Il n'est possible de mettre des shortcodes comme argument d'une option dans le fichier prefs.ini

Je n'ai pas d'exemple d'utilisation, mais une construction comme celle-ci est possible .... et elle fonctionne : la preuve !

{up readmore=
   {up icon=
      {up php=echo 'pl'.'us';}
   } 
  voir un exemple tiré par les cheveux ...
  | textless={up icon=Ux26d4} Super 
}

Ordre d'évaluation des shortcodes

les shortcodes sont évalués en commençant par la fin de l'article et les plus inclus en premier.

Les shortcodes
{up table-par-lignes} 
   {up csv2table} 
      {up jnews=8  
          | template={id};{title} 
          | new-html={up icon=etoile} 
      }
   {/up csv2table}
{/up table-par-lignes}
L'ordre d'évaluation
  • ❶ action icon. l'option new-html contiendra, comme argument, le code HTML pour afficher une étoile [2777,#369

Cet exemple démontre bien la méthode d'analyse retenue par UP.
Il n'existe pas de relation directe ou échange d'information entre les actions. Elles sont toutes autonomes et indépendantes.
Elles récupèrent simplement du contenu comme vous auriez pu le saisir manuellement.

Attention cela peut poser des problèmes lorsqu'une action enfant ajoute directement du code dans le head.

Un exemple pour mieux comprendre :

Les shortcodes
{up filter=period:1220-1226} 
   {up snowfall=images/noel} 
{/up filter}
L'ordre d'évaluation
  • ❶ action snowfall. ajoute du code css et js dans le head de la page sans retourner de contenu. [2777,#369

Pour répondre à ce problème, les actions concernées ont (ou auront) une option filter. Il faut utiliser la forme

{up snowfall=images/noel | filter=period:1220-1226}

D'autres infos

164 Premiers pas
128 Les options courantes
connaitre les options, présentes dans beaucoup d'actions, qui ont les mêmes noms et effets
55 Les erreurs fréquentes
c'est souvent des fautes de frappe ou d'inattention