Pour cela, vous utiliserez la méthode setData() sur l'objet formulaire, qui accepte en argument, le nom du champ à préremplir, et la valeur à lui donner :

  $form->setData("prenom","Laurent");

Les valeurs peuvent être récupérées d'ailleurs, comme bon vous semble.

Cependant, si vous voulez utiliser un dao, il existe un moyen rapide pour remplir un formulaire. La méthode initFromDao() permet d'utiliser un DAO pour remplir plusieurs champs du formulaire. Il suffit d'indiquer à cette méthode le selecteur du dao à utiliser. Vous pouvez aussi spécifier en deuxième argument la valeur de la clé primaire si l'identifiant du formulaire ne correspond pas à la valeur de cette clé (sachant que la valeur peut être un tableau de valeurs si la clé est sur plusieurs champs). Par défaut donc, initFromDao() utilisera la valeur de l'identifiant du formulaire comme identifiant de l'enregistrement à récupérer.

   $form = jForms::create("shop~product", $product_id);
   $form->initFromDao("shop~products");

Ici le formulaire sera pré-rempli avec les valeurs de l'enregistrement dont la clé est $product_id, et le dao "shop~products" sera utilisé pour cette lecture. Vous pouvez aussi indiquer un objet DAO record à initFromDao() plutôt qu'un sélecteur.

Cependant, seuls les champs de saisie qui ont le même nom que des propriétés du dao indiqué seront pré-remplis. Les autres resteront vides.

Notez que vous pouvez utiliser plusieurs daos pour pré-remplir les champs. En effet, on peut avoir besoin d'un formulaire qui contient des champs de saisie qui seront stockés dans plusieurs tables.

Pour les champs <checkboxes> et <listbox multiple="true">, la valeur à initialiser n'est pas forcément une simple valeur, mais une liste de valeurs qui correspondent à tous les choix qu'il faut pré-sélectionner. (Attention, on parle bien ici des valeurs pré sélectionnées, pas de la liste des choix).

On peut donc les initialiser avec setData(), en leur passant un tableau contenant les valeurs des choix à présélectionner :

    $form->setData('categories', array(5, 8, 10));

En général cependant, ces listes de valeurs sont stockées dans une base de données, dans ce qu'on appelle une table de jointure. C'est à dire une table qui fait la jointure entre deux tables, et dont la clé primaire est constituée de deux clés étrangères, l'une et l'autre appartenant à une autre table. Par exemple, on a une table pour les produits ('products'), une table pour les catégories de produits ('categories'), et si un produit peut appartenir à plusieurs catégories, il faut une table de jointure ('products_categories'), contenant les clés des produits et les clés des catégories qui sont en relation (product_id et category_id).

Pour initialiser la liste ou les cases à cocher, il va donc aller lire dans cette table 'products_categories' les relations. Il existe pour cela une méthode, initControlFromDao() :

   $form->initControlFromDao("categories", "shop~products_categories");

Le dao "shop~products_categories" sera utilisé pour lire les valeurs sélectionnées pour le champs catégories. jForms s'attend ici à ce que la première clé déclarée dans le dao corresponde à l'identifiant du produit, et la deuxième clé à l'identifiant des catégories. Si ce n'est pas le cas, il faut alors indiquer les noms de ces clés dans le dao, dans un array à passer en troisième paramètre :

   $form->initControlFromDao("categories", "shop~products_categories", array('product_id','category_id'));

Vu qu'il s'agit dans cet exemple de la saisie d'un enregistrement product, et que l'identifiant du formulaire correspond à l'identifiant du produit, la valeur de cet identifiant sera utilisée comme critère de recherche dans la table, pour récupérer les id de catégories correspondantes.

Dans le fichier xml jforms, vous avez vu que pour indiquer la liste des choix possibles dans un <menulist>, une <listbox>, un <radiobuttons> ou un <checkboxes>, vous pouviez indiquer une liste de valeurs statiques, ou un dao qui servira à récupérer les choix.

Il peut cependant arriver que cela soit insuffisant, et que le remplissage dépende de critères ou autre. Dans ce cas, vous n'indiquerez pas de balise <item> ni d'attribut dao* dans le fichier xml. Et vous indiquerez la liste des choix dans votre contrôleur, des manières suivantes.

   // récupérez vos données dans un tableau associatif,
   $data = array(...);
   
   // on crée un objet implémenté via l'interface jIFormsDatasource2
   $datasource = new jFormsStaticDatasource();
   $datasource->data = $data
   
   // on récupère le contrôle et on lui indique les données
   $form->getControl('nom_du_control')->datasource = $datasource;

$data est un tableau dont les clés sont les valeurs des choix, et les valeurs sont les libellés des choix.

Note : ce remplissage doit se faire dans la même action que celle qui affiche le formulaire. Ces données sont perdues à la fin de l'action.

Il est possible d'avoir des cas où l'on ne veuille pas afficher certains champs du formulaire. Vous avez pour cela les méthodes deactivate() et isActivated(). À ces deux méthodes, vous devez indiquer le nom du contrôle. La deuxième méthode permet de savoir si un champ est activé : on l'utilisera surtout dans les actions de traitement des données saisies. La première permet d'activer ou désactiver un champ. On peut lui donner en deuxième paramètre (facultatif) un booléen qui indique s'il faut désactiver (true) ou activer (false).

   $form->deactivate('nom_du_control');
   // équivalent à 
   $form->deactivate('nom_du_control', true);

   // et pour réactiver un contrôle désactivé :
   $form->deactivate('nom_du_control', false);

   // pour savoir l'état d'activation :
   if ($form->isActivated('nom_du_control')) ...
    

On préférera dans la plupart des cas le principe d'activation/désactivation, cela est plus simple à écrire, et en lisant le fichier XML, on a ainsi toute la liste des contrôles possibles.

Cependant, il y a des cas où on ne peut déclarer le composant dans le formulaire, comme par exemple le besoin de créer un nombre indéterminé à l'avance d'un élément précis. Un exemple concret : la saisie de fichiers joints à un article. Le formulaire permet de saisir les données de l'article (son titre, son contenu...), mais aussi d'ajouter des fichiers joints, comme des photos illustrant l'article. Quand on modifie un article, pour chaque photo existante, on voudrait pouvoir avoir un champs pour modifier son titre, un autre pour uploader une nouvelle version de cette photo, et un bouton pour la supprimer. Il faut ainsi créer plusieurs de ces champs de saisies en fonction du nombre de ces photos, sans avoir à en limiter le nombre.

Pour ce genre de cas, il faut alors créer les contrôles "à la main" et les ajouter dans le formulaire.

Le principe est assez simple :

• récupérer le formulaire avec jForms::get() ou jForms::create() (mais pas jForms::fill(), voir plus bas)
• instancier un objet qui hérite de jFormsControl. Il existe une classe dédiée à chaque type de contrôle : jFormsControlInput, jFormsControlListbox, jFormsControlRadiobuttons, jFormsControlHtmlEditor, etc. Voir la liste dans la documentation de référence.
• ajouter cet objet à l'objet formulaire via la méthode addControl, ou addControlBefore pour l'ajouter après un autre contrôle existant précis.
• vous pouvez ensuite afficher le formulaire, ou le remplir avec les données en paramètre grâce à la méthode initFromRequest().

Il faut savoir qu'il faut ajouter ces champs à chaque fois que vous créez ou récupérez le formulaire. En effet, à chaque fois que vous récupérer un formulaire avec jForms::get() ou jForms::fill(), jForms instancie toujours l'objet form à partir de ce qui est décrit dans le fichier XML (qui est traduit en classe PHP) et donc sans votre champs. C'est pourquoi il faut ajouter votre champs non seulement à la creation avant l'affichage, mais aussi avant son remplissage avec les données soumises.

1 – Ajout du champ à l'initialisation :

  $form = jForms::get('myModule~myForm');
  $ctrl= new jFormsControlInput('identifiant');
  $ctrl->required=true;
  $ctrl->datatype->addFacet('maxLength',255);
  $ctrl->label='Identifiant';
  $ctrl->size=100;
  $form->addControl($ctrl);

2 – Gestion après soumission :

  $form = jForms::get('myModule~myForm');
  $ctrl= new jFormsControlInput('identifiant');
  $ctrl->required=true;
  $ctrl->datatype->addFacet('maxLength',255);
  $ctrl->label='Identifiant';
  $ctrl->size=100;
  $form->addControl($ctrl);
  $form->initFromRequest();

Il est plus esthétique de factoriser la création du champ dans une méthode de votre contrôleur du type getMyControl() afin de ne pas dupliquer le code.

• *Attention** : Il ne faut surtout pas utiliser la méthode fill(), car cette méthode fait un get() puis un initFromRequest() et ne vous donne donc pas l'opportunité d'ajouter votre champ avant que les données soumises soient stockées dans le formulaire (par initFromRequest()).

3 - Pendant le remplissage dynamique d'un contrôle

Si le formulaire contient une liste qui dépend d'un autre contrôle, la liste est remplie via un appel http au contrôleur dédié à jForms.

Lors de cette action, le contrôleur emet un évènement jformsPrepareToFillDynamicList, avant de récupérer et renvoyer le contenu de la liste, permettant de préparer l'objet formulaire avec tous les champs de saisie attendu.

L'évènement contient les paramètres suivants :

• form : l'objet formulaire.
• controlRef : l'identifiant du contrôle dont la liste des valeurs sera générée.