Champs de formulaires
- Options communes à tous les types de champs
- Types de champs

Champs de formulaires

Lorsque vous créez un formulaire, vous définissez les champs en instanciant des sous-classes de SField. Chaque sous-classe possède une logique de validation spécifique, implémentée dans la méthode clean(). Cette méthode prend un seul argument et lève une exception SValidationError si la valeur n'est pas valide (autrement, la valeur est retournée). Bien sûr, la classe SForm s'occupe d'appeller la méthode clean() pour chacun des champs lorsque vous appellez SForm::is_valid(), vous n'avez donc pas à vous en soucier directement, sauf si vous souhaitez créer un nouveau type de champ.

Lorsque vous instanciez un champ, vous pouvez lui fournir un certain nombre d'options ; certaines sont communes à tous les types de champs, d'autres sont spécifiques :

$f = new SCharField(array('required' => true, 'initial' => 'Your name', 'label' => 'Your super name', 'length' => 25));

Options communes à tous les types de champs

required : par défaut, aucun champ n'est obligatoire ; si vous passez l'option 'required' ⇒ true, une exception SValidationError sera levée si une valeur vide (null ou une chaîne vide) est passée à la méthode clean().
label : cette option vous permet de spécifier un label à utiliser pour le champ. Le label n'est utilisé que lors de l'affichage du formulaire. Le label par défaut est généré à partir du nom du champ, les underscores étant convertis en espaces et la 1ère étant passée en majuscule.
initial : cette option vous permet de définir une valeur initiale à utiliser lors du rendu du formulaire avant son association avec des valeurs (via la méthode is_valid() notamment). Il est important de comprendre que les valeurs initiales ne doivent pas être passées au constructeur du formulaire sous peine de déclencher la validation. Si vous souhaitez définir d'un coup les valeurs initiales de tous les champs du formulaire, utilisez la méthode SForm::set_initial_values().
input : cette option vous permet de spécifier une sous-classe de SInput à utiliser pour la génération HTML du champ. C'est à l'aide de cette option que vous pouvez par exemple définir des champs cachés :

$f = new SCharField(array('input' => 'SHiddenInput'));

input_attrs : cette option vous permet de spécifier des attributs HTML à fournir au SInput chargé du rendu du champ. C'est à l'aide de cette option que vous pouvez par exemple préciser le nombre de colonnes et de lignes d'un <textarea /> :

$f = new STextField(array('input_attrs' => array('cols' => 80, 'rows' => 20)));

help_text : cette option vous permet de spécifier un texte d'aide à afficher à côté du champ. Notez qu'il ne sera pas affiché par le rendu standard du formulaire, mais que vous pourrez l'utiliser dans la création de vos templates de formulaires.
error_messages : cette option vous permet de surcharger les messages d'erreur par défaut du champ.

$name = new SCharField(array('error_messages' => array('required' => 'Please enter your name')));

Types de champs

Les sous-classes de SField représentent la plupart des besoins de validation courants. Vous trouverez ci-dessous la description de ces différents types de champs. Pour chaque type sont indiqués la sous-classe de SInput utilisée par défaut pour la génération HTML ainsi que les options spécifiques au champ.

SBooleanField

input par défaut : SCheckboxInput
typecasting : un booléen true ou false

SCharField

input par défaut : STextInput
options : length, max_length, min_length permettant de spécifier des nombres de caractères à vérifier lors de la validation, et regex, une expression régulière permettant de vérifier le format de la chaîne de caractères.