Créer une action

Création d'une action simple

Le dossier plugins/content/up/actions/_example_simple est le modèle à utiliser

Les opérations minimales et prioritaires sont:

  1. choisir un nom pour la nouvelle action. il doit être entièrement en minuscule. Les underscores (tiret du 8) sont permis.
    Si votre action concerne les images, préfixez-la par image. Inspirez-vous des noms des actions existantes.
    Pour info: la saisie du nom de l'action dans le shortcode est non sensible à la case et les tirets seront convertis en underscores.
    En option, le nom peut être traduit dans le fichier dico.json. {up bonjour-le-monde} sera compris comme {up hello_world}
    Dans cette explication, nous utiliserons monaction
  2. créer un dossier monaction dans le dossier plugins/content/up/actions
  3. copier le script plugins/content/up/actions/_exemple_simple/_exemple_simple.php en monaction.php
  4. renommer la classe de ce script (_exemple_simple) en monaction
  5. indiquer au début du script, sa fonction et les informations utiles. Elles seront utilisées pour la documentation automatique.

Votre nouvelle action est prête !

Le shortcode {up monAction | class=foo | style=color:red}contenu{/up monAction}

renverra le code html <div class="foo" style="color:red">contenu</div>

Enrichir votre action

Votre classe "action" dispose des propriétés suivantes :

  • $this->$name : le nom de l'action. Le même que celui du script.
  • $this->$actionUserName : le nom de l'action tel que le rédacteur l'a saisi dans le shortcode.
  • $this->options_user : un tableau avec toutes les options indiquées dans le shortcode. ex: 'monaction'=>true, 'class'=>'foo', 'style'=>'color:red'
  • $this->content : le code entre le shortcode ouvrant et le shortcode fermant. ex: contenu
  • $this->actionprefs : les paramètres du plugin pour les actions. ex: apikey, ...

Pour info, la propriété $this->article est disponible. Elle contient la totalité des infos de l'article. Cela peut-être utile pour des actions comme TOC (sommaire d'un article).

Le but d'une action est d'interpréter ces données pour générer un code HTML qui remplacera le shortcode complet.

La première chose à faire est de compléter et documenter le tableau $options_def avec les options que vous proposez dans votre action.

  // ===== valeur paramètres par défaut
  // il est indispensable de tous les définir ici
  $options_def = array (
    $this->name => '',         // le paramètre principal
    'id' => '',      // id générée automatiquement par UP
    'class' => '',   // classe(s) ajoutées au bloc principal
    'style' => ''    // style inline ajouté au bloc principal
  );

le tableau $options va contenir toutes les options après contrôle et fusion des options.
Si une demande d'aide ou de debug est demandée, ce sera fait lors de cet appel.

  // fusion et contrôle des options
  $options = $this->ctrl_options($options_def);

Après ce contrôle interne, vous pouvez ajouter vos propres vérifications et conversions.

Par exemple, si une option admet du code HTML saisi au format "simili BBCode" de UP, vous devez demander la conversion par

$options['mon_option'] = $this->get_bbcode($options['mon_option']);
Ensuite vous pourrez mettre le code nécessaire pour réaliser votre action.

Mise en forme du code retour

Dans le but de simplifier et clarifier la génération du code HTML, UP propose une méthode que l'on peut voir dans ce code

  // === le code HTML
  // -- ajout options utilisateur dans la div principale
  $outer_div['id']    = $options['id'];
  $outer_div['class'] = $options['class'];
  $outer_div['style'] = $options['css'];

  // -- le code en retour
  $out = $this->set_attr_tag('div', $outer_div);
  $out.=   $this->content;
  $out.= '</div>';

$outer_div est le bloc principal qui va encadrer notre contenu interprété. Le tableau $outer_div contient les couples attribut-argument de la balise

Pour créer le code HTML à retourner, il suffit de faire appel à set_attr_tag qui va retourner <div id="25-1" class="foo">. Style ne figure pas car seuls les attributs avec une valeur sont spécifiés.
Il est aussi possible d'utiliser la version courte si vous n'avez qu'un élément à mettre entre les balises:

$out = $this->set_attr_tag('div', $outer_div, $this->content);

Consulter la page Les fonctions d'aide (helper) sur les mises en forme HTML et le chaînes de caractères

La dernière étape

Retourner le code HTML pour remplacer le shortcode dans l'article. Si votre action n'a pas de retour visible, il suffit de retourner une chaîne vide.

return $out;

Il est possible de retourner un tableau avec du code pour remplacer le shortcode, du code à mettre en début et fin d'article. Voir le code de l'image "image_gallery" ou "anim-aos"

Inspirez-vous d'une action existante pour écrire la vôtre

D'autres infos

188 Utiliser la feuille de style UP
informations sur l'utilisation de la feuille de style UP dans les actions
186 Les fonctions d'aide (upAction.php)
UP met à disposition des méthodes pour faciliter la programmation des actions
173 Prefset : les jeux d'options
Comment programmer les jeux d'options
37 Les règles
Les règles à respecter pour programmer une action
67 Organisation des fichiers de UP
Comment s'y retrouver dans les 1000 fichiers et 350 dossiers de UP
63 Site de démonstration des actions
comment faire le lien entre votre action et le site de démonstration