表单¶

创建表单的选项¶

$options 数组是大多数表单配置发生的地方。这个特殊的数组可以包含许多不同的键值对，它们会影响表单标签的生成方式。有效值

• 'type' - 允许你选择要创建的表单类型。如果没有提供类型，它将根据表单上下文自动检测。有效值

  • 'get' - 将表单方法设置为 HTTP GET。

  • 'file' - 将表单方法设置为 POST，并将 'enctype' 设置为“multipart/form-data”。

  • 'post' - 将方法设置为 POST。

  • 'put', 'delete', 'patch' - 当提交表单时，将分别使用 PUT、DELETE 或 PATCH 覆盖 HTTP 方法。

• 'method' - 有效值与上述相同。允许你显式覆盖表单的方法。

• 'url' - 指定表单将提交到的 URL。可以是字符串或 URL 数组。

• 'encoding' - 设置表单的 accept-charset 编码。默认为 Configure::read('App.encoding')。

• 'enctype' - 允许你显式设置表单编码。

• 'templates' - 你想要为这个表单使用的模板。提供的任何模板都将合并到已加载的模板之上。可以是 /config 中的某个文件名（不含扩展名），也可以是 要使用的模板数组。

• 'context' - 表单上下文类的额外选项。（例如，EntityContext 接受一个 'table' 选项，它允许你设置表单应该基于的特定 Table 类。）

• 'idPrefix' - 为生成的 ID 属性添加的前缀。

• 'templateVars' - 允许您为 formStart 模板提供模板变量。

• autoSetCustomValidity - 设置为 true 以在控件的 HTML5 有效性消息中使用自定义的必需和非空验证消息。默认值为 true。

从其他值源获取表单值¶

FormHelper 的值源定义了其渲染的元素（例如输入标签）从何处获取其值。

支持的源是 context、data 和 query。您可以通过设置 valueSources 选项或使用 setValuesSource() 来使用一个或多个源。由 FormHelper 生成的任何小部件将从源中收集其值，按照您设置的顺序。

默认情况下，FormHelper 从 data 或 context 获取其值，即它将从 $request->getData() 中获取数据，或者如果不存在，则从活动上下文的 data 中获取数据，在 EntityContext 的情况下，这些数据是实体的数据。

但是，如果您正在构建一个需要从查询字符串中读取数据的表单，您可以更改 FormHelper 读取输入数据的位置

// Use query string instead of request data:
echo $this->Form->create($article, [
    'type' => 'get',
    'valueSources' => ['query', 'context'],
]);

// Same effect:
echo $this->Form
    ->setValueSources(['query', 'context'])
    ->create($articles, ['type' => 'get']);

当输入数据需要由实体处理，即编组转换、表查询结果或实体计算，并在一次或多次表单提交后（其中保留请求数据）显示时，您需要将 context 放在首位

// Prioritize context over request data:
echo $this->Form->create($article,
    'valueSources' => ['context', 'data'],
]);

当调用 end() 时，值源将重置为默认值 ['data', 'context']。

更改表单的 HTTP 方法¶

使用 type 选项，您可以更改表单将使用的 HTTP 方法

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

输出

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

为 type 指定一个 'file' 值，将表单提交方法更改为 'post'，并在表单标签中包含一个 enctype 为 “multipart/form-data”。如果表单中有任何文件元素，则应使用此方法。缺少正确的 enctype 属性会导致文件上传无法正常工作。

例如

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

输出

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

当使用 'put'、'patch' 或 'delete' 作为 'type' 值时，您的表单在功能上将等效于 'post' 表单，但在提交时，HTTP 请求方法将被覆盖为 'PUT'、'PATCH' 或 'DELETE'。这允许 CakePHP 在 Web 浏览器中模拟正确的 REST 支持。

为表单设置 URL¶

使用 'url' 选项，您可以将表单指向当前控制器中的特定操作或应用程序中的另一个控制器。

例如，如果您想将表单指向当前控制器的 publish() 操作，您需要提供一个 $options 数组，如下所示

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

输出

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

如果所需的表单操作不在当前控制器中，您可以为表单操作指定一个完整的 URL。提供的 URL 可以是相对于您的 CakePHP 应用程序的

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

输出

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

或者，您可以指向一个外部域

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

输出

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

如果您不想将 URL 作为表单操作输出，请使用 'url' => false。

使用自定义验证器¶

模型通常会包含多个验证器集合，您可以让 FormHelper 根据控制器操作将要应用的特定验证器来标记字段是否必需。例如，您的 Users 表包含仅在注册帐户时才适用的特定验证规则

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

上面的代码将使用在 register 验证器中定义的验证规则，这些规则由 UsersTable::validationRegister() 为 $user 和所有相关关联定义，来对 $user 进行验证。如果您正在为关联实体创建表单，您可以使用数组为每个关联定义验证规则

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

上面的代码将对用户使用 register，对用户的评论使用 default。FormHelper 使用验证器来生成 HTML5 必需属性、相关的 ARIA 属性，并使用 浏览器验证器 API 设置错误消息。如果您想禁用 HTML5 验证消息，请使用

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

这不会禁用 required/aria-required 属性。

创建上下文类¶

虽然内置的上下文类旨在涵盖您会遇到的基本情况，但如果您使用的是其他 ORM，您可能需要构建一个新的上下文类。在这种情况下，您需要实现 Cake\View\Form\ContextInterface。实现此接口后，您可以将新的上下文连接到 FormHelper。通常最好在 View.beforeRender 事件侦听器或应用程序视图类中执行此操作

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

上下文工厂函数是您可以添加逻辑的地方，用于检查表单选项以确定正确的实体类型。如果找到匹配的输入数据，您可以返回一个对象。如果没有匹配项，则返回 null。

字段命名约定¶

创建控件小部件时，您应该根据表单实体中匹配的属性来命名您的字段。例如，如果您为一个 $article 实体创建了一个表单，您将创建以属性命名的字段。例如 title、body 和 published。

您可以通过将 association.fieldname 作为第一个参数传递来创建关联模型或任意模型的控件。

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

您的字段名称中的任何点都会转换为嵌套的请求数据。例如，如果您创建了一个名为 0.comments.body 的字段，您将获得一个看起来像 0[comments][body] 的名称属性。此约定与您在 ORM 中使用的约定相匹配。各种关联类型的详细信息可以在创建关联数据的输入部分找到。

创建与日期时间相关的控件时，FormHelper 将追加一个字段后缀。您可能会注意到名为 year、month、day、hour、minute 或 meridian 的其他字段被添加。当实体被封送时，这些字段将被自动转换为 DateTime 对象。

控件选项¶

FormHelper::control() 通过其 $options 参数支持大量选项。除了它自己的选项之外，control() 接受为推断/选择的生成控件类型（例如，对于 checkbox 或 textarea）的选项，以及 HTML 属性。本小节将介绍特定于 FormHelper::control() 的选项。

• $options['type'] - 指定要生成的控件类型的字符串。除了在创建表单控件中找到的字段类型之外，您还可以创建 'file'、'password' 和 HTML5 支持的任何其他类型。通过指定 'type'，您将强制生成控件的类型，从而覆盖模型自省。默认为 null。

  例如

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

  输出

  <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'] - 可以是字符串标题或标签选项的数组。您可以将此键设置为要在通常伴随着 input HTML 元素的标签中显示的字符串。默认为 null。

  例如

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

  输出

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

  或者，将此键设置为 false 以禁用 label 元素的生成。

  例如

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

  输出

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

  如果标签被禁用，并且提供了 placeholder 属性，生成的输入将设置 aria-label。

  将 label 选项设置为数组以提供 label 元素的额外选项。如果您这样做，您可以使用数组中的 'text' 键来自定义标签文本。

  例如

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

  输出

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

• $options['options'] - 您可以在此处提供一个数组，其中包含要为诸如 radio 或 select 之类的控件生成的元素，这些控件需要一个包含项目数组的参数（有关更多详细信息，请参见创建单选按钮和创建选择器）。默认为 null。

• $options['error'] - 使用此键可以覆盖默认的模型错误消息，并且可以使用它来设置 i18n 消息，例如。要禁用错误消息输出和字段类，请将 'error' 键设置为 false。默认为 null。

  例如

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

  要覆盖模型错误消息，请使用一个数组，其键与原始验证错误消息匹配。

  例如

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

  如上所示，您可以为模型中的每个验证规则设置错误消息。此外，您可以为表单提供 i18n 消息。

  要仅对错误消息禁用 HTML 实体编码，可以使用 'escape' 子键。

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

• $options['nestedInput'] - 与复选框和单选按钮一起使用。控制输入元素是在 label 元素内部还是外部生成。当 control() 生成复选框或单选按钮时，您可以将其设置为 false 以强制在 label 元素之外生成 HTML input 元素。

  另一方面，您可以将其设置为 true 以强制在标签内生成任何控件类型的输入元素。如果您更改了单选按钮的设置，那么您还需要修改默认的radioWrapper 模板。根据生成的控件类型，它默认为 true 或 false。

• $options['templates'] - 您想要为此输入使用的模板。任何指定的模板都将在已加载的模板之上进行合并。此选项可以是 /config 中包含您想要加载的模板的文件名（不含扩展名），也可以是模板数组。

• $options['labelOptions'] - 将其设置为 false 以禁用嵌套小部件周围的标签，或将其设置为要提供给 label 标签的属性数组。

• $options['readonly'] - 将字段设置为表单中的 readonly。

  例如

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

特定控件的通用选项¶

许多不同的控件元素方法支持一组通用的选项，这些选项根据使用的方法，必须在 $options 还是在 $attributes 数组参数中提供。所有这些选项也受 control() 方法支持。为了减少重复，所有控件方法共享的通用选项如下所示。

• 'id' - 将此键设置为强制控件的 DOM id 的值。这将覆盖可能设置的 'idPrefix'。

• 'default' - 用于为控件字段设置默认值。如果传递给表单的数据不包含该字段的值（或根本没有传递数据），则使用该值。如果没有提供默认值，将使用该列的默认值。

  使用示例。

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

  使用 select 字段的示例（“Medium”尺寸将被选中为默认值）。

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

  注意

  您不能使用 default 来选中复选框 - 相反，您可以在控制器中的 $this->request->getData() 中设置值，或者将控制选项 'checked' 设置为 true。

  注意使用 false 来分配默认值。一个 false 值用于禁用/排除控制字段的选项，因此 'default' => false 不会设置任何值。 相反，使用 'default' => 0。

• 'value' - 用于为控制字段设置特定值。这将覆盖从上下文注入的任何值，例如 Form、Entity 或 request->getData() 等。

  注意

  如果您想将字段设置为不渲染从上下文或 valuesSource 获取的值，您需要将 'value' 设置为 ''（而不是将其设置为 null）。

除了以上选项之外，您可以混合任何您希望使用的 HTML 属性。任何非特殊选项名称将被视为 HTML 属性，并应用于生成的 HTML 控制元素。

创建文本输入¶

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

• $name - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $options - 一个可选数组，包括任何 特定控制的通用选项 以及任何有效的 HTML 属性。

创建一个简单的 input HTML 元素，类型为 text。

例如

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

将输出

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

创建密码输入¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $options - 一个可选数组，包括任何 特定控制的通用选项 以及任何有效的 HTML 属性。

创建一个简单的 input 元素，类型为 password。

例如

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

将输出

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

创建隐藏输入¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $options - 一个可选数组，包括任何 特定控制的通用选项 以及任何有效的 HTML 属性。

创建一个隐藏表单输入。

例如

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

将输出

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

创建文本区域¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $options - 一个可选数组，包括任何 特定控制的通用选项、特定文本区域选项（见下文）以及任何有效的 HTML 属性。

创建一个文本区域控制字段。使用的默认小部件模板是

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

例如

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

将输出

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

如果表单正在被编辑（即数组 $this->request->getData() 包含之前为 User 实体保存的信息），则与 notes 字段对应的值将自动添加到生成的 HTML 中。

示例

<textarea name="notes" id="notes">
    This text is to be edited.
</textarea>

文本区域选项

除了 特定控制的通用选项 之外，textarea() 还支持一些特定的选项

• 'escape' - 确定是否应该转义文本区域的内容。默认值为 true。

  例如

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

• 'rows', 'cols' - 您可以使用这两个键来设置指定 textarea 字段的行数和列数的 HTML 属性。

  例如

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

  输出

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

创建选择、复选框和单选按钮控件¶

这些控件有一些共性，以及一些选项，因此，为了便于参考，它们都在本小节中进行了分组。

$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('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>

echo $this->Form->radio(
    'favorite_color',
    [
        ['value' => 'r', 'text' => 'Red', 'label' => ['class' => 'red']],
        ['value' => 'u', 'text' => 'Blue', 'label' => ['class' => 'blue']],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="favorite-color-r" class="red">
    <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
    Red
</label>
<label for="favorite-color-u" class="blue">
    <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
    Blue
</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>

创建文件输入¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $options - 一个可选数组，包括任何 特定控制的通用选项 以及任何有效的 HTML 属性。

在表单中创建一个文件上传字段。默认使用的窗口模板是

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

要向表单添加文件上传字段，首先必须确保表单的 enctype 设置为 'multipart/form-data'。

因此，从以下 create() 方法开始

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

接下来，将类似于以下两行中的任何一行添加到表单的视图模板文件

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

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

为了防止 submittedfile 被覆盖为空白，请将其从 $_accessible 中删除。或者，您可以使用 beforeMarshal 取消设置索引。

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

提交后，可以通过请求上的 UploadedFileInterface 对象访问文件字段。要将上传的文件移动到永久位置，可以使用

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

// Existing files with the same name will be replaced.
$fileobject->moveTo($destination);

创建日期和时间相关控件¶

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

• $fieldName - 将用作 select 元素的 HTML name 属性前缀的字符串。

• $options - 一个可选数组，包括任何 特定控制的通用选项 以及任何有效的 HTML 属性。

此方法将生成一个类型为“datetime-local”的输入标记。

例如

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

输出

<input type="datetime-local" name="registered">

输入的值可以是任何有效的日期时间字符串或 DateTime 实例。

例如

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

输出

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

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

<input type="date" name="registered">

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

<input type="time" name="released">

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

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

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

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

显示错误¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

• $text - 可选。提供错误消息的字符串或数组。如果为数组，则它应该是键名称 => 消息的哈希。默认为 null。

• $options - 可选数组，只能包含一个布尔值，其键为 'escape'，它将定义是否对错误消息的内容进行 HTML 转义。默认为 true。

显示给定字段的验证错误消息（由 $text 指定），如果发生了验证错误。如果没有提供 $text，则将使用该字段的默认验证错误消息。

使用以下模板窗口

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

'errorList' 和 'errorItem' 模板用于格式化每个字段的多个错误消息。

示例

// If in TicketsTable you have a 'notEmpty' validation rule:
public function validationDefault(Validator $validator): Validator
{
    $validator
        ->requirePresence('ticket', 'create')
        ->notEmpty('ticket');
}

// And inside templates/Tickets/add.php you have:
echo $this->Form->text('ticket');

if ($this->Form->isFieldError('ticket')) {
    echo $this->Form->error('ticket', 'Completely custom error message!');
}

如果您在不为“Ticket”字段提供值的情况下单击表单的“Submit”按钮，则您的表单将输出

<input name="ticket" class="form-error" required="required" value="" type="text">
<div class="error-message">Completely custom error message!</div>

检查错误¶

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

• $fieldName - 表单中的字段名称，格式为 'Modelname.fieldname'。

如果提供的 $fieldName 具有活动验证错误，则返回 true，否则返回 false。

示例

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

在 HTML5 有效性消息中显示验证消息¶

如果 autoSetCustomValidity FormHelper 选项设置为 true，则该字段的 required 和 notBlank 验证规则的错误消息将用于替代默认的浏览器 HTML5 required 消息。启用该选项将向您的字段添加 onvalid 和 oninvalid 事件属性，例如

<input type="text" name="field" required onvalid="this.setCustomValidity('')" oninvalid="this.setCustomValidity('Custom notBlank message')">

如果您想使用自定义 JavaScript 手动设置这些事件，可以将 autoSetCustomValidity 选项设置为 false，并使用特殊的 customValidityMessage 模板变量。当字段是必填字段时，会添加此模板变量

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

// would create an input like this
<input type="text" name="field" required data-error-message="Custom notBlank message" />

然后，您可以使用 JavaScript 按照您的意愿设置 onvalid 和 oninvalid 事件。

创建提交元素¶

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

• $caption - 一个可选字符串，提供按钮的文本标题或图像路径。默认为 'Submit'。

• $options - 一个可选数组，包括任何 特定控件的通用选项，或特定提交选项（见下文）以及任何有效的 HTML 属性。

创建一个 input 元素，类型为 submit，值为 $caption。如果提供的 $caption 是指向图像的 URL（即，如果该字符串包含 '://' 或包含任何扩展名 'jpg, jpe, jpeg, gif'），则将生成一个图像提交按钮，使用指定的图像（如果存在）。如果第一个字符是 ' / '，则图像路径相对于 *webroot*，否则如果第一个字符不是 ' / '，则图像路径相对于 *webroot/img*。

默认情况下，它将使用以下小部件模板

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

提交选项

• 'type' - 将此选项设置为 'reset' 以生成重置按钮。默认为 'submit'。

• 'templateVars' - 将此数组设置为为输入元素及其容器提供额外的模板变量。

• 任何其他提供的属性都将分配给 input 元素。

以下

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

将输出

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

您可以将图像的相对或绝对 URL 传递给标题参数，而不是标题文本

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

将输出

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

提交输入在您只需要基本文本或图像时很有用。如果您需要更复杂的按钮内容，您应该使用 button()。

创建按钮元素¶

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

• $title - 提供按钮的文本标题的必填字符串。

• $options - 一个可选数组，包括任何 特定控件的通用选项，或特定按钮选项（见下文）以及任何有效的 HTML 属性。

创建一个具有指定标题和默认类型为 'button' 的 HTML 按钮。

按钮选项

• 'type' - 您可以将其设置为以下三种可能的值之一

  1. 'submit' - 与 $this->Form->submit() 方法类似，它将创建一个提交按钮。但是，这不会像 submit() 那样生成一个包装的 div。这是默认类型。

  2. 'reset' - 创建一个表单重置按钮。

  3. 'button' - 创建一个标准的推送按钮。

• 'escapeTitle' - 布尔值。如果设置为 true，它将对 $title 中提供的值进行 HTML 编码。默认为 true。

• 'escape' - 布尔值。如果设置为 true，它将对为按钮生成的 HTML 属性进行 HTML 编码。默认为 true。

• 'confirm' - 点击时显示的确认消息。默认为 null。

例如

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

将输出

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

'escapeTitle' 选项的使用示例

// Will render unescaped HTML.
echo $this->Form->button('<em>Submit Form</em>', [
    'type' => 'submit',
    'escapeTitle' => false,
]);

创建 POST 按钮¶

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

• $title - 提供按钮的文本标题的必填字符串。默认情况下不进行 HTML 编码。

• $url - 以字符串或数组形式提供的表单的 URL。

• $options - 一个可选数组，包括任何 特定控件的通用选项，或特定选项（见下文）以及任何有效的 HTML 属性。

创建一个带有周围 <form> 元素的 <button> 标签，默认情况下通过 POST 提交。此外，默认情况下，它为 SecurityComponent 生成隐藏的输入字段。

POST 按钮选项

• 'data' - 包含键值对的数组，用于传递到隐藏输入中。

• 'method' - 要使用的请求方法。例如，设置为 'delete' 来模拟 HTTP/1.1 DELETE 请求。默认值为 'post'。

• 'form' - 包含任何 FormHelper::create() 可以接受的选项的数组。

• 此外，postButton() 方法将接受对 button() 方法有效的选项。

例如

// In templates/Tickets/index.php
<?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

将输出类似于以下的 HTML

<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">Delete Record</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>

由于此方法生成一个 form 元素，因此不要在已打开的表单中使用此方法。而是使用 Cake\View\Helper\FormHelper::submit() 或 Cake\View\Helper\FormHelper::button() 在打开的表单内创建按钮。

创建 POST 链接¶

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

• $title - 必填字符串，提供要包装在 <a> 标签中的文本。

• $url - 可选。包含表单 URL 的字符串或数组（Cake 相对 URL 或以 http:// 开头的外部 URL）。

• $options - 一个可选数组，包括任何 特定控件的通用选项，或特定选项（见下文）以及任何有效的 HTML 属性。

创建 HTML 链接，但使用您指定的方法访问 URL（默认为 POST）。要求浏览器中启用 JavaScript

// In your template, to delete an article, for example
<?= $this->Form->postLink(
    'Delete',
    ['action' => 'delete', $article->id],
    ['confirm' => 'Are you sure?'])
?>

POST 链接选项

• 'data' - 包含键值对的数组，用于传递到隐藏输入中。

• 'method' - 要使用的请求方法。例如，将其设置为 'delete' 将模拟 HTTP/1.1 DELETE 请求。默认值为 'post'。

• 'confirm' - 点击时显示的确认消息。默认为 null。

• 'block' - 将此选项设置为 true 将表单追加到视图块 'postLink' 或提供自定义块名称。默认值为 null。

• 此外，postLink 方法将接受对 link() 方法有效的选项。

此方法创建一个 <form> 元素。如果您想在现有表单内使用此方法，则必须使用 block 选项，以便将新表单设置为 视图块，该块可以在主表单之外呈现。

如果您只想要一个按钮来提交表单，那么您应该使用 Cake\View\Helper\FormHelper::button() 或 Cake\View\Helper\FormHelper::submit() 代替。

模板列表¶

可以在 FormHelper API 文档 中找到默认模板列表、它们的默认格式以及它们期望的变量。

// Add custom radio wrapping HTML
$this->Form->setTemplates([
    'radioContainer' => '<div class="form-radio">{{content}}</div>'
]);

// Create a radio set with our custom wrapping div.
echo $this->Form->control('email_notifications', [
    'options' => ['y', 'n'],
    'type' => 'radio'
]);

// Add custom radio form group
$this->Form->setTemplates([
    'radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>'
]);

向模板添加其他模板变量¶

您可以在自定义模板中添加其他模板占位符，并在生成控件时填充这些占位符。

例如

// Add a template with the help placeholder.
$this->Form->setTemplates([
    'inputContainer' => '<div class="input {{type}}{{required}}">
        {{content}} <span class="help">{{help}}</span></div>'
]);

// Generate an input and populate the help variable
echo $this->Form->control('password', [
    'templateVars' => ['help' => 'At least 8 characters long.'],
]);

输出

<div class="input password">
    <label for="password">
        Password
    </label>
    <input name="password" id="password" type="password">
    <span class="help">At least 8 characters long.</span>
</div>

将复选框和单选按钮移出标签¶

默认情况下，CakePHP 将通过 control() 创建的复选框和通过 control() 和 radio() 创建的单选按钮嵌套在标签元素中。这有助于更轻松地集成流行的 CSS 框架。如果您需要将复选框/单选按钮输入放置在标签之外，您可以通过修改模板来实现

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

这将使单选按钮和复选框在它们的标签之外呈现。

创建多个控件¶

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

• $fields - 要生成的字段数组。允许为每个指定的字段设置自定义类型、标签和其他选项。

• $options - 可选。一个选项数组。有效的键是

  1. 'fieldset' - 将其设置为 false 以禁用字段集。如果为空，则字段集将被启用。也可以是将作为 HTML 属性应用于 fieldset 标签的参数数组。

  2. legend - 用于自定义 legend 文本的字符串。将其设置为 false 以禁用为生成的输入集生成的图例。

生成针对给定上下文的一组控件，并将其包装在 fieldset 中。您可以通过将它们包含在内来指定生成的字段

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

您可以使用一个选项来自定义图例文本

echo $this->Form->controls($fields, ['legend' => 'Update news post']);

您可以通过在 $fields 参数中定义其他选项来自定义生成的控件

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

在自定义 $fields 时，您可以使用 $options 参数来控制生成的图例/字段集。

例如

echo $this->Form->controls(
    [
        'name' => ['label' => 'custom label'],
    ],
    [
        'legend' => 'Update your post',
    ]
);

如果你禁用 fieldset，legend 不会被打印。

为整个实体创建控件¶

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

• $fields - 可选。要生成的字段的自定义数组。允许设置自定义类型、标签和其他选项。

• $options - 可选。一个选项数组。有效的键是

  1. 'fieldset' - 将其设置为 false 以禁用 fieldset。如果为空，则 fieldset 将被启用。也可以是应用为 fieldset 标签的 HTML 属性的数组参数。

  2. legend - 用于自定义 legend 文本的字符串。将其设置为 false 以禁用为生成的控件集创建的 legend。

此方法与 controls() 密切相关，但是 $fields 参数默认为当前顶级实体中的所有字段。要从生成的控件中排除特定字段，请在 $fields 参数中将其设置为 false

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

构建小部件类¶

小部件类有一个非常简单的必需接口。它们必须实现 Cake\View\Widget\WidgetInterface。此接口要求实现 render(array $data) 和 secureFields(array $data) 方法。 render() 方法期望一个用于构建小部件的数据数组，并期望返回小部件的 HTML 字符串。 secureFields() 方法也期望一个数据数组，并期望返回包含此小部件要保护的字段列表的数组。如果 CakePHP 正在构建您的小部件，您可以期望获取一个 Cake\View\StringTemplate 实例作为第一个参数，然后是您定义的任何依赖项。如果我们想构建一个自动完成小部件，我们可以执行以下操作

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 Templates list.
     */
    public function __construct(StringTemplate $templates)
    {
        $this->_templates = $templates;
    }

    /**
     * Methods that render the widget.
     *
     * @param array $data The data to build an input with.
     * @param \Cake\View\Form\ContextInterface $context The current form context.
     *
     * @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']];
    }
}

显然，这是一个非常简单的示例，但它演示了如何构建自定义小部件。此小部件将呈现“自动完成”字符串模板，例如

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

有关字符串模板的更多信息，请参阅 自定义 FormHelper 使用的模板。

使用小部件¶

您可以在加载 FormHelper 时或使用 addWidget() 方法加载自定义小部件。加载 FormHelper 时，小部件被定义为设置

// In View class
$this->loadHelper('Form', [
    'widgets' => [
        'autocomplete' => ['Autocomplete'],
    ],
]);

如果您的窗口小部件需要其他窗口小部件，您可以通过声明它们让 FormHelper 填充这些依赖项

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

在上面的示例中，autocomplete 小部件将依赖于 text 和 label 小部件。如果您的窗口小部件需要访问视图，您应该使用 _view “窗口小部件”。创建 autocomplete 小部件时，将传递与 text 和 label 名称相关的窗口小部件对象。要使用 addWidget() 方法添加窗口小部件，操作如下

// Using a classname.
$this->Form->addWidget(
    'autocomplete',
    ['Autocomplete', 'text', 'label']
);

// Using an instance - requires you to resolve dependencies.
$autocomplete = new AutocompleteWidget(
    $this->Form->getTemplater(),
    $this->Form->getWidgetLocator()->get('text'),
    $this->Form->getWidgetLocator()->get('label'),
);
$this->Form->addWidget('autocomplete', $autocomplete);

添加/替换后，可以使用控件“类型”使用窗口小部件

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

这将创建具有 label 和包装 div 的自定义窗口小部件，就像 controls() 一样。或者，您可以使用魔术方法仅创建控件窗口小部件

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