README

这是一个简单的Symfony2 Bundle数据网格。它旨在易于使用和扩展。

警告：版本3

版本3适用于symfony ~3.3和~4.0以及PHP 7，并且仅支持twig ~1.8

版本3在此。如果您想保持旧版本，可以切换到分支2.x（或标签2.x）。

版本2和版本3之间的使用没有BC中断，但版本3不兼容symfony < 3.3。

警告：版本2

版本2在此。如果您想保持旧版本，可以切换到分支1.x（或标签1.x）。版本1和版本2之间存在BC中断。

实际状态

参见VERSIONS.md

• v3.x处于测试版，功能没有变化
• v2.5.x跟随doctrine的v2.5.x版本
• v2.4.x跟随doctrine的v2.4.x版本
• v2.x稳定，适用于生产
• v1.x稳定，适用于生产

功能

• 从Doctrine 2查询构建器显示数据网格
• 自动筛选
• 按列排序
• 易于配置
• 易于扩展
• 已文档化（本README的 basics 和 Resources/doc 的 advanced topics）
• 分页器可以作为独立组件使用
• 使用事件更改数据网格行为
• 使用twig嵌入更改数据网格展示

系统需求

• 您的页面上必须存在jQuery
• twig的版本必须为1.8+（使用twig嵌入）

文档

文档在此README和Resources/doc中

• 安装和简单用户指南：在此README中
• 网格扩展使用
• 独立分页器
• 事件用于扩展使用案例

安装

您需要在您的deps中添加以下行

在composer.json中添加KitpagesChainBundle

{
    "require": {
        "kitpages/data-grid-bundle": "~2.4" // Use ~2.5 if you use doctrine >= 2.5
    }
}

现在，通过运行以下步骤让composer下载bundle

$ php composer.phar update kitpages/data-grid-bundle

AppKernel.php

$bundles = array(
    ...
    new Kitpages\DataGridBundle\KitpagesDataGridBundle(),
);

config.yml中的配置

这些值是默认值。如果您觉得可以，可以跳过配置。

kitpages_data_grid:
    grid:
        default_twig: KitpagesDataGridBundle:Grid:grid.html.twig
    paginator:
        default_twig: KitpagesDataGridBundle:Paginator:paginator.html.twig
        item_count_in_page: 50
        visible_page_count_in_paginator: 5

注意：您可以使用以下配置来使用Bootstrap 3

kitpages_data_grid:
    grid:
        default_twig: KitpagesDataGridBundle:Grid:bootstrap3-grid.html.twig
    paginator:
        default_twig: KitpagesDataGridBundle:Paginator:bootstrap3-paginator.html.twig

简单使用示例

在控制器中

use Kitpages\DataGridBundle\Grid\GridConfig;
use Kitpages\DataGridBundle\Grid\Field;
use Symfony\Component\HttpFoundation\Request;

class ContactController
{
    public function productListAction(Request $request)
    {
        // create query builder
        $repository = $this->getDoctrine()->getRepository('AcmeStoreBundle:Product');
        $queryBuilder = $repository->createQueryBuilder('item')
            ->where('item.price > :price')
            ->setParameter('price', '19.90')
        ;

        $gridConfig = new GridConfig();
        $gridConfig
            ->setQueryBuilder($queryBuilder)
            ->setCountFieldName('item.id')
            ->addField('item.id')
            ->addField('item.slug', array('filterable' => true))
            ->addField('item.updatedAt', array(
                'sortable' => true,
                'formatValueCallback' => function($value) { return $value->format('Y/m/d'); }
            ))
        ;

        $gridManager = $this->get('kitpages_data_grid.grid_manager');
        $grid = $gridManager->getGrid($gridConfig, $request);

        return $this->render('AppSiteBundle:Default:productList.html.twig', array(
            'grid' => $grid
        ));
    }
}

关联Twig

在您的twig中，只需放入此代码即可显示您配置的网格。

{% embed kitpages_data_grid.grid.default_twig with {'grid': grid} %}
{% endembed %}

更高级的使用

在控制器中

与之前相同的控制器

关联Twig

如果您想在表格的右侧添加列，您可以在您的twig中放入此代码。

{% embed kitpages_data_grid.grid.default_twig with {'grid': grid} %}

    {% block kit_grid_thead_column %}
        <th>Action</th>
    {% endblock %}

    {% block kit_grid_tbody_column %}
        <td><a href="{{ path ("my_route", {"id": item.id}) }}">Edit</a></td>
    {% endblock %}

{% endembed %}

更高级的使用

在控制器中

use Kitpages\DataGridBundle\Grid\GridConfig;
use Kitpages\DataGridBundle\Grid\Field;
use Symfony\Component\HttpFoundation\Request;

class AdminController extends Controller
{

    public function listAction(Request $request, $state)
    {
        // create query builder
        $em = $this->get('doctrine')->getEntityManager();
        $queryBuilder = $em->createQueryBuilder()
            ->select('m, e, c')
            ->from('KitappMissionBundle:Mission', 'm')
            ->leftJoin('m.employee', 'e')
            ->leftJoin('m.client', 'c')
            ->where('m.state = :state')
            ->add('orderBy', 'm.updatedAt DESC')
            ->setParameter('state', $state)
        ;

        $gridConfig = new GridConfig();
        $gridConfig
            ->setQueryBuilder($queryBuilder)
            ->setCountFieldName("m.id");
            ->addField('m.title', array('label' => 'title', 'filterable' => true))
            ->addField('m.country', array('filterable' => true))
            ->addField('c.corporation', array('filterable' => true))
            ->addField('e.lastname', array('filterable' => true))
            ->addField('e.email', array('filterable' => true))
        ;

        $gridManager = $this->get('kitpages_data_grid.grid_manager');
        $grid = $gridManager->getGrid($gridConfig, $request);

        return $this->render('KitappMissionBundle:Admin:list.html.twig', array(
            'grid' => $grid
        ));
    }
}

关联Twig

与之前相同的Twig

字段 "as"

对于如下请求

$queryBuilder->select("item, item.id * 3 as foo");

您可以使用以下方式显示foo字段

$gridConfig->addField("item.id");
$gridConfig->addField("foo");

事件

您可以通过监听事件并修改注入到$event中的某些对象来修改此bundle的工作方式。

参见Resources/doc/30-Events.md中的事件文档

标签

标签系统用于通过标签获取一些字段。当您创建字段时，您可以为此字段定义一些相关标签。之后，在网格配置中，您可以找到匹配此标签的字段。

// add tag as the third parameter of the field 
$gridConfig->addField("item.id", [], ['foo', 'bar']);
$gridConfig->addField("foo", [], ['myTag', 'foo']);

// get fieldList matching 'bar' tag. There is only one result.
$fieldList = $gridConfig->getFieldListByTag('bar');
$fieldList[0] // -> this is the first Field (which name is 'item.id')

为$grid对象自定义类

默认情况下，以下行

$grid = $gridManager->getGrid($gridConfig, $request);

返回一个Grid类型的对象

您可以使用自己的Grid子类。默认情况下，GridManager创建Grid的实例$grid，但您也可以自行创建实例。

class CustomGrid extends Grid
{
	public $myParameter;
}
$myCustomGrid = new CustomGrid();
$grid = $gridManager->getGrid($gridConfig, $request,$myCustomGrid);

// now the $grid object is an instance of CustomGrid (it 
// is exactly the same object than $myCustomGrid, not cloned)

参考指南

在gridConfig中添加字段

当您添加字段时，可以设置以下参数

$gridConfig->addField('slug', array(
    'label' => 'Mon slug',
    'sortable' => false,
    'visible' => true,
    'filterable' => true,
    'translatable' => true,
    'formatValueCallback' => function($value) { return strtoupper($value); },
    'autoEscape' => true,
    'category' => null, // only used by you for checking this value in your events if you want to...
    'nullIfNotExists' => false, // for leftJoin, if value is not defined, this can return null instead of an exception
));

您可以在twig模板中个性化什么

使用twig 1.8及更高版本的嵌入系统，您可以覆盖默认渲染的一些部分（请参阅“更高级的使用”段落中的示例）。

您可以通过此处查看基本twig模板，了解您可以个性化什么。 https://github.com/kitpages/KitpagesDataGridBundle/blob/master/Resources/views/Grid/grid.html.twig