UP-v5.0.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}
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 Pour être reconnu, un séparateur doit commencer par une accolade suivie de 3 signes égal et se terminer par une accolade. 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. 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. 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 L'action lang peut être utilisée sauf dans le fichier prefs.ini Pour saisir du code HTML compris par UP, mais ignoré des éditeurs. 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) ou pour nommer les cooies d'un module. ? : 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. 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 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 : css-head : ajoute des règles CSS dans le head de la page. exemple : filter : n'exécute pas l'action si une des conditions est fausse. exemple : 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. Le shortcode est visible sur la page générée. Action non trouvée le shortcode ne semble pas fonctionner message : contenu non trouvé les options ne sont pas prises en compte comportement bizarre UP ne reconnait pas cette option : =1
Le tiret et trait de soulignement ont la même signification.Les shortcodes séparateurs
{up filter | guest} vous êtes invité {===} vous êtes identifié {/up filter}
{up flexauto=2} bloc 1 {=== commentaire} bloc 2 {/up flexauto}
Il est permis d'ajouter un commentaire avant l'accolade fermante ❴====== commentaire❵Shortcodes internes ou secondaires
{up osmap=48.865, 2.30}
{marker=48.8709, 2.33223 | popup-text=... }
{/up osmap}
Shortcodes comme argument
{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}
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.Format date
BBCode
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
{up hr=param}
et {up hr | prefset=param}
produisent le même résultat.a[title]{color:red}
, on écrit a\[title\][color:red]
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=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=motclé:condition;!motclé:condition;...
le point d'exclamation inverse le sens de la conditionAide et assistance
Les erreurs fréquentes
- Détails
Les règles de UP - version 5.0.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
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>[];\]' 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('. $js_params.');';
$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
$str=$this->set_attr_tag($tag, $attr, $close=false, $doublequote=true, $bbcode=false);
$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);
Messages
// ajout message dans la file des messages de Joomla $this->msg_error($msg); $this->msg_info($msg; $title='');
$msg=$this->msg_inline($text) // message à afficher comme résultat action
$this->mail2admin($suject, $text) // envoi un mail à l'admin du site
$this->msg_journal($text) // interne, ajoute un fichier de suivi des erreurs avec envoi mail// obsolete: 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=':', $quote=true); // ['un']=>1 [2]=>'deux'
$str=$this->sreplace($old,$new,$src,$nb=1); // remplace nb occurences de $old par $new
$str=$this->supertrim($str, $add); // supprime " \t\n\r\0\x0B\xA0\xC2" + $add aux extrémités
$this->kw_replace(&$tmpl, $keyword, $replace); // remplace un motclé par une valeur dans un template
$content=$this->import_content($content); // prise en charge des plugins de contenu
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);
Base de données
$val=$this->get_db_value($select, $table, $where) // valeur unique
Date
$date=$this->up_strtotime($date) // retourne une date interprétable par strtotime
$this->set_locale($tag=''); OBSOLETE PHP8
$str=$this->up_date_format($date, $format=NULL, $locale = '')
%y: AA, %Y: AAAA, %m: 01-12, %b: mois 3 lettres, %B: nom mois, %d: 01-31, %e: 1-31, %a: joursem 3 lettres, %A: jour sem, %U: N° semaine, %l: heure (1-12) AM/PM - L min, %I: heure (01-12) AM/PM - i maj, %k: heure (0-23), %H: heure (00-23), %P: am/pm, %p: AM/PM, %M: minute (00-59)
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, ...)
- Détails
une synthèse de toutes les classes de UP sur une seule page !
- Détails