Zend Framework: Zend_Form generation from models Component Proposal

Proposed Component Name	Zend_Form generation from models
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Form generation from models
Proposers	Jani Hartikainen
Zend Liaison	TBD
Revision	1.0 - 19 October 2008: Initial Draft. (wiki revision: 10)

For example, if the user has a model for a table with the following columns: firstname, lastname, address, email, creating a form and code for saving it would usually involve creating some kind of a zend_form object with the fields for the columns and then some logic in a controller to parse the fields from the form into a record and store the record.

This class automates the whole process. You can simply pass the model's name to the generator, and it will create a form with fields for each of the columns. You can then simply display the form to the user. When the user posts the form back, you use isValid(), like with "normal" zend_forms, and then you can simply call save() to store the new record with the values from the fields.

You can also use the generated forms for editing existing records. Simply fetch the record, and pass it to the form. When saving a form with an existing record, it will update the existing record instead of saving a new one.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

This component will generate forms based on models
Generated forms will utilize Zend_Form and its other functionality, such as validators
This component will be able to create new, or update old, models
This component will allow users to add support to other model types with an adapter
This component will be able to support relations

4. Dependencies on Other Framework Components

Zend_Form

5. Theory of Operation

The main generator class (Zend_Form_Model) will use the adapter to gather information on the model. It will also look at the parameters passed by the user, and generate a form field for each of the columns on the model. The generator class will also be able to parse data posted by the user to create new or update exsting records.

The generator's behavior can be customized in two ways:
You instanciate it directly and pass arguments to the constructor, and it will work similarily to instancing a Zend_Form class, except with some additional parameters.

You inherit the generator in a custom form class. This way you can provide the parameters in the class properties, and you can also hook custom functionality by overriding _preGenerate, _postGenerate and _postSave.

If the adapter provides support for relations in the model, the generator can provide a select box for choosing a "has one" related record, or a subform for creating/editing/deleting "has many" records. Relations can also be ignored by passing in parameters ignoring the columns.

Many-support with subforms

The many-relation support using subforms currently works by adding buttons to the form, which the user can use to add new related objects.

This works by the means of hooking isValid, and parsing the button responses from the passed data. Based on these, the form class can insert a new sub form for adding completely new records, or if the user had modified the data shown in one of the subforms, it can update the records already stored in the database.

It can also delete records if the user chooses the delete button visible on each subform.

6. Milestones / Tasks

Milestone 1: [DONE] Initial prototype
Milestone 2: [DONE] Unit tests for the generator
Milestone 3: Adapter interface finalized
Milestone 4: Unit tests for the adapters

7. Class Index

The class names are tentative. If you have a better name, feel free to suggest.

Zend_Form_Model
Zend_Form_Model_Adapter_Interface
Zend_Form_Model_Adapter_DbTable
Zend_Form_Model_Adapter_Doctrine

8. Use Cases

UC-01: Fast creation

Zend_Form_Model::setDefaultAdapter(new Zend_Form_Model_Adapter_DbTable());

//Generates a form for FooModel
$form = new Zend_Form_Model(array(
	'model' => 'FooModel'
));

UC-02: Settings

$form = new Zend_Form_Model(array(
	'model' => 'FooModel',
	'ignoreColumns' => array('bar'),
	'action' => '/form' //standard Zend_Form parameter
));

UC-03: Inheritance based forms

This class is from the unit tests, and is used to confirm the pre/post methods are called.

class Zend_Form_ModelTest_Form extends Zend_Form_Model
{
	public $preGenerated = false;
	public $postGenerated = false;
	public $postSaved = false;


	protected function _preGenerate()
	{
		$this->preGenerated = true;
	}

	protected function _postGenerate()
	{
		$this->postGenerated = true;
	}

	protected function _postSave($persist)
	{
		$this->postSaved = true;
	}
}

UC-04: Full example in a controller

This shows an exampel how you might use the form inside a controller

class MyController extends Zend_Controller_Action
{
	/**
	 * This creates new records
	 */
	public function newAction()
	{
		$form = new Zend_Form_Model(array(
			'model' => 'FooModel'
		));

		if($this->getRequest()->isPost() && $form->isValid())
		{
			$record = $form->save();
			$this->_redirect('/show/' . $record->id);
			exit;
		}

		$this->view->form = $form;
	}

	/**
	 * This edits records
	 */
	public function editAction()
	{
		$form = new Zend_Form_Model(array(
			'model' => 'FooModel'
		));

		$id = $this->_getParam('id');

		//Imagine _getRecord gets us a usable record of the correct type
		$record = $this->_getRecord($id);
		$form->setRecord($record);

		if($this->getRequest()->isPost() && $form->isValid())
		{
			$record = $form->save();
			$this->_redirect('/show/' . $record->id);
			exit;
		}

		$this->view->form = $form;
	}
}

The view would simply output the form like normal. Note that when editing a record, the main difference is that you use setRecord to tell the form what record it's working with.

9. Class Skeletons

interface Zend_Form_Model_Adapter_Interface
{
	public function getColumns();
	public function getRelations();
	public function getRelationPkValue($name, $relation);
	public function getRecordPkValue($record);
	public function getManyRecords($name);
	public function getOneRecords($relation);
	public function addManyRecord($name, $record);
	public function deleteRecord($record);
	public function setTable($table);
	public function getTable();
	public function setRecord($instance);
	public function getRecord();
	public function getNewRecord();
	public function saveRecord();
	public function getRecordValue($column);
	public function setRecordValue($column, $value);
}

class Zend_Form_Model extends Zend_Form
{
	const RELATION_ONE = 'one';
	const RELATION_MANY = 'many';
	const FORM = 'form';
	public static function setDefaultAdapter(Zend_Form_Model_Adapter_Interface $adapter);
	public function setOptions(array $options);
	public function setAdapter(Zend_Form_Model_Adapter_Interface $adapter);
	public function getAdapter();
	public function setGenerateManyFields();
	public function getGenerateManyFields();
	public function setFieldLabels(array $labels);
	public function setColumnTypes(array $types);
	public function ignoreColumns(array $columns);
	public static function create(array $options = array());
	public function getPluginLoader($type = null);
	public function getTable();
	public function setRecord($instance);
	public function getRecord();
	public function isValid($data);
	public function getColumnElementName($name);
	public function getRelationElementName($name);
	public function getElementForColumn($name);
	public function getElementForRelation($relation);
	public function save($persist = true);
}

Page Operations

Browse Space

Zend_Form generation from models - Jani Hartikainen

Labels