README

由 Ibrahim Azhar Armar 开发和维护

简介

Zf2LazyForm 模块是为了消除元素、验证器、过滤器、属性、选项等的重复，并强制重用而开发的。我们增强了该模块，使其在zend-form的现有功能基础上支持更多特性。

• 简短语法
• 可配置验证器、过滤器、属性与选项
• 懒加载集合
• 占位符
• 全局表单元素和属性
• 可配置错误消息 - @TODO

安装

使用 composer 安装

composer require oromedialab/zf2-lazy-form dev-master

使用 GIT 克隆安装

git clone https://github.com/oromedialab/zf2-lazy-form.git

启用 Zf2 模块

通过在您的 config/application.config.php 文件中添加 Oml\Zf2LazyForm 来启用该模块。

重要说明

表单必须使用 FormElementManager 进行初始化，让我们看看一个例子

// Correct approach
$sm = $this->getServiceLocator();
$form = $sm->get('FormElementManager')->get('User\Form\Create');

// Incorrect approach
$sm = $this->getServiceLocator();
$form = new User\Form\Create();

例子

简短语法

让我们考虑以下例子，以定义使用简短语法的表单元素

use Oml\Zf2LazyForm\Form\Base;

class MyForm extends Base
{
	public function init
	{
		// First Name
		$this->addFormElement(['name' => 'first_name', 'label' => 'First name', 'type' => 'text']);
		// Last Name
		$this->addFormElement(['name' => 'last_name', 'label' => 'Last name', 'type' => 'text']);
		// Remove form element
		$this->removeFormElement('last_name');
		// It is IMPORTANT to call parent::init() in the bottom, failing to add this will end-up in form not being displayed
		parent::init();
	}
}

当使用 addFormElement() 定义元素时，默认会注入空输入过滤器，您不需要单独定义输入过滤器。更准确地说，您不再在表单中定义输入过滤器，而是在配置文件中定义并跨表单和元素重用它，我们将在下面看到一个例子。

您也可以使用 ZF2 提供的 简短名称，而不是为定义表单元素而编写 Zend\Form\Element\Text，您只需键入 text，其他元素也是如此。

可配置验证器、过滤器、属性与选项

在配置文件中定义验证器、过滤器、属性和选项以跨表单和元素重用。语法与您在 zend-form 中使用的语法相同。

return [
	'oml' => [
		'zf2-lazy-form' => [
			'validators' => [
				'not-empty' => ['name' => 'NotEmpty'],
				'string-length' => [
	                'name'    => 'StringLength',
	                'options' => array(
	                    'encoding' => 'UTF-8',
	                    'min' => 2,
	                    'max' => 255
	                )
				]
			],
			'filters' => [
				'strip-tags' => ['name' => 'StripTags'],
	            'string-trim' => ['name' => 'StringTrim']
			]
			'attributes' => [
				'submit-btn' => [
					'type' => 'submit',
					'class' => 'submit-btn'
				]
			],
			'options' => [
				'label-option' => [
					'label_attributes' => [
		                'class' => 'col-sm-2 font_16'
		            ]
				]
			]
		]
	]
];

懒加载集合

一旦定义了配置，就可以使用懒加载集合重用它。

return [
	'oml' => [
		'zf2-lazy-form' => [
			'lazy-set' => [
				1 => [
					'validators' => ['not-empty', 'string-length'],
					'filters' => ['strip-tags', 'string-trim'],
					'attributes' => ['submit-btn'],
					'options' => ['label-option']
				],
				2 => [
					'attributes' => ['submit-btn'],
					'filters' => false
				]
			]
		]
	]
];

要在表单元素中使用懒加载集合，您需要在每个元素中使用数组定义它，以下是一个例子，其中我们将 lazy-set = [1] 应用到一个元素上。

$this->addFormElement(['name' => 'first_name', 'label' => 'First name', 'type' => 'text', 'lazy-set' => [1]]);

在某些情况下，您可能想要禁用过滤器，您可以通过使用 filters => false 来实现，以下是一个例子，其中我们应用了 lazy-set = 2，它有一个元素带有 filters => false。

$this->addFormElement(['name' => 'submit', 'label' => 'Submit', 'type' => 'button', 'lazy-set' => [2]]);

占位符

在许多情况下，您可能想要为给定的验证器定义不同的验证值。以 StringLength 为例，它对所有表单元素具有默认的最小和最大长度是有意义的，但对于特定元素，我们可能希望用特定值覆盖它，这就是占位符发挥作用的地方，让我们看一些例子。

return [
	'oml' => [
		'zf2-lazy-form' => [
			'validators' => [
				'not_empty' => ['name' => 'NotEmpty'],
				'string_length' => [
                    'name'    => 'StringLength',
                    'options' => array(
                        'encoding' => 'UTF-8',
                        'min' => ':min',
                        'max' => ':max',
                    )
				]
			]
		]
	]
];

上述配置中定义的占位符 :min 和 :max 可以在三个级别上替换：

• 全局
• 表单
• 元素

在全局级别替换占位符值

// Apply global placeholder
return [
	'oml' => [
		'zf2-lazy-form' => [
			'default' => [
				'placeholder' => [
					':min' => 2,
					':max' => 200
				]
			]
		]
	]
];

在表单级别替换占位符值

use Oml\Zf2LazyForm\Form\Base;

class MyForm extends Base
{
	public function init
	{
		// Overwrite :min and :max value for this form
		$this->setPlaceholderParameter(':min', 20);
		$this->setPlaceholderParameter(':max', 500);
		// Add form element
		$this->addFormElement(['name' => 'first_name', 'label' => 'First name', 'type' => 'text', 'lazy-set' => [1]]);
		// It is IMPORTANT to call parent::init() in the bottom, failing to add this will end-up in form not being displayed
		parent::init();
	}
}

按元素替换占位符值

use Oml\Zf2LazyForm\Form\Base;

class MyForm extends Base
{
	public function init
	{
		// Overwrite :min and :max value for first name
		$this->setPlaceholderParameter(':min', 20, 'first_name');
		$this->setPlaceholderParameter(':max', 500, 'first_name');
		// Add form element
		$this->addFormElement(['name' => 'first_name', 'label' => 'First name', 'type' => 'text', 'lazy-set' => [1]]);
		// It is IMPORTANT to call parent::init() in the bottom, failing to add this will end-up in form not being displayed
		parent::init();
	}
}

Zend\ServiceManager\ServiceManager

您可以通过使用 $this->getServiceLocator() 在您的 Form::init() 中访问 ServiceManager 对象。因为表单是通过 FormElementManager 初始化的，所以默认情况下，一个 ServiceManager 的实例被注入到表单中。

全局表单元素和属性

我们经常在表单中使用通用元素，例如，所有表单都必须有一个提交按钮，必须包含 CSRF 令牌，必须包含特定的类名，或者绑定 hydrator 等。这可以通过您的配置文件中的闭包轻松实现。

return [
	'oml' => [
		'zf2-lazy-form' => [
			'*' => function(\Zend\Form\Form $form) {
				// Apply form attribute
				$form->setAttribute('class', 'form-horizontal form');
				// Add an element in the form
				$form->addFormElement(['name' => 'submit', 'label' => 'Submit', 'type' => 'button', 'lazy-set' => [2]]);
				// Set hydrator
				$form->setHydrator(new \Zend\Stdlib\Hydrator\ClassMethods(true));
			},
		]
	]
];

当您使用闭包定义$config['oml']['zf2-lazy-form'][*]时，默认会注入一个Zend\Form实例，这允许您在全局范围内修改或添加表单元素，您还可以在这里使用addFormElement()或其他可用模块函数

选项

配置文件中的可用选项

• $config['oml']['zf2-lazy-form']['*'] = function(\Zend\Form\Form $form){} : 全局元素和属性
• $config['oml']['zf2-lazy-form']['default']['placeholder'] : 占位符的默认值
• $config['oml']['zf2-lazy-form']['attributes'] : 表单元素属性
• $config['oml']['zf2-lazy-form']['options'] : 表单元素选项
• $config['oml']['zf2-lazy-form']['validators'] : 表单元素验证器
• $config['oml']['zf2-lazy-form']['filters'] : 表单元素过滤器
• $config['oml']['zf2-lazy-form']['lazy-set'] : 可重用元素的延迟设置

在扩展Oml\Zf2LazyForm\Form\Base的表单类中的可用选项

• addFormElement(array $params) : 接受名称、类型、标签和延迟设置
• removeFormElement($name) : 删除表单元素
• setPlaceholderParameter($name, $value, $elementName = null) : 替换表单或元素的占位符值

如果本模块提供的功能无法满足您的需求，请随意使用原生zend-form函数与此模块并行使用。它旨在避免与现有的Zend\Form功能冲突，因此允许您在表单中使用add()或addFormElement()一起