README

Developed and Maintained by Ibrahim Azhar Armar

Introduction

Zf2LazyForm module is developed to eliminate duplication and enforce reuse for elements, validators, filters, attributes, options etc. We enhanced the module to support numerous features on top of existing features of zend-form

Installation

Install using composer

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

Install using GIT clone

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

Enable Zf2 Module

Enable the module by adding Oml\Zf2LazyForm in your config/application.config.php file.

Important Instruction

Form must be initialized using FormElementManager, lets see an example

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

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

Example

Short Syntax

Let's consider the below example to define form element using short syntax

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();
	}
}

When an element is defined using addFormElement() by default empty input filters are injected, you don't have to worry about defining input filters separately. To be precise you never define input filters in form again, instead you define it in the config file and reuse it across forms and elements, we'll see an example of this below

You can also use short names offered by ZF2, instead of writing Zend\Form\Element\Text for defining form elements, you can just type text, same goes for rest of elements

Configurable Validators, Filters, Attrbutes & Options

Define validators, filters, attributes and options in config file to reuse it across forms and elements. the syntax is same as what you use in 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'
		            ]
				]
			]
		]
	]
];

Lazy Set

Once configuration is defined, it can be reused using lazy-set

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

To use lazy-set(s) in your form element, you need to define it in each element using an array, refer the example below where we apply lazy-set = [1] to an element

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

In some cases you may want to disable filters, you can do it by using filters => false, refer the below example where we apply lazy-set = 2 which has an element with filters => false

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

Placeholders

In many instances you may want to define different validation values for a given validator. Lets consider StringLength where it makes sense to have a default minimum and maximum length for all form elements, however for specific element we may want to overwrite it with specific values, this is where Placeholders comes to our rescue, lets see some example

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

The defined placeholder :min and :max in above configuration can be replaced on 3 level

Global
Form
Element

Replace placeholder value on a global level

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

Replace placeholder value on a form level

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();
	}
}

Replace placeholder value per element

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

You can access ServiceManager object in your Form::init() by using $this->getServiceLocator(). Because form is intiailized using FormElementManager, by default an instance of ServiceManager is injected in the form

Global Form Elements and Attributes

Most often we use common elements in forms such as, all forms must have a submit button, a csrf token must be included, it must contain specific class names, or bind hydator etc. this can be done easily using closure in your config file

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));
			},
		]
	]
];

An instance of Zend\Form is injected by default when you define $config['oml']['zf2-lazy-form'][*] with closure, this allows you to modify or add elements to the form on a global level, you can also use addFormElement() or other available module functions here

Options

Available Options in Config File :

$config['oml']['zf2-lazy-form']['*'] = function(\Zend\Form\Form $form){} : Global elements and attributes
$config['oml']['zf2-lazy-form']['default']['placeholder'] : Default values for placeholder
$config['oml']['zf2-lazy-form']['attributes'] : Form element attributes
$config['oml']['zf2-lazy-form']['options'] : Form element options
$config['oml']['zf2-lazy-form']['validators'] : Form element validators
$config['oml']['zf2-lazy-form']['filters'] : Form element filters
$config['oml']['zf2-lazy-form']['lazy-set'] : Lazy set for reusable elements

Available Options in Form Class Extending Oml\Zf2LazyForm\Form\Base :

addFormElement(array $params) : Accepts name, type, label and lazy-set
removeFormElement($name) : Remove form element
setPlaceholderParameter($name, $value, $elementName = null) : Replace placeholder value for form or element

Feel free to use native zend-form functions parallelly with this module if the function offered by this module does not suffice your need. it is designed to avoid conflict with existing Zend\Form functionality, hence allowing you to use add() or addFormElement() together in your form

oromedialab / zf2-lazy-form

Maintainers

Details