Commit bab1868c authored by Bertrand Gauthier's avatar Bertrand Gauthier
Browse files

Correction de la doc à propos du MultipageFormPlugin

parent d84421c0
This diff is collapsed.
......@@ -2,11 +2,11 @@
===== Formulaires =====
====== MultipageForm ======
====== MultipageFormPlugin ======
Classe mère des formulaire multi-pages (saisie en plusieurs étapes).
Cf. documentation du plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins#multipageform|MultipageForm]].
Cf. documentation du plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins#multipageform|MultipageFormPlugin]].
===== Éléments de formulaire =====
......
......@@ -10,7 +10,7 @@ MultipageForm
Classe mère des formulaire multi-pages (saisie en plusieurs étapes).
Cf. documentation du plugin de contrôleur
[MultipageForm](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins#multipageform).
[MultipageFormPlugin](./Plugins.md#multipageformplugin).
Éléments de formulaire
----------------------
......
......@@ -169,7 +169,7 @@ public function popoverAction()
}
</file>
===== MultipageForm =====
===== MultipageFormPlugin =====
Plugin de contrôleur facilitant la mise en œuvre d'un processus de saisie en plusieurs étapes (formulaire multi-pages) :
* les infos saisies à l'étape courante doivent être valides pour pouvoir passer à l'étape suivante
......
......@@ -4,16 +4,16 @@ Plugins de contrôleur (controller plugins)
Confirm
-------
Ce plugin forme un couple avec l\'aide de vue du même nom.
Ce plugin forme un couple avec l'aide de vue du même nom.
Dans l\'exemple qui suit, on affiche une fenêtre (modale) de demande de
confirmation lorsqu\'on clique sur le lien de suppression d\'un contrat.
Dans l'exemple qui suit, on affiche une fenêtre (modale) de demande de
confirmation lorsqu'on clique sur le lien de suppression d'un contrat.
La requête de suppression du contrat est une requête AJAX (grâce au
mécanisme installé sur les liens classés \"ajax-modal\", cf.
`AjaxModalListener` dans \"unicaen.js\").
mécanisme installé sur les liens classés "ajax-modal", cf.
`AjaxModalListener` dans "unicaen.js").
Voici la vue affichant le lien de suppression d\'un contrat :
Voici la vue affichant le lien de suppression d'un contrat :
``` {.html}
<?php $urlSuppression = $this->url('contrat/supprimer', ['contrat' => $this->contrat->getId()]); ?>
......@@ -30,7 +30,7 @@ Voici la vue affichant le lien de suppression d\'un contrat :
```
Voici le contrôleur répondant aux requêtes de suppression de contrat
(route \'contrat/supprimer\') :
(route 'contrat/supprimer') :
``` {.php}
public function supprimerAction()
......@@ -55,8 +55,8 @@ public function supprimerAction()
}
```
Et voici la vue associée à l\'action `supprimerAction` qui utilise
l\'aide de vue `confirm` :
Et voici la vue associée à l'action `supprimerAction` qui utilise
l'aide de vue `confirm` :
``` {.php}
<h1><?php echo $this->title ?></h1>
......@@ -73,7 +73,7 @@ dédiée.](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins/uploader)
LdapGroupService
----------------
Fournit le service d\'accès aux groupes LDAP. Exemple :
Fournit le service d'accès aux groupes LDAP. Exemple :
``` {.php}
$this->ldapGroupService()->getMapper()->findOneByDn('cn=support_info,ou=groups,dc=unicaen,dc=fr');
......@@ -82,7 +82,7 @@ $this->ldapGroupService()->getMapper()->findOneByDn('cn=support_info,ou=groups,d
LdapPeopleService
-----------------
Fournit le service d\'accès aux individus LDAP. Exemple :
Fournit le service d'accès aux individus LDAP. Exemple :
``` {.php}
$this->ldapPeopleService()->getMapper()->findOneByUsername('gauthierb');
......@@ -91,7 +91,7 @@ $this->ldapPeopleService()->getMapper()->findOneByUsername('gauthierb');
LdapStructureService
--------------------
Fournit le service d\'accès aux structures LDAP. Exemple :
Fournit le service d'accès aux structures LDAP. Exemple :
``` {.php}
$this->ldapStructureService()->getMapper()->findOneByDnOrCodeEntite('HS_C68');
......@@ -100,7 +100,7 @@ $this->ldapStructureService()->getMapper()->findOneByDnOrCodeEntite('HS_C68');
Mail
----
Fournit le service d\'envoi de mail. Vous pouvez le paramétrer dans la
Fournit le service d'envoi de mail. Vous pouvez le paramétrer dans la
config locale du module UnicaenApp, exemple :
``` {.php}
......@@ -120,7 +120,7 @@ config locale du module UnicaenApp, exemple :
),
```
Exemple d\'utilisation :
Exemple d'utilisation :
``` {.php}
// corps au format HTML
......@@ -143,8 +143,8 @@ $this->mail()->send($message);
ModalInnerViewModel
-------------------
Encapsule le résultat d\'une vue (ViewModel) dans le marquage attendu
par Bootstrap pour l\'intégrer dans une fenêtre modale.
Encapsule le résultat d'une vue (ViewModel) dans le marquage attendu
par Bootstrap pour l'intégrer dans une fenêtre modale.
Exemple :
......@@ -171,12 +171,12 @@ public function modalAction()
PopoverInnerViewModel
---------------------
Encapsule le résultat d\'une vue (ViewModel) dans le marquage attendu
par Bootstrap pour l\'intégrer dans un élément \"popover\".
Encapsule le résultat d'une vue (ViewModel) dans le marquage attendu
par Bootstrap pour l'intégrer dans un élément "popover".
Exemple :
``` {.php}
``` {.php
public function popoverAction()
{
$terminal = $this->getRequest()->isXmlHttpRequest();
......@@ -196,32 +196,31 @@ public function popoverAction()
}
```
MultipageForm
MultipageFormPlugin
-------------
Plugin de contrôleur facilitant la mise en œuvre d\'un processus de
Plugin de contrôleur facilitant la mise en œuvre d'un processus de
saisie en plusieurs étapes (formulaire multi-pages) :
- les infos saisies à l\'étape courante doivent être valides pour
pouvoir passer à l\'étape suivante
- les infos saisies à l'étape courante doivent être valides pour
pouvoir passer à l'étape suivante
- stockage en session des infos saisies à chaque étape
- application du pattern
[Post-Redirect-Get](http://fr.wikipedia.org/wiki/Post-Redirect-Get)
(délégation au [plugin fourni par
ZF2](http://framework.zend.com/manual/2.0/en/modules/zend.mvc.plugins.html#the-post-redirect-get-plugin))
(délégation au [plugin fourni par ZF](http://framework.zend.com/manual/2.0/en/modules/zend.mvc.plugins.html#the-post-redirect-get-plugin))
- possibilité de revenir en arrière sans perdre les infos saisies
(même en cas de saisie partielle à l\'étape courante)
(même en cas de saisie partielle à l'étape courante)
### Formulaire
L\'idée est de créer un formulaire global héritant de la classe
L'idée est de créer un formulaire global héritant de la classe
`\UnicaenApp\Form\MultipageForm` composé de plusieurs fieldsets, chaque
fieldset correspondant à une étape de la saisie.
Exemple d\'un formulaire de contact avec une saisie en 3 étapes
Exemple d'un formulaire de contact avec une saisie en 3 étapes
(identité, coordonnées, divers) :
``` {.php}
```php
namespace Application\Form;
use UnicaenApp\Form\MultipageForm;
......@@ -247,7 +246,7 @@ Chaque fieldset hérite de la classe `\Zend\Form\Fieldset`.
Exemple du fieldset de saisie des coordonnées :
``` {.php}
```php
namespace Application\Form;
use Zend\Form\Element\Text;
......@@ -301,37 +300,44 @@ class CoordFieldset extends Fieldset implements InputFilterProviderInterface
}
```
\<note\>Implémenter l\'interface `InputFilterProviderInterface` (méthode
`getInputFilterSpecification()`) n\'est pas obligatoire mais elle permet
*Implémenter l'interface `InputFilterProviderInterface` (méthode
`getInputFilterSpecification()`) n'est pas obligatoire mais elle permet
de fournir les règles de filtrage et de validation des valeurs saisie
dans le fieldset.\</note\>
dans le fieldset.*
### Contrôleur
Pour fonctionner, le plugin a besoin de connaître :
- Le formulaire global :
<!-- -->
* Il doit donc être fourni à **chaque** invocation du plugin : ''$this->multipageForm($this->getForm())''.
* La table de correspondance qui associe à chacun des fieldsets du formulaire une action du contrôleur :
* Par défaut, le nom de l'action correspondant à un fieldset est le nom de ce fieldset. Par exemple, le fieldset ''new CoordFieldset('coordonnees')'' correspondra à l'action nommée ''coordonnees'' (i.e. méthode ''coordonneesAction()'' du contrôleur).
* Cette table de correspondance est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une table différente en appelant la méthode ''setFieldsetActionMapping()'' du formulaire.
* L'action du contrôleur correspondant au récapitulatif et à la demande de confirmation de la saisie complète (facultatif)
* Par défaut, c'est '''confirmer'''.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la méthode ''setConfirmAction()'' du formulaire.
* L'action du contrôleur correspondant à l'enregistrement de la saisie
* Par défaut, c'est '''enregistrer'''.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la méthode ''setProcessAction()'' du formulaire.
* L'action du contrôleur correspondant à l'abandon à tout moment de la saisie
* Par défaut, c'est '''annuler'''.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la méthode ''setCancelAction()'' du formulaire.
\<note important\> NB: il est possible de spécifier un préfixe à
appliquer à **tous** les noms d\'actions grâce à la méthode
- Le formulaire global :
* Il doit donc être fourni à **chaque** invocation du plugin : `$this->multipageForm($this->getForm())`.
- La table de correspondance qui associe à chacun des fieldsets du formulaire une action du contrôleur :
* Par défaut, le nom de l'action correspondant à un fieldset est le nom de ce fieldset. Par exemple, le fieldset
`new CoordFieldset('coordonnees')` correspondra à l'action nommée `coordonnees` (i.e. méthode `coordonneesAction()`
du contrôleur).
* Cette table de correspondance est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une table
différente en appelant la méthode `setFieldsetActionMapping()` du formulaire.
- L'action du contrôleur correspondant au récapitulatif et à la demande de confirmation de la saisie complète (facultatif)
* Par défaut, c'est `'confirmer'`.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la
méthode `setConfirmAction()` du formulaire.
- L'action du contrôleur correspondant à l'enregistrement de la saisie
* Par défaut, c'est `'enregistrer'`.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la
méthode `setProcessAction()` du formulaire.
- L'action du contrôleur correspondant à l'abandon à tout moment de la saisie
* Par défaut, c'est `'annuler'`.
* Elle est obtenue par le plugin auprès du formulaire, vous pouvez donc spécifier une action différente grâce à la
méthode `setCancelAction()` du formulaire.
*NB: il est possible de spécifier un préfixe à
appliquer à **tous** les noms d'actions grâce à la méthode
`setActionPrefix()` du formulaire. Dans notre exemple, le préfixe
`'ajouter-`\' est spécifié pour pointer vers les méthodes :
`'ajouter-`' est spécifié pour pointer vers les méthodes :*
- `ajouterIdentiteAction()` plutôt que vers `identiteAction()`
- `ajouterCoordonneesAction()` plutôt que vers `coordonneesAction()`
......@@ -340,22 +346,17 @@ appliquer à **tous** les noms d\'actions grâce à la méthode
- `ajouterEnregistrerAction()` plutôt que vers `enregistrerAction()`
- `ajouterAnnulerAction()` plutôt que vers `annulerAction()`
\</note\>
Exemple de contrôleur pour la saisie d'une candidature :
Exemple de contrôleur pour la saisie d\'une candidature :
- l'action `ajouter` est le point d'entrée du processus
- l'action `ajouter-identite` est la première étape
- l'action `ajouter-coordonnees` est la deuxième étape
- l'action `ajouter-divers` est la troisième et dernière étape
- l'action `ajouter-confirmer` est chargée de récapituler les infos saisies et demander confirmation
- l'action `ajouter-enregistrer` est chargée d'enregistrer les infos saisies dans une base de données par exemple
- l'action `ajouter-annuler` correspond à la requête d'abandon de la saisie
- l\'action `ajouter` est le point d\'entrée du processus
- l\'action `ajouter-identite` est la première étape
- l\'action `ajouter-coordonnees` est la deuxième étape
- l\'action `ajouter-divers` est la troisième et dernière étape
- l\'action `ajouter-confirmer` est chargée de récapituler les infos
saisies et demander confirmation
- l\'action `ajouter-enregistrer` est chargée d\'enregistrer les infos
saisies dans une base de données par exemple
- l\'action `ajouter-annuler` correspond à la requête d\'abandon de la
saisie
``` {.php}
```php
namespace Application\Controller;
use Application\Form\ContactForm;
......@@ -426,49 +427,48 @@ class DemandeController extends AbstractActionController
#### Étape de saisie
Un script de vue par étape de saisie doit être fourni, dans lequel
l\'aide de vue `MultipageFormFieldset` doit être utilisée. Cette aide de
vue génère un titre (h2) indiquant \"Étape i sur N\", le code HTML du
fieldset de l\'étape en cours ainsi que les boutons de navigation.
l'aide de vue `MultipageFormFieldset` doit être utilisée. Cette aide de
vue génère un titre (h2) indiquant "Étape i sur N", le code HTML du
fieldset de l'étape en cours ainsi que les boutons de navigation.
Exemple :
``` {.php}
```phtml
<h1>Formulaire de contact</h1>
<?php echo $this->multipageFormFieldset(); ?>
```
\<note important\>Inscrivez le même titre h1 pour toutes les
étapes.\</note\>
*Inscrivez le même titre h1 pour toutes les étapes.*
#### Confirmation
Vous devez fournir le script de vue pour la page de
récapitulatif/confirmation et utiliser l\'aide de vue
récapitulatif/confirmation et utiliser l'aide de vue
`MultipageFormRecap`. Cette aide de vue génère automatiquement la liste
de toutes les informations saisies et les boutons de navigation.
Exemple :
``` {.php}
```phtml
<h1>Formulaire de contact</h1>
<h2>Récapitulatif et confirmation des informations saisies</h2>
<?php echo $this->multipageFormRecap(); ?>
```
\<note important\> L\'aide de vue `MultipageFormRecap` explore
*L'aide de vue `MultipageFormRecap` explore
automatiquement tous les éléments visibles de tous les fieldsets du
formulaire afin de collecter leur labels et leur valeurs et les
présenter sous la forme d\'une liste de définition (dl). Si vous
présenter sous la forme d'une liste de définition (dl). Si vous
souhaitez maîtriser plus finement la façon dont sont constitués les
labels ou les valeurs d\'un fieldset, faites implémenter à la classe de
ce fieldset l\'interface
labels ou les valeurs d'un fieldset, faites implémenter à la classe de
ce fieldset l'interface
`\UnicaenApp\Form\MultipageFormFieldsetInterface` pour fournir via la
méthode `getLabelsAndValues()` les labels et valeurs de tous les
éléments de ce fieldset.
éléments de ce fieldset.*
Exemple :
``` {.php}
```php
namespace Application\Form;
use Unicaen\Exception;
......@@ -513,5 +513,3 @@ class DiversFieldset extends Fieldset implements InputFilterProviderInterface, M
}
}
```
\</note\>
......@@ -901,7 +901,7 @@ Exemple :
<?php echo $this->multipageFormFieldset(); ?>
</file>
<note important>Le fieldset courant est transmis à la vue par le plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins:multipageform|MultipageForm]] via la variable de vue ''fieldset''.</note>
<note important>Le fieldset courant est transmis à la vue par le plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins:multipageform|MultipageFormPlugin]] via la variable de vue ''fieldset''.</note>
====== MultipageFormNav ======
......@@ -919,7 +919,7 @@ Exemple :
<?php echo $this->multipageFormRecap(); ?>
</file>
<note important>Le formulaire complet est transmis à la vue par le plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins:multipageform|MultipageForm]] via la variable de vue ''form''.</note>
<note important>Le formulaire complet est transmis à la vue par le plugin de contrôleur [[develop:unicaen2:moduleunicaenunicaenapp:controllerplugins:multipageform|MultipageFormPlugin]] via la variable de vue ''form''.</note>
<note important>
Cette aide de vue explore automatiquement tous les éléments visibles de tous les fieldsets du formulaire afin de collecter leur labels et leur valeurs et les présenter sous la forme d'une liste de définition (dl).
......
......@@ -1035,7 +1035,7 @@ Exemple :
\<note important\>Le fieldset courant est transmis à la vue par le
plugin de contrôleur
[MultipageForm](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins/multipageform)
[MultipageFormPlugin](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins/multipageform)
via la variable de vue `fieldset`.\</note\>
MultipageFormNav
......@@ -1063,7 +1063,7 @@ Exemple :
\<note important\>Le formulaire complet est transmis à la vue par le
plugin de contrôleur
[MultipageForm](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins/multipageform)
[MultipageFormPlugin](/develop/unicaen2/moduleunicaenunicaenapp/controllerplugins/multipageform)
via la variable de vue `form`.\</note\>
\<note important\> Cette aide de vue explore automatiquement tous les
......
......@@ -11,6 +11,7 @@ use Zend\Mvc\Controller\Plugin\AbstractPlugin;
use Zend\Mvc\Plugin\Prg\PostRedirectGet;
use Zend\Router\Http\RouteMatch;
use Zend\Session\Container;
use UnicaenApp\Form\Element;
/**
* Plugin de contrôleur facilitant la mise en oeuvre d'un formulaire multi-pages.
......@@ -29,13 +30,13 @@ class MultipageForm extends AbstractPlugin
const ACTION_CANCEL = 'cancel';
const ACTION_CONFIRM = 'confirm';
const NAV = \UnicaenApp\Form\Element\MultipageFormNav::NAME;
const PREFIX = \UnicaenApp\Form\Element\MultipageFormNav::PREFIX;
const NEXT = \UnicaenApp\Form\Element\MultipageFormNav::NEXT;
const PREVIOUS = \UnicaenApp\Form\Element\MultipageFormNav::PREVIOUS;
const SUBMIT = \UnicaenApp\Form\Element\MultipageFormNav::SUBMIT;
const CANCEL = \UnicaenApp\Form\Element\MultipageFormNav::CANCEL;
const CONFIRM = \UnicaenApp\Form\Element\MultipageFormNav::CONFIRM;
const NAV = Element\MultipageFormNav::NAME;
const PREFIX = Element\MultipageFormNav::PREFIX;
const NEXT = Element\MultipageFormNav::NEXT;
const PREVIOUS = Element\MultipageFormNav::PREVIOUS;
const SUBMIT = Element\MultipageFormNav::SUBMIT;
const CANCEL = Element\MultipageFormNav::CANCEL;
const CONFIRM = Element\MultipageFormNav::CONFIRM;
/**
* Navigation element names
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment