From 5975d36a1cc67fe832a5934787fea685abd49c64 Mon Sep 17 00:00:00 2001 From: Benjamin Renard Date: Wed, 26 Aug 2020 11:25:56 +0200 Subject: [PATCH] Doc / contrib: add section about LSformElements --- doc/LS.entities.xml | 3 ++ doc/contrib/contrib.docbook | 88 +++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) diff --git a/doc/LS.entities.xml b/doc/LS.entities.xml index 6eaec076..16cd103e 100644 --- a/doc/LS.entities.xml +++ b/doc/LS.entities.xml @@ -38,4 +38,7 @@ LSselect"> LSsearch"> +LSformElement"> +LSformElements"> + diff --git a/doc/contrib/contrib.docbook b/doc/contrib/contrib.docbook index 52f3b87c..f3779f04 100644 --- a/doc/contrib/contrib.docbook +++ b/doc/contrib/contrib.docbook @@ -516,4 +516,92 @@ + + LSformElements + + Les &LSformElements; sont les types de champs de formulaire supportés par l'application. + Pour chaque type implémenté, on devra trouver : + + Une classe PHP dérivée de la classe LSattr_html et devant s'appeler + LSattr_html_[nom du type d'attribut HTML]. Dans celle-ci, il devra être défini à minima la variable de classe + LSformElement_type permettant de référencer le type d'&LSformElement; à utiliser ; + + Une classe PHP dérivée de la classe LSformElement et devant s'appeler + LSformElement_[nom du type d'LSformElement]. Cette classe implémentera tous ce qui concerne l'affichage du champ + dans le formulaire et le traitement d'une valeur retourné par ce dernier. Cela concerne notamment les méthodes suivantes: + + + + getDisplay() + + Retourne les informations d'affichage du champ dans un formulaire sous la forme d'un tableau (implémentation + obligatoire, pas de méthode par défaut). Il sera possible de s'appuyer sur la méthode getLabelInfos() + permettant de générer et récupérer tous ce qui concerne le label du champ du formulaire. Il faudra cependant à minima fournir + également la clé html dans le tableau retourné qui devra contenir le bout de code HTML correspondant au champ + du formulaire. Communément, ce code HTML est généré en appelant la méthode fetchTemplate(). + + + + + fetchTemplate() + + Retourne le code HTML du champ dans le formulaire. L'implémentation de cette méthode est facultative et par défaut, cette + méthode utilisera la variable de classe $template pour connaître le fichier de template à utiliser. Ce fichier + de template permettra la génération de la liste de tous les champs associés à chacune des valeurs de l'attribut. Individuellement, + le champ d'une des valeurs de l'attribut est généré à l'aide du fichier de template référencé dans la variable de class + $fieldTemplate. + La variable de classe $fieldTemplate est également utilisée par la méthode + LSformElement :: getEmptyField() qui sert à générer le code HTML d'un champ du formulaire pour une nouvelle + valeur de l'attribut. Cette méthode est notamment utilisée lorsque l'on clique sur le bouton permettant d'ajouter une valeur à + un champ du formulaire. + + + + + getPostData() + + Récupère dans les données postées par le formulaire, celle concernant ce champ. Cette méthode devra potentiellement + traiter l'ensemble des valeurs de l'attribut envoyées par le formulaire et les définir dans le tableau passé en référence en tant + que premier argument, les valeurs de l'attribut. L'implémentation de cette méthode est facultative et par défaut, un tableau de + valeurs portant le nom de l'attribut LDAP correspondant sera récupérée comme valeur de l'attribut. + Pour plus d'informations sur le rôle et fonctionnement de cette méthode, référer à la méthode par défaut, définie + dans la classe PHP parente LSformElement. + + + + + setValueFromPostData() + + Défini les valeurs de l'attribut à partir des données reçus du formulaire (et récupérée par la méthode + getPostData). L'implémentation de cette méthode est facultative et par défaut, aucune transformation ne sera + faites à cette étape sur les données récupérées depuis le formulaire. Implémenter cette méthode pourra cependant se révéler utile + en cas de champs de formulaire complexe (attribut composite par exemple). + + + + + autocomplete_attr_values() + + Génère de la liste des valeurs possibles de l'attribut dans un contexte CLI. + Pour plus d'informations sur le rôle et fonctionnement de cette méthode, référer aux commentaires de la méthode par + défaut, définie dans la classe PHP parente LSformElement. Vous pouvez également vous inspirer des exemples + d'implémentations fournies avec les autres type d'&LSformElement;. + + + + + + Un (ou plusieurs) fichier template pour la génération du code HTML du champ du formulaire. Communément, le fichier + LSformElement.tpl est utilisé pour générer la structure de la liste des champs correspondant aux différentes valeurs + de l'attribut. Ce template utilise une variable $fieldTemplate pour définir quel fichier template devra être utilisé + pour générer le code HTML de chaque champ associés à une valeur. C'est ce second fichier de template qui est en général à fournir à + minima avec votre &LSformElement;. + + + Il peut être utile d'étendre un type d'&LSformElement; existant pour faciliter l'implémentation d'un nouveau type. Pour + cela, vous devez utiliser l'héritage de classe PHP en faisant dériver vos nouvelles classes des classes du &LSformElement; dont vous vous + inspirer, plutôt que les classes génériques. Vous pouvez prendre exemple sur le type d'&LSformElement; pre qui s'inspire + du type textarea, ou encore du type url dérivé du type text. + +