README

Version: 1.2.0

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

Installation

// app/AppKernel.php
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            [...]
            new Cscfa\Bundle\DataGridBundle\CscfaDataGridBundle(),
        );
        
        [...]
    }
}

Create you'r first datagrid

// in php file
use Cscfa\Bundle\DataGridBundle\Objects\DataGridContainer;

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.

	// Asume this code is into a controller
	
	$datas = array(array("element 1.1", "element 1.2"), array("element 2.1", "element 2.2"));
	
	$dataGrid = new DataGridContainer($datas, array(0, 1), array("head1", "head2"), DataGridContainer::TYPE_ARRAY);
	
	$this->render("AcmeBundle:Default:index.html.twig", array("data"=>$dataGrid));

And into the twig template :

	{# in your template file #}
	{{ renderDatagrid(data) }}

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 :

	// Asume this code is into a controller
	$dataGrid = new DataGridContainer();
	
	$this->render("AcmeBundle:Default:index.html.twig", array("data"=>$dataGrid));

And define each arguments with this :

	// Asume this code is into a controller
	/*
	 * Note we use here the result of a doctrine request
	 * And we specify the the type is object.
	 */
    $manager = $this->getDoctrine()->getManager();
    $repository = $manager->getRepository("Acme\Bundle\AcmeBundle\Entity\Miscellaneous");
    $miscs = $repository->findAll();
            
	$dataGrid = new DataGridContainer();
	
	$dataGrid->setContainer($miscs);
	$dataGrid->setAccessMethods("getName", "getId");
	$dataGrid->setHeader("name", "identity");
	$dataGrid->setType(DataGridContainer::TYPE_OBJECT);
	
	$this->render("AcmeBundle:Default:index.html.twig", array("data"=>$dataGrid));

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

    //This access to $miscs->getBag()->getName()
    $dataGrid->setContainer($miscs);
    $dataGrid->setAccessMethods("getBag.getName");

Advanced use with callbacks

// in php file
use Cscfa\Bundle\DataGridBundle\Objects\DataGridStepper;

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:

	// in php file
	$dataGrid = new DataGridContainer();
    $dataGrid->setStepper(new DataGridStepper());

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.

	// in php file
	$dataGrid = new DataGridContainer();
    $dataGrid->setStepper(new DataGridStepper());
    
    // This one display the header before each values
    $dataGrid->getStepper()->addCallback("onElementPrepend", function($type, $process, $row, $data){
        return $data['header']." : ";
    });
    
    // This one display a title before the datagrid
    $dataGrid->getStepper()->addCallback("onGridStart", function($type, $process, $row, $data){
        return "<h3>See our awesome datagrid : </h3>";
    }, true);
    
    // This one set the style of the header at 'color: red'
    $dataGrid->getStepper()->addCallback("onHead", function($type, $process, $row, $data){
        return "style='color: ".$data["color"].";'";
    }, false, array("color"=>"red"));

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.

# in app/config/config.yml
cscfa_data_grid:
	template: AcmeBundle:Default:YourTemplate.html.twig

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

{# in your template file #}
{{ renderDatagrid(data, "AcmeBundle:Default:YourTemplate.html.twig") }}

by extend

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

{# in your template file #}
{% extends 'CscfaDataGridBundle:Default:datagrid.html.twig' %}

{% block datagrid %}
    {% block header %}
        {{ parent() }}
    {% endblock %}
    {% block body %}
        {% block row %}
            {{ parent() }}
        {% endblock %}
    {% endblock %}
{% endblock %}

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.

	{# in your template file #}
    {% set datas = data.getData() %}

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

	{# in your template file #}
    {% set stepper = data.getStepper() %}

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).

	{# in your template file #}
	{{ datagc("onAcmeCallback", null, data.getStepper()) }}
	
	<table>
    {% if data.getHeader() is not empty %}
	    <tr>
        {% for head in data.getHeader() %}
            <th>{{ head }}</th>
        {% endfor %}
	    </tr>
	{% for row in data.getData() %}
		<tr>
		{{ datagc("onAcmeRow", loop.index0, data.getStepper()) }}
		{% set rowIndex = loop.index0 %}
		{% for element in row %}
			<td>
			{{ datagc("onAcmeElement", rowIndex~':'~loop.index0, data.getStepper()) }}
			</td>
		{% endfor %}
		</tr>
	{% endfor %}
	</table>

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.

	// In a php context
	$datas = array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)

	/* 
     * Instanciate with arguments
     * 
     * In this example, we instanciate the paginator
     * with a 10 index array, on page 2, with 4 data
     * per page. 
     */
    $paginator = new DataGridPaginator($datas, 2, 4);

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

	//In a php context
    
    /*
     * Note that this example render the
     * same result as the previous example.
     */
    $paginator = new DataGridPaginator();
    $paginator->setPage(2)
    	->setLimit(4)
        ->setData(array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10));

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 :

	//In a php context
	$datas = array(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
    $paginator = new DataGridPaginator($datas, 2, 4);
    
    $data = new DataGridContainer($paginator->getPageData());

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.

	{# in twig template #}
	{{ renderPaginator(pager) }}

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.

# in app/config/config.yml
cscfa_data_grid:
	paginator_template: AcmeBundle:Default:YourTemplate.html.twig

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

{# in your template file #}
{{ renderPaginator(pager, "AcmeBundle:Default:YourTemplate.html.twig") }}

by extend

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

{# in your template file #}
{% extends 'CscfaDataGridBundle:Default:paginatorPageSelector.html.twig' %}

{% block pager %}
    {% block pagedList %}
	    {% block selector %}
	    {% endblock %}
    {% endblock %}
{% endblock %}

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 :

	{# in your twig template #}
	
    {% for page in start..end %}
    	{# the element display here #}
    {% endfor %}

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.

	{# in your twig template #}
	
	{{ renderPaginator(pager, null, 5) }}

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.

	{# in your twig template #}
	
	{{ renderPaginatorLimit(pager) }}
	
	{# or #}
	{{ renderPaginatorLimit(pager, "AcmeBundle:Default:AcmeTemplate.html.twig") }}

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.

//in your controller
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Cscfa\Bundle\DataGridBundle\Objects\PaginatorLimitForm;

class AcmeController extends Controller
{
	public function limitAction(Request $request)
	{
		$paginatorLimitForm = new PaginatorLimitForm();
		$paginatorLimitForm->setAllowedLimits(array(5, 10, 25, 50, 100));
		
        $limitForm = $this->createForm("paginatorLimit", $paginatorLimitForm);
        
        if ($request->getMethod() === "POST") {
            $limitForm->handleRequest($request);
            
            $choice = $paginatorLimitForm->getLimit();
            $value = $paginatorLimitForm->getAllowedLimits()[$choice];
            
            $lastLimit = $paginatorLimitForm->getLastLimit();
            $page = $paginatorLimitForm->getPage();
            
        	// render the template
            
        } else {
        	// render the template
        }
	}
}

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.

# in app/config/config.yml
cscfa_data_grid:
	paginator_limit_template: AcmeBundle:Default:YourTemplate.html.twig

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

{# in your template file #}
{{ renderPaginatorLimit(pager, "AcmeBundle:Default:AcmeTemplate.html.twig") }}

by extend

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

{# in your template file #}
{% extends 'CscfaDataGridBundle:Default:paginatorPageSelector.html.twig' %}

{% block limit %}
    {% block select %}
    	{{ parent() }}
    {% endblock %}
    {% block submit %}
    	{{ parent() }}
    {% endblock %}
{% endblock %}

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 :

	{# in your twig template #}
	
    {{ form_start(form) }}
	    {{ form_row(form.limit) }}
	    {{ form_row(form.submit) }}
    {{ form_end(form) }}

cscfa / datagrid-bundle

Maintainers

Details

README

Version: 1.2.0

Installation

Create you'r first datagrid

Advanced use with callbacks

Create your own template

by extend

by yourself

Use pagination

Use pagination in twig

Create your own template

by extend

by yourself

Limit the page selection list amount

Limit pagination

Create your own template

by extend

by yourself