Zend_Grid - Bento Vilas Boas

{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Grid
{zone-data}

{zone-data:proposer-list}
[Bento Vilas Boas|mailto:geral@petala-azul.com]
{zone-data}

{zone-data:revision}
1.0 - 26 June 2010: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Grid is a component for display/manage data with source abstraction. Although it can be used anywhere in your application, it has a comprehensive feature list that fits the needs for an administrative grid where we need to easily display and edit data, create reports and even create WebServices to access information.
{zone-data}

{zone-data:references}
* Community
{zone-data}

{zone-data:requirements}
Must Support:
* Zend_Config
* Multiples sources
* CRUD operations with bulk add/edit/remove options and auto-validation from tables definition
* PRG Form Processing
* Templates
* Multiples renders (Table, PDF, Print, Xml, Excel, etc, etc)
* Extra columns
* Extra rows
* Aggregate Expressions
* Horizontal splitting of records
* Multiple instances per page
* Custom Filters
* Auto-filters based on field definition (enum, set, etc, etc)
* Mass actions
* Cache
* Content format plugins
* Ajax
* Conditional Field Rendering
* Render specific parts of grid
* Sorting results
* Auto-paging. Change number of results per page
* Save params in session (Filters, Order, Page, Records per page)
* Detailed view of records
* Internationalization
* Decorators
* Callbacks
* Routing
{zone-data}

{zone-data:dependencies}
* Zend_View
* Zend_Config
* Zend_Form
* Zend_Session
* Zend_Controller
* Zend_Registry
* Zend_Cache
* Zend_Exception
{zone-data}

{zone-data:operation}
TDB
{zone-data}

{zone-data:milestones}
Milestone 1: [DONE] Working prototype written and tested. [Demos|http://zfdatagrid.com]
Milestone 2: [DONE] Create initial documentation. [Project Code|http://code.google.com/p/zfdatagrid/]
Milestone 3: [Done] Working code and tests checked into SVN.
Milestone 4: [DONE] Submitted to Ready for Review.
{zone-data}

{zone-data:class-list}
* Zend_Grid
* Zend_Grid_Column
* Zend_Grid_Deploy_Csv
* Zend_Grid_Deploy_DeployInterface
* Zend_Grid_Deploy_Jqgrid
* Zend_Grid_Deploy_Json
* Zend_Grid_Deploy_Ods
* Zend_Grid_Deploy_Odt
* Zend_Grid_Deploy_Ofc
* Zend_Grid_Deploy_Pdf
* Zend_Grid_Deploy_Print
* Zend_Grid_Deploy_Table
* Zend_Grid_Deploy_Word
* Zend_Grid_Deploy_Wordx
* Zend_Grid_Deploy_Xml
* Zend_Grid_Exception
* Zend_Grid_Extra_Column
* Zend_Grid_Extra_Row
* Zend_Grid_Filters_Render_Date
* Zend_Grid_Filters_Render_Number
* Zend_Grid_Filters_Render_RenderAbstract
* Zend_Grid_Filters_Render_RenderInterface
* Zend_Grid_Filters_Render_Select
* Zend_Grid_Filters_Render_Text
* Zend_Grid_Filters
* Zend_Grid_Form
* Zend_Grid_Formatter_Array
* Zend_Grid_Formatter_Currency
* Zend_Grid_Formatter_Date
* Zend_Grid_Formatter_FormatterInterface
* Zend_Grid_Formatter_Image
* Zend_Grid_GridInterface
* Zend_Grid_Source_Array
* Zend_Grid_Source_Csv
* Zend_Grid_Source_Db_DbAbstract
* Zend_Grid_Source_Doctrine
* Zend_Grid_Source_Json
* Zend_Grid_Source_SourceInterface
* Zend_Grid_Source_Xml
* Zend_Grid_Source_Zend_Select
* Zend_Grid_Source_Zend_Table
* Zend_Grid_Template_Ods_Ods
* Zend_Grid_Template_Odt_Odt
* Zend_Grid_Template_Print_Print
* Zend_Grid_Template_Table_Table
* Zend_Grid_Template_Word_Word
* Zend_Grid_Template_Wordx_Wordx
* Zend_Grid_Translator

{zone-data}



{zone-data:use-cases}

{composition-setup}

{deck:id=use-cases1}

{card:label=UC 1 : Basic Usage}
UC1: Basic Usage
{code}
$select = $db->select()->from('Users');
$grid = new Zend_Grid::factory('Table',Zend_Config $config, $gridId);
$grid->setSource(new Zend_Grid_Source_Zend_Select($select));
$grid->deploy();
{code}

{card}


{card:label=UC 2 : Customize one field }
UC 2 : Customize one field
{code}

$select = $db->select()->from('Users',array('id','username','email','firstname','lastname','access'));
$grid = new Zend_Grid::factory('Table',Zend_Config $config, $gridId);
$grid->setSource(new Zend_Grid_Source_Zend_Select($select));

//Change title display for email column
$grid->updateColumn('email',array('title'=>"User's Email"));

//Id id column
$grid->updateColumn('id',array('hidden'=>1));

//Apply different css classes based on field value
$grid->setClassCellCondition('access', "'{{access}}' == 'admin'", "red", 'green');

$grid->deploy();
{code}
{card}


{card:label=UC 3 : CRUD Operations }
UC 3 : CRUD Operations
{code}


$grid = new Zend_Grid::factory('Table',Zend_Config $config);
$grid->setSource(new Zend_Grid_Source_Zend_Table(new Bugs()));

$form = new Zend_Grid_Form();
$form->setAdd(true)->setEdit(true)->setDelete(true);

$grid->setForm($form);
$grid->deploy();
{code}
{card}

{card:label=UC 4 : XML Source }
UC 4 : XML Source
{code}

$grid->setSource(new Zend_Grid_Source_Xml('http://zfdatagrid.com/feed/', 'channel,item'));
$grid->setNumberRecordsPerPage(10);

$grid->updateColumn('title', array('decorator' => '<a href="{{link}}">{{title}}</a>', 'style' => 'width:200px;'));
$grid->updateColumn('pubDate', array('class' => 'width_200'));
$grid->setGridColumns(array('title', 'comments', 'pubDate'));
{code}
{card}

{card:label=UC 5 : Mass Actions}
UC 5 : Mass Actions
{code}


$grid = new Zend_Grid::factory('Table',Zend_Config $config, $gridId);
$select = $this->_db->select()->from('Country');
$grid->query($select);


$grid->setMassAction(
array(
array(
'url' => $grid->getUrl(),
'caption' => 'Remove (Nothing will happen)',
'confirm' => 'Are you sure?'),
array(
'url' => $grid->getUrl() . '/nothing/happens',
'caption' => 'Some other action')
)
);
{code}
{card}

{card:label=UC 6 : Conditional Rendering}
UC 6 : Conditional Rendering
{code}


$grid = new Zend_Grid::factory('Table',Zend_Config $config, $gridId);
$select = $this->_db->select()->from('Country');
$grid->query($select);

$grid->setClassCellCondition('Population', "'{{Population}}' > 200000", "red", 'green');
$grid->setClassRowCondition("'{{Population}}' > 20000", "green", 'red');
{code}
{card}

{card:label=UC 7 : Extra Rows}
UC 7 : Extra Rows
{code}


$grid = new Zend_Grid::factory('Table',Zend_Config $config, $gridId);
$select = $this->_db->select()->from('Country', array('Name', 'Continent', 'Population', 'LocalName', 'GovernmentForm'));
$grid->setSource(new Zend_Grid_Source_Zend_Select($select));



$rows = new Zend_Grid_Extra_Rows();
$rows->addRow('beforeHeader', array('', array('colspan' => 1, 'class' => 'myclass', 'content' => 'my content'), array('colspan' => 2, 'class' => 'myotherclass', 'content' => 'some '), array('colspan' => 1, 'class' => 'myclass', 'content' => 'flowers:) ')));
rows->addRow('beforePagination', array(array('colspan' => 5, 'content' => "This is an extra row added before pagination")));
$grid->addExtraRows($rows);

{code}
{card}
{card:label=UC 8 : Others}
UC 8 : Others

[Check the source code of a controller|http://zfdatagrid.com/grid/site/code]

{card}


{deck}

{zone-data}







{zone-data:skeletons}

{composition-setup}

{deck:id=interface}

{card:label=UC 1 : Zend_Grid_Source_SourceInterface}
UC1: Zend_Grid_Source_SourceInterface
{code}

interface Zend_Grid_Source_SourceInterface
{


/**
* Should return true|false if this source support
* crud operations
*
* @return bool
*/
public function hasCrud ();


/**
* Gets a unique record as a associative array
*
* @param string $table
* @param array $condition
*
* @return array
*/
public function getRecord ($table, array $condition);


/**
* builds a key=>value array
*
* they must have two options
* title and field
* field is used to perform queries.
* Must have table name or table alias as a prefix
* ex: user.id | country.population
*
* The key for this array is the output field
* If raw sql is something like
*
* select name as alias, country from users
*
* the return array must be like this:
*
* array('alias'=>array('title'=>'alias','field'=>'users.name'));
*
* its not bad idea to apply this to fields titles
* $title = ucwords(str_replace('_',' ',$title));
*
* @return string
*/
public function buildFields ();


/**
* Should return the database server name or source name
*
* Ex: mysql, pgsql, array, xml
*
* @return string
*/
public function getSourceName ();


/**
* Runs the query and returns the result as a associative array
*
* @return array
*/
public function execute ();


/**
* Get a record detail based the current query
*
* @param array $where
*
* @return array
*/
public function fetchDetail (array $where);


/**
* Return the total of records
*
* @return int
*/
public function getTotalRecords ();


/**
* Ex: array('c'=>array('tableName'=>'Country'));
* where c is the table alias. If the table as no alias,
* c should be the table name
*
* @return array
*/
public function getTableList ();


/**
* Return possible filters values based on field definition
* This is mostly used for enum fields where the possible
* values are extracted
*
* Ex: enum('Yes','No','Empty');
*
* should return
*
* array('Yes'=>'Yes','No'=>'No','Empty'=>'Empty');
*
* @param string $field
*
* @return mixed
*/
public function getFilterValuesBasedOnFieldDefinition ($field);


/**
* Return field type
* char, varchar, int
*
* Note: If the field is enum or set,
* the value returned must be set or enum,
* and not the full definition
*
* @param string $field
*
* @return string
*/

public function getFieldType ($field);


/**
* Returns the "main" table
* the one after select * FROM {MAIN_TABLE}
*
* @return string
*/
public function getMainTable ();


/**
*
* Build the order part from the query.
*
* The first arg is the field to be ordered and the $order
* arg is the correspondent order (ASC|DESC)
*
* If the $reset is set to true, all previous order should be removed
*
* @param string $field
* @param string $order
* @param bool $reset
*
* @return void
*/
public function buildQueryOrder ($field, $order, $reset = false);


/**
* Build the query limit clause
*
* @param $start
* @param $offset
*
* @return void
*/
public function buildQueryLimit ($start, $offset);


/**
* Returns the select object
*
* @return mixed
*/
public function getSelectObject ();


/**
* returns the selected order
* that was defined by the user in the query entered
* and not the one generated by the system
*
*If empty a empty array must be returned.
*
*Else the array must be like this:
*
*Array
* (
* [0] => field
* [1] => ORDER (ASC|DESC)
* )
*
*
* @return array
*/
public function getSelectOrder ();


/**
* Should perform a query based on the provided by the user
* select the two fields and return an array $field=>$value
* as result
*
* ex: SELECT $field, $value FROM *
* array('1'=>'Something','2'=>'Number','3'=>'history')....;
*
* @param string $field
* @param string $value
*
* @return array
*/
public function getDistinctValuesForFilters ($field, $fieldValue, $order = 'name ASC');


/**
*
*Perform a sqlexp
*
*$value = array ('functions' => array ('AVG'), 'value' => 'Population' );
*
*Should be converted to
*SELECT AVG(Population) FROM *
*
*$value = array ('functions' => array ('SUM','AVG'), 'value' => 'Population' );
*
*Should be converted to
*SELECT SUM(AVG(Population)) FROM *
*
* @param array $value
* @param array $where
*
* @return array
*/
public function getSqlExp (array $value, $where = array());


/**
* Adds a fulltext search instead of a addcondition method
*
*$field has an index search
*$field['search'] = array('extra'=>'boolean|queryExpansion','indexes'=>'string|array');
*
*if no indexes provided, use the field name
*
*boolean => IN BOOLEAN MODE
*queryExpansion => WITH QUERY EXPANSION
*
* @param string $filter
* @param string $field
*
* @return mixed
*/
public function addFullTextSearch ($filter, $field);


/**
* Adds a new condition to the current query
* $filter is the value to be filtered
* $op is the operand to be used: =,>=, like, llike,REGEX,
* $completeField. use the index $completField['field'] to
* specify the field, to avoid ambiguous
*
* @param string $filter
* @param string $op
* @param array $completeField
*/
public function addCondition ($filter, $op, $completeField);


/**
*Insert an array of key=>values in the specified table
* @param string $table
* @param array $post
*/
public function insert ($table, array $post);


/**
*Update values in a table using the $condition clause
*
*The condition clause is a $field=>$value array
*that should be escaped by YOU (if your class doesn't do that for you)
* and using the AND operand
*
*Ex: array('user_id'=>'1','id_site'=>'12');
*
*Raw SQL: * WHERE user_id='1' AND id_site='12'
*
* @param string $table
* @param array $post
* @param array $condition
*/
public function update ($table, array $post, array $condition);


/**
* Delete a record from a table
*
* The condition clause is a $field=>$value array
* that should be escaped by YOU (if your class doesn't do that for you)
* and using the AND operand
*
* Ex: array('user_id'=>'1','id_site'=>'12');
* Raw SQL: * WHERE user_id='1' AND id_site='12'
*
* @param string $table
* @param array $condition
*/
public function delete ($table, array $condition);


/**
* Removes any order in que query
*/
public function resetOrder ();


/**
* Cache handler.
*
* @param Zend_Cache
*/
public function setCache ($cache);


/**
* Build the form based on a Model or query
*
* @param array $fields
* @param array $inputsType
*/
public function buildForm ($fields = array(), $inputsType = array());


/**
* Returns tables primary keys separeted by commas ","
* This is necessary for mass actions
*
* @param string $table
* @param array $fields
*/
public function getMassActionsIds ($table, $fields);


/**
* Fetch pairs from a table
*
* @param string $table
* @param string $field
* @param string $fieldValue
* @param string $order
*/
public function getValuesForFiltersFromTable ($table, $field, $fieldValue, $order = 'name ASC');

{code}

{card}




{deck}

{zone-data}


{zone-template-instance}