Aide-mémoire développeur

Aide-mémoire développeur

UP Version 6.0

Dans la version 6.0, UP utilise les namespaces et respecte le formalisme Joomla! version 5.x et supérieures.

Les fonctions communes ont été transférées dans UpHelper.Les actions héritent désormais de Up au lieu de UpAction.

Ainsi, en début d'action, il faut ajouter 

use Lomart\Plugin\Content\Up\Helper\UpHelper;

Au niveau de la classe, elle devient :

class NomAction extends Lomart\Plugin\Content\Up\Extension\Up

Les fonctions communes sont appelées depuis UpHelper. Il faut leur ajouter le paramètres $this afin de savoir l'action appelante.

Par exemple, à la place de $this->set_demopage(), on aura UpHelper::set_demopage($this);

Initialisation d'une action

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

Chargement ressources

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

Chemin et URL

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

HTML

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

Nettoyage

// $tags: 0=a l'identique, 1=neutralisecode HTML ou liste tags autorisés ('a,img,b')
$content = UpHelper::clean_HTML($this,$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

UpHelper::load_inifile($this,$file, $sections=false, $alert=true) // array avec contenu fichier 

Consolider

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

Images

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

Le contenu

// vérifie si contenu entre shortcode. Affiche message Joomla
if (!UpHelper::ctrl_content_$this,exists()) { return false; }

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

if (UpHelper::ctrl_content_parts($this,$this->content))
  $list = UpHelper::get_content_parts($this,$this->content);
// retourne $content après prise en charge des plugins de contenu
$content = UpHelper::import_content($this,$content);

Shortcodes internes

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

CSV

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

Nettoyage avant analyse regex

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

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

Base de données

$val=UpHelper::get_db_value($this,$select, $table, $where) // valeur unique

// les options saisies par l'utilisateur pour envoi sélectif au script JS
$js_options = UpHelper::only_using_options($this,$js_options_def, $options_user=null);
// pour la prise compte modif par only_using_options  
UpHelper::js_actualise($this,$actionName, $val, &$options, &$js_options_def);  
// conversion en chaine Json (mode1=normal, mode2=sans guillemets, mode3=crochets array)
$js_params = UpHelper::json_arrtostr($this,$js_options, $mode=1, $bracket=true);
// le contenu d'un fichier json dans un array
$arr=UpHelper::get_jsontoarray($this,$filename, $ficpath = '')
// Analyse une liste d'options non gerees par l'action pour un script JS
$arr=UpHelper::params_decode($this,$str, $sep_param=',', $sep_key=':', $quote='"', $echap ='\\');

$code = '$("#' . $options['id'] . '").xxx('. $js_params.');';
UpHelper::load_jquery_code($this,$code,$in_head=false); // retourne code jquery encapsulé
UpHelper::load_js_code($this,$code, $in_head=true) // dans head ou retourne <script>code JS</script>

$str=$this->set_attr_tag($tag, $attr, $close=false, $doublequote=true, $bbcode=false);

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

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

traduction

$str=UpHelper::lang($this,'en=yes;fr=oui');
// motclé dans up/language/xx-XX/xx-XX.ini ou up/actions/action/up/xx-XX.ini
$str=UpHelper::trad_keyword($this,$key);

Messages

// ajout message dans la file des messages de Joomla
UpHelper::msg_error($this,$msg);
UpHelper::msg_info($this,$msg; $title='');
$msg=UpHelper::msg_inline($this,$text) // message à afficher comme résultat action
UpHelper::mail2admin($this,$suject, $text) // envoi un mail à l'admin du site
UpHelper::msg_journal($this,$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 UpHelper::info_debug($this,$txt, $infoUP=true);

Divers sur les chaines

$str=UpHelper::preg_string($this,'#alt="(.*)"#i', '<img alt="label">'); // retourne label
$array=UpHelper::strtoarray($this,'un:1,2:deux',$row=',', $col=':', $quote=true); // ['un']=>1 [2]=>'deux'
$str=UpHelper::sreplace($this,$old,$new,$src,$nb=1); // remplace nb occurences de $old par $new
$str=UpHelper::supertrim($this,$str, $add); // supprime " \t\n\r\0\x0B\xA0\xC2" + $add aux extrémités
$str=UpHelper::spaceNormalize($this,$str, $add); // remplace les espaces durs par des simples
UpHelper::kw_replace($this,&$tmpl, $keyword, $replace); // remplace un motclé par une valeur dans un template
$content=UpHelper::import_content($this,$content); // prise en charge des plugins de contenu

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

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

Date

$date=UpHelper::up_strtotime($this,$date) // retourne une date interprétable par strtotime
UpHelper::set_locale($this,$tag=''); OBSOLETE PHP8
$str=UpHelper::up_date_format($this,$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=UpHelper::get_action_pref($this,$key, $default=null); // clé dans plugin
$arr=UpHelper::up_actions_list($this); // liste des actions
$str=UpHelper::get_dico_synonym($this,$key); // liste synonyme (sep virgule)
$str=UpHelper::shortcode2code($this,$str);  // shortcode neutralisé pour affichage
$str=UpHelper::up_action_infos($this,$action,$lang=null); // info action pour doc
$arr=UpHelper::up_action_options($this,$action,$csv=false,$lang=null); // options pour doc 
$str=UpHelper::up_prefset_list($this,$action, $full=true); // Liste des jeux d'options 
$str=UpHelper::up_help_text($this); // contenu custom/help.txt
UpHelper::set_demopage($this,$webpage=''); // emplacement demo de l'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, ...)