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 中）
• 分页器可以作为独立组件使用
• 使用事件更改 DataGrid 行为
• 使用 twig embeds 更改 DataGrid 的展示

系统要求

• 您的页面必须包含 jQuery
• 强制要求 twig 的版本 1.8+（使用 twig embeds）

文档

文档在此 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: @KitpagesDataGrid/Grid/grid.html.twig
    paginator:
        default_twig: @KitpagesDataGrid/Paginator/paginator.html.twig
        item_count_in_page: 50
        visible_page_count_in_paginator: 5

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

kitpages_data_grid:
    grid:
        default_twig: @KitpagesDataGrid/Grid/bootstrap3-grid.html.twig
    paginator:
        default_twig: @KitpagesDataGrid/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 中的某些对象来修改此 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