FormHelper¶

Création de Formulaire¶

La première méthode dont vous aurez besoin d’utiliser pour prendre pleinement avantage du Helper Form (Helper Formulaire) est create(). Cette méthode affichera un tag d’ouverture de formulaire.

FormHelper::create(string $model = null, array $options = array())¶

Tous les paramètres sont optionnels. Si create() est appelée sans paramètres, CakePHP supposera que vous voulez créer un formulaire en rapport avec le controller courant, ou l’URL actuelle. La méthode par défaut pour les formulaires est POST. L’élément du formulaire est également renvoyé avec un DOM ID. Cet identifiant est créé à partir du nom du model, et du nom du controller en notation CamelCase (les majuscules délimitent les mots). Si j’appelle create() dans une vue de UsersController, j’obtiendrai ce genre de rendu dans ma vue :

<form id="UserAddForm" method="post" action="/users/add">

Note

Vous pouvez aussi passer false pour $model. Ceci placera vos donnée de formulaire dans le tableau: $this->request->data (au lieu du sous tableau:$this->request->data['Model']). Cela peut être pratique pour des formulaires courts qui ne représenteraient rien dans votre base de données.

La méthode create() nous permet également de personnaliser plusieurs paramètres. Premièrement, vous pouvez spécifier un nom de model. Ce faisant, vous modifiez le contexte de ce formulaire. Tous les champs seront supposés dépendre de ce model (sauf si spécifié), et tous les models devront être liés à lui. Si vous ne spécifiez pas de model, CakePHP supposera que vous utilisez le model par défaut pour le controller courant.

// si vous êtes sur /recipes/add
echo $this->Form->create('Recipe');

Affichera:

<form id="RecipeAddForm" method="post" action="/recipes/add">

Ce formulaire enverra les données à votre action add() de RecipesController (RecettesController) . Cependant, vous pouvez utiliser la même logique pour créer et modifier des formulaires. Le helper Form utilise la propriété $this->request->data pour détecter automatiquement s’il faut créer un formulaire d’ajout ou de modification. Si $this->request->data contient un tableau nommé d’après le model du formulaire , et que ce tableau contient une valeur non nulle pour la clé primaire du model, alors le FormHelper créera un formulaire de modification pour cet enregistrement précis. Par exemple, si on va à l’adresse https://site.com/recipes/edit/5, nous pourrions avoir cela:

// Controller/RecipesController.php:
public function edit($id = null) {
    if (empty($this->request->data)) {
        $this->request->data = $this->Recipe->findById($id);
    } else {
        // La logique de sauvegarde se fera ici
    }
}

// View/Recipes/edit.ctp:
// Puisque $this->request->data['Recipe']['id'] = 5,
// nous aurons un formulaire d'édition
<?php echo $this->Form->create('Recipe'); ?>

Affichera:

<form id="RecipeEditForm" method="post" action="/recipes/edit/5">
<input type="hidden" name="_method" value="PUT" />

Note

Comme c’est un formulaire de modification, un champ caché (hidden) est créé pour réécrire la méthode HTTP par défaut

A la création de formulaires pour les models dans des plugins. Nous devrons toujours utiliser la syntaxe de plugin à la création d’un formulaire. Cela assurera que le formulaire est correctement généré:

echo $this->Form->create('ContactManager.Contact');

Le tableau $options est l’endroit où la plupart des paramètres de configurations sont stockés. Ce tableau spécial peut contenir un certain nombre de paires clé-valeur qui peuvent affecter la manière dont le formulaire sera créé.

Modifié dans la version 2.0.

L’Url par défaut pour tous les formulaires, est maintenant l’Url incluant passed, named, et les paramètres de requête (querystring). Vous pouvez redéfinir cette valeur par défaut en fournissant $options['url'] en second paramètre de $this->Form->create().

Fermer le Formulaire¶

FormHelper::end($options = null, $secureAttributes = array())¶

Le FormHelper inclut également une méthode end() qui complète le marquage du formulaire. Souvent, end() affiche juste la base fermante du formulaire, mais l’utilisation de end() permet également au FormHelper d’ajouter les champs cachées dont le component Security SecurityComponent à besoin.:

<?php echo $this->Form->create(); ?>

<!-- Ici les éléments de Formulaire -->

<?php echo $this->Form->end(); ?>

Si une chaîne est fournie comme premier argument à end(), le FormHelper affichera un bouton submit nommé en conséquence en même temps que la balise de fermeture du formulaire.

echo $this->Form->end('Termine');

Affichera:

<div class="submit">
    <input type="submit" value="Termine" />
</div>
</form>

Vous pouvez spécifier des paramètres détaillés en passant un tableau à end():

$options = array(
    'label' => 'Update',
    'div' => array(
        'class' => 'glass-pill',
    )
);
echo $this->Form->end($options);

Affichera:

<div class="glass-pill"><input type="submit" value="Update!" name="Update"></div>

Voir l’API du Helper Form pour plus de détails.

Note

si vous utilisez le component sécurité SecurityComponent dans votre application vous devez toujours terminer vos formulaires avec end().

Modifié dans la version 2.5: Le paramètre $secureAttributes a été ajouté dans 2.5.

Création d’éléments de Formulaire¶

Il y a plusieurs façons pour créer des Forms inputs (entrée de formulaire) Commençons par regarder input(). Cette méthode inspecte automatiquement le champ du model qui lui est fourni afin de créer une entrée appropriée pour ce champ. En interne input() délègue aux autre méthode du FormHelper.

FormHelper::input(string $fieldName, array $options = array())¶

Crée les éléments suivants en donnant un Model.field particulier:

• div enveloppante (wrapping div).

• label de l’élément (Label element)

• input de(s) l’élément(s) (Input element(s))

• Erreur de l’élément avec un message si c’est applicable.

Le type d’input créé dépends de la colonne datatype:

Column Type

Champ de formulaire résultant

string (char, varchar, etc.)

text

boolean, tinyint(1)

checkbox

text

textarea

text, avec le nom de password, passwd, ou psword

password

text, avec le nom de email

email

text, avec le nom de tel, telephone, ou phone

tel

date

day, month, et year selects

datetime, timestamp

day, month, year, hour, minute, et meridian selects

time

hour, minute, et meridian selects

binary

file

Le paramètre $options vous permet de personnaliser le fonctionnement de input(), et contrôle finement ce qui est généré.

Le div entourant aura un nom de classe required ajouté à la suite si les règles de validation pour le champ du Model ne spécifient pas allowEmpty => true. Une limitation de ce comportement est que le champ du model doit avoir été chargé pendant la requête. Ou être directement associé au model fourni par create().

Nouveau dans la version 2.5: Le type binaire mappe maintenant vers un input de fichier.

Nouveau dans la version 2.3.

Depuis 2.3, l’attribut HTML5 required va aussi être ajouté selon les règles de validation du champ. Vous pouvez explicitement définir la clé required dans le tableau d’options pour la surcharger pour un champ. Pour échapper la validation attrapée par le navigateur pour l’ensemble du formulaire, vous pouvez définir l’option 'formnovalidate' => true pour l’input button que vous générez en utilisant FormHelper::submit() ou définir 'novalidate' => true dans les options pour FormHelper::create().

Par exemple, supposons que votre model User contient les champs username (varchar), password (varchar), approved (datetime) et quote (text). Vous pouvez utiliser la méthode input() de l’Helper Formulaire (Formhelper) pour créer une entrée appropriée pour tous les champs du formulaire.

echo $this->Form->create();

echo $this->Form->input('username');   //text
echo $this->Form->input('password');   //password
echo $this->Form->input('approved');   //day, month, year, hour, minute,
                                       //meridian
echo $this->Form->input('quote');      //textarea

echo $this->Form->end('Add');

Un exemple plus complet montrant quelques options pour le champ de date:

echo $this->Form->input('birth_dt', array(
    'label' => 'Date de naissance',
    'dateFormat' => 'DMY',
    'minYear' => date('Y') - 70,
    'maxYear' => date('Y') - 18,
));

Outre les options spécifique pour input() vu ci-dessus, vous pouvez spécifier n’importe quelle options pour le type d’input et n’importe quel attribut HTML (actuellement dans le focus). Pour plus d’information sur les $options et $htmlAttributes voir HTMLHelper.

Supposons un User hasAndBelongsToMany Group. Dans votre controller, définissez une variable camelCase au pluriel (groupe -> groupes dans cette exemple, ou ExtraFunkyModele -> extraFunkyModeles) avec les options de sélections. Dans l’action du controller vous pouvez définir:

$this->set('groups', $this->User->Group->find('list'));

Et dans la vue une sélection multiple peut être crée avec ce simple code:

echo $this->Form->input('Group', array('multiple' => true));

Si vous voulez un champ de sélection utilisant une relation belongsTo ou hasOne, vous pouvez ajouter ceci dans votre controller Users (en supposant que l’User belongsTo Group):

$this->set('groups', $this->User->Group->find('list'));

Ensuite, ajouter les lignes suivantes à votre vue de formulaire:

echo $this->Form->input('group_id');

Si votre nom de model est composé de deux mots ou plus, ex. « UserGroup », quand vous passez les données en utilisant set() vous devrez nommer vos données dans un format CamelCase (les Majuscules séparent les mots) et au pluriel comme ceci:

$this->set('userGroups', $this->UserGroup->find('list'));
// ou bien
$this->set(
    'reallyInappropriateModelNames',
    $this->ReallyInappropriateModelName->find('list')
);

Note

Essayez d’éviter l’utilisation de FormHelper::input() pour générer les boutons submit. Utilisez plutôt FormHelper::submit().

FormHelper::inputs(mixed $fields = null, array $blacklist = null, $options = array())¶

Génère un ensemble d’inputs (entrées) pour $fields. Si $fields est null, tous les champs, sauf ceux définis dans $blacklist, du model courant seront utilisés.

En plus de l’affichage des champs de controller, $fields peut être utilisé pour contrôler legend et fieldset (jeu de champs) rendus avec les clés fieldset et legend. $form->inputs(array('legend' => 'Ma légende')); Générera un jeu de champs input avec une légende personnalisée. Vous pouvez personnaliser des champs input individuels a travers $fields comme ceci.

echo $form->inputs(array(
    'name' => array('label' => 'label perso')
));

En plus des champs de contrôle (fields control), inputs() permet d’utiliser quelques options supplémentaires.

• fieldset Mis à false pour désactiver le jeu de champs (fieldset). Si une chaîne est fournit, elle sera utilisée comme nom de classe (classname) pour l’élément fieldset.

• legend Mis à false pour désactiver la légende (legend) pour le jeu de champs input (input set) généré. Ou fournit une chaîne pour personnaliser le texte de la légende (legend).

<input type="text" id="ModelnameFieldname" name="data[Modelname][fieldname]">

echo $this->Form->input('Modelname.fieldname');

echo $this->Form->input('Modelname.0.fieldname');
echo $this->Form->input('Modelname.1.fieldname');

<input type="text" id="Modelname0Fieldname"
    name="data[Modelname][0][fieldname]">
<input type="text" id="Modelname1Fieldname"
    name="data[Modelname][1][fieldname]">

echo $this->Form->input('Model.year', array(
    'type' => 'text',
    'name' => 'data[Model][year]'
));

// Crée <input name="email" type="text" />
echo $this->Form->input('User.email');

// Crée <select name="Tags" multiple="multiple">
echo $this->Form->input('Tags.Tags', array('multiple' => true));

// Crée le plus habituel <input name="data[User][email]" type="text" />
echo $this->Form->input('User.email', array('name' => 'data[User][email]'));

Générer des types d’inputs spécifiques¶

En plus de la méthode générique input(), le FormHelper à des méthodes spécifiques pour générer différents types d’inputs. Ceci peut être utilisé pour générer juste un extrait de code input, et combiné avec d’autres méthodes comme label() et error() pour générer des layouts (mise en page) complètements personnalisées.

Éléments de Formulaire-Méthodes spécifiques¶

Tous les elements sont créés dans un form pour le model User comme dans les exemples ci-dessous. Pour cette raison, le code HTML généré contiendra des attributs qui font référence au model User Ex: name=data[User][username], id=UserUsername

FormHelper::label(string $fieldName, string $text, array $options)¶

Crée un élément label. $fieldName est utilisé pour générer le Dom id. Si $text n’est pas défini, $fieldName sera utilisé pour définir le texte du label:

echo $this->Form->label('User.name');
echo $this->Form->label('User.name', 'Your username');

Affichera :

<label for="UserName">Name</label>
<label for="UserName">Your username</label>

$options peut soit être un tableau d’attributs HTML, ou une chaîne qui sera utilisée comme nom de classe:

echo $this->Form->label('User.name', null, array('id' => 'user-label'));
echo $this->Form->label('User.name', 'Your username', 'highlight');

Affichera:

<label for="UserName" id="user-label">Name</label>
<label for="UserName" class="highlight">Your username</label>

FormHelper::text(string $name, array $options)¶

Les autres méthodes disponibles dans l’Helper Form permettent la création d’éléments spécifiques de formulaire. La plupart de ces méthodes utilisent également un paramètre spécial $options. Toutefois, dans ce cas, $options est utilisé avant tout pour spécifier les attributs des balises HTML (comme la valeur ou l’id DOM d’un élément du formulaire).

echo $this->Form->text('username', array('class' => 'users'));

Affichera:

<input name="data[User][username]" type="text" class="users" id="UserUsername" />

FormHelper::password(string $fieldName, array $options)¶

Création d’un champ password.

echo $this->Form->password('password');

Affichera:

<input name="data[User][password]" value="" id="UserPassword" type="password">

FormHelper::hidden(string $fieldName, array $options)¶

Créera un form input caché. Exemple:

echo $this->Form->hidden('id');

Affichera:

<input name="data[User][id]" id="UserId" type="hidden">

Si le form est édité (qui est le tableau $this->request->data va contenir les informations sauvegardées pour le model User), la valeur correspondant au champ id sera automatiquement ajoutée au HTML généré. Exemple pour data[User][id] = 10:

<input name="data[User][id]" id="UserId" type="hidden" value="10" />

Modifié dans la version 2.0: Les champs cachés n’enlèvent plus la classe attribute. Cela signifie que si il y a des erreurs de validation sur les champs cachés, le nom de classe error-field sera appliqué.

FormHelper::textarea(string $fieldName, array $options)¶

Crée un champ input textarea (zone de texte).

echo $this->Form->textarea('notes');

Affichera:

<textarea name="data[User][notes]" id="UserNotes"></textarea>

Si le form est édité (ainsi, le tableau $this->request->data va contenir les informations sauvegardées pour le model User), la valeur correspondant au champs notes sera automatiquement ajoutée au HTML généré. Exemple:

<textarea name="data[User][notes]" id="UserNotes">
Ce texte va être édité.
</textarea>

Note

Le type d’input textarea permet à l’attribut $options d’échapper 'escape' lequel détermine si oui ou non le contenu du textarea doit être échappé. Par défaut à true.

echo $this->Form->textarea('notes', array('escape' => false);
// OU....
echo $this->Form->input('notes', array('type' => 'textarea', 'escape' => false);

Options

En plus de Options Communes, textarea() supporte quelques options spécifiques:

• $options['rows'], $options['cols'] Ces deux clés spécifient le nombre de lignes et de colonnes:

  echo $this->Form->textarea('textarea', array('rows' => '5', 'cols' => '5'));
  

  Affichera:

  <textarea name="data[Form][textarea]" cols="5" rows="5" id="FormTextarea">
  </textarea>
  

FormHelper::checkbox(string $fieldName, array $options)¶

Crée un élément de formulaire checkbox. Cette méthode génère également un input de formulaire caché pour forcer la soumission de données pour le champ spécifié.

echo $this->Form->checkbox('done');

Affichera:

<input type="hidden" name="data[User][done]" value="0" id="UserDone_" />
<input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

Il est possible de modifier la valeur du checkbox en utilisant le tableau $options:

echo $this->Form->checkbox('done', array('value' => 555));

Affichera:

<input type="hidden" name="data[User][done]" value="0" id="UserDone_" />
<input type="checkbox" name="data[User][done]" value="555" id="UserDone" />

Si vous ne voulez pas que le Helper Form génère un input caché:

echo $this->Form->checkbox('done', array('hiddenField' => false));

Affichera:

<input type="checkbox" name="data[User][done]" value="1" id="UserDone" />

FormHelper::radio(string $fieldName, array $options, array $attributes)¶

Crée un jeu d’inputs radios.

Options

• $attributes['value'] pour définir quelle valeur sera sélectionnée par défaut.

• $attributes['separator'] pour spécifier du HTML entre les boutons (ex <br />).

• $attributes['between'] spécifie quelques contenus à insérer entre la légende et le premier argument.

• $attributes['disabled'] définit a true ou 'disabled' désactivera tous les boutons radios générés.

• $attributes['legend'] Les éléments Radio sont enveloppés avec un legend et un fieldset par défaut. Définir $attributes['legend'] à false pour les retirer.

  $options = array('H' => 'Homme', 'F' => 'Femme');
  $attributes = array('legend' => false);
  echo $this->Form->radio('genre', $options, $attributes);
  

  Affichera:

  <input name="data[User][genre]" id="UserGenre_" value="" type="hidden">
  <input name="data[User][genre]" id="UserGenreH" value="H" type="radio">
  <label for="UserGenreH">Homme</label>
  <input name="data[User][genre]" id="UserGenreF" value="F" type="radio">
  <label for="UserGenreF">Femme</label>
  

Si pour quelque raisons vous ne voulez pas du input caché, définissez $attributes['value'] à une valeur sélectionnée ou le booléen false

• $attributes['fieldset'] Si l’attribut legend n’est pas défini à false, alors cet attribut peut être utilisé pour définir la classe de l’élément fieldset.

Modifié dans la version 2.1: L’option d’attribut $attributes['disabled'] a été ajoutée dans CakePHP 2.1.

Modifié dans la version 2.8.5: L’option d’attribut $attributes['fieldset'] a été ajoutée dans CakePHP dans 2.8.5.

FormHelper::select(string $fieldName, array $options, array $attributes)¶

Crée un menu de sélection, rempli des éléments compris dans $options, avec l’option spécifiée par $attributes['value'] sera montré comme sélectionné par défaut. Définir à false la clé “empty” dans la variable $attributes pour empêcher l’option empty par défaut:

$options = array('H' => 'Homme', 'F' => 'Femme');
echo $this->Form->select('genre', $options)

Affichera:

<select name="data[User][genre]" id="UserGenre">
<option value=""></option>
<option value="H">Homme</option>
<option value="F">Femme</option>
</select>

L’input de type select permet un attribut $option spécial appelée 'escape' qui accepte un booléen et détermine si il faut que l’entité HTML encode le contenu des options sélectionnées. Par défaut à true:

$options = array('H' => 'Homme', 'F' => 'Femme');
echo $this->Form->select('genre', $options, array('escape' => false));

• $attributes['options'] Cette clé vous permets de spécifier manuellement des options pour un input select (menu de sélection), ou pour un groupe radio. A moins que le “type” soit spécifié à “radio”, le Helper Form supposera que la cible est un input select (menu de sélection):

  echo $this->Form->select('field', array(1,2,3,4,5));
  

  Affichera:

  <select name="data[User][field]" id="UserField">
      <option value=""></option>
      <option value="0">1</option>
      <option value="1">2</option>
      <option value="2">3</option>
      <option value="3">4</option>
      <option value="4">5</option>
  </select>
  

  Les options peuvent aussi être fournies comme des paires clé-valeur:

  echo $this->Form->select('field', $options, array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2',
      'Value 3' => 'Label 3'
  ));
  

  Affichera:

  <select name="data[User][field]" id="UserField">
      <option value="Value 1">Label 1</option>
      <option value="Value 2">Label 2</option>
      <option value="Value 3">Label 3</option>
  </select>
  

  Si vous souhaitez générer un select avec des groupes optionnels, passez les données dans un format hiérarchique. Ceci fonctionnera avec les checkboxes multiples et les boutons radios également, mais au lieu des groupes optionnels enveloppez les éléments dans des fieldsets:

  $options = array(
     'Group 1' => array(
        'Value 1' => 'Label 1',
        'Value 2' => 'Label 2'
     ),
     'Group 2' => array(
        'Value 3' => 'Label 3'
     )
  );
  echo $this->Form->select('field', $options);
  

  Affichera:

  <select name="data[User][field]" id="UserField">
      <optgroup label="Group 1">
          <option value="Value 1">Label 1</option>
          <option value="Value 2">Label 2</option>
      </optgroup>
      <optgroup label="Group 2">
          <option value="Value 3">Label 3</option>
      </optgroup>
  </select>
  

• $attributes['multiple'] Si “multiple” a été défini à true pour un input select, celui ci autorisera les sélections multiples:

  echo $this->Form->select('Model.field', $options, array('multiple' => true));
  

  Vous pouvez également définir “checkbox” à “multiple” pour afficher une liste de check boxes reliés:

  $options =  array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2'
  );
  echo $this->Form->select('Model.field', $options, array(
      'multiple' => 'checkbox'
  ));
  

  Affichera:

  <div class="input select">
     <label for="ModelField">Field</label>
     <input name="data[Model][field]" value="" id="ModelField" type="hidden">
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 1" id="ModelField1" type="checkbox">
        <label for="ModelField1">Label 1</label>
     </div>
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 2" id="ModelField2" type="checkbox">
        <label for="ModelField2">Label 2</label>
     </div>
  </div>
  

• $attributes['disabled'] Lors de la création de checkboxes, cette option peut être défini pour désactiver tout ou quelques checkboxes. Pour désactiver toutes les checkboxes, définissez disabled à true:

  $options = array(
      'Value 1' => 'Label 1',
      'Value 2' => 'Label 2'
  );
  echo $this->Form->select('Model.field', $options, array(
      'multiple' => 'checkbox',
      'disabled' => array('Value 1')
  ));
  

  Output:

  <div class="input select">
     <label for="ModelField">Field</label>
     <input name="data[Model][field]" value="" id="ModelField"
      type="hidden">
     <div class="checkbox">
        <input name="data[Model][field][]" disabled="disabled"
          value="Value 1" id="ModelField1" type="checkbox">
        <label for="ModelField1">Label 1</label>
     </div>
     <div class="checkbox">
        <input name="data[Model][field][]" value="Value 2"
          id="ModelField2" type="checkbox">
        <label for="ModelField2">Label 2</label>
     </div>
  </div>
  

Modifié dans la version 2.3: Le support pour les tableaux dans $attributes['disabled'] a été ajoutée dans 2.3.

FormHelper::file(string $fieldName, array $options)¶

Pour ajouter un champ upload à un formulaire, vous devez vous assurer que le enctype du formulaire est définit a « multipart/form-data », donc commençons avec une fonction create comme ci-dessous:

echo $this->Form->create('Document', array(
    'enctype' => 'multipart/form-data'
));
// OU
echo $this->Form->create('Document', array('type' => 'file'));

Ensuite ajoutons l’une ou l’autre des deux lignes dans le fichier de vue de votre formulaire:

echo $this->Form->input('Document.submittedfile', array(
    'between' => '<br />',
    'type' => 'file'
));

// OU

echo $this->Form->file('Document.submittedfile');

En raisons des limitations du code HTML lui même, il n’est pas possible de placer des valeurs par défauts dans les champs inputs de type “file”. A chacune des fois ou le formulaire sera affiché, la valeur sera vide.

Lors de la soumission, le champ file fournit un tableau étendu de données au script recevant les données de formulaire.

Pour l’exemple ci-dessus, les valeurs dans le tableau de données soumis devraient être organisées comme à la suite, si CakePHP à été installé sur un server Windows .”tmp_name” aura un chemin différent dans un environnement Unix:

$this->request->data['Document']['submittedfile'] = array(
    'name' => conference_schedule.pdf,
    'type' => application/pdf,
    'tmp_name' => C:/WINDOWS/TEMP/php1EE.tmp,
    'error' => 0,
    'size' => 41737,
);

Ce tableau est généré par PHP lui-même, pour plus de détails sur la façon dont PHP gère les données passées a travers les champs files. lire la section file uploads du manuel de PHP.

public function isUploadedFile($params) {
    $val = array_shift($params);
    if ((isset($val['error']) && $val['error'] == 0) ||
        (!empty( $val['tmp_name']) && $val['tmp_name'] != 'none')
    ) {
        return is_uploaded_file($val['tmp_name']);
    }
    return false;
}

echo $this->Form->create('User', array('type' => 'file'));
echo $this->Form->file('avatar');

<form enctype="multipart/form-data" method="post" action="/users/add">
<input name="data[User][avatar]" value="" id="UserAvatar" type="file">

Création des boutons et des éléments submits¶

FormHelper::submit(string $caption, array $options)¶

Crée un bouton submit avec la légende $caption. Si la $caption fournie est l’URL d’une image (il contient un caractère “.”), le bouton submit sera rendu comme une image.

Il est encapsulé entre des div par défaut; vous pouvez empêcher cela en déclarant $options['div'] = false:

echo $this->Form->submit();

Affichera:

<div class="submit"><input value="Submit" type="submit"></div>

Vous pouvez aussi passer une URL relative ou absolue vers une image pour le paramêtre caption au lieu d’un caption text:

echo $this->Form->submit('ok.png');

Affichera:

<div class="submit"><input type="image" src="/img/ok.png"></div>

FormHelper::button(string $title, array $options = array())¶

Crée un boutton HTML avec le titre spécifié et un type par défaut « button ». Définir $options['type'] affichera l’un des trois types de boutons possibles:

1. submit: Comme celui de la méthode $this->Form->submit- (par défaut).

2. reset: Crée un bouton reset.

3. button: Crée un bouton standard.

echo $this->Form->button('Un bouton');
echo $this->Form->button('Un autre Bouton', array('type' => 'button'));
echo $this->Form->button('Initialise le Formulaire', array('type' => 'reset'));
echo $this->Form->button('Soumettre le Formulaire', array('type' => 'submit'));

Affichera :

<button type="submit">Un bouton</button>
<button type="button">Un autre Bouton</button>
<button type="reset">Initialise le Formulaire</button>
<button type="submit">Soumettre le Formulaire</button>

Le input de type button supporte l’option escape qui accepte un booléen et détermine si oui ou non l’entité HTML encode le $title du bouton. Par défaut à false:

echo $this->Form->button('Submit Form', array('type' => 'submit', 'escape' => true));

FormHelper::postButton(string $title, mixed $url, array $options = array ())¶

Crée un tag``<button>`` avec un <form> l’entourant qui soumets à travers POST.

Cette méthode crée un élément <form>. Donc n’utilisez pas pas cette méthode dans un formulaire ouvert. Utilisez plutôt FormHelper::submit() ou :php:meth:`FormHelper::button() pour créer des boutons a l’intérieur de formulaires ouvert.

FormHelper::postLink(string $title, mixed $url = null, array $options = array ())¶

Crée un lien HTML, mais accède à l’Url en utilisant la méthode POST. Requiert que JavaScript soit autorisé dans votre navigateur.

Cette méthode crée un élément <form>. Si vous souhaitez utiliser cette méthode dans un formulaire existant, vous devez utiliser les options inline ou block pour que le nouveau formulaire soit affiché à l’extérieur de son formulaire parent.

Si vous cherchez un bouton pour soumettre votre formulaire, vous devrez plutôt utiliser FormHelper::submit() instead.

Modifié dans la version 2.3.

L’option method a été ajoutée.

Modifié dans la version 2.5: Les options inline et block ont été ajoutées. Elles permettent de mettre en tampon la balise de form générée au lieu de la retourner avec le lien. Ceci permet d’éviter les balises de form imbriquées. Définir 'inline' => false va ajouter la balise de form en block de contenu postLink, si vous voulez utiliser un block personnalisé vous pouvez le spécifier en utilisant plutôt l’option block.

Modifié dans la version 2.6: L’argument $confirmMessage a été dépréciée. Utilisez la clé confirm dans $options à la place.

Crée des inputs de date et d’heure (date and time inputs)¶

FormHelper::dateTime($fieldName, $dateFormat = 'DMY', $timeFormat = '12', $attributes = array())¶

Crée un jeu d’inputs pour la date et l’heure. Les valeurs valides pour $dateformat sont “DMY”, “MDY”, “YMD” ou “NONE”. Les valeurs valides pour $timeFormat sont “12”, “24”, et null.

Vous pouvez spécifier de ne pas afficher les valeurs vides en paramétrant « array(“empty” => false) » dans les paramètres des attributs. il pré-sélectionnera également les champs a la date et heure courante.

FormHelper::year(string $fieldName, int $minYear, int $maxYear, array $attributes)¶

Crée un élément select`(menu de sélection) rempli avec les années depuis $minYear jusqu’à $maxYear. Les attributs HTML devrons être fournis dans $attributes. Si $attributes['empty'] est false, le select n’inclura pas d’option empty:

echo $this->Form->annee('purchased', 2000, date('Y'));

Affichera:

<select name="data[User][purchased][annee]" id="UserPurchasedYear">
<option value=""></option>
<option value="2009">2009</option>
<option value="2008">2008</option>
<option value="2007">2007</option>
<option value="2006">2006</option>
<option value="2005">2005</option>
<option value="2004">2004</option>
<option value="2003">2003</option>

<option value="2002">2002</option>
<option value="2001">2001</option>
<option value="2000">2000</option>
</select>

FormHelper::month(string $fieldName, array $attributes)¶

Crée un élément select (menu de sélection) avec le nom des mois:

echo $this->Form->month('mob');

Affichera:

<select name="data[User][mob][month]" id="UserMobMonth">
<option value=""></option>
<option value="01">January</option>
<option value="02">February</option>
<option value="03">March</option>
<option value="04">April</option>
<option value="05">May</option>
<option value="06">June</option>
<option value="07">July</option>
<option value="08">August</option>
<option value="09">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12">December</option>
</select>

Vous pouvez passer votre propre tableau des mois à utiliser en paramétrant l’attribut “monthNames”, ou avoir les mois affichés comme des nombres en passant false. (Note: les mois par défaut sont internationalisés et peuvent être traduits en utilisant la localisation):

echo $this->Form->month('mob', array('monthNames' => false));

FormHelper::day(string $fieldName, array $attributes)¶

Crée un élément select (menu de sélection) rempli avec les jours (numériques) du mois.

Pour créer une option empty avec l’affichage d’un texte de votre choix (ex. la première option est “Jour”), vous pouvez fournir le texte comme paramètre final comme ceci:

echo $this->Form->day('created');

Affichera:

<select name="data[User][created][day]" id="UserCreatedDay">
<option value=""></option>
<option value="01">1</option>
<option value="02">2</option>
<option value="03">3</option>
...
<option value="31">31</option>
</select>

FormHelper::hour(string $fieldName, boolean $format24Hours, array $attributes)¶

Crée un élément select (menu de sélection) rempli avec les heures de la journée.

FormHelper::minute(string $fieldName, array $attributes)¶

Crée un élément select (menu de sélection) rempli avec les minutes d’une heure.

FormHelper::meridian(string $fieldName, array $attributes)¶

Crée un élément select (menu de sélection) rempli avec “am” et “pm”.

Afficher et vérifier les erreurs¶

FormHelper::error(string $fieldName, mixed $text, array $options)¶

Affiche un message d’erreur de validation, spécifiée par $texte, pour le champ donné, dans le cas où une erreur de validation a eu lieu.

Options:

• “escape” booléen si il faut ou non que le HTML échappe le contenu de l’erreur.

• “wrap” valeur mixte définissant s’il faut ou pas que le message d’erreur soit envelopper d’une div. Si c’est une chaîne , sera utilisé comme le tag HTML à utiliser.

• “class” string Le nom de classe du message d’erreur.

FormHelper::isFieldError(string $fieldName)¶

Retourne true si le champ $fieldName fourni a une erreur de validation en cours:

if ($this->Form->isFieldError('genre')) {
    echo $this->Form->error('genre');
}

Note

En utilisant FormHelper::input(), les erreurs sont retournées par défaut.

FormHelper::tagIsInvalid()¶

Retourne false si le champ fourni décrit par l’entité courante ne contient pas d’erreur. Sinon retourne le message de validation.

Configuration par défaut pour tous les champs¶

Vous pouvez déclarer un ensemble d’options par défaut pour input() en utilisant FormHelper::inputDefaults(). Changer les options par défaut vous permet de consolider les options répétées dans un appel à une unique méthode:

$this->Form->inputDefaults(array(
        'label' => false,
        'div' => false,
        'class' => 'fancy'
    )
);

Tous les champs créés à partir ce point de retour vont hériter des options déclarées dans inputDefaults. Vous pouvez surcharger les options par défaut en déclarant l’option dans l’appel input():

echo $this->Form->input('password'); // Pas de div, pas de label avec la classe 'fancy'
echo $this->Form->input('username', array('label' => 'Username')); // a un élément label avec les mêmes valeurs par défaut

Travailler avec le Component Sécurity¶

SecurityComponent offre plusieurs fonctionnalités qui rendent vos formulaires plus sûres et plus sécurisés. En incluant simplement le component sécurité SecurityComponent dans votre controller, vous bénéficierez automatiquement de CSRF (Cross-site request forgery) et des fonctionnalités pour éviter la falsification.

Quand vous utilisez le SecurityComponent (component de sécurité), vous devez toujours fermer vos formulaires en utilisant FormHelper::end(). Ceci assurera que les inputs jeton spéciaux _Token seront générés.

FormHelper::unlockField($name)¶

Déverrouille un champ en le rendant exempt du hachage (hashing) du SecurityComponent. Ceci permet également au champ d’être manipulé par Javascript. Le paramètre $name devra être le nom d’entité de l’input:

$this->Form->unlockField('User.id');

FormHelper::secure(array $fields = array())¶

Génère un champ caché avec hachage sur le champ utilisé dans le formulaire.

Mises à jour 2.0¶

$selected parameter removed

Le paramètre $selected``a été retiré de plusieurs méthodes du Helper Form (FormHelper). Toutes les méthodes supportent désormais un clé  ``$attributes['value'] qui devra être utilisée en remplacement de $selected. Ce changement simplifie les méthodes du Helper Form, en réduisant le nombre d’arguments, et réduit les duplications que $selected crée. Les méthodes sont:

• FormHelper::select()

• FormHelper::dateTime()

• FormHelper::year()

• FormHelper::month()

• FormHelper::day()

• FormHelper::hour()

• FormHelper::minute()

• FormHelper::meridian()

L’URL par défaut des formulaires est l’action courante

L’URL par défaut pour tous les formulaires, est désormais l’URL courante incluant passed, named, et les paramètres de la requête (querystring parameters). Vous pouvez redéfinir cette valeur par défaut en fournissant $options['url'] dans le second paramètre de $this->Form->create().

FormHelper::hidden()

Les champs cachés n’enlèvent plus les attributs de classe. Cela signifie que si il y a des erreurs de validation sur les champs cachés le nom de classe error-field sera appliqué.