README

版本：1.2.0

DataGrid 包允许在 twig 模板中显示数据网格。

安装

将包注册到 app/appKernel.php 中

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

创建你的第一个数据网格

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

数据网格系统使用 DataGridContainer 类来定义数据网格信息。

基本上，这个类通过一组要显示的数据、获取每个元素的特定数据的方法、要显示的标题和元素类型来实例化。

在这里，“元素”是指行数据容器。这个元素可以是数组或对象。默认情况下，容器将每个元素视为数组。如果您提供对象数组，如 doctrine findAll 结果，您必须通过将 DataGridContainer::TYPE_OBJECT 作为构造函数的第四个参数传递来指定它。

要显示数据，您必须指定访问方法。通过传递一个字符串数组，您可以通知每个元素的访问方法。如果元素是数组，则访问方法将是显示的键数组。如果元素是对象，则访问方法是对象的 getter 方法。

标题参数是一个字符串数组，它通知每个列的标题。

	// 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));

在 twig 模板中

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

没有参数是必需的来实例化 DataGridContainer 类，并且空容器不会生成异常。

您可以使用以下代码实例化数据网格

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

并使用以下代码定义每个参数

	// 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));

从版本 1.2.0 开始，DataGridContainer 允许通过使用 '.' 分隔符在各个访问方法之间使用链式访问方法。

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

使用回调的高级用法

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

数据网格可以使用回调，这些回调将在 DataGridStepper 的渲染步骤中逐个调用。其中一些回调已存在于默认模板中。我们可以使用

要注册 steppers 到数据网格，您可以使用 setStepper 方法

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

两个类之间建立了一个单向连接，因此，stepper 只能有一个数据网格作为父级，反之亦然，数据网格只能有一个 steppers。

要注册回调，您必须使用 steppers addCallback 方法。这个方法接受作为参数的回调名称、用作闭包的函数、可选的 html 安全状态，以及一个额外的数据数组。

回调的名称可以是之前的任何回调，或者如果您使用自定义模板，可以是模板回调。不存在的回调名称不会创建错误，但它永远不会被调用。

在这个例子中，我们可以看到回调的结果是自然转义的，但第三个参数允许通过传递 true 来显示 HTML 标签。

	// 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"));

注册的函数可以接受四个参数，由 steppers 提供。这些参数可能根据模板中的位置而为 null。第一个参数是元素的类型。第二个是处理的数据总数作为数组，第三个是当前行，第四个是额外数据数组。

• 元素的类型是一个整数。0 是对象类型，1 是数组。
• 处理的数据是一个数组，它包含名为 'type' 的类型索引和每个行作为整数索引。
• 当前行是一个数组，它包含当前元素作为 'primary' 的索引和每个数据作为整数索引。
• 附加数据是一个数组，在回调注册时定义，其中我们找到当前行索引、当前元素索引、当前表头名称和当前DataGridStepper，分别命名为“索引”、“元素”、“表头”和“步进器”。注意，如果您在回调定义中使用此索引，它们将在回调调用之前被覆盖。

注意，回调必须返回一个字符串，并且回调对变量的访问不同。它们存在，但将是null。请参考以下表格以查看访问

考虑使用一个服务来定义回调。

创建自己的模板

您可以通过配置config.yml symfony文件来配置自己的模板以显示数据网格。

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

第二个选择是通过renderDatagrid twig函数传递模板

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

通过扩展

您还可以扩展DataGridBundle模板。这个模板由块组成。您将找到以下块

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

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

变量定义在以下块中

自己

注意，DataGridContainer通过变量'data'传递到模板中。

要从DataGridContainer获取数据，您必须使用getData方法。

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

要从DataGridContainer获取步进器，您必须使用getStepper方法。

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

要渲染回调，您必须使用datagc函数（datagridRenderCallback）。此函数接受三个参数

• 将从中调用步进器的回调名称
• 当前行索引和元素索引的格式化字符串
• 步进器实例

索引的格式化字符串为“i:e”，其中“i”是行索引，“e”是元素索引。如果当前模板位置没有定义，则函数接受null。如果只定义了行索引，则可以单独传递。

表头可以通过DataGridContainer的getHeader方法访问（作为'data'变量传递）。

	{# 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>

使用分页

1.1.0版本引入了分页的使用。

主分页类必须使用DataGridPaginator类在PHP上下文中实例化。

此类可以用三个参数实例化

• 第一个参数是作为数组的要显示的数据
• 第二个参数是要渲染的整数页
• 第三个参数是要显示的对象的整数限制

所有这些参数都是可选的，DataGridPaginator类可以无参数实例化。

	// 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);

分页器允许无参数实例化，因此提供了一些设置器来完成其任务。

	//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));

要使用分页，分页器类提供了一些getter方法，如下所示

注意，当定义限制或数据时，DataGridPaginator类会自动处理数据选择。

使用不存在的页面、负限制或空数据不会创建错误。

要与其DataGridContainer实例一起使用，只需使用

	//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());

在twig中使用分页

1.1.0版本引入了在twig上下文中分页的使用。

要显示分页器页面选择器，DataGridBundle提供renderPaginator()函数。它接受分页器类作为第一个参数。

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

与DataGridContainer一样，分页器允许使用DataGridStepper来自定义渲染模板。允许的回调包括

请参考以下表格以查看回调变量访问

onHref回调可以访问data['page']和data['limit']变量。

创建自己的模板

您可以在config.yml symfony文件中配置自己的模板以显示您的分页器。

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

第二个选择是通过renderPaginator twig函数传递模板

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

通过扩展

您还可以扩展DataGridBundle模板。这个模板由块组成。您将找到以下块

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

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

变量定义在以下块中

自己

注意，分页器实例作为'pager'变量传递。

分页器模板的回调定义与DataGrid模板相同，使用'datagc'函数。

要显示元素，简单的方法是使用循环。

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

由twig扩展类定义的'start'和'end'变量用于限制页面选择列表的数量。

限制页面选择列表的数量。

renderPaginator() twig函数的目的是通过传递一个整数作为第三个参数来限制显示的页面数量。这个整数代表一个间隔，如果你将其定义为3，则在当前页面前显示一页，在当前页后显示一页。

该函数的默认行为将显示奇数页数，并且不显示不存在的页面。

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

限制分页。

分页限制在PHP上下文中由分页器类设置，但可以向客户端提供一个限制选择器。

通过在分页器'`setAllowedLimits(array())'方法后面传递一个允许限制的数组来执行此操作。这些信息用于在模板中填充选择选项标签。

限制分页的twig扩展将显示一个表单来管理限制选择。此表单由Cscfa\Bundle\DataGridBundle\Form\Type\PaginatorLimit类型创建，其中包含当前页和限制信息，以及一个限制。

该表单的渲染是通过{{ renderPaginatorLimit(pager) }} twig函数执行的。该函数接受第二个参数作为模板名称，以覆盖配置中定义的模板。

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

与其他模板一样，此模板也使用分页器步进器来定制一些信息，但许多回调必须返回数组而不是字符串。要这样做，需要将'true'作为第三个参数传递。

请参考回调列表

要访问新的限制，控制器动作必须接收表单信息。路由可以由'inLimitFirst'回调定义。

//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
        }
	}
}

创建自己的模板

您可以通过在symfony的config.yml文件中配置来自定义显示分页器限制表单的模板。

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

另一种选择是通过传递模板给renderPaginatorLimit twig函数

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

通过扩展

您还可以扩展DataGridBundle模板。这个模板由块组成。您将找到以下块

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

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

变量定义在以下块中

自己

请注意，分页器实例作为'pager'变量传递，表单视图作为'form'变量传递。

分页器模板的回调定义与DataGrid模板相同，使用'datagc'函数。

要显示元素，简单的方法是使用twig表单函数。

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