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:
- 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 - créer un dossier monaction dans le dossier plugins/content/up/actions
- copier le script plugins/content/up/actions/_exemple_simple/_exemple_simple.php en monaction.php
- renommer la classe de ce script (_exemple_simple) en monaction
- 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 (
__class__ => '', // 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
Il existe une fonction simplifiée pour créer les attributs d'une balise. On indique le nom du tableau suivi des classes et styles.
$attr_div['id'] = $options['id'];
$this->get_attr_style($attr_div, $options['class'], $options['style'], 'foo', 'color:red');Si $options['class']=bg-jaune;border:red dotted 2px et $options['style']=t-red, on obtient le code HTML suivant :
<div id="up-98-1" class="bg-jaune t-red foo" style="border:red dotted 2px;color:red">test </div>Notez que les styles et classes sont correctement répartis !!
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 Aide-mémoire développeur 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 :
- $out['tag'] = "code HTML pour remplacer le shortcode"
- $out['before'] = "code HTML à mettre au début de l'article"
- $out['after'] = "code HTML à mettre à la fin de l'article"
Vous pouvez voir ce principe dans le code des actions "image_gallery" ou "anim-aos"
Inspirez-vous d'une action existante pour écrire la vôtre