README

安装此扩展包

1. Composer 需求

$php composer require digipolisgent/datatables-bundle

2. 启用扩展包

在 AppKernel 中，在 RegisterBundles() 方法内部添加以下行

public function registerBundles()
{
    $bundles = [
        // other bundles
        new DigipolisGent\DatatablesBundle\DatatablesBundle(),
    ];
}

将扩展包的路由添加到你的应用中，在你的 routing.yml 文件中

datatables:
    resource: "@DatatablesBundle/Resources/config/routing.yml"

将扩展包的 JavaScript 添加到你的应用中，在你的 layout.html.twig 文件中

{% block javascripts %}
    <!-- other scripts -->
    <script src="{{ asset('bundles/datatables/js/datatables.min.js') }}"></script>
{% endblock %}

此扩展包假设你的应用中已经有一个运行的 jQuery 版本。

创建一个数据表

1. 创建一个数据提取器

数据提取器包含一个方法；'extract'。此方法将接收一个 DatatableRequest，它包含默认的 symfony2 HttpRequest 以及一些额外的参数，例如页面、每页大小、查询、偏移等。

数据提取器将根据这些参数从外部源（如数据库或 API）提取数据。

数据将通过一个名为 "Extraction" 的包装对象传递。这样做是为了使扩展包不依赖于外部分页类和/或扩展包。Extraction 对象包含一页数据以及所有可用记录的总数。也提供了 ExtractionInterface。

以下是一个示例：

class ProductDataExtractor implements DataExtractorInterface
{
    // constructor etc.
    public function extract(RequestInterface $request)
    {
        $query = $this->entityManager->createQuery('// some DQL');
        $query->setMaxResults($request->getPageSize());
        $query->setFirstResult($request->getOffset());

        $paginator = new Paginator($query);

        return new Extraction(
            $paginator->getIterator()->getArrayCopy(),
            $paginator->count()
        );
    }
}

注意：在此示例中省略了 "search" 参数的使用。在实际应用中，你应该根据此参数构建你的查询。参数可以通过以下方式访问

$request->getSearch();

2. 在工厂中创建你的表格

我们在工厂中创建我们的 Datatable 实现。Datatable 通过别名和提取器作为参数进行构建。列是在工厂方法中添加到表格中的。

// ...
class ProductDataTableFactory
{
    public static function create(Extractor $extractor)
    {
        $table = new DataTable('product', $extractor);

        $table
            ->createColumn('owner', ['property' => 'owner.name'])
            ->createColumn('sku')
            ->createColumn('price')
            ->addColumn(new DateTimeColumn('created_at', ['format' => 'd-m-Y']))
        ;

        return $table;
    }
}

3. 将 Datatable 注册为服务并标记为服务。

当 Datatable 注册为 Datatable 时，它将通过 DatatableCompilerPass 注入到 DatatableManager 中。这将允许 DataController 调用正确的数据表并返回其数据。

services:

    #  Extractor
    app.datatable.extractor.product:
        class: App\AppBundle\Datatable\Extractor\ProductExtractor
        arguments:
            - '@doctrine'

    #  Table
    app.datatable.table.product:
        class: DigipolisGent\DatatablesBundle\Datatable\Datatable
        factory: [App\AppBundle\Factory\ProductTableFactory, 'create']
        arguments:
            - '@app.datatable.extractor.product'
        tags:
            - {name: 'digipolisgent_datatables.table'}

4. 使用 Datatable

当你的 Datatable 正确注册后，我们现在可以将 Datatable 本身传递到控制器中，并传递到视图中。可以使用 Twig 函数轻松渲染数据表。除了渲染数据表外，你不需要执行任何其他操作，数据表将自动实例化并自行运行。

数据表显示的数据将从这个扩展包的 DataController 中获取。

将数据表传递到 Twig 模板中

public function listAction()
{
    retun $this->renderer->renderResponse('path/to/twig.html.twig', [
        'table' => $this->get('app.datatable.table.product');
    ]);
}

使用 Twig 函数渲染表格

{% block content %}
    <div class="some-wrapper">
        {{ datatables_render_table(table) }}
    </div>
{% endblock %}

元素

DataTableBundle 包含两个 "Element" 类来生成标签和按钮。它们生成一个简单的 HTML 字符串，将被 DataTable 输出。这样你可以轻松创建编辑/删除按钮和/或标签。

这两个元素实现了 ElementInterface，它包含一个方法 'generate'。此方法接受一个包含选项的数组作为参数。

1. 按钮

按钮元素生成一个带有默认 btn 类的 "a" 标签。

按钮元素有 4 个选项

link : 将添加到 href 属性的 uri。（默认：'#'）
type: 将添加到 btn-%s 类中的指定类型。因此 "danger" 将导致 btn btn-danger。（默认：'danger'）
class: 将添加到 class 属性中的自定义类名（默认：null）
text: a 元素的 html 正文。（默认：'编辑'）

2. 标签

标签元素生成一个带有默认 'label' 类的 'span' 标签。

标签元素有 3 个选项

类型：指定的类型将被添加到 label-%s 类中。所以 "success" 将会生成 label-success。（默认：'success'）
class: 将添加到 class 属性中的自定义类名（默认：null）
文本：span 元素的 html 正文。（默认：'yes'）

3. 示例

生成按钮或标签很简单。作为一个例子，我们将创建一个简单的标签

$label = Label::generate([
    'type' => 'danger',
    'class' => 'example-label',
    'text' => 'Some Generated Text'
]);

将会生成

<span class="label label-danger example-label">Some Generated Text</span>

高级用法

列

1. 列选项

默认列有一组预定义的选项可以传递。

属性：这定义了列应该提取哪个属性。默认提取器将使用 Symfony\PropertyAccess 类来访问对象属性。更多信息请见：https://symfony.com.cn/doc/current/components/property_access/introduction.html，了解 PropertyAccess 类以及如何设置 "property" 选项。

$shop = new Shop();
$shop->setName('Some Shop');
$user = new User();
$user->setShop($shop);

$column = new Column('shop', ['property' => 'shop.name']);

$value = $column->extractValue($user); // $value === 'Some Shop'

提取器：此选项应包含一个有效的回调或实现 __invoke 方法的可调用类。您可以通过提供自定义提取器来覆盖默认的 Column 使用 PropertyAccess 提取器。通过使用自定义提取器，您可以几乎做任何事。在这个例子中，我们使用一个自定义提取器根据给定的实体生成按钮。

$callback = function(User $user) use($router) {
    return Button::generate([
        'link' => $router->generate('user_edit', ['id' => $user->getId()]),
        'text' => 'Edit User'
    ])
};

$column = new Column('_edit', ['extractor' => $callback]);

当使用自定义提取器时，可以省略 "property" 选项。在表中，此列将显示我们的 User 实体的以下内容

<tr>
    <!-- other columns-->
    <td>
        <a href="/user/48/edit" class="btn btn-danger btn-flat">Edit User</a>
    </td>
</tr>

属性：此选项支持键 => $value 属性的数组。这些属性将渲染到表头中。默认情况下，存在一个 data-name 属性。

$column = new Column('name', ['attributes' => ['data-status' => 'status_1']]);

前面的代码将生成以下内容

<tr>
    <!-- other columns -->
    <th data-status="status_1">Name</th>
</tr>

标签：您可以为每个列提供自定义标签。标签用于表头。标签在输出前通过翻译组件传递。假设以下代码 general.first_name 被翻译成 "First Name"。

$column = new Column('first_name', ['label' => 'general.first_name']);

前面的代码将生成以下内容

<tr>
    <!-- other columns -->
    <th data-name="first_name">First Name</th>
</tr>

默认情况下，标签生成方式为 ucfirst($column->getName());

1. 自定义列

在这个包中，您有默认的 "Column" 对象，用于定义表的列。Datatable 中的 'createColumn' 方法将创建具有给定参数的默认 Column。

但是，您也可以使用 ColumnInterface 扩展或创建自定义列。自定义列通过 Datatable 中的 'addColumn' 方法添加。

$datatable = new Datatable('example', $extractor);

$datatable
    ->createColumn('id')
    ->addColumn(new CustomColumn())
;

Bootstrap 配置

要启用应用程序中 Datatables 的 Bootstrap 实现，您需要将不同的文件包含在 layout.html.twig 文件中

{% block stylesheets %}
    <!--- Other stylesheets -->
    <link rel="stylesheet" href="{{ asset('bundles/datatables/css/datatables-bootstrap.min.css') }}">
{% endblock %}

注意，我们包含的是 datatables-bootstrap.min.css 而不是默认的 datatables.min.css。您只需要包含这两个文件中的一个。不要同时包含两个。

对于 JavaScript 文件也是如此

{% block javascripts %}
    <!-- other scripts -->
    <script src="{{ asset('bundles/datatables/js/datatables-bootstrap.min.js') }}"></script>
{% endblock %}

Font-Awesome 图标

要启用 Font-Awesome 图标（排序图标等）的使用，您需要包含第二个 css 文件

{% block stylesheets %}
    <!--- Other stylesheets -->
    <link rel="stylesheet" href="{{ asset('bundles/datatables/css/datatables-bootstrap.min.css') }}">
    <link rel="stylesheet" href="{{ asset('bundles/datatables/css/datatables-font-awesome.min.css') }}">
{% endblock %}

注意，这里我们包含这两个文件。您可以将 Font-Awesome 图标与默认的 datatables 布局结合使用。

digipolisgent / datatables-bundle

维护者

详细信息