Form¶

Options pour la Création de Formulaire¶

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

• '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' - Écrasera la méthode HTTP avec PUT, DELETE ou PATCH, respectivement, 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.

• autoSetCustomValidity - Défini à true pour utiliser des messages de validation personnalisés pour required et notBlank dans le message de validité HTML5 du contrôle. Par défaut true.

Récupérer les valeurs du formulaire depuis d’autres sources¶

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

Les sources supportées sont context, data et query. Vous pouvez utiliser une ou plusieurs de ces sources en définissant l’option valueSources ou en appelant setValuesSource(). Tous les éléments générés par FormHelper vont collecter leurs valeurs à partir de ces sources, dans l’ordre que vous aurez défini.

Par défaut, Formhelper récupère ses valeurs depuis les data ou le « context », c’est-à-dire qu’il va récupérer les données avec $request->getData() ou, si elles sont absentes, à partir des données du contexte actif, qui sont les données de l’entity dans le cas de EntityContext.

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, [
    'type' => 'get',
    'valueSources' => ['query', 'context']
]);

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

Lorsque les données reçues ont besoin d’être traitées par l’entity (c’est-à-dire les convertir, traiter une table ou computer des entités) et affichées après une ou plusieurs soumissions de formulaire pendant lesquelles les données de la requête sont conservées, vous aurez besoin de placer context en premier:

// Donner la priorité au contexte par rapport aux données de la requête:
echo $this->Form->create($article,
    'valueSources' => ['context', 'data']
]);

Les sources définies seront réinitialisées à leur valeur par défaut ['data', '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 publish() du controller courant, vous pouvez fournir le tableau $options comme suit:

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

Affichera:

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

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' => 'https://www.google.com/search',
    'type' => 'get'
]);

Affichera:

<form method="get" action="https://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. FormHelper utilise les validateurs pour générer les attributs HTML5 required, les attributs ARIA appropriés, et définir les messages d’erreur avec la browser validator API . Si vous voulez désactiver les messages de validation HTML5, utilisez:

$this->Form->setConfig('autoSetCustomValidity', false);

Cela ne désactivera pas les attributs``required``/aria-required.

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 implémenter Cake\View\Form\ContextInterface . Une fois que vous avez implémenté cette interface, vous pouvez connecter votre nouveau contexte dans le FormHelper. Le mieux est souvent de le faire 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($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, retournez 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 des 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 en 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 coorespond à celle de 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 seront traité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 (devinés ou choisis, comme les checkbox ou les textarea), ou encore 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ée comme valeur pour l’élément HTML <label>, soit un tableau d’options pour le label. Vous pouvez placer sous cette clé le texte que vous voudriez voir affiché dans le label qui accompagne habituellement les éléments HTML input. 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 le label est désactivé et qu’un attribut placeholder est fourni, l’input généré aura un aria-label défini.

  Définissez l’option label comme un tableau pour fournir des options supplémentaires pour l’élément label. Si vous faites ainsi, 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 passer à cette option un tableau contenant les choix pour les éléments comme les radio et les select, qui ont besoin d’un tableau d’items en argument. Reportez-vous à Créer des Boutons Radio et Créer des Select pour plus de détails. Le défaut est null.

• $options['error'] Utiliser cette clé vous permettra de transformer les messages par défaut du model 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 présente dans vos models. De plus, vous pouvez fournir des messages i18n pour vos formulaires.

• $options['nestedInput'] - À utiliser avec les inputs checkbox et radio. Cette option permet de contrôler si les éléments input doivent être générés à l’intérieur 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.

  D’autre part, 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”. Selon le 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, soit 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 à Tous les Inputs¶

Parmi les différentes méthodes d’input, beaucoup supportent un jeu d’options communes qui, selon la méthode de formulaire utilisée, doivent être insérées soit sous la clé $options soit sous la clé $attributes du tableau en argument. Toutes ces 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). Si aucune valeur par défaut n’est définie, c’est la valeur par défaut de la colonne qui sera utilisée.

  Exemple d’utilisation:

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

  Exemple avec un champ select (la taille « Medium » sera sélectionnée 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 checkbox - 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. À 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 valuesSource, vous devrez définir value à '' (au lieu de le définir à null).

En plus des options ci-dessus, vous pouvez y mélanger n’importe quel attribut HTML que vous souhaitez utiliser. Tout nom d’option non spécifiquement prévu par CakePHP sera traité comme un attribut HTML, et appliqué à l’élément HTML input généré.

Créer des Inputs Text¶

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

• $name - Le nom du champ (attribut name) sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales ainsi que n’importe quels attributs HTML valides.

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 nom du champ (attribut name) sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales ainsi que n’importe quels attributs HTML valides.

Création d’un input simple de type 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 nom du champ (attribut name) sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales ainsi que n’importe quels attributs HTML valides.

Créera un input de type hidden. Exemple:

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

Affichera:

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

Créer des Textareas¶

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

• $name - Le nom du champ (attribut name) sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales, des options spécifiques aux textareas (cf. ci-dessous) ou encore n’importe quels attributs HTML valides.

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 formulaire est un formulaire d’édition (c’est-à-dire si le tableau $this->request->getData() contient des informations précédemment sauvegardées pour l’entity User), la valeur correspondant au champ notes sera automatiquement ajoutée au HTML généré. Exemple:

<textarea name="notes" id="notes">
    Ce Texte est fait pour être édité.
</textarea>

Options pour Textarea

En plus des options générales, textarea() supporte quelques 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 désignent respectivement le nombre de lignes et de colonnes::;

  echo $this->Form->textarea(“comment”, [“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 certains points communs et des options communes, c’est pourquoi ils sont regroupés dans cette section.

$options = $examples->combine('id', 'name');

$options = $examples->map(function ($value, $key) {
    return [
        'value' => $value->id,
        'text' => $value->name,
        'data-created' => $value->created
    ];
});

'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('genre', ['Masculin','Féminin','Neutre']);

<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>

echo $this->Form->radio(
    'couleur_preferee',
    [
        ['value' => 'r', 'text' => 'Rouge', 'label' => ['class' => 'rouge']],
        ['value' => 'u', 'text' => 'Bleu', 'label' => ['class' => 'bleu']],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="couleur-preferee-r" class="rouge">
    <input type="radio" name="couleur_preferee" value="r" id="couleur-preferee-r">
    Rouge
</label>
<label for="couleur-preferee-u" class="bleu">
    <input type="radio" name="couleur_preferee" value="u" id="couleur-preferee-u">
    Bleu
</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 nom du champ (attribut name) sous la forme 'Modelname.fieldname'.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales ainsi que n’importe quels attributs HTML valides.

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');

Pour empêcher le submittedfile d’être écrasé par un contenu vide, enlevez-le de $_accessible. Au choix, vous pouvez aussi retirer sa clé depuis la méthode beforeMarshal:

public function beforeMarshal(\Cake\Event\EventInterface $event, \ArrayObject $data, \ArrayObject $options)
{
   if ($data['submittedfile'] === '') {
      unset($data['submittedfile']);
   }
}

Lors de la soumission du formulaire, vous pouvez accéder aux inputs de type file par le biais des objets UploadedFileInterface présents dans la requête. Pour déplacer les fichiers uploadés vers un emplacement permanent, vous pouvez utiliser:

$fileobject = $this->request->getData('submittedfile');
$destination = UPLOAD_DIRECTORY . $fileobject->getClientFilename();

// S'il existe un fichier du même nom, il sera écrasé.
$fileobject->moveTo($destination);

-.. _create-datetime-controls:

Créer des éléments de formulaire pour les dates et heures¶

Cake\View\Helper\FormHelper::dateTime($fieldName, $options = [])¶

• $fieldName - Une chaîne qui sera utilisée comme préfixe pour l’attribut name des select.

• $options - Un tableau optionnel pouvant contenir n’importe quelles options générales ainsi que n’importe quels attributs HTML valides.

Générera une balise input de type « datetime-local ».

Par exemple

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

Affichera:

<input type="datetime-local" name="inscription" />

Le valeur de l’input peut être n’importe quel datetime valide ou une instance DateTime.

Par exemple

<?= $this->form->dateTime('inscription', ['value' => new DateTime()]) ?>

Affichera:

<input type="datetime-local" name="inscription" value="2019-02-08T18:20:10" />

<?= $this->form->date('inscription') ?>

<input type="date" name="inscription" />

echo $this->Form->time('redemarrage');

<input type="time" name="redemarrage" />

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

<input type="month" name="mob" />

echo $this->Form->year('achat', [
    'min' => 2000,
    'max' => date('Y')
]);

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

Afficher les Erreurs¶

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

• $fieldName - Le nom du champ (attribut name) 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 paires 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é par $text, pour le champ donné, dans le cas où une erreur de validation s’est produite. 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:

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

// Et dans templates/Tickets/add.php 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>

Si vous utilisez un champ particulier du modèle pour générer des champs de formulaire multiples via control(), et si vous voulez que le même message d’erreur soit utilisé pour chacun d’eux, il sera probablement préférable de définir votre message d’erreur personnalisé dans les validator rules.

Vérifier la Présence d’Erreurs¶

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

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

Renvoie 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');
}

Afficher des messages dans le système de validation HTML5¶

Si l’option autoSetCustomValidity du FormHelper est définie à true, les messages du navigateur HTML5 pour signifier qu’un champ est obligatoire seront remplacés par les messages d’erreur des règles de validation required et notBlank . L’activation de cette option ajoutera les attributs onvalid et oninvalid à vos champs, par exemple:

<input type="text" name="field" required onvalid="this.setCustomValidity('')"
 oninvalid="this.setCustomValidity('Message personnalisé pour la règle notBlank')" />

Si vous voulez définir manuellement ces events avec votre propre JavaScript, vous pouvez définir l’option autoSetCustomValidity à false et utiliser à la place la variable de template spéciale customValidityMessage. Cette variable de template est ajoutée quand un champ est obligatoire:

// template exemple
[
    'input' => '<input type="{{type}}" name="{{name}}" data-error-message="{{customValidityMessage}}" {{attrs}}/>',
]

// créerait un input ressemblant à cela
<input type="text" name="field" required
 data-error-message="Message personnalisé pour la règle notBlank" />

Vous pourriez alors utiliser le JavaScript pour définir les events onvalid et oninvalid de la façon dont vous le souhaitez.

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. Tableau qui peut contenir n’importe quelles des options générales, ou des options spécifiques aux boutons submit (cf. ci-dessous), ainsi que n’importe quels attributs HTML valides.

Crée un input submit avec la valeur $caption. Si la $caption fournie est l’URL d’une image (c’est-à-dire si la valeur fournie contient “://” ou une des extensions “.jpg, .jpe, .jpeg, .gif”), une image cliquable sera générée comme bouton sibmit (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 du formulaire). Défaut à 'submit'.

• 'templateVars' - Utilisez ce tableau pour fournir des variables de template supplémentaires pour l’élément et ses conteneurs.

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

Le code suivant:

echo $this->Form->submit('Cliquez ici');

Affichera:

<div class="submit"><input value="Cliquez ici" type="submit"></div>

Vous pouvez aussi passer une URL relative ou absolue vers une image au paramètre caption au lieu d’un texte:

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 Éléments Button¶

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

• $title - Chaîne obligatoire qui correspond au texte du bouton.

• $options - Optionel. Tableau qui peut contenir n’importe quelles des options générales, ou des options spécifiques aux boutons (cf. ci-dessous), ainsi que n’importe quels attributs HTML valides.

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

Options pour les Button

• 'type' - Vous pouvez définir 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 cela 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 formulaire.

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

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

• 'escape' - Booléen. S’il est défini à true, tous les attributs HTML générés pour le bouton seront échappés. Défaut à true.

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

Par exemple:

echo $this->Form->button('Un bouton');
echo $this->Form->button('Un autre bouton', ['type' => 'button']);
echo $this->Form->button('Réinitialiser le formulaire', ['type' => 'reset']);
echo $this->Form->button('Valider', ['type' => 'submit']);

Affichera:

<button type="submit">Un bouton</button>
<button type="button">Un autre bouton</button>
<button type="reset">Réinitialiser le formulaire</button>
<button type="submit">Valider</button>

Exemple en utilisant l’option escapeTitle:

// Rendra le code HTML sans échappement.
echo $this->Form->button('<em>Valider</em>', [
    'type' => 'submit',
    'escapeTitle' => false,
]);

Créer des Boutons POST¶

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

• $title - Chaîne obligatoire qui sera utilisée 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. Tableau qui peut contenir n’importe quelles des options générales, ou des options spécifiques (cf. ci-dessous), ainsi que n’importe quels attributs HTML valides.

Crée une balise <button> avec un <form> l’entourant qui soumet par défaut 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 requête à utiliser. Par exemple si vous voulez émettre 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.php
<?= $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>

Dans la mesure où cette méthode crée un élément <form>, ne l’utilisez pas à l’intérieur d’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ée comme texte du lien.

• $url - URL cible du formulaire, sous forme de chaîne ou de tableau. L’URL est soit relative à CakePHP, soit externe si elle commence par http://.

• $options - Optionel. Tableau qui peut contenir n’importe quelles des options générales, ou des options spécifiques (cf. ci-dessous), ainsi que n’importe quels attributs HTML valides.

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

// Dans votre template, à l'emplacement pour supprimer un article
<?= $this->Form->postLink(
   'Supprimer',
   ['action' => 'delete', $article->id],
   ['confirm' => 'Êtes-vous sûr ?'])
?>

Options pour les liens POST

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

• 'method' - La méthode de requête à utiliser. Par exemple si vous voulez émettre 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 dans un bloc de vue qui peut être affiché en dehors du formulaire principal.

Si vous souhaitez seulement 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('email_notifications', [
    'options' => ['y', 'n'],
    'type' => 'radio'
]);

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

Ajouter des Variables de Template Supplémentaires aux Templates¶

Vous pouvez aussi ajouter des espaces réservés supplémentaires dans des templates personnalisés et les remplir lors de la génération des inputs.

Par exemple:

// Ajoute un template avec un espace réservé pour un message d'aide
$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 frameworks 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(array $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ée pour personnaliser 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 la 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 supplémentaires 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é']
    ],
    ['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ée pour personnaliser 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 certains champs de la liste d’inputs générée, définissez-les à false dans le paramètre $fields:

echo $this->Form->allControls(['password' => false]);

Construire une Classe Widget¶

L’interface que les classes Widget doivent respecter est vraiment simple. Il s’agit de Cake\View\Widget\WidgetInterface. Cette interface nécessite d’implémenter les méthodes render(array $data) et secureFields(array $data). La méthode render() attend un tableau de données pour construire le widget et doit renvoyer une chaine HTML pour le widget. La méthode secureFields() attend également un tableau de données et doit retourner un tableau contenant la liste des champs à sécuriser pour ce widget. Si CakePHP construit votre widget, vous pouvez vous attendre à recevoir une instance de Cake\View\StringTemplate en premier argument, suivi de toutes les dépendances que vous aurez définies. Si vous vouliez construire un widget Autocomplete, vous pourriez le faire comme ceci:

namespace App\View\Widget;

use Cake\View\Form\ContextInterface;
use Cake\View\StringTemplate;
use Cake\View\Widget\WidgetInterface;

class AutocompleteWidget implements WidgetInterface
{

    /**
     * StringTemplate instance.
     *
     * @var \Cake\View\StringTemplate
     */
    protected $_templates;

    /**
     * Constructor.
     *
     * @param \Cake\View\StringTemplate $templates Liste des templates.
     */
    public function __construct(StringTemplate $templates)
    {
        $this->_templates = $templates;
    }

    /**
     * Méthode qui fait le rendu du widget.
     *
     * @param array $data Les données à utiliser pour construire l'input.
     * @param \Cake\View\Form\ContextInterface $context Le contexte courant du formulaire.
     *
     * @return string
     */
    public function render(array $data, ContextInterface $context): string
    {
        $data += [
            'name' => '',
        ];
        return $this->_templates->format('autocomplete', [
            'name' => $data['name'],
            'attrs' => $this->_templates->formatAttributes($data, ['name'])
        ]);
    }

    public function secureFields(array $data): array
    {
        return [$data['name']];
    }
}

Évidemment, c’est un exemple très simple, mais il montre comment développer un widget personnalisé. Ce widget ferait un rendu de la chaîne de template « autocomplete », si définie comme ceci par exemple:

$this->Form->setTemplates([
    'autocomplete' => '<input type="autocomplete" name="{{name}}" {{attrs}} />'
]);

Pour plus d’informations sur les templates, référez-vous à la section Personnaliser les Templates Utilisés par FormHelper.

Utiliser les Widgets¶

Vous pouvez charger des widgets personnalisés lors du chargement du FormHelper ou en utilisant la méthode addWidget(). Lors du chargement du FormHelper, les widgets sont définis comme des paramètres:

// Dans une classe de View
$this->loadHelper('Form', [
    'widgets' => [
        'autocomplete' => ['Autocomplete']
    ]
]);

Si votre widget nécessite d’autres widgets, le FormHelper peut remplir ces dépendances lorsqu’elles sont déclarées:

$this->loadHelper('Form', [
    'widgets' => [
        'autocomplete' => [
            'App\View\Widget\AutocompleteWidget',
            'text',
            'label'
        ]
    ]
]);

Dans l’exemple ci-dessus, le widget autocomplete dépendrait des widgets text et label. Si votre widget doit accéder à la View, vous devrez utiliser le “widget” _view. Lorsque le widget autocomplete est créé, les objets widget liés aux noms text et label lui sont passés. Ajouter des widgets en utilisant la méthode addWidget ressemblerait à ceci:

// En utilisant un nom de classe.
$this->Form->addWidget(
    'autocomplete',
    ['Autocomplete', 'text', 'label']
);

// En utilisant une instance - vous oblige à résoudre les dépendances.
$autocomplete = new AutocompleteWidget(
    $this->Form->getTemplater(),
    $this->Form->widgetRegistry()->get('text'),
    $this->Form->widgetRegistry()->get('label'),
);
$this->Form->addWidget('autocomplete', $autocomplete);

Une fois ajoutés/remplacés, les widgets peuvent être utilisés en tant que “type” de l’input:

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

Cela créera un widget personnalisé avec un label et une div enveloppante tout comme le fait toujours control(). Sinon vous pouvez juste créer un widget en utilisant la méthode magique:

echo $this->Form->autocomplete('search', $options);