MForm

Présentation

MForm est une classe php pour afficher des formulaires à partir d'un fichier de configuration plus simple à écrire que le html qui est généré et qui offre beaucoup de fonctionnalités embarquées.

Avec un code php comme celui-ci :

$form = mlib\ui\form\MFormFactory::createFromFile(__DIR__."/path/to/form.conf");
$form->registerAssetsPath("path/to/assets_libs/mlib/MForm/");

$form->display();

et un fichier "form.conf" relativement simple à écrire (voir plus bas), voici le genre de formulaire que l'on peut créer :

Comme on le voit, il s'agit de simples formulaires verticaux mais MForm donne accès, de manière simple, nous le verrons, à plusieurs fonctionnalités comme les champs combinés, les champs multiples, les boutons d'aide …

Le fichier de configuration qui a permis de générer ce formulaire : mform_sample.conf

Le fichier de configuration

Les fichiers de configuration pour MForm sont des fichiers de type MConfig (voir ici).

Ils consistent en une succession de blocs comme ceci :

<nom_du_champ_de_formulaire>
   type = le_type
   display = le_label
   ...
   ...
</nom_du_champ_de_formulaire>

Paramètres communs, quelque soit le type :

Requis :

• type : une des valeurs parmis : hidden, input, number, email, password, text, checkbox, radio, select, file, date, datetime, time, complex, custom
• display : le label qui doit être affiché en regard du champ de formulaire

Optionnels :

• required (booléen) : si le champ est requis ou non
• disabled (booléen) : si le champ est désactivé ou non. N'est pris en compte que si le formulaire est en edition
• help : une url qui renvoie le contenu d'une aide sur le champ et qui sera chargé en ajax dans une boite modale
• default_value : une valeur par défaut

En fonction du type renseigné, un certain nombre d'autre directives seront à fournir de manière obligatoire ou optionnelle.

input

Le type input correspond à un input type text en html. C'est un champ texte simple d'une ligne.

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels
• placeholder : permet de mettre une indication en filigrane quand le champ est vide
• multi (booléen) : permet à l'utilisateur de spécifier plusieurs valeurs en ajoutant des lignes grâce à un "+" à la droite du champ

email

Idem type input, mais le type html sera email. Il n'y aura pas de différence si on a désactivé la validation navigateur (voir ici)

number

Le type number correspond à un input type number en html.

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels
• placeholder : permet de mettre une indication en filigrane quand le champ est vide
• multi (booléen) : permet à l'utilisateur de spécifier plusieurs valeurs en ajoutant des lignes grâce à un "+" à la droite du champ
• step :
• min :
• max :

password

Le type password correspond à un input type password en html.

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels
• placeholder : permet de mettre une indication en filigrane quand le champ est vide

text

Le type text correspond à une textarea en html.

Paramètres requis :

• nb_lines : le nombre de lignes de la zone de texte

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels
• placeholder : permet de mettre une indication en filigrane quand le champ est vide

select

Le type select correspond à un select en html.

Paramètres requis :

• options (config) : un bloc de configuration pour les valeurs du select (voir ici)

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels
• multi (booléen) : indique si le select est multiple. La fonctionnalité est implémentée différemment : on bascule sur des checkboxs présentés dans une liste déroulante pour une interface utilisateur plus conviviale que le maintient de la touche ctrl.
• nb_lines : nombre de lignes visibles si multi

checkbox

Le type checkbox correspond à un input type checkbox en html.

Paramètres requis :

• options (config) : un bloc de configuration pour les valeurs des checkbox (voir ici)

radio

Le type radio correspond à un input type radio en html.

Paramètres requis :

• options (config) : un bloc de configuration pour les valeurs des boutons radio (voir ici)

date

Le type date correspond à un input type date. Un date picker apparait quand on clique dans le champ.

Paramètres (tous optionnels):

• format : une chaine de caractères parmi :
  • 'Y-m-d' (default)
  • 'd-m-Y'
  • 'Y/m/d'
  • 'd/m/Y'
• min : la date minimale acceptée (la date du jour si non renseigné)
• max : la date maximale acceptée (la date du jour + 1 an si non renseigné)

min et max peuvent être des dates au format spécifié (Y-m-d par défaut) ou bien

• Y ou Y ± N (avec N un nombre entier) : le 1er janvier (min) ou le 31 décembre (max) de l'année ± N années
• M ou M ± N (avec N un nombre entier) : le 1er (min) ou dernier (max) jour du mois ± N mois
• D ou D ± N (avec N un nombre entier) : aujourd'hui ± N jours

Exemples :

  min = D       # à partir d'aujourd'hui
  max = D+365   # à l'horizon d'un an

  min = Y-1   # du premier janvier de l'année précédente
  max = Y+1   # au 31 décembre de l'anée suivante

datetime

idem date à part les options de format :

• 'Y-m-d H:i' (default)
• 'd-m-Y H:i'
• 'Y/m/d H:i'
• 'd/m/Y H:i'

time

Le type time est une heure au format 24h : 00:00 → 23:59

Aucune option

file

Le type file correspond à un input type file.

Paramètres optionnels :

• width : permet de spécifier une largeur en pixels

En mode edition, si on précise une valeur pour un champ de ce type, cette valeur (nom d'un fichier) sera affichée dans le placeholder du champ à titre indicatif, mais le champ sera vide si un nouveau fichier n'est pas chargé par l'utilisateur. On ne peut pas pré-remplir un input type file.

complex

Le type complex permet d'agréger (de combiner) différents champs entre entre eux.
Chaque ensemble de valeurs représente une valeur du champ complexe.

Paramètres requis :

• une ou plusieurs configs des champs qui composent le champ combiné

Paramètres optionnels :

• multi (booléen) : si on peut préciser plusieurs valeurs du champ combiné ou non

custom

Le type custom permet de faire un champ de formulaire personnalisé (si aucun autre type ne convient à ce que l'on veut faire).
Pour cela on devra écrire une classe php qui hérite de MForm, dans laquelle on écrira une méthode chargée d'afficher le champ de formulaire. On indiquera le nom de cette méthode dans un paramètre de la configuration du champ.

Paramètres requis :

• display_method : le nom de la méthode à appeler pour afficher le champ

Le bloc "options" pour les types select, checkbox et radio

Le bloc "options" doit contenir le paramètre "type" qui peut prendre une des deux valeurs suivantes :

• constant : la liste des options est toujours la même. Elle doit être indiquée dans le bloc (voir ci-dessous)
• custom : la liste des options est dynamique. Elle sera précisée à l'exécution grâce à la méthode setCustomOptions (voir plus bas). On utilisera cette méthode si les éléments d'une liste déroulante sont stockés en base de données par exemple.

Si le type est "contant", il faut alors préciser les 2 paramètres suivants :

• values : les valeurs des options séparées par des "/" (Ex : 1/2/3)
• displays : les libellés de ces options séparées par des "/" dans le même ordre (Ex : red/green/blue)

Exemple d'un select avec des options constantes :

<le_nom_du_champ>
    type = select
    display = Choisissez une valeur   #ce qui s'affiche en regard du champ, équivalent à un label
    <options>
        type = constant
        values = 1/2/3
        displays = red/green/blue
    </options>
</le_nom_du_champ>

Exemple d'un select avec des options dynamiques à l’exécution :

<le_nom_du_champ>
    type = select
    display = Choisissez une valeur   #ce qui s'affiche en regard du champ, équivalent à un label
    <options>
        type = custom
    </options>
</le_nom_du_champ>

Exemple d'utilisation de setCustomOptions :

$form = mlib\ui\form\MFormFactory::createFromFile(__DIR__."/path/to/form.conf");
$form->registerAssetsPath("path/to/assets_libs/mlib/MForm/");

$values = $database->getValuesOrderByValues(); // pour l'exemple
$labels = $database->getLabelsOrderByValues(); // pour l'exemple

$form_options = array(
    'my_select_with_dynamic_options' => array('values' => $values, 'displays' => $labels)
    // other options for other fields could be set here
  );
$form->setCustomOptions($form_options);

$form->display();

Extras

Aides

Comme indiqué plus haut, on peut, pour chaque champ du formulaire, spécifier une url pour afficher une aide.
On utilise pour cela le paramètre help
On peut aussi utliser les paramètre help_width et help_height pour préciser les dimensions de la boite modale

Fieldsets

On peut regrouper des champs du formumaire des fielsets simplement en encadrant ces champs dans une balise nommée fieldset*

Le nom du fielset n'a aucune valeur. C'est à dire qu'on peut lui donner le nom qu'on veut, la seule contrainte étant que deux fieldsets ne peuvent avoir le même nom.

Exemple :

<fieldset_1>
    hiddeable
    display = A Fieldset
    help = path/to/help_for_fieldset.txt


    <field1>
    ....
    </field1>
    <field2>
    ...
    </field2>

</fieldset_1>

On voit ici qu'il existe des options pour les fieldsets :
* display : le libellé qui sera affiché
* hiddeable (booléen): si le fieldset peut être replié ou non
* help : voir au dessus, pareil que pour un champ de formulaire

Submit et action

En dehors de tous les champs et fieldsets du formulaire on peut spécifier à la racine du fichier de configuration le paramètre action si l'url de traitement du formulaire n'est pas la même que l'url du formulaire

On peut aussi préciser un bloc spécial submit pour modifier la valuer du bouton de validation du formulaire et/ou ajouter un captcha.

Exemple:

<submit>
    display = Envoyer
  captcha = path/to/something/which/generate/an/image
</submit>

S'il y a un captcha, le code qui aura généré l'image devra avoir stocké le code dans la session.
Le code saisi par l'utilisateur se trouvera dans le champ mform_captcha à la réception du formulaire

Validation navigateur