README

此 Symfony 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 处于 beta 阶段，功能没有变化
• v2.5.x 跟随 doctrine 的 v2.5.x 版本
• v2.4.x 跟随 doctrine 的 v2.4.x 版本
• v2.x 稳定，可用于生产
• v1.x 稳定，可用于生产

功能

• 从 Doctrine 2 查询构建器显示数据网格
• 自动筛选
• 按列排序
• 易于配置
• 易于扩展
• 已文档化（本 README 中有基础知识，Resources/doc 中有高级主题）
• 分页器可以作为独立组件使用
• 使用事件更改数据网格行为
• 使用 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 下载程序包

$ 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['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 中的某些对象来修改此包的工作方式。

请参阅 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