frendeitpt

Aide-mémoire rédacteur

 

UP-v2.8.2 : aide-mémoire rédacteur


Les shortcodes

UP permet de donner des instructions en mode code ou wysiwyg dans un article ou un module personnalisé à l'aide de shortcodes.

{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 (identique à celui du shortcode ouvrant) :

{/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

Les shortcodes séparateurs

ils sont utilisés 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 suivie 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}

 Shortcodes comme argument

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

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

{up table-par-lignes} 
  {up csv2table | header=id;titre} 
     {up jnews=8  
          | main-tag=0 | item-tag=0
| template=##id##;##title## | new-html={up icon=etoile} } {/up csv2table} {/up table-par-lignes}

Les actions sont autonomes et indépendantes. Elles doivent renvoyer un contenu qui soit compatible avec l'action parente.

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

Traduction

option=lang[en=YES;fr=OUI] permets de proposer des alternatives selon la langue du visiteur. Si sa langue n'est pas spécifiée, on utilise la première option.

L'action lang peut être utilisée sauf dans le fichier prefs.ini

BBCode

Pour saisir du code HTML compris par UP, mais ignoré des éditeurs. 

Il faut remplacer les <> par des crochets []. Exemple : [b]gras[/b]

Pour insérer un crochet, il faut l'échapper avec un anti-slash \[

Seules les balises les plus courantes sont prises en charge :

a|br|p|h3..6|div|span|b|i|u|img|small|sup|sub|quote|ul|ol|li|code|tt|kbd

Les options courantes

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 prefsets définis pour votre site.

prefset : permets 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 écrit 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, échappez 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)

Aide et assistance

Si vous ajoutez un point d'interrogation ou le mot debug comme option au shortcode, UP affichera de l'aide au début de la page sur le site.

Les erreurs fréquentes

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.
  • dans un module custom sans prise en charge des plugins de contenu

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

Aide-mémoire développeur

Les règles de UP - version 2.8.2

  • tous les fichiers d'une action dans le dossier de l'action.
    L'ajout du dossier installe l'action, sa suppression la supprime.
  • l'utilisateur dispose toujours d'une documentation.
    Sans fichier up/xx-FR.ini, la doc est récupérée dans le script action.
  • les shortcodes doivent pouvoir être saisis en mode wysiwyg
  • Tous les noms (actions, fichiers et options) en anglais.
    Traduction ou abréviation dans fichier dico.ini de l'action
  • Utiliser {up upactionlist | csv} pour attribuer le nom des options
  • Préfixer le nom des actions proches (ex: image_gallery, image_magnify)

Initialisation d'une action

// doit-on exécuter l'action ?
if ($this->filter_ok($options['filter']) !== true) { return ''; }

Chargement ressources

// charge css ou js avec gestion dossier custom de l'action si path vide
$this->load_file($ficpath, $options=array(), $attributes=array());
$this->load_css_head($code_css, $id=null); // charge code CSS dans le head. gère #id
$this->load_custom_code_head($code); // charge code libre dans le head
$this->load_js_file_body($ficpath); // charge fichier JS après contenu article

Chemin et URL

// ajoute custom à $path si $file existe dans le dossier. 
$file = $this->get_custom_path($file, $path=dossier_action);
$path = $this->get_asset_path($url);
// ajoute racine si besoin: images/foo.png  -> /rootFolder/images/foo.png
$url = $this->get_url_relative($url, $urlencode=false);
// retourne URL sous forme absolue: images/foo.png -> https://site.fr/images/foo.png
$url = $this->get_url_absolute($url, $urlencode=false);
$this->on_server($url); // true si URL sur le serveur

HTML

// Charge flux HTML avec timeout pour éviter blocage
$str = $this->get_html_contents($url, $timeout=10, $url2='')
// récupère array avec les attributs d'une balise HTML
$attr = $this->get_attr_tag($tag, $force='id,class,style');

Nettoyage

// $tags: 0=a l'identique, 1=neutralisecode HTML ou liste tags autorisés ('a,img,b')
$content = clean_HTML($content, $tags=false, $forceEOL=false)

Les options

Pour mémoire, un passage obligé ctrl_options($options_def, $js_options_def='')

if (!empty($options['nom_option'])) { ... } // Tester si une option est vrai ou fausse
$this->load_inifile($file, $sections=false, $alert=true) // array avec contenu fichier 

Consolider

// convertir bbcode en HTML
$options['title']=$this->get_bbcode($options['title']);
$code=$this->get_code($input); // '\[text&gt[];\]' en [text>{}] // affecte $val si $option='' (true) ex: ('mp4', 'ficname.mp4') $this->set_option_user_if_true($option, $val); // vérifie si argument dans liste sans tenir compte de la case, sinon retourne 1er. $arg = $this->ctrl_argument($arg, $autorized_list, $debug=true);

Images

// vérifier si unité existe, sinon affecte la première de la liste
$options['size']=$this->ctrl_unit($options['size'],'px,%,rem');
// conversion px<->rem
$arr=convert_size($size, $unit_target='px') // $arr[0]=(int)val, [1]=$unit_target
// Retourne UNC sans chemins, extensions, underscore, tiret (2+tirets=1), compteur
$str=link_humanize($unc, $capitalize=true);

Le contenu

// vérifie si contenu entre shortcode. Affiche message Joomla
if (!$this->ctrl_content_exists()) { return false; }

Récupérer les parties séparées par {===} dans un array

if ($this->ctrl_content_parts($this->content)) {
  $list = $this->get_content_parts($this->content);
}

Shortcodes internes

// retourne un tableau avec tous les shortcodes avec $keyword
$this->get_content_shortcode($content, $keyword='.*')

CSV

// $cleanTags:liste tags non supprimés, $bbcode:liste bbcodes 
$arr=$this->get_content_csv($content, $cleanTags='', $bbcode='').

Nettoyage avant analyse regex

$content = str_replace(PHP_EOL, '', $content);

Préparer attributs HTML

$attr['id']=$options['id'];
// ventile vers $attr['class'] et $attr['style']
$this->get_attr_style($attr, 'bg-red:color:#FFF', $options['class'], ...);

JS - jQuery

Consolider les paramètres

// les options saisies par l'utilisateur pour envoi sélectif au script JS
$js_options = $this->only_using_options($js_options_def, $options_user=null);
// conversion en chaine Json (mode1=normal, mode2=sans guillemets, mode3=crochets array)
$js_params = $this->json_arrtostr($js_options, $mode=1, $bracket=true);
// le contenu d'un fichier json dans un array
$arr=$this->get_jsontoarray($filename, $ficpath = '')
// Analyse une liste d'options non gerees par l'action pour un script JS
$arr=$this->params_decode($str, $sep_param=',', $sep_key=':', $quote='"', $echap ='\\');
$code = '$("#' . $options['id'] . '").xxx(';
$code .= $js_params;
$code .= ');';
$this->load_jquery_code($code,$in_head=false); // retourne code jquery encapsulé
$this->load_js_code($code, $in_head=true) // dans head ou retourne <script>code JS</script>

Construire le HTML en retour

$html[] = $this->set_attr_tag('ul', $attr);
$html[] = $this->set_attr_tag('li', array(), 'contenu'); // attr vide
$html[] = </ul>
return implode(PHP_EOL, $html);

Blocs imbriqués. On construit à partir du milieu.
Un underscore devant le tag le rend optionnel si aucun attribut, on retourne le contenu.

$out = $this->set_attr_tag('div', $attr_niv3, 'niveau-3')
$out = $this->set_attr_tag('div', $attr_niv2, $out)
$out = $this->set_attr_tag('_div', $attr_niv1, $out)
return $out

traduction

$str=$this->lang('en=yes;fr=oui');
// motclé dans up/language/xx-XX/xx-XX.ini ou up/actions/action/up/xx-XX.ini
$str=$this->trad_keyword($key);
// définir la langue affichée. $this->set_locale($options['date-locale']);
$this->set_locale($tag='');

Messages

// ajout message dans la file des messages de Joomla
$this->msg_error($msg);
$this->msg_info($msg; $title=''); 
// retourne texte très visible avec référence action si $infoUP
if (true) return $this->info_debug($txt, $infoUP=true);

Divers sur les chaines

$str=$this->preg_string('#alt="(.*)"#i', '<img alt="label">'); // retourne label
$array=$this->strtoarray('un:1,2:deux',$row=',', $col=':'); // ['un']=>1 [2]=>'deux'
$str=$this->sreplace($old,$new,$src,$nb=1); // remplace nb occurences de $old par $new

Ajouter une chaine à une autre avec gestion séparateur, préfixe et suffixe

$str = str_append($str, $add, $sep=' ', $prefix='', $suffix='');
add_str(&$str, $add, $sep=' ', $prefix='', $suffix='');
add_class(&$str, $newclass, $prefix='');
add_style(&$str, $property, $val);

Interne UP

$str=$this->get_action_pref($key, $default=null); // clé dans plugin
$arr=$this->up_actions_list(); // liste des actions
$str->$this->get_dico_synonym($key); // liste synonyme (sep virgule)
$str=$this->shortcode2code($str); // shortcode neutralisé pour affichage
$str=$this->up_action_infos($action,$lang=null); // info action pour doc
$arr=$this->up_action_options($action,$csv=false,$lang=null); // options pour doc
$str=$this->up_prefset_list($action, $full=true); // Liste des jeux d'options
$str=$this->up_help_text(); // contenu custom/help.txt
$this->set_demopage($webpage=''); // emplacement demo de l'action

Propriétés disponibles ($this)

actionPath : chemin dossier action en cours | upPath : plugins/content/up | name : nom dossier action | actionUserName : nom action saisi dans shortcode | options_user : array options saisies dans shortcode | content : contenu HTML entre shortcodes | article : article ou module contenant les shortcodes | actionprefs : préférences plugin | demopage : URL vers page démo (usehelpsite & urlhelpsite) | dico : table correspondance des noms | J4 : version Joomla >=4

Action privée

UPactionList affiche toutes les actions sauf celles commençant par un underscore.
Pour utiliser le nom sans l'underscore, utiliser dico.ini : nom_action=_nom_action

Utiliser la feuille de style UP

Pour fichier SCSS dans dossier d'une action.

@import "../../assets/custom/variables"; // version webmaster
@import "../../assets/scss/variables"; // UP par défaut

Mediaqueries: $breakpoint-s, $breakpoint-m Couleurs: voir feuille css pour noms FR et GB Ombres: $shadow[-max|-bottom|-large|-white] bordures: $up-border-[0|1|2|3] Espaces: $up‑space-[0|1|2|3]

Les couleurs sont déclarées comme variables CSS (--jaune, --yellow, ...)

 

CSS - la feuille de style interne

une synthèse de toutes les classes de UP sur une seule page !