README

Welcome to the official ZfcDataGrid documentation. This documentation will help you to quickly understand how to use ZfcDataGrid.

If you are looking for some information that is not listed in the documentation, please open an issue!

ZF DataGrid Plugin Module based on ZfcDatagrid and is a kind of superstructure. Its main goal to reduce using complexity and improve code readability.

This module register new data_grid_plugins global config key and add ColumnFactory.

Working principle is using ZF2 way like Zend\Form which use array configuration for create form elements.

Important! DataGridPluginManager set $shareByDefault = false, this allow avoid redundant classes declaration in configuration.

Usage

Register Plugin. For this move content of vendor/popovserhii/zfc-data-grid-plugin/config/application.config.php.sample in global config/application.config.php

In general you create new Grid class which will be response for concrete Grid in your ecosystem.

namespace Popov\Invoice\Block\Grid;

use Popov\ZfcDataGrid\Block\AbstractGrid;

class InquiryGrid extends AbstractGrid
{
    public function init()
    {
        $grid = $this->getDataGrid();
        $grid->setId('invoice');
        $grid->setTitle('Invoices');
        $grid->setRendererName('jqGrid');
        
        // native configuration
        #$colId = new Column\Select('id', 'invoice');
        #$colId->setIdentity();
        #$grid->addColumn($colId);
        
        // array configuration
        $colId = $this->add([
            'name' => 'Select',
            'construct' => ['id', 'invoice'],
            'identity' => true,
        ])->getDataGrid()->getColumnByUniqueId('invoice_id');
        
        // native configuration
        #$col = new Column\Select('code', 'invoice');
        #$col->setLabel('Invoice code');
        #$col->setIdentity(false);
        #$grid->addColumn($col);
        
        // array configuration
        $this->add([
            'name' => 'Select',
            'construct' => ['code', 'invoice'],
            'label' => 'Код инвойса',
            'identity' => false,
        ]);
        
        // native configuration
        #$colType = new Type\DateTime();
        #$col = new Column\Select('createdAt', 'invoice');
        #$col->setLabel('Date Create');
        #$col->setTranslationEnabled();
        #$col->setType($colType);
        #$col->setWidth(2);
        #$grid->addColumn($col);
        
        // array configuration
        $this->add([
            'name' => 'Select',
            'construct' => ['createdAt', 'invoice'],
            'label' => 'Date Create',
            'translation_enabled' => true,
            'width' => 2,
            'type' => ['name' => 'DateTime'],
        ]);
        
        // native configuration
        #$col = new Column\Select('name', 'contractor');
        #$col->setLabel('Contractor');
        #$col->setTranslationEnabled();
        #$col->setWidth(3);
        #$col->setUserSortDisabled(true);
        #$col->setUserFilterDisabled(true);
        #$grid->addColumn($col);
        
        // array configuration
        $this->add([
            'name' => 'Select',
            'construct' => ['name', 'contractor'],
            'label' => 'Contractor',
            'width' => 3,
            'user_sort_disabled' => true,
            'user_filter_disabled' => true,
        ]);
        
        // native configuration
        #$bg = new Style\BackgroundColor([224, 226, 229]);
        #$fmtr = new Column\Formatter\Link();
        #$fmtr->setAttribute('class', 'pencil-edit-icon');
        #$fmtr->setLink('/invoice/view/' . $fmtr->getColumnValuePlaceholder($colId));
        #$actions = new Column\Action('edit');
        #$actions->setLabel(' ');
        #$actions->setTranslationEnabled();
        #$actions->setFormatters([$fmtr]);
        #$actions->addStyle($bg);
        #$actions->setWidth(1);
        #$grid->addColumn($actions);
        
        // array configuration
        $this->add([
            'name' => 'Action',
            'construct' => ['edit'],
            'label' => ' ',
            'width' => 1,
            'styles' => [
                [
                    'name' => 'BackgroundColor',
                    'construct' => [[224, 226, 229]],
                ],
            ],
            'formatters' => [
                [
                    'name' => 'Link',
                    'attributes' => ['class' => 'pencil-edit-icon'],
                    // next two line are identical
                    //'link' => ['href' => '/invoice/view/%s', 'placeholder_column' => 'invoice_id'],
                    'link' => ['href' => '/invoice/view/%s', 'placeholder_column' => $colId], // special config
                ],
            ],
        ]);
        
        $formatter = <<<FORMATTER_JS
      function (value, options, rowObject) {
        return '<div class="input-btn-group">'
        	+ '<button class="btn btn-default btn-xs barcode-print" title="{$this->__('Print Bar code')}">' + value + '</button>'
          + '</div>';
      }
FORMATTER_JS;
        
        // native configuration
        #$formatterLink = new Formatter\Barcode();
        #$formatterLink->setSourceAttr('data-barcode');
        #$formatterLink->setAttribute('class', 'barcode-icon');
        #$formatterLink->setBasedOn($grid->getColumnByUniqueId('product_id'));
        #$actions = new Column\Action('barcode');
        #$actions->setLabel(' ');
        #$actions->setTranslationEnabled();
        #$actions->setFormatters([$formatterLink]);
        #$actions->setRendererParameter('formatter', $formatterJs, 'jqGrid');
        #$actions->setWidth(1);
        #$grid->addColumn($actions);
        
        // array configuration
        $this->add([
            'name' => 'Action',
            'construct' => ['barcode'],
            'label' => ' ',
            'translation_enabled' => true,
            'width' => 1,
            'renderer_parameter' => ['formatter', $formatter, 'jqGrid'],
            'formatters' => [
                [
                    'name' => 'Barcode',
                    'source_attr' => 'data-barcode',
                    //'placeholder_column' => $grid->getColumnByUniqueId('product_id'),
                    'attributes' => [
                        'class' => 'barcode-icon',
                    ],
                ],
            ],
        ]);
    }
}

Columns

Columns Introduction

The column definition is a central part of ZfcDataGrid, they are used to tell the grid what columns to display and how to display them.

Column Types

Select

A minimal column definition looks like this:

$this->add([
    'name' => 'Select',
    'construct' => ['name', 'product'],
    'label' => 'Name',
]);

GROUP_CONCAT

Doctrine

Sometimes we need use built-in database functions for aggregate result. For this purpose we need give \Zend\Db\Sql\Expression or \Doctrine\ORM\Query\Expr\Func as argument to Select column.

$this->add([
	'name' => 'Select',
	'construct' => [new \Doctrine\ORM\Query\Expr\Select("GROUP_CONCAT(serial.number)"), 'serial_all'], // Doctrine usage
	// or 
	'construct' => [new \Doctrine\ORM\Query\Expr\Func('GROUP_CONCAT', ['serial.number']), 'serial_all'], // Doctrine usage
	'label' => 'Serial Number',
]);

Advanced Usage
Doctrine DOES NOT support expression below and throw Exception [Syntax Error] line 0, col 218: Error: Unexpected 'NULL':

$this->add([
	'name' => 'Select',
	// @see https://github.com/doctrine/orm/issues/5801
	'construct' => [new Expr\Func('GROUP_CONCAT', ['CASE WHEN serial.cartItem > 0 THEN serial.number ELSE NULL END']), 'serial_id'],
]);

Insteat of example above you can use NULLIF operator (which is supported):

$this->add([
   'name' => 'Select',
   'construct' => [new Expr\Select('GROUP_CONCAT(CASE WHEN serial.cartItem > 0 THEN serial.number ELSE NULLIF(1,1) END)'), 'serial_id'],
]);

Notice: Some functions like GROUP_CONCAT is represented only in one database so Doctrine don't support it by default so you need include relative package to you project.

ZendTable

$this->add([
	'name' => 'Select',
	'construct' => [new \Zend\Db\Sql\Expression ('GROUP_CONCAT(serial.number)'), 'serial_all'],
	'label' => 'Serial number',
]);

Column Data Types

Number

The Number (original: Type\Number) column data types is used to format numbers using the PHP NumberFormatter, and so you can use the NumberFormatter properties in this data type, to do so you create a Number object which can takes the following parameters in order:

Format Style: default NumberFormatter::DECIMAL
Format Type: default NumberFormatter::TYPE_DEFAULT
Locale: Default Locale::getDefault()

You can also do the following for this type:

'type' => ['prefix' => 'prefix']
'type' => ['suffix' => 'suffix']
'type' => ['attribute' => ['attrName', 'attrValue']]

A usage Example of this column data type is the following:

$this->add([
    'name' => 'Select',
    'construct' => ['weight', 'product'],
    'label' => 'Weight',
    'type' => [
        'name' => 'Number',
        'attribute' => [\NumberFormatter::FRACTION_DIGITS, 2],
        'suffix' => ' kg'
    ],
]);

Column Data Styles

Align

The Align is used to change text direction of rows or columns of the grid, to create the Align do the following:

$this->add([
    'name' => 'Select',
    'construct' => ['price', 'product'],
    'label' => 'Asin',
    'styles' => [[
        'name' => 'Align',
        'construct' => ['right'],
    ]],
]);

$this->add([
    'name' => 'Select',
    'construct' => ['price', 'product'],
    'label' => 'Asin',
    'styles' => [[
        'name' => 'Align',
        'construct' => [\ZfcDatagrid\Column\Style\Align::$RIGHT],
    ]],
]);

If you set column type as Number the text direction automatically will be changed to right

$this->add([
    'name' => 'Select',
    'construct' => ['price', 'product'],
    'label' => 'Asin',
    'type' => [
        'name' => 'Number'
    ],
]);

BackgroundColor

The BackgroundColor is used to change background color of rows or columns of the grid, to create a BackgroundColor do the following:

$this->add([
    'name' => 'Select',
    'construct' => ['temperature', 'planet'],
    'label' => 'Temperature',
    'styles' => [[
        'name' => 'BackgroundColor',
        'constuct' => [200, 200, 200]
    ]],
]);

where the parameters are the color red green blue values.