Form¶

Options for Form Creation¶

Le tableau $options est là où la configuration du formulaire se passe. Ce tableau spécial peut contenir un certain nombre de paires de clé-valeur différentes qui affectent la façon dont la balise form est générée. Voici les valeurs autorisés :

• 'type' - Vous permet de choisir le type de formulaire à créer. Si vous ne fournissez pas de type, il sera automatiquement détecté en fonction du “context” du formulaire. Cette option peut prendre une des valeurs suivantes :

  • 'get' - Définira la method du formulaire à GET.

  • 'file' - Définira la method du formulaire à POST et le 'enctype' à « multipart/form-data ».

  • 'post' - Définira la method à POST.

  • 'put', 'delete', 'patch' - Définira le verbe HTTP à, respectivement, PUT, DELETE ou PATCH quand le formulaire sera soumis.

• 'method' - Vous permet de définir explicitement la method du formulaire. Les valeurs autorisés sont les même que pour le paramètre ci-dessus.

• 'url' - Permet de spécifier l’URL à laquelle le formulaire postera les données. Peut être une chaîne ou un tableau de paramètre d’URL.

• 'encoding' - Permet de définir l’attribut accept-charset du formulaire. Par défaut, la valeur de Configure::read('App.encoding') sera utilisée.

• 'enctype' - Vous permet de définir l’encodage du formulaire de manière explicite.

• 'templates' - Les templates pour les éléments à utiliser pour ce formulaire. Tous les templates fournis écraseront les templates déjà chargés. Ce paramètre peut soit être un nom de fichier (sans extension) du dossier /config ou un tableau de templates.

• 'context' - Options supplémentaires qui seront fournies à la classe de “context” liée au formulaire. (Par exemple, le “context” EntityContext accepte une option table qui permet de définir la classe Table sur laquelle le formulaire devra se baser.

• 'idPrefix' - Préfixe à utiliser pour les attributs id des éléments du formulaire.

• 'templateVars' - Vous permet de définir des variables de template pour le template formStart.

Récupérer les valeurs du formulaire depuis la query string¶

Les sources de valeurs du FormHelper définissent d’où les éléments du formulaire reçoivent leurs valeurs.

Par défaut, Formhelper récupère ses valeurs depuis le « context ». Les contextes par défaut, comme le EntityContext, récupèrera ses valeurs depuis l’entité qui lui est attribuée ou dans $request->data.

Cependant, si vous construisez un formulaire qui a besoin d’aller récupérer ses valeurs dans la query string, vous pouvez utiliser valueSource() pour définir où le FormHelper doit aller récupérer les valeurs de ses champs:

// Donner la priorité à la query string plutôt qu'au contexte
echo $this->Form->create($article, [
    'valueSources' => ['query', 'context']
]);

// Même effet :
echo $this->Form
    ->setValueSources(['query', 'context'])
    ->create($articles);

// Lecture des valeurs seulement dans la query string
echo $this->Form->create($article);
$this->Form->setValueSources('query');

// Même effet :
echo $this->Form->create($article, ['valueSources' => 'query']);

Les sources supportées sont context, data et query. Vous pouvez utiliser une ou plusieurs sources. Tous les widgets générés par le FormHelper iront récupérer leurs valeurs dans les sources spécifiées, dans l’ordre dans lequel vous les avez définies.

Les sources définies seront réinitialisées à leur valeur par défaut (['context']) quand end() sera appelée.

Changer la méthode HTTP pour un Formulaire¶

En utilisant l’option type, vous pouvez changer la méthode HTTP qu’un formulaire va utiliser:

echo $this->Form->create($article, ['type' => 'get']);

Affichera:

<form method="get" action="/articles/edit/5">

En spécifiant file à l’option type, cela changera la méthode de soumission à “post”, et ajoutera un enctype « multipart/form-data » dans le tag du formulaire. Vous devez l’utiliser si vous avez des demandes de fichiers dans votre formulaire. L’absence de cet attribut enctype empêchera le fonctionnement de l’envoi de fichiers:

echo $this->Form->create($article, ['type' => 'file']);

Affichera:

<form enctype="multipart/form-data" method="post" action="/articles/add">

Quand vous utilisez put, patch ou delete dans l’option type, votre formulaire aura un fonctionnement équivalent à un formulaire de type “post”, mais quand il sera envoyé, la méthode de requête HTTP sera respectivement réécrite avec “PUT”, “PATCH” ou “DELETE”. Cela permet à CakePHP d’émuler un support REST dans les navigateurs web.

Définir l’URL pour le Formulaire¶

Utiliser l’option url vous permet de diriger le formulaire vers une action spécifique dans votre controller courant ou dans toute votre application. Par exemple, si vous voulez diriger le formulaire vers une action login() du controller courant, vous pouvez fournir le tableau $options comme ce qui suit:

echo $this->Form->create($article, ['url' => ['action' => 'login']]);

Affichera:

<form method="post" action="/users/login">

Si l’action que vous désirez appeler avec le formulaire n’est pas dans le controller courant, vous pouvez spécifier une URL dans le formulaire. L’URL fournie peut être relative à votre application CakePHP:

echo $this->Form->create(null, [
    'url' => ['controller' => 'Articles', 'action' => 'publish']
]);

Affichera:

<form method="post" action="/articles/publish">

ou pointer vers un domaine extérieur:

echo $this->Form->create(null, [
    'url' => 'http://www.google.com/search',
    'type' => 'get'
]);

Affichera:

<form method="get" action="http://www.google.com/search">

Utilisez 'url' => false si vous ne souhaitez pas d’URL en tant qu’action de formulaire.

Utiliser des Validateurs Personnalisés¶

Les models vont souvent avoir des ensembles de validation multiples et vous voudrez que FormHelper marque les champs nécessaires basés sur les règles de validation spécifiques que l’action de votre controller est en train d’appliquer. Par exemple, votre table Users a des règles de validation spécifiques qui s’appliquent uniquement quand un compte est enregistré:

echo $this->Form->create($user, [
    'context' => ['validator' => 'register']
]);

L’exemple précédent va utiliser les règles de validation définies dans le validateur register, définies par UsersTable::validationRegister(), pour le $user et toutes les associations liées. Si vous créez un formulaire pour les entities associées, vous pouvez définir les règles de validation pour chaque association en utilisant un tableau:

echo $this->Form->create($user, [
    'context' => [
        'validator' => [
            'Users' => 'register',
            'Comments' => 'default'
        ]
    ]
]);

Ce qui est au-dessus va utiliser register pour l’utilisateur, et default pour les commentaires de l’utilisateur.

Créer des Classes de Contexte¶

Alors que les classes de contexte intégrées essaient de couvrir les cas habituels que vous pouvez rencontrer, vous pouvez avoir besoin de construire une nouvelle classe de contexte si vous utilisez un ORM différent. Dans ces situations, vous devrez intégrer Cake\View\Form\ContextInterface . Une fois que vous avez intégré cette interface, vous pouvez connecter votre nouveau contexte dans le FormHelper. Il est souvent mieux de faire ceci dans un event listener View.beforeRender, ou dans une classe de vue de l’application:

$this->Form->addContextProvider('myprovider', function($request, $data) {
    if ($data['entity'] instanceof MyOrmClass) {
        return new MyProvider($request, $data);
    }
});

Les fonctions de fabrique de contexte sont l’endroit où vous pouvez ajouter la logique pour vérifier les options du formulaire pour le type d’entity approprié. Si une donnée d’entrée correspondante est trouvée, vous pouvez retourner un objet. Si n’y a pas de correspondance, retourne null.

Conventions de Nommage des Champs¶

Lors de la création de widgets, vous devez nommer vos champs d’après leur attribut correspondant dans l’entity du formulaire. Par exemple, si vous créez un formulaire pour un $article, vous créez des champs nommés d’après les propriétés. Par exemple title, body et published.

Vous pouvez créer des inputs pour les models associés, ou pour les models arbitraires en le passant dans association.fieldname en premier paramètre:

echo $this->Form->control('association.fieldname');

Tout point dans vos noms de champs sera converti dans des données de requête imbriquées. Par exemple, si vous créez un champ avec un nom 0.comments.body vous aurez un nom d’attribut qui sera 0[comments][body]. Cette convention facilite la sauvegarde des données avec l’ORM. Plus de détails pour tous les types d’associations se trouvent dans la section Créer des Inputs pour les Données Associées.

Lors de la création d’inputs de type datetime, FormHelper va ajouter un suffixe au champ. Vous pouvez remarquer des champs supplémentaires nommés year, month, day, hour, minute, ou meridian qui ont été ajoutés. Ces champs seront automatiquement convertis en objets DateTime quand les entities sont triées.

Options pour la méthode control()¶

FormHelper::control() supporte un nombre important d’options via son paramètre $options. En plus de ses propres options, control() accepte des options pour les champs input générés (et les autres type d’éléments comme les checkbox ou les textarea), comme les attributs HTML. Ce qui suit va couvrir les options spécifiques de FormHelper::control().

• $options['type'] - Une chaîne qui précise le type de widget à générer. En plus des types de champs vus dans Création d’éléments de Formulaire, vous pouvez aussi créer input de type file, password et tous les types supportés par HTML5. En spécifiant vous-même le type de l’élément à générer, vous écraserez le type automatique deviné par l’introspection du Model. Le défaut est null:

  echo $this->Form->control('field', ['type' => 'file']);
  echo $this->Form->control('email', ['type' => 'email']);
  

  Affichera:

  <div class="input file">
      <label for="field">Field</label>
      <input type="file" name="field" value="" id="field" />
  </div>
  <div class="input email">
      <label for="email">Email</label>
      <input type="email" name="email" value="" id="email" />
  </div>
  

• $options['label'] Soit une chaîne qui sera utilisé comme valeur pour l’élément HTML <label> ou bien un tableau d’options pour le label. Le défaut est null. Par exemple:

  echo $this->Form->control('name', [
      'label' => 'The User Alias'
  ]);
  

  Affiche :

  <div class="input">
      <label for="name">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

  Vous pouvez définir cette clé à false pour désactiver l’affichage de l’élément <label> Par exemple:

  echo $this->Form->control('name', ['label' => false]);
  

  Affiche :

  <div class="input">
      <input name="name" type="text" value="" id="name" />
  </div>
  

  Si vous passez un tableau, vous pourrez fournir des options supplémentaires pour l’element label. Si vous le faîtes, vous pouvez utiliser une clé text dans le tableau pour personnaliser le texte du label:: Par exemple:

  echo $this->Form->control('name', [
      'label' => [
          'class' => 'thingy',
          'text' => 'The User Alias'
      ]
  ]);
  

  Affiche :

  <div class="input">
      <label for="name" class="thingy">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

• $options['options'] - Vous pouvez passez à cette option un tableau contenant les choix pour les éléments comme les radio et les select. Reportez vous à Créer des Boutons Radio et Créer des Select pour plus de détails. Les défaut est null.

• $options['error'] Utiliser cette clé vous permettra de transformer les messages de model par défaut et de les utiliser, par exemple, pour définir des messages i18n. Pour désactiver le rendu des messages d’erreurs définissez la clé error à false:

  echo $this->Form->control('name', ['error' => false]);
  

  Pour surcharger les messages d’erreurs du model utilisez un tableau avec les clés respectant les messages d’erreurs de validation originaux:

  $this->Form->control('name', [
      'error' => ['Not long enough' => __('This is not long enough')]
  ]);
  

  Comme vu précédemment, vous pouvez définir le message d’erreur pour chaque règle de validation dans vos models. De plus, vous pouvez fournir des messages i18n pour vos formulaires.

• $options['nestedInput'] - Utilisez avec les inputs checkbox et radio. Cette option permet de contrôler si les éléments input doivent être générés dans ou à l’extérieur de l’élément label. Quand control() génère une checkbox ou un bouton radio, vous pouvez définir l’option à false pour forcer la génération de l’élément input en dehors du label.

  Cependant, vous pouvez également la définir à true pour n’importe quel type d’élément pour forcer la génération de l’élément input dans le label. Si vous changez l’option pour les boutons radio, vous aurez également besoin de modifier le template par défaut “radioWrapper”. En fonction du type d’élément à générer, la valeur par défaut sera true ou false.

• $options['templates'] - Les templates à utiliser pour cet input. N’importe quel template spécifié via cette option surchargera les templates déjà chargés. Cette option accepte soit un nom de fichier (sans extension) provenant de /config qui contient les templates à charger ou bien un tableau définissant les templates à utiliser.

• $options['labelOptions'] - Définissez l’option à false pour désactiver les label autour des nestedWidgets ou bien définissez un tableau d’attributs à appliquer à l’élément label.

Options Communes¶

Beaucoup des différentes méthodes d’input supportent un jeu d’options communes. Toutes ses options sont aussi supportées par control(). Pour réduire les répétitions, les options communes partagées par toutes les méthodes input sont :

• id Définir cette clé pour forcer la valeur du DOM id pour cet input. Cela remplacera l”idPrefix qui pourrait être fixé.

• default Utilisé pour définir une valeur par défaut au champ input. La valeur est utilisée si les données passées au formulaire ne contiennent pas de valeur pour le champ (ou si aucune donnée n’est transmise). Une valeur par défaut explicite va surcharger toute valeur définie par défaut dans le schéma.

  Exemple d’utilisation:

  echo $this->Form->text('ingredient', ['default' => 'Sugar']);
  

  Exemple avec un champ sélectionné (Taille « Medium » sera sélectionné par défaut):

  $sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];
  echo $this->Form->select('size', $sizes, ['default' => 'm']);
  

  Note

  Vous ne pouvez pas utiliser default pour sélectionner une chekbox - vous devez plutôt définir cette valeur dans $this->request->getData() dans votre controller, ou définir l’option checked de l’input à true.

  Attention à l’utilisation de false pour assigner une valeur par défaut. Une valeur false est utilisée pour désactiver/exclure les options d’un champ, ainsi 'default' => false ne définirait aucune valeur. A la place, utilisez 'default' => 0.

• value Utilisée pour définir une valeur spécifique pour le champ d’input. Ceci va surcharger toute valeur qui aurait pu être injectée à partir du contexte, comme Form, Entity or request->getData() etc.

  Note

  Si vous souhaitez définir un champ pour qu’il ne rende pas sa valeur récupérée à partir du contexte ou de la source de valeurs, vous devrez définir value en '' (au lieu de le définir avec null).

En plus des options ci-dessus, vous pouvez mixer n’importe quel attribut HTML que vous souhaitez utiliser. Tout nom d’option non-special sera traité comme un attribut HTML, et appliqué à l’élément HTML input généré. NdT. celui qui capte cette phrase gagne un giroTermoOnduleur à double convection.

Créer des Inputs Text¶

Cake\View\Helper\FormHelper::text(string $name, array $options)¶

• $name - Le name du champ sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel d’options avec n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Va créer un input de type text:

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

Affichera:

<input name="username" type="text" class="users">

Créer des Inputs Password¶

Cake\View\Helper\FormHelper::password(string $fieldName, array $options)¶

• $name - Le name du champ sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel d’options avec n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Création d’un input password:

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

Affichera:

<input name="password" value="" type="password">

Créer des Inputs Cachés¶

Cake\View\Helper\FormHelper::hidden(string $fieldName, array $options)¶

• $name - Le name du champ sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel d’options avec n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Créera un input hidden de form. Exemple:

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

Affichera:

<input name="id" value="10" type="hidden" />

Créer des Textareas¶

Cake\View\Helper\FormHelper::textarea(string $fieldName, array $options)¶

• $name - Le name du champ sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel d’options avec n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Crée un champ textarea (zone de texte). Le template utilisé par défaut est:

'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'

Par exemple:

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

Affichera:

<textarea name="notes"></textarea>

Si le form est édité (ainsi, le tableau $this->request->getData() 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="notes" id="notes">
    Ce Texte va être édité.
</textarea>

Options for Textarea

En plus des options générales, textarea() supporte 2 autres options spécifiques :

• 'escape' - Permet de définir si le contenu du textarea doit être échappé ou non. Le défaut est true.

  Par exemple:

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

• 'rows', 'cols' - Ces deux clés permettent de définir les attributs HTML du même nom et qui sont, respectivement, le nombre de lignes et de colonnes:

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

  Affichera:

<textarea name="textarea" cols="5" rows="5">
</textarea>

Créer des Select, des Checkbox et des Boutons Radio¶

Ces éléments ont options et des points en communs, c’est pourquoi ils sont regroupés dans section.

'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'

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

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="1">

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

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="555">

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

<input type="checkbox" name="done" value="1">

'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
'radioWrapper' => '{{label}}'

$this->Form->radio('gender', ['Masculine','Feminine','Neuter']);

<input name="gender" value="" type="hidden">
<label for="gender-0">
    <input name="gender" value="0" id="gender-0" type="radio">
    Masculine
</label>
<label for="gender-1">
    <input name="gender" value="1" id="gender-1" type="radio">
    Feminine
</label>
<label for="gender-2">
    <input name="gender" value="2" id="gender-2" type="radio">
    Neuter
</label>

echo $this->Form->radio(
    'favorite_color',
    [
        ['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],
        ['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],
        ['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="favorite-color-r">
    <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
    Red
</label>
<label for="favorite-color-u">
    <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
    Blue
</label>
<label for="favorite-color-g">
    <input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
    Green
</label>

'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>'
'option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'

'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>'
'selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</select>'

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

<select name="field">
    <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>

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

<select name="field">
    <option value="Value 1">Label 1</option>
    <option value="Value 2">Label 2</option>
    <option value="Value 3">Label 3</option>
</select>

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

<select name="field">
    <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>

$options = [
    ['text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1'],
    ['text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2'],
    ['text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_value'],
];
echo $this->Form->select('field', $options);

<select name="field">
    <option value="value 1" attr_name="attr_value 1">Description 1</option>
    <option value="value 2" attr_name="attr_value 2">Description 2</option>
    <option value="value 3" other_attr_name="other_attr_value">Description 3</option>
</select>

Créer des Inputs File¶

Cake\View\Helper\FormHelper::file(string $fieldName, array $options)¶

• $name - Le name du champ sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel d’options avec n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Permet de créer un input de type file dans votre formulaire, pour faire de l’upload de fichier. Le template de widget utilisé sera:

'file' => '<input type="file" name="{{name}}"{{attrs}}>'

Vous devez vous assurer que le enctype du formulaire est défini a multipart/form-data. Pour cela, commencez par appeler la méthode create de votre formulaire via une des deux méthodes ci-dessous:

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

Ensuite ajoutez l’une des deux lignes dans votre formulaire:

echo $this->Form->control('submittedfile', [
    'type' => 'file'
]);

// OU
echo $this->Form->file('submittedfile');

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 ci-dessous, si CakePHP à été installé sur un server Windows (la clé tmp_name aura un chemin différent dans un environnement Unix):

$this->request->data['submittedfile'] = [
    'name' => 'conference_schedule.pdf',
    'type' => 'application/pdf',
    'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',
    'error' => 0, // Peut être une chaine sur Windows.
    '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.

Creating Date & Time Related Controls¶

{{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}

<?= $this->form->dateTime('registered') ?>

<select name="registered[year]">
    <option value="" selected="selected"></option>
    <option value="2022">2022</option>
    ...
    <option value="2012">2012</option>
</select>
<select name="registered[month]">
    <option value="" selected="selected"></option>
    <option value="01">January</option>
    ...
    <option value="12">December</option>
</select>
<select name="registered[day]">
    <option value="" selected="selected"></option>
    <option value="01">1</option>
    ...
    <option value="31">31</option>
</select>
<select name="registered[hour]">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    ...
    <option value="23">23</option>
</select>
<select name="registered[minute]">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    ...
    <option value="59">59</option>
</select>

echo $this->Form->dateTime('released', [
    'year' => [
        'class' => 'year-classname',
    ],
    'month' => [
        'class' => 'month-class',
        'data-type' => 'month',
    ],
]);

<select name="released[year]" class="year-class">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    <option value="01">1</option>
    <!-- .. snipped for brevity .. -->
</select>
<select name="released[month]" class="month-class" data-type="month">
    <option value="" selected="selected"></option>
    <option value="01">January</option>
    <!-- .. snipped for brevity .. -->
</select>

// En partant du principe que l'année en cours est 2017, cet appel va
// désactiver le select pour le jour, retirer l'option vide pour le select
// de l'année, limiter l'année minimum à 2018, ajouter des attributs HTML
// à l'année, ajouter une chaîne pour l'option vide des mois et changer les
// mois pour qu'il soit afficher sous forme de chiffres
<?php
    echo $this->Form->date('registered', [
        'minYear' => 2018,
        'monthNames' => false,
        'empty' => [
            'year' => false,
            'month' => 'Choisissez un mois...'
        ],
        'day' => false,
        'year' => [
            'class' => 'cool-years',
            'title' => 'Année d'inscription'
        ]
    ]);
?>

<select class= "cool-years" name="registered[year]" title="Année d'inscription">
    <option value="2022">2022</option>
    <option value="2021">2021</option>
    ...
    <option value="2018">2018</option>
</select>
<select name="registered[month]">
    <option value="" selected="selected">Choisissez un mois...</option>
    <option value="01">1</option>
    ...
    <option value="12">12</option>
</select>

echo $this->Form->time('released', [
    'interval' => 15,
    'hour' => [
        'class' => 'foo-class',
    ],
    'minute' => [
        'class' => 'bar-class',
    ],
]);

<select name="released[hour]" class="foo-class">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    <option value="01">1</option>
    <!-- .. snipped for brevity .. -->
<option value="22">22</option>
<option value="23">23</option>
</select>
<select name="released[minute]" class="bar-class">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    <option value="15">15</option>
    <option value="30">30</option>
    <option value="45">45</option>
</select>

echo $this->Form->year('purchased', [
    'minYear' => 2000,
    'maxYear' => date('Y')
]);

<select name="purchased[year]">
    <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>

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

<select name="mob[month]">
    <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>

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

echo $this->Form->day('created', ['empty' => 'Jour']);

<select name="created[day]">
    <option value="" selected="selected">Jour</option>
    <option value="01">1</option>
    <option value="02">2</option>
    <option value="03">3</option>
    ...
    <option value="31">31</option>
</select>

echo $this->Form->hour('created', [
    'format' => 12
]);
echo $this->Form->hour('created', [
    'format' => 24
]);

echo $this->Form->minute('arrival', [
    'interval' => 10
]);

<select name="arrival[minute]">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    <option value="10">10</option>
    <option value="20">20</option>
    <option value="30">30</option>
    <option value="40">40</option>
    <option value="50">50</option>
</select>

Afficher les Erreurs¶

Cake\View\Helper\FormHelper::error(string $fieldName, mixed $text, array $options)¶

• $fieldName - Le name du champ sous la forme 'Modelname.fieldname'.

• $text - Optionnel. Une chaîne ou un tableau fournissant le(s) message(s) d’erreur. Si c’est un tableau, cela devra être un tableau de paire clé / valeur où la clé est le nom du champ en erreur et la valeur le message associé. Défaut à null.

• $options - Tableau optionnel qui ne peut contenir qu’une clé escape qui attend un booléen et qui permet de définir si le contenu HTML du message d’erreur doit être échappé ou non. Défaut à true.

Affiche un message d’erreur de validation, spécifiée par $text, pour le champ donné, dans le cas où une erreur de validation a eu lieu. Si $text n’est pas fourni alors le message de validation par défaut pour le type de champ sera utilisé.

Cette méthode utilise les templates de widgets suivant:

'error' => '<div class="error-message">{{content}}</div>'
'errorList' => '<ul>{{content}}</ul>'
'errorItem' => '<li>{{text}}</li>'

Les templates 'errorList' et 'errorItem' sont utilisés pour formater plusieurs messages d’erreur pour un seul champ.

Exemple:

// Dans TicketsTable vous avez une règle de validation 'notEmpty' :
public function validationDefault(Validator $validator)
{
    $validator
        ->requirePresence('ticket', 'create')
        ->notEmpty('ticket');
}

// Dans Templates/Tickets/add.ctp vous avez :
echo $this->Form->text('ticket');

if ($this->Form->isFieldError('ticket')) {
    echo $this->Form->error('ticket', 'Message d\'erreur 100% personnalisé !');
}

Si vous soumettez le formulaire sans fournir de valeur pour le champ Ticket, votre formulaire affichera :

<input name="ticket" class="form-error" required="required" value="" type="text">
<div class="error-message">Message d'erreur 100% personnalisé !</div>

Vérifier la Présence d’Erreurs¶

Cake\View\Helper\FormHelper::isFieldError(string $fieldName)¶

• $fieldName - Un nom de champ sous la forme 'Modelname.fieldname'.

Retourne true si le champ $fieldName fourni a une erreur de validation en cours. Sinon, retournera false:

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

Créer des éléments Submit¶

Cake\View\Helper\FormHelper::submit(string $caption, array $options)¶

• $caption - Chaîne optionnelle qui permet de fournir le texte à afficher ou le chemin vers une image pour le bouton. Défaut à 'Submit'.

• $options - Optionel. Chaîne ou tableau qui peut contenir n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Crée un input submit avec le texte $caption. Si la $caption fournie est l’URL d’une image (sous-entendu que la valeur fournie contient “://” ou que son extension soit “.jpg, .jpe, .jpeg, .gif”), un bouton submit de l’image sera généré (si l’image existe). Si le premier caractère est “/” alors le chemin de l’image sera relatif à webroot, sinon, il sera relatif à webroot/img.

Par défaut, les templates de widgets utilisés sont:

'inputSubmit' => '<input type="{{type}}"{{attrs}}/>'
'submitContainer' => '<div class="submit">{{content}}</div>'

Options pour les Submit

• 'type' - Définissez cette option à 'reset' pour générer un bouton « reset » (de remise à zéro) pour le formulaire. Défaut à 'submit'.

• 'templateVars' - Utilisez ce tableau pour fournir des templates de variables supplémentaire pour l’élément et / ou ses conteneurs.

• Tout autre paramètre sera considéré comme un attribut à l’élément HTML input.

Le code suivant:

echo $this->Form->submit('Click me');

Affichera:

<div class="submit"><input value="Click me" type="submit"></div>

Vous pouvez aussi passer une URL relative ou absolue vers une image au 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>

Les inputs submit sont utiles quand vous avez seulement besoin de textes basiques ou d’images. Si vous avez besoin d’un contenu de bouton plus complexe, vous devrez plutôt utiliser button().

Créer des Elements Button¶

Cake\View\Helper\FormHelper::button(string $title, array $options = [])¶

• $title - Chaîne obligatoire qui permet de fournir le texte du bouton.

• $options - Optionel. Chaîne ou tableau qui peut contenir n’importe laquelle des options générales ainsi que n’importe quel attribut HTML valide.

Crée un bouton HTML avec le titre spécifié et un type par défaut button. Définir

Options pour les Button

• $options['type'] - Définissez cette variable à l’une des trois valeurs suivantes :

  1. 'submit' - Comme pour la méthode $this->Form->submit(), cela créera un bouton de type submit. Notez cependant que ça ne générera pas de div autour comme pour submit(). C’est le type par défaut.

  2. 'reset' - Crée un bouton « reset » (remise à zéro) pour le formulairere.

  3. 'button' - Crée un bouton standard.

• $options['escape'] - Booléen. Si cette option est définie à true, le contenu HTML de la valeur fournie pour $title sera échappé. Défaut à false.

Par exemple:

echo $this->Form->button('A Button');
echo $this->Form->button('Another Button', ['type' => 'button']);
echo $this->Form->button('Reset the Form', ['type' => 'reset']);
echo $this->Form->button('Submit Form', ['type' => 'submit']);

Affichera :

<button type="submit">A Button</button>
<button type="button">Another Button</button>
<button type="reset">Reset the Form</button>
<button type="submit">Submit Form</button>

Exemple en utilisant l’option escape:

// Va afficher le HTML echappé.
echo $this->Form->button('<em>Submit Form</em>', [
    'type' => 'submit',
    'escape' => true
]);

Créer des Boutons POST¶

Cake\View\Helper\FormHelper::postButton(string $title, mixed $url, array $options = [])¶

• $title - Chaîne obligatoire qui sera utilisé comme texte du bouton. Notez que, par défaut, cette valeur ne sera pas échappée.

• $url - URL cible du formulaire, sous forme de chaîne ou de tableau.

• $options - Optionel. Chaîne ou tableau qui peut contenir n’importe laquelle des options générales, les options spécifiques (ci-dessous) ainsi que n’importe quel attribut HTML valide.

Crée une balise <button> avec un <form> l’entourant qui soumet une requête POST. De plus, par défaut, cela générera des inputs hidden pour le SecurityComponent.

Options for POST Button

• 'data' - Tableau clé / valeur à passer aux inputs hidden.

• 'method' - La méthode de la requête à utiliser. Par exemple si vous voulez que la requête émise simule une requête HTTP/1.1 DELETE, passez delete. La valeur par défaut est post.

• 'form' - Tableau dans lequel vous pouvez passer n’importe quelle valeur supportée par FormHelper::create().

• De plus, la méthode postButton() acceptera n’importe quelle option également valide pour la méthode button().

Par exemple

// Dans Templates/Tickets/index.ctp
<?= $this->Form->postButton('Supprimer', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

Affichera un HTML similaire à:

<form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5">
    <div style="display:none;">
        <input name="_method" value="POST" type="hidden">
    </div>
    <button type="submit">Supprimer</button>
    <div style="display:none;">
        <input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A" type="hidden">
        <input name="_Token[unlocked]" value="" type="hidden">
        <input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden">
    </div>
</form>

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

Créer des liens POST¶

Cake\View\Helper\FormHelper::postLink(string $title, mixed $url = null, array $options = [])¶

• $title - Chaîne obligatoire qui sera utilisé comme texte du bouton. Notez que, par défaut, cette valeur ne sera pas échappée.

• $url - URL cible du formulaire, sous forme de chaîne ou de tableau.

• $options - Optionel. Chaîne ou tableau qui peut contenir n’importe laquelle des options générales, les options spécifiques (ci-dessous) ainsi que n’importe quel attribut HTML valide.

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

Options pour les liens POST

• 'data' - Tableau clé / valeur à passer aux inputs hidden.

• 'method' - La méthode de la requête à utiliser. Par exemple si vous voulez que la requête émise simule une requête HTTP/1.1 DELETE, passez delete. La valeur par défaut est post.

• 'confirm' - Le message de confirmation à afficher lors du clic sur le lien. Défaut à null.

• 'block' - Définissez cette option à true pour ajouter le lien au « view block » 'postLink' ou pour fournir un nom de bloc personnalisé. Défaut à null.

• De plus, la méthode postLink acceptera n’importe quelle option également valide pour la méthode link().

Cette méthode crée un élément <form>. Si vous souhaitez utiliser cette méthode à l’intérieur d’un formulaire existant, vous devez utiliser l’option block pour que le nouveau formulaire soit défini en un view block qui peut être affiché en dehors du formulaire principal.

Si vous souhaitez plutôt créer un bouton pour soumettre votre formulaire, alors vous devriez plutôt utiliser Cake\View\Helper\FormHelper::button() ou Cake\View\Helper\FormHelper::submit().

Liste des Templates¶

La liste des templates par défaut, leur format par défaut et les variables qu’ils attendent se trouvent dans la documentation API du FormHelper.

// Ajoute du HTML personnalisé autour d'un input radio
$this->Form->setTemplates([
    'radioContainer' => '<div class="form-radio">{{content}}</div>'
]);

// Crée un ensemble d'inputs radio avec notre div personnalisé autour
echo $this->Form->control('User.email_notifications', [
    'options' => ['y', 'n'],
    'type' => 'radio'
]);

// Ajoute un groupe de formulaire pour radio personnalisé
$this->Form->setTemplates([
    'radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>'
]);

Ajouter des Variables de Template Supplémentaires aux Templates¶

Vous pouvez aussi ajouter des placeholders de template supplémentaires dans des templates personnalisés et remplir ces placeholders lors de la génération des inputs.

Par exemple:

// Ajoute un template avec le placeholder help.
$this->Form->setTemplates([
    'inputContainer' => '<div class="input {{type}}{{required}}">
        {{content}} <span class="help">{{help}}</span></div>'
]);

// Génère un input et remplit la variable help
echo $this->Form->control('password', [
    'templateVars' => ['help' => 'Au moins 8 caractères.']
]);

Affichera:

<div class="input password">
    <label for="password">
        Password
    </label>
    <input name="password" id="password" type="password">
    <span class="help">Au moins 8 caractères.</span>
</div>

Déplacer les Checkboxes & Boutons Radios à l’Extérieur du Label¶

Par défaut, CakePHP incorpore les cases à cocher créées via control() et les boutons radios créés par control() et radio() dans des éléments label. Cela contribue à faciliter l’intégration des framework CSS populaires. Si vous avez besoin de placer ces éléments à l’extérieur de la balise label, vous pouvez le faire en modifiant les templates:

$this->Form->setTemplates([
    'nestingLabel' => '{{hidden}}{{input}}<label{{attrs}}>{{text}}</label>',
    'formGroup' => '{{input}}{{label}}',
]);

Cela générera les checkbox et les boutons radio à l’extérieur de leurs labels.

Créer plusieurs éléments (controls)¶

Cake\View\Helper\FormHelper::controls(mixed $fields = [], $options = [])¶

• $fields - Un tableau des champs à générer. Permet de définir des types personnalisés, des labels et toutes autres options pour chaque champ.

• $options - Optionnel. Un tableau d’options. Les clés supportées sont :

  1. 'fieldset' - Définir à false pour désactiver l’ajout d’un fieldset. Si vide, le fieldset sera ajouté. Peut aussi être un tableau de paramètres à appliquer comme attributs HTML au fieldset généré.

  2. legend - Chaîne utilisé pour personnalisé le texte de l’élément legend. Définir à false pour désactiver l’ajout de l’élément legend.

Génère un ensemble d’inputs pour un contexte donné, entouré d’un fieldset. Vous pouvez spécifier les champs générés en les incluant:

echo $this->Form->controls([
    'name',
    'email'
]);

Vous pouvez personnaliser le texte de légende en utilisant une option:

echo $this->Form->controls($fields, ['legend' => 'Mettre à jour le post']);

Vous pouvez personnaliser les inputs générés en définissant des options additionnelles dans le paramètre $fields:

echo $this->Form->controls([
    'name' => ['label' => 'Label personnalisé']
]);

Quand vous personnalisez fields, vous pouvez utiliser le paramètre $options pour contrôler les éléments legend et fieldset générés.

Par exemple:

echo $this->Form->controls(
    [
        'name' => ['label' => 'Label personnalisé']
    ],
    null,
    ['legend' => 'Mettre à jour votre post']
);

Si vous désactiver le fieldset, la legend ne s’affichera pas.

Créer les éléments pour une Entity complète¶

Cake\View\Helper\FormHelper::allControls(array $fields, $options = [])¶

• $fields - Optionnel. Un tableau de paramétrages pour les champs qui seront générés. Permet de définir des types personnalisés, des labels et toutes autres options.

• $options - Optionnel. Un tableau d’options. Les clés supportées sont :

  1. 'fieldset' - Définir à false pour désactiver l’ajout d’un fieldset. Si vide, le fieldset sera ajouté. Peut aussi être un tableau de paramètres à appliquer comme attributs HTML au fieldset généré.

  2. legend - Chaîne utilisé pour personnalisé le texte de l’élément legend. Définir à false pour désactiver l’ajout de l’élément legend.

Cette méthode est étroitement liée à controls(), cependant l’argument $fields est égal par défaut à tous les champs de l’entity de niveau supérieur actuelle. Pour exclure des champs spécifiques de la liste d’inputs générées, définissez les à false dans le paramètre $fields:

echo $this->Form->allControls(['password' => false]);
// Avant 3.4.0:
echo $this->Form->allInputs(['password' => false]);