View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Dojo - dojox.grid.DataGrid Support
{zone-data}

{zone-data:proposer-list}
[~matthew]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 15 January 2009: Initial Draft.
{zone-data}

{zone-data:overview}
dojox.grid.DataGrid provides a powerful abstraction for presenting dynamic, infinitely scrolling grids of data that are backed by server-side data stores. While it is relatively easy to create these either programmatically or declaratively, ZF developers could benefit from having a PHP OOP interface for generating the necessary markup or Javascript. This proposal introduces a view helper to solve this task.

In addition to supporting dojox.grid.DataGrid, this proposal will add support for generating client-side dojo.data objects using declarative or programmatic syntax via a view helper. (For creating the actual data consumed by dojo.data objects, Zend_Dojo_Data will still be used.)
{zone-data}

{zone-data:references}
* [dojox.grid Documentation|http://docs.dojocampus.org/dojox/grid]
* [dojo.data Documentation|http://docs.dojocampus.org/dojo/data]
{zone-data}

{zone-data:requirements}
* The DataGrid view helper *will* support *both* declarative *and* programmatic generation
* The DataGrid view helper *could* support multi-row items (optional requirement)
* The DataGrid view helper *will* load the required stylesheets to ensure display
** Loading of stylesheets *should* be switchable (in the case that they are loaded in a user-defined theme, for example)
* The DataGrid view helper *will* allow capturing <script> content for use with the grid
* The DataGrid view helper *will* allow specifying each field and all options related to each field
* the DataGrid view helper *must* allow programmatically specifying all grid options, as well as passing them during configuration.
* The DataStore view helper *must* require minimally a jsId and dojoType in order to work
* The DataStore view helper *will* use all options aside from the jsId and dojoType in order to configure the data store
* The DataStore view helper *will* support *both* declarative *and* programmatic generation
{zone-data}

{zone-data:dependencies}
* Zend_Dojo_View_Helper_Dojo
* Zend_Dojo_View_Helper_Dijit
{zone-data}

{zone-data:operation}
The developer will use the dojox.grid and dojo.data store view helpers as they would normal view helpers: passing an identifier, any other required options, and then an optional array of additional parameters used to configure the helper. However, each will return a unique object instead of a string that may then be further manipulated.

As an example, the following generates a grid object, and then configures it:

{code:php}
$grid = $this->dataGrid('foogrid');
$grid->setStore('fooStore')
->setQuery("\{ id: '*' \}");
{code}

The object returned will implement __toString(), which will allow it to be echoed directly:

{code:php}
echo $grid;
{code}

The object will receive an instance of the view object, which will allow it ot interact with the dojo() and dijit() view helpers in order to setup appropriate dojo.require statements, dojo.addOnLoad events, etc.
{zone-data}

{zone-data:milestones}
* Milestone 1: Initial proposal written
* Milestone 2: Working prototype of dataStore() view helper checked into incubator (with tests)
* Milestone 3: Working prototype of dataGrid() view helper checked into incubator (with tests)
* Milestone 4: Full documentation completed
{zone-data}

{zone-data:class-list}
* Zend_Dojo_View_Helper_DataStore
* Zend_Dojo_View_Helper_DataStore_Instance
* Zend_Dojo_View_Helper_DataGrid
* Zend_Dojo_View_Helper_DataGrid_Instance
{zone-data}

{zone-data:use-cases}
||UC-01||
h4. Programmatic dojo.data store creation
{code:php}
// Required arguments are jsId and dojoType
$store = $this->dataStore('fooStore', 'dojox.data.QueryReadStore');
$store->setUrl('/api/spindle/bug/list'); // set URL for data store
echo $store; // Rendering will throw an exception if
{code}

||UC-02||
h4. Passing options during dojo.data store creation
{code:php}
$store = $this->dataStore('fooStore', 'dojox.data.QueryReadStore', array(
'url' => '/api/spindle/bug/list',
));
echo $store;
{code}

||UC-03||
h4. Programmatic configuration of a grid object
{code:php}
$grid = $this->dataGrid('foogrid'); // minimally, pass the id

$grid->setJsId('foogrid') // optional; by default, uses id
->setStore('fooStore') // references a store identified by 'fooStore'
->setRowsPerPage(30)
->setSelectionMode('single')
->setClientSort(false)
->setQuery("{ id: '*' }")
->setDelayScroll(true);

$grid->scriptCaptureStart('dojo/method', 'onClick', array('args' => 'evt')); ?>
var row = foogrid.selection.getFirstSelected();

var bugTreePane = dijit.byId("bugTreePane");
bugTreePane.tree.model.newItem({ name: row.i.id });

var bugPane = dijit.byId("bugPane");
bugPane.setHref("/api/spindle/bug/content/bug-" + row.i.id + ".html");
bugPane.refresh();
<?php $grid->scriptCaptureEnd();
$grid->addField('id', 'ID', array('width' => '16em'))
->addField('summary', 'Summary')
->addField('type_id', 'Type')
->addField('priority_id', 'Priority')
->addField('date_created'); // if no label passed, uses field name

echo $grid;
{code}

||UC-04||
h4. Configuration of data grid at creation
{code:php}
$grid = $this->dataGrid('foogrid', array(
'store' => 'fooStore',
'rowsPerPage' => 30,
'selectionMode' => 'single',
'clientSort' => false,
'query' => "{ id: '*' }",
'delayScroll' => true,
'fields' => array(
array('field' => 'id', 'label' => 'ID', 'options' => array('width' => '16em')),
array('field' => 'summary', 'label' => 'Summary'),
array('field' => 'type_id', 'label' => 'Type'),
'priority_id' => 'Priority', // field/label pair
'date_created', // field (label will be the same)
),
));
// Scripts must still be added via capturing, per UC-03

echo $grid;
{code}
{zone-data}

{zone-data:skeletons}
TBD
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>