README

这个SymfonyBundle是一个简单的数据网格包。它的目标是易于使用和扩展。

警告：版本3

版本3是为symfony ~3.3和~4.0以及PHP 7设计的，并且仅支持twig ~1.8

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

版本2和版本3之间在用法上没有不兼容，但版本3与symfony < 3.3不兼容。

警告：版本2

版本2在这里。如果您想保持旧版本，可以切换到分支1.x（或标签1.x）。版本1和版本2之间存在不兼容。

当前状态

参见CHANGELOG.md

特性

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

系统要求

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

文档

文档在本README和Resources/doc中

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

安装

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

在您的composer.json中添加KitpagesChainBundle

{
    "require": {
        "vysokeskoly/data-grid-bundle": "^5.0"
    }
}

现在运行以下步骤让composer下载包

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

AppKernel.php

$bundles = [
    ...
    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;
use Symfony\Component\HttpFoundation\Response;

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

        $gridConfig = new GridConfig($queryBuilder, 'item.id');
        $gridConfig
            ->addField('item.id')
            ->addField('item.slug', ['filterable' => true])
            ->addField('item.updatedAt', [
                'sortable' => true,
                'formatValueCallback' => fn ($value) => $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', [
            '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;
use Symfony\Component\HttpFoundation\Response;

class AdminController extends Controller
{
    public function listAction(Request $request, $state): Response
    {
        // 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($queryBuilder, 'm.id');
        $gridConfig
            ->addField('m.title', ['label' => 'title', 'filterable' => true])
            ->addField('m.country', ['filterable' => true])
            ->addField('c.corporation', ['filterable' => true])
            ->addField('e.lastname', ['filterable' => true])
            ->addField('e.email', ['filterable' => true])
        ;

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

        return $this->render('KitappMissionBundle:Admin:list.html.twig', [
            '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', [
    'label' => 'Mon slug',
    'sortable' => false,
    'visible' => true,
    'filterable' => true,
    'translatable' => true,
    'formatValueCallback' => fn ($value) => 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
]);

提示：使用FieldOption枚举

$gridConfig->addField('slug', [
    FieldOption::Label->value => 'Mon slug',
    FieldOption::Sortable->value => false,
    FieldOption::Visible->value => true,
    FieldOption::Filterable->value => true,
    FieldOption::Translatable->value => true,
    FieldOption::FormatValueCallback->value => fn ($value) => strtoupper($value),
    FieldOption::AutoEscape->value => true,
    FieldOption::Category->value => null, // only used by you for checking this value in your events if you want to...
    FieldOption::NullIfNotExists->value => 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