mmucklo/grid-bundle

symfony2或symfony3或symfony4或symfony5的Datagrid

维护者

详细信息

github.com/mmucklo/DtcGridBundle

源代码

问题

安装数: 314 779

依赖者: 3

建议者: 2

安全性: 0

星标: 20

关注者: 5

分支: 11

开放问题: 13

类型:symfony-bundle

7.3.0 2021-06-04 15:59 UTC

Requires

Requires (Dev)

MIT c6ed13ccc06181254f9f87e133bce8decee0a9e1

  • David Tee
  • Matthew J Mucklo <mmucklo.woop@gmail.com>

jqgridgridtable

This package is auto-updated.

Last update: 2024-09-04 22:52:22 UTC

README

Build Status Scrutinizer Code Quality Code Coverage

从Doctrine ORM实体或Doctrine MongoDB文档生成可搜索的Grid

  • 利用jQuery DataTables、jqGrid(*)或样式HTML表(*)
  • 使用Bootstrap轻松定制样式
  • 自定义列和更多...
  • (新版本2.0): 易于安装，快速开始

(*) 仅在DataTables上支持搜索功能

使用jqGrid、jQuery DataTables或样式HTML表渲染可定制的表格。

支持Doctrine ORM和Doctrine MongoDB ODM

Screenshot

安装

Symfony 4/5

    composer.phar require mmucklo/grid-bundle

您可能会看到类似这样的信息（如果提示，请回答'y'）

  -  WARNING  mmucklo/grid-bundle (>=5.0): From github.com/symfony/recipes-contrib:master
    The recipe for this package comes from the "contrib" repository, which is open to community contributions.
    Review the recipe at https://github.com/symfony/recipes-contrib/tree/master/mmucklo/grid-bundle/4.0

    Do you want to execute this recipe?
    [y] Yes
    [n] No
    [a] Yes for all packages, only for the current installation session
    [p] Yes permanently, never ask again for this project
    (defaults to n): y
  - Configuring mmucklo/grid-bundle (>=5.0): From github.com/symfony/recipes-contrib:master

Symfony 2/3

将其添加到AppKernel.php文件中

    public function registerBundles()
    {
        $bundles = [
            ...
            new \Dtc\GridBundle\DtcGridBundle(),
            ...
        ]

将其添加到app/config/routing.yml文件中

dtc_grid:
    resource: '@DtcGridBundle/Resources/config/routing.yml'

使用方法

开始使用

安装后，所有具有Grid注解的实体和文档都应通过dtc_grid路由可用

(注意：以下示例为symfony5，对于symfony2/3，类的命名空间可能不同 - 例如AppBundle而不是App)

设置页面的Grid有两种推荐方式，通过注解或通过反射

反射

通过在config/packages/dtc_grid.yaml配置文件中设置参数reflections: allowed_entities: [...]可以自动设置Grid

dtc_grid:
    reflection:
        # allow any entity to be shown via the /dtc_grid route
        # allowed_entities: ~, '*', or an array of entity names [ 'App:Product', 'App:Category', ... ]
        #  ~ - no entities allowed for reflection
        #  * - all entities allowed for reflection
        #  [ 'App:Product', 'App:Category' ] - only App:Product and App:Category allowed
        allowed_entities: ~

(6.0版本新功能) grid yaml文件定义

您可以将grid列定义放置在自定义yaml文件中

步骤1 - 创建yaml文件
# File location(s):
#   - symfony 4+: config/dtc_grid/*.yaml (will load all *.yaml files in this directory)
#   - symfony 2/3: src/*/*/Resources/config/dtc_grid.yaml (will only load files with this name or the name 'dtc_grid.yml')
#   - custom (bundles): add the following to a CompilerPass:
#        # $cacheDir = $container->getParameter('kernel.cache_dir');
#        \Dtc\GridBundle\Grid\Source\ColumnSource::cacheClassesFromFile($cacheDir, $filename);
App\User:
  columns:
    id:
      sortable: true
    username:
      sortable: true
      searchable: true
    email:
      searchable: true
    createdAt:
      sortable: true
    updatedAt:
      sortable: true
    status:
      sortable: true
      searchable: true
  actions:
    -
      label: Show
      type: show
      route: dtc_grid_show
    -
      label: Archive
      type: delete
      route: dtc_grid_delete
  sort:
    id: ASC

App\Article:
  columns:
    id:
      sortable: true
    userId:
      sortable: true
    createdAt:
      sortable: true
    updatedAt:
      sortable: true
    subject:
      searchable: true
    status:
      sortable: true
  actions:
    -
      label: Show
      type: show
      route: dtc_grid_show
    -
      label: Custom
      onclick: "alert('custom action')"
      button_class: btn-info
  sort:
    createdAt: DESC

注解简单示例

注意：此示例仍然使用反射来发现列，但是如果您想自定义显示的列以及哪些列显示，请参阅下文标题为“自定义列”的部分

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Dtc\GridBundle\Annotation as Grid;

/**
 * Class User
 * @Grid\Grid
 * @ORM\Entity
 * @package App\Entity
 */
class User {
    //...
}

现在在添加注解后，您可能需要做

    bin/console cache:clear
    bin/console cache:warmup

访问Grid

您可以通过以下URL访问Grid而无需在任何地方嵌入

  • 路由：dtc_grid/dtc_grid/grid?class=App:User
  • 参数
    • class=[文档或实体]
      • 这可以是完全限定的类名或symfony风格的实体/文档格式，用':'分隔
        • 例如：'App:User'或'App\Entity\User'
    • type=[datatables|table|jq_grid]

示例

# A default HTML-based table
# (warning: if your table is large, skip this example, and try the paginated datatables path below)


# Datatables
/dtc_grid/grid?class=App:User&type=datatables

# Full Class syntax 
/dtc_grid/grid?class=App\Entity\User&type=datatables
 
# MongoDB ODM examples
/dtc_grid/grid?class=App:Event&type=datatables
/dtc_grid/grid?class=App\Document\Event&type=datatables

# Other types of tables
/dtc_grid/grid?class=App:Event&type=jq_grid
/dtc_grid/grid?class=App:Event&type=table

注意 - 安全性

对于生产系统，您可能需要在security.yml中添加路径^/dtc_grid，并使其防火墙/仅限管理员访问

security:
    # ...
    access_control:
        # ...
        - { path: ^/dtc_grid, roles: ROLE_ADMIN }

添加操作

目前有几种操作可以添加到您的Grid中，这些操作将显示在名为“操作”的最后一列中

这些必须作为注解添加到Grid注解中

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Dtc\GridBundle\Annotation as Grid;

/**
 * Class User
 * @Grid\Grid(actions={@Grid\ShowAction(), @Grid\DeleteAction(), @Grid\Action(label="Custom",buttonClass="btn-info",onclick="alert('custom-action')")})
 * @ORM\Entity
 * @package App\Entity
 */
class User {
    //...
}

更自定义的路由

/**
 * @Route("/users", name="app_grid_users")
 */
public function usersAction(Request $request) {
    $renderer = $this->get('dtc_grid.renderer.factory')->create('datatables');
    $gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
    $renderer->bind($gridSource);
    return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
}

更改渲染器

/**
 * @Route("/users_table", name="app_grid_users_table")
 */
public function usersAction(Request $request) {
    $renderer = $this->get('dtc_grid.renderer.factory')->create('table');
    $gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
    $renderer->bind($gridSource);
    return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
}

自定义列

在Dtc\GridBundle\Annotation中有一个@Column注解，您将其放置在每个希望可见的列上。然后您可以指定自定义标签以及排序性（如果您想的话）。如果没有@GridColumn注解，则默认显示所有列。

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Dtc\GridBundle\Annotation as Grid;

/**
 * Class User
 * @Grid\Grid
 * @ORM\Entity
 * @package App\Entity
 */
class User {

    /**
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

    /**
     * @Grid\Column(searchable=true)
     * @ORM\Column(type="string")
     */
    protected $firstName;

    /**
     * @Grid\Column(label="Last", sortable=true, searchable=true)
     * @ORM\Column(type="string")
     */
    protected $lastName;

自定义jQuery、Purl、DataTables

可以在config.yml中自定义jQuery、Purl和DataTables的版本

dtc_grid:
    theme: # theme defaults to bootstrap 3
        css:
            - 'path_or_url_to/bootstrap_or_any_other.css'
            - 'etc. as necessary'
        js:
            - 'path_or_url_to/any_javascript_needed_for_theme.js'
            - 'etc. as necessary'            
    purl: 'path_or_url_to/purl.js' # presently defaults to v2.3.1 hosted on cdnjs
    jquery: # presently defaults to 3.2.1 hosted on jquery's code.jquery.com cdn
        url: 'path_or_url_to/jquery.js'
        integrity: ~ # or an integrity for the file
        crossorigin: ~ # or what goes in the crossorigin section of the script tag
    datatables: # presently defaults to 1.10.16 hosted on cdn.datatables.net
        css:
            - 'path_or_url_to/datatables.css'
            - 'path_or_url_to/any_other_needed.css'
        js:
            - 'path_or_url_to/datatables.js'
            - 'path_or_url_to/datatables_theme.js'
            - 'etc. as necessary'

JQ Grid

要使用JQ Grid，您需要指定绝对URL或相对/绝对路径到JQGrid文件。

由于JQ Grid的许可与该包不同，因此没有提供默认设置。

# config.yml
dtc_grid:
    jq_grid:
        css:
            - 'path_or_url_to/prettify.css'
            - 'path_or_url_to/ui.jqgrid-bootstrap.css'
        js:
            - 'path_or_url_to/grid.locale-en.js'
            - 'path_or_url_to/jquery.jqGrid.js'
    /**
     * @Route("/users_table", name="app_grid_users_table")
     */
    public function usersAction(Request $request) {
        $renderer = $this->get('dtc_grid.renderer.factory')->create('jq_grid');
        $gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
        $renderer->bind($gridSource);
        return $this->render('@DtcGrid/Page/datatables.html.twig', $renderer->getParams());
    }

自定义Bootstrap

    # config.yml
    dtc_grid:
        bootstrap:
            css: path_or_url_to_bootstrap.css
            js: path_or_url_to_bootstrap.js

同一页面上多个Grid

如果您想在同一页面上渲染多个Grid，则需要使用RendererFactory。

目前支持三种渲染器类型

  • datatables
  • jq_grid
  • table
    /**
     * List jobs in system by default.
     *
     * @Route("/jobs/")
     */
    public function jobsAction()
    {
        $rendererFactory = $this->get('dtc_grid.renderer.factory');
        $renderer = $rendererFactory->create('datatables');
        $gridSource = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\Job');
        $renderer->bind($gridSource);
        $params = $renderer->getParams();

        $renderer2 = $rendererFactory->create('datatables');
        $gridSource2 = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\JobArchive');
        $renderer2->bind($gridSource2);
        $params2 = $renderer2->getParams();

        $params['archive_grid'] = $params2['dtc_grid'];
        return $this->render('@DtcQueue/Queue/jobs.html.twig', $params);
    }

在同一个页面上渲染多个网格的Twig文件

jobs.html.twig

{% extends "DtcGridBundle:Page:datatables.html.twig" %}

{% block grid %}
    <h3>Live Jobs</h3>
    {{ dtc_grid.render | raw }}
    <h3>Archived Jobs</h3>
    {{ archive_grid.render | raw }}
{% endblock %}

你甚至可以在同一个页面上渲染多种类型的网格

    /**
     * List jobs in system by default.
     *
     * @Route("/jobs/")
     */
    public function jobsAction()
    {
        $rendererFactory = $this->get('dtc_grid.renderer.factory');
        $renderer = $rendererFactory->create('jq_grid');  // NOTE THE DIFFERENT GRID TYPE
        $gridSource = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\Job');
        $renderer->bind($gridSource);
        $params = $renderer->getParams();

        $renderer2 = $rendererFactory->create('datatables');
        $gridSource2 = $this->get('dtc_grid.manager.source')->get('Dtc\\QueueBundle\\Documents\\JobArchive');
        $renderer2->bind($gridSource2);
        $params2 = $renderer2->getParams();

        $params['archive_grid'] = $params2['dtc_grid'];
        return $this->render('@DtcQueue/Queue/jobs.html.twig', $params);
    }

jobs.html.twig（由于需要包含两种网格类型的样式和JavaScript，所以稍微复杂一些，但如果使用“table”类型的渲染器，则不需要这样做，因为它的CSS和JavaScript与“datatables”渲染器重叠）

{% extends '@DtcGrid/layout_base_jquery.html.twig' %}

{% block dtc_grid_stylesheets %}
    {% for stylesheet in dtc_grid_jq_grid_css %}
        <link rel="stylesheet" href="{{ stylesheet }}" />
    {% endfor %}
    {% for stylesheet in dtc_grid_datatables_css %}
        <link rel="stylesheet" href="{{ stylesheet }}" />
    {% endfor %}
{% endblock %}

{% block dtc_grid_javascripts %}
    {{ parent() }}
    {% for javascript in dtc_grid_jq_grid_js %}
        <script type="text/javascript" src="{{ javascript }}"></script>
    {% endfor %}    
    {% for javascript in dtc_grid_datatables_js %}
        <script src="{{ javascript }}"></script>
    {% endfor %}
{% endblock %}

{% block grid %}
    <h3>Live Jobs</h3>
    {{ dtc_grid.render | raw }}
    <h3>Archived Jobs</h3>
    {{ archive_grid.render | raw }}
{% endblock %}

自定义/嵌入网格

要自定义网格的CSS/JavaScript或将它嵌入到现有页面中，请参考下面的示例

/**
 * @Route("/users_custom", name="app_grid_users_custom")
 */
public function usersCustomAction(Request $request) {
    // other setup, etc.
    // Assuming you have a variable called "$params"

    $renderer = $this->get('dtc_grid.renderer.factory')->create('datatables'); // or whichever renderer you want to use

    $gridSource = $this->get('dtc_grid.manager.source')->get('App:User');
    $renderer->bind($gridSource);

    $renderer->getParams($params); // This will add the grid-specific params (mainly 'grid', and the bootstrap urls)
    
    // Alternatively you can do
    // $dataGridParams = $renderer->getParams();
    // $myParams['my_grid'] = $dataGridParams['dtc_grid'];

    // render your page
    return $this->render('@App/Something/somepage.html.twig', $params);
}

datatables Twig 示例

<html>
<head>
    {% block stylesheets %}
        {% for stylesheet in dtc_grid_theme_css %}
            <link rel="stylesheet" href="{{ stylesheet }}">
        {% endfor %}
    {% endblock %}

    {% block dtc_grid_stylesheets %}
        {% for stylesheet in dtc_grid_datatables_css %}
            <link rel="stylesheet" href="{{ stylesheet }}" />
        {% endfor %}
        {% for stylesheet in dtc_grid_local_css %}
           <link rel="stylesheet" href="{{ app.request.baseUrl }}{{ stylesheet }}" />
        {% endfor %}
    {% endblock %}
    
    {% block dtc_grid_javascripts %}
        <script src="{{ dtc_grid_jquery.url }}"
            {% if dtc_grid_jquery.integrity is not empty  %} integrity="{{ dtc_grid_jquery.integrity }}"{% endif %}
            {% if dtc_grid_jquery.crossorigin is not empty  %} crossorigin="{{ dtc_grid_jquery.crossorigin }}"{% endif %}>
        </script>
        <script src="{{ dtc_grid_purl }}"></script>
        {% for javascript in dtc_grid_datatables_js %}
            <script src="{{ javascript }}"></script>
        {% endfor %}
    {% endblock %}
    
    {% block javascripts %}
        {% for javascript in dtc_grid_theme_js %}
            <script src="{{ javascript }}"></script>
        {% endfor %}
        {% for javascript in dtc_grid_local_js %}
            <script src="{{ app.request.baseUrl }}{{ javascript }}"></script>
        {% endfor %}
    {% endblock javascripts %}
</head>
<body>

<!-- .... -->
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}

<!-- ... -->
</body>
</html>

JQGrid Twig 示例

<html>
<head>
    {% block stylesheets %}
        {% for stylesheet in dtc_grid_theme_css %}
            <link rel="stylesheet" href="{{ stylesheet }}">
        {% endfor %}
        {% for stylesheet in dtc_grid_local_css %}
           <link rel="stylesheet" href="{{ app.request.baseUrl }}{{ stylesheet }}" />
        {% endfor %}
    {% endblock %}

    {% block dtc_grid_stylesheets %}
        {% for stylesheet in dtc_grid_jq_grid_css %}
            <link rel="stylesheet" href="{{ stylesheet }}" />
        {% endfor %}
    {% endblock %}
    
    {% block dtc_grid_javascripts %}
        <script src="{{ dtc_grid_jquery.url }}"
            {% if dtc_grid_jquery.integrity is not empty  %} integrity="{{ dtc_grid_jquery.integrity }}"{% endif %}
            {% if dtc_grid_jquery.crossorigin is not empty  %} crossorigin="{{ dtc_grid_jquery.crossorigin }}"{% endif %}>
        </script>
        <script src="{{ dtc_grid_purl }}"></script>
        {% for javascript in dtc_grid_jq_grid_js %}
            <script type="text/javascript" src="{{ javascript }}"></script>
        {% endfor %}    
    {% endblock %}
    
    {% block javascripts %}
        {% for javascript in dtc_grid_theme_js %}
            <script src="{{ javascript }}"></script>
        {% endfor %}
        {% for javascript in dtc_grid_local_js %}
            <script src="{{ app.request.baseUrl }}{{ javascript }}"></script>
        {% endfor %}
    {% endblock javascripts %}
</head>
<body>

<!-- .... -->
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}

<!-- ... -->
</body>
</html>

Table Twig 示例

<html>
<head>
    {% block stylesheets %}
        {% for stylesheet in dtc_grid_theme_css %}
            <link rel="stylesheet" href="{{ stylesheet }}">
        {% endfor %}
        {% for stylesheet in dtc_grid_local_css %}
           <link rel="stylesheet" href="{{ app.request.baseUrl }}{{ stylesheet }}" />
        {% endfor %}
    {% endblock %}

    {% block javascripts %}
        {% for javascript in dtc_grid_theme_js %}
            <script src="{{ javascript }}"></script>
        {% endfor %}
        {% for javascript in dtc_grid_local_js %}
            <script src="{{ app.request.baseUrl }}{{ javascript }}"></script>
        {% endfor %}
    {% endblock javascripts %}
</head>
<body>

<!-- .... -->
{# This is the most important part - 'dtc_grid.render' should be 'dtc_grid.render' or 'my_grid.render', or whatever you called it if you change the parameter's name #}
{{ dtc_grid.render | raw }}

<!-- ... -->
</body>
</html>

文档

在 Resources/doc/ 中存储了额外的（目前有些过时的）文档

过时

你以前需要使用“生成器”来创建网格.source服务，但现在不再需要了，但是关于如何使用它的文档仍然可以在Resources/doc/区域找到。

许可证

此软件包采用MIT许可证（请参阅Resources/meta/LICENSE文件下的LICENSE文件）。

贡献

最初由 @dtee 编写，由 @mmucklo 维护