Download the PHP package cscfa/datagrid-bundle without Composer

DataGrid bundle documentation

Version: 1.2.0

The DataGrid bundle allow to display a datagrid into twig template.

Installation

Register the bundle into app/appKernel.php

Create you'r first datagrid

The datagrid system use the DataGridContainer class to define the datagrid informations.

Basically, this class is instanciate with a set of data to display, the access method to get the specifically data from each elements, the headers to display and the elements type.

By 'element', we understand the row data container. This element can be an array or an object. By default, the container use each element as array. If you give an array of object, as a doctrine findAll result, you will must specify it by passing DataGridContainer::TYPE_OBJECT as fourth argument of the constructor.

To display data, you'll must specify the access methods to it. By passing an array of string you can inform on the access method of each elements data. If the elements are array, the access method will be an array of key to display. If the elements are objects, the access method will be the getter methods of the objects.

The header argument is an array of string that inform on the header of each column.

And into the twig template :

No one of the arguments are required to instanciate the DataGridContainer class and empty container does not generate exception.

You can instanciate a datagrid with this code :

And define each arguments with this :

Since version 1.2.0, the DataGridContainer allow to use chained access method by using a '.' delimiter bteween each access method.

Advanced use with callbacks

The datagrid can use callbacks that will be calls by a DataGridStepper into the rendering step by step. Some of this callbacks already exists into the default templates. We can use :

To register a stepper into the datagrid, you can use the setStepper method:

An unidirectionnal connection is done between the two class, so, a stepper can only have one DataGrid as parent, and in return, a DataGrid can only have one stepper.

To register a callback, you'll must use the stepper addCallback method. This one take as argument the callback name, the function to use as a closure, the html safe state as optional, and an array of additionnal data.

The name of the callback can be one of the previous callback or any of template callback if you use a personal template. An inexisting callback name does not create error but it will never call.

In this example, we can see that the result of callbacks are naturally escaped, but the third argument allow to display html tags by passing true.

The function registered can take four arguments, given by the stepper. This arguments may be null in function of the place in the template. The first argument is the type of the elements. The second is the total processed data as array, the third will be the current row and the fourth is the array of additional data.

• The type of element is an integer. 0 is an object type and 1 is array.
• The processed data is an array that contain the type as 'type' named index and each rows into integer index.
• The current row is an array that contain the current element as 'primary' named index and each data into integer index.
• The additional data is an array defined on callback registering and where we find in addition the current row index, the current element index, the current header name and the current DataGridStepper, respectively into 'index', 'element', 'header' and 'stepper' named index. Note that if you use this index into the callback definition, they will be override before the callback calling.

Note that the callback must return a string and callbacks have different access to the the variables. They exists but would be null. Refer to the following table to see the access :

Consider to use a service to define the callbacks.

Create your own template

You can define your own template to display you'r datagrid by configure it into the config.yml symfony file.

A second choice would be by passing the template by the renderDatagrid twig function :

by extend

You can also extend of the DataGridBundle template. This one is composed with blocks. You will find the following blocks :

The variables are defined into the followed blocks :

by yourself

Note, the DataGridContainer is passed to the template into the variable 'data'.

To get data from the DataGridContainer, you'll must use the getData method.

To get the stepper from the DataGridContainer, you'll must use the getStepper method.

To render a callback, you must use the datagc function (datagridRenderCallback). This function take three arguments :

• The callback name that will be call from the stepper
• The current row index and element index as formated string
• The stepper instance

The formated string of the index is "i:e" where 'i' is the row index and 'e' the element index. If no one is define at the current template place, the function accept null. If only the row index is define, it can be passed alone.

The headers are accessibles from the getHeader method of the DataGridContainer (passed as 'data' variable).

Use pagination

The 1.1.0 version introduce pagination usage.

The main pagination class must be instanciate into a php context by using DataGridPaginator class.

This class can be instanciate withe three arguments :

• The data to display in an array as first argument
• The integer page to render as second argument
• The integer limit of objects to display as third argument

All of these arguments are optional, the DataGridPaginator class can be instanciate without arguments.

The paginator allow to be instanciate without arguments, so it purpose some setters to perform it's task.

To use pagination, the paginator class purpose access to several getter methods, as followed :

Note that the DataGridPaginator class auto process the data selection when the limit or the data is defined.

The usage of unexisting page, sub zero limit or empty data does not create error.

To use it with the DataGridContainer instance, simply use :

Use pagination in twig

The 1.1.0 version introduce pagination usage in a twig context.

To display the paginator page selector, the DataGridBundle purpose the renderPaginator() function. It take the paginator class as first argument.

The paginator, same as DataGridContainer allow to use a DataGridStepper to customize the rendering template. The allowed callbacks are :

Referer to the following table to see callbacks variable access :

The onHref callback have access to a data['page'] and data['limit'] variables.

Create your own template

You can define your own template to display you'r paginator by configure it into the config.yml symfony file.

A second choice would be by passing the template by the renderPaginator twig function :

by extend

You can also extend of the DataGridBundle template. This one is composed with blocks. You will find the following blocks :

The variables are defined into the followed blocks :

by yourself

Note that the paginator instance is passed as 'pager' variable.

The callback definition of the paginator template is the same as the DataGrid template with the 'datagc' function usage.

To display the elements, the simple way is to use a loop :

The 'start' and 'end' variables are defined by the twig extension class to allow the page selection list amount limit.

Limit the page selection list amount

The renderPaginator() twig function purpose to limit the page amount to display by passing an integer as third arguments. This integer represent an interval, if you define it at 3, a page will be before the current page, and a page will be displayed after the current page.

The default comportment of the function will display an odd number of page and does not display unexisting pages.

Limit pagination

The pagination limit is setted by the paginator class in a php context, but it possible to purpose a limit selector to the client.

This action is performed by passing an array of allowed limits behind the paginator 'setAllowedLimits(array())' method. This information is used into the template for hydrate the select options tags.

The limit pagination twig extension will display a form to manage the limit choice. This form is created from a Cscfa\Bundle\DataGridBundle\Form\Type\PaginatorLimit type, that contain the current page and limit information, and a limit.

The rendering of the form is perform by the {{ renderPaginatorLimit(pager) }} twig function. This function accept as second argument a template name to override the configuration's defined template.

As the other template, this one use the pager stepper to customize some informations, but many of callbacks must return an array instead of string. To do it, it is necessary to pass 'true' as third argument.

Refer to the list of callbacks :

To access to the new limit, a controller action must receive the form informations. The route can be defined by the 'inLimitFirst' callback.

Create your own template

You can define your own template to display you'r paginator limit form by configure it into the config.yml symfony file.

A second choice would be by passing the template by the renderPaginatorLimit twig function :

by extend

You can also extend of the DataGridBundle template. This one is composed with blocks. You will find the following blocks :

The variables are defined into the followed blocks :

by yourself

Note that the paginator instance is passed as 'pager' variable and the form view as 'form' variable.

The callback definition of the paginator template is the same as the DataGrid template with the 'datagc' function usage.

To display the elements, the simple way is to use the twig form functions :