README

创建和配置表单

通过示例更简单地展示典型表单创建

$f = new \CMSx\Form('myform');
$f->addInput('name', 'Имя')
  ->setIsRequired(true);
$f->addSelect('city')
  ->setOptions('Москва', 'Киев', 'Минск')
$f->addInput('email', 'E-mail')
  ->setRegexp('/[some_regexp]/uis');

目前存在以下类型的元素

• Input - 文本字段
• Password - 密码字段
• Hidden - 隐藏字段
• Select - 从列表中选择 <select>
• Radio - 从列表中选择 input[type=radio]
• Checkbox - 一个复选框
• CheckboxListing - 从多个选项中选择 input[type=checkbox]
• Textarea - 文本字段
• Caption - 标题和文本（无 input）

即：创建表单对象后，我们可以单独添加字段。每个 add* 方法都会在表单中创建并返回相应元素的对象，具有自己的配置集合。所有元素都继承自 CMSx\Form\Element 类，因此可以轻松扩展此集合。

同时，也提供了对整个表单的配置

• setAction() - 设置 action；
• setFormAttributes() - 表单标签的属性；
• setSubmitButton($text, $attr = null) - 提交按钮的文本和属性；
• setTmpl*() - sprintf() 用于形成表单标记的模板。

绘制表单

配置表单后，可以使用 $f->render() 完整地绘制表单。将生成一个包含所有已配置字段以及“发送”按钮的 <form> 标签。

可以使用 render* 方法单独生成表单的部分。如果需要非标准布局，可以单独访问表单中的每个元素：$f->field('email')。对于它们，可以调用 render() 方法，从而绘制相应的输入元素，或获取其他属性，例如 getLabel()、getIsRequired() 等。

表单验证

在配置表单时，可以为每个字段指定验证参数

• 必填：setIsRequired()
• 正则表达式检查：setRegexp()
• 过滤器（回调）检查：setFilter()
• 选项列表检查：setOptions()。所有选择列表（select、radiobutton、checkbox listing）都会自动检查其值是否与给定选项匹配。

通过调用 validate() 方法将数据传递给表单。每个字段都按其验证器进行检查，并保存检查结果。检查表单状态

• isSent() - 是否已发送表单；
• isValidated() - 是否已启动验证；
• hasErrors() - 是否存在错误；
• isValid() - 表单是否有效，即已启动验证且没有错误。

如果表单有效，可以通过调用 getValues() 或 getValue($field) 方法从其中获取数据。即使用户发送了额外的字段，它们也不会进入“纯净数据”。在表单验证之前，表单中的数据不可用。可以通过将每个元素传递给 getTaintedValues() 方法来获取“原始”值。

扩展

表单的基本类设计得尽可能简单，以简化继承和配置以满足特定需求。因此，在表单和每个元素中都有一个 init() 方法，它在构造函数之后被调用，允许继承和进一步配置元素。

为了保持一致性，表单中有一个 process() 方法，其中应该包含处理表单的逻辑：发送电子邮件、保存到数据库等。由于验证和执行逻辑经常相关联，还提供了一个组合方法 validateAndProcess()。

为了创建额外的表单处理器，可以重写 beforeValidation() 和 afterValidation() 方法，这些方法允许在主要字段验证之前和之后添加任何逻辑和复杂规则。方法 beforeValidation() 还允许更改要验证的数据。

整个表单的HTML代码的生成是通过使用sprintf()函数模板以及与部分元素绘制方法 render* 的结合来完成的，这为精细调整提供了无限可能。