Développement:Fonctions output
Remarque : la traduction de cet article n'est pas terminée. N'hésitez pas à traduire tout ou partie de cette page ou à la compléter. Vous pouvez aussi utiliser la page de discussion pour vos recommandations et suggestions d'améliorations.
Cette page essaie d'expliquer un peu comment les données dynamiques doivent être envoyées depuis Moodle au navigateur d'une manière organisée et standard. Bien entendu il est possible d'avoir vos propres méthodes d'output mais, sachant que vous vous apprêtez à partager votre code (et oui, c'est un projet OpenSource !), et d'une manière collaborative, nous essayons de construire et maintenir le système chaque jour, ce serait vraiment mieux de suivre les directives de base expliquées ci-dessous.
En les utilisant vous serez aidé pour avoir un meilleur code, plus sécurisé et lisible. Passez quelques minutes à essayer de les comprendre, s'il vous plaît !
Bien sûr, ces fonctions peuvent être discutées, modifiées et de nouvelles fonctions peuvent arriver s'il y a de bonnes raisons à cela. Discutez-en sur le Forum général des développeurs sur moodle.org.
Pour chacune des fonctions ci-dessous, nous essaierons d'expliquer quand elles doivent être utilisées, expliquant les paramètres nécessaires les plus importants et leur signification. Passons-les en revue !
p() et s()
function s($var, $strip=false) function p($var, $strip=false)
Ces fonctions partagent le même code, donc elles seront expliquées ensemble. La seule différence est que s() retourne la chaîne tandis que p() l'affiche directement.
Ces fonctions doivent être utilisées pour :
- afficher toutes les valeurs des champs de formulaires comme les étiquettes <input> ou <textarea>.
- pour montrer du texte quelconque (non html) qui a été entré par l'utilisateur (chaîne à rechercher, réponses de quizz...).
- en général, toutes les données dynamiques, n'étant pas du html, qui n'ont pas besoin d'être nettoyées ni traitées par des filtres
Il est important de ne pas utiliser ces fonctions pour des chaînes qui contiennent du html.
Les fonctions remplacent certains caractères qui pourraient avoir une signification spéciale en html ( <, >, ", ', et &) par des entités html, ainsi elles sont affichées comme prévu. Notez que même si la valeur des champs du formulaire affichées avec p() auraient eu leurs caractères convertis en entités html, les valeurs soumises contiendront à nouveau les caractères originaux.
Le paramètre-clé de cette fonction est :
- strip : il décide s'il veut effacer les slashes de la chaîne ou non. Par défaut il est à 'false', donc aucune suppression de sera faite. Nous devrions mettre un tel paramètre à 'true' quand la donnée à traiter ne vient pas de la base de données mais de requêtes http (formulaires, liens...).
format_text()
function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )
Cette fonction doit être utilisée pour :
- afficher tout texte html/quelconque/markdown/moodle, nécessitant une des caractéristiques ci-dessous. Principalement utilisé pour les longues chaînes telles que les messages, les réponses, les articles du glossaires...
Notez que cette fonction est vraiment lourde parce qu'elle aide au nettoyage des contenus dangereux, délègue le traitement aux filtres, admet différents formats de texte et exécute beaucoup de conversions automatiques comme ajouter des smileys, fabriquer des liens. Aussi, elle inclue un solide mécanisme de cache (basé sur la BD) qui soulagera le serveur de beaucoup de traitements.
Quelques paramètres intéressants de cette fonction :
- format: To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See Formatting options.
- options : Ici, nous pouvons spécifier comment nous voulons que le traitement soit exécuté. Vous avez seulement besoin de les définir si elles sont différents des valeurs par défaut. Les principales options sont :
- options->noclean : Pour décider si nous voulons passer le nettoyage du texte, se déprotéger des attaques et autres défauts de sécurité (par défaut à false, donc la protection est activée. Vous ne devez pas la mettre à true sans être sûr à 200% que seuls les utilisateurs restreints peuvent la modifier (principalement les administrateurs). Ne l'utilisez jamais pour des zones de textes générales (posts...) ou vous serez attaqués tôt ou tard ! Notez que cette option est ignorée pour FORMAT_PLAIN, le texte n'est jamais nettoyé.
- options->filter : Pour décider si vous voulez accepter que les filtres traitent le texte (true par défaut). C'est ignoré par FORMAT_PLAIN pour lequel les filtres ne sont jamais appliqués.
- options->smiley : Pour décider si vous voulez une conversion des smileys en images automatiquement (true par défaut). C'est ignoré par FORMAT_PLAIN pour lequel les smileys ne sont jamais convertis.
- options->para : Pour décider si vous voulez que chaque paragraphe soit automatiquement entouré de balises html de paragraphes (<p>...</p>) (true par défaut). Cette option s'applique seulement au FORMAT_MOODLE.
- options->newlines : Pour décider si les passages à la ligne du texte doivent être convertis en passages à la ligne html (<br />) (true par défaut). Cette option s'applique seulement au FORMAT_MOODLE.
- courseid : Ce paramètre doit toujours être passé pour aider les filtres à savoir comment ils doivent travailler. Ce paramètre deviendra de moins en moins important, Moodle connaissant le cours courant en utilisant les variables de session ou globales mais, pour le moment, il est recommandé de toujours le mettre à l'appel de la fonction.
format_string()
function format_string ($string, $striplinks = true, $courseid=NULL )
Cette fonction doit être utilisée pour :
- afficher de courtes chaînes (non html) qui ont besoin d'être traitées par un filtre (titres d'activités, concepts de glossaire...).
Veuillez noter que cette fonction est fondamentalement une version extraite de la fonction complète format_text() détaillée ci-dessus, et elle ne propose aucune option ou protection. Elle filtre simplement les chaînes et retourne le résultat, donc nous devons nous assurer que le texte qui sera traité a été convenablement nettoyé au moment de l'entrée, en utilisant la bonne fonction xxx_param().
Quelques paramètres intéressants pour cette fonction :
- striplinks : Pour décider si, une fois le texte traité par les filtres, nous devons supprimer un lien du texte résultat. Utilisé quand nous voulons montrer le texte à l'intérieur de menus, titres de pages... (true par défaut).
- courseid : Ce paramètre doit toujours être passé pour aider les filtres à savoir comment ils doivent travailler. Ce paramètre deviendra de moins en moins important, Moodle connaissant le cours courant en utilisant les variables de session ou globales mais, pour le moment, il est recommandé de toujours le mettre à l'appel de la fonction.
print_textarea()
function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value='', $courseid=0, $return=false)
Cette fonction doit être utilisée pour :
- afficher des champs <textarea> quand nous voulons autoriser des utilisateurs (basé sur leurs préférences et les capacités de leur navigateur) à utiliser l'éditeur HTML à la place des zones standard 'quelconques'.
Quelques paramètres intéressants de cette fonction :
- usehtmleditor : pour décider si l'éditeur HTML doit être montré. La valeur de ce paramètre doit être calculée par la fonction can_use_html_editor().
- rows,cols : à appliquer si la zone de texte standard est montrée.
- width, height' : à appliquer si l'éditeur HTML est utilisé
- name : le nom du champ qui contiendra le texte une fois le formulaire soumis.
- value : la valeur initiale de la zone de texte.
- courseid : Ce paramètre doit toujours être passé pour aider les filtres à savoir comment ils doivent travailler. Ce paramètre deviendra de moins en moins important, Moodle connaissant le cours courant en utilisant les variables de session ou globales mais, pour le moment, il est recommandé de toujours le mettre à l'appel de la fonction.
- return : pour décider si le code html généré doit être retourné à l'appelant (true) ou affiché directement (faux). false par défaut.
