README

Yii2 Widget for DataTables plug-in for jQuery

安装

建议通过composer安装此扩展。

运行

composer require nullref/yii2-datatables

或

"nullref/yii2-datatables": "~1.0"

将以下内容添加到您的composer.json文件的require部分。

基本用法

<?= \nullref\datatable\DataTable::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        'id',
        'name',
        'email'
    ],
]) ?>

为了向后兼容，仍然支持通过data的老式用法。

<?= \nullref\datatable\DataTable::widget([
    'data' => $dataProvider->getModels(),
    'columns' => [
        'id',
        'name',
        'email'
    ],
]) ?>

DataTable选项

您还可以使用所有Datatables选项

作为小部件选项传递

<?= \nullref\datatable\DataTable::widget([
    'data' => $dataProvider->getModels(),
    'scrollY' => '200px',
    'scrollCollapse' => true,
    'paging' => false,
    'columns' => [
        'name',
        'email'
    ],
    'withColumnFilter' => true,
]) ?>

指定单元格的标签和CSS类

    <?= \nullref\datatable\DataTable::widget([
        'columns' => [
            //other columns
            [
                'data' => 'active',
                'title' => 'Is active',
                'sClass' => 'active-cell-css-class',
            ],
        ],
    ]) ?>

指定DataTable的ID

<?= \nullref\datatable\DataTable::widget([
    'data' => $dataProvider->getModels(),
    'id' => 'your-datatable-id'
]) ?>

添加行链接

    <?= \nullref\datatable\DataTable::widget([
        'columns' => [
            //other columns
            [
                'class' => 'nullref\datatable\LinkColumn',
                'url' => ['/model/delete'],
                'linkOptions' => ['data-confirm' => 'Are you sure you want to delete this item?', 'data-method' => 'post'],
                'label' => 'Delete',
            ],
        ],
    ]) ?>

LinkColumn属性

label - 放置在a标签中的文本；
title - 列的标题；
url - 将传递给Url::to()；
linkOptions - a标签的HTML选项；
queryParams - 添加到url的参数数组，默认为['id']；
render - 自定义渲染js函数。例如

//config ...
    'columns' => [
        //...
        [
            'class' => 'nullref\datatable\LinkColumn',
            'queryParams' => ['some_id'],
            'render' => new JsExpression('function render(data, type, row, meta ){
                return "<a href=\"/custom/url/"+row["some_id"]+"\">View</a>"
            }'),
        ],
    ],
//...

您应该将使用渲染函数的字段传递到queryParams属性。

列筛选

您可以通过将withColumnFilter选项设置为true来添加列筛选功能

默认情况下，它生成一个文本字段作为筛选输入。
在定义列时，可以使用filter参数替换为组合框。它应该是一个关联数组，其中键用于筛选（发送到服务器的值）和单元格渲染值
将filter设置为false可以避免生成筛选

    <?= \nullref\datatable\DataTable::widget([
        'columns' => [
            'id',
            //...
            [
                'data' => 'active',
                'title' => \Yii::t('app', 'Is active'),
                'filter' => ['true' => 'Yes', 'false' => 'No'],
            ],
            [
                'data' => 'last_connection',
                'filter' => false,
            ],
        ],
    ]) ?>
//...

在上面的示例中，发送到服务器的active字段的筛选将包含'true'或'false'，但单元格内容将是'是'或'否'，并且筛选将呈现为组合框。

不会为last_connection属性生成筛选。

高级列定义

可以使用\nullref\datatable\DataTableColumn类自定义单元格渲染或筛选。

    <?= \nullref\datatable\DataTable::widget([
        'columns' => [
            //other columns
            [
                'class' => 'nullref\datatable\DataTableColumn', // can be omitted
                'data' => 'active',
                'renderFiler' => new \yii\web\JsExpression('function() { ' .
                    'return jQuery(\'<input type="checkbox" value="true"/> Active only\'); ' .
                '}'),
                'render' => new \yii\web\JsExpression('function(data, type, row, meta) { ' .
                    'return jQuery(\'<input type="checkbox" value="true" disabled/>\')' .
                    '    .prop(\'checked\', data == \'true\'); ' .
                    '}'),
            ],
        ],
    ]) ?>

样式

DataTables支持几种样式解决方案，包括Bootstrap、jQuery UI、Foundation。

'assetManager' => [
    'bundles' => [
        'nullref\datatable\assets\DataTableAsset' => [
            'styling' => \nullref\datatable\assets\DataTableAsset::STYLING_BOOTSTRAP,
        ]
    ],
],

Bootstrap

Bootstrap表格需要类'table'，因此您需要通过小部件配置使用tableOptions添加'table'类。

<?= \nullref\datatable\DataTable::widget([
    'data' => $dataProvider->getModels(),
    'tableOptions' => [
        'class' => 'table',
    ],
    'columns' => [
        'id',
        'name',
        'email',
    ],
]) ?>

自定义资源

可以使用自定义样式和脚本。

'nullref\datatable\assets\DataTableAsset' => [
    'sourcePath' => '@webroot/js/plugin/datatables/',
    'js' => [
        'jquery.dataTables-1.10-cust.js',
        'DT_bootstrap.js',
    ],
    'css' => [
        'data-table.css',
    ],
    'styling' => false,
]

服务器端处理

要启用服务器端处理，请将DataTableAction添加到控制器中，如下所示

class SomeController extends Controller
{
    public function actions()
    {
        return [
            'datatables' => [
                'class' => 'nullref\datatable\DataTableAction',
                'query' => Model::find(),
            ],
        ];
    }
}

可以使用闭包自定义搜索和排序

public function actions()
{
    return [
         'datatables' => [
             'class' => 'nullref\datatable\DataTableAction',
             'query' => Model::find(),
             'applyOrder' => function($query, $columns, $order) {
                //custom ordering logic
                $orderBy = [];
                foreach ($order as $orderItem) {
                    $orderBy[$columns[$orderItem['column']]['data']] = $orderItem['dir'] == 'asc' ? SORT_ASC : SORT_DESC;
                }
                return $query->orderBy($orderBy);
             },
             'applyFilter' => function($query, $columns, $search) {
                //custom search logic
                $modelClass = $query->modelClass;
                $schema = $modelClass::getTableSchema()->columns;
                foreach ($columns as $column) {
                    if ($column['searchable'] == 'true' && array_key_exists($column['data'], $schema) !== false) {
                        $value = empty($search['value']) ? $column['search']['value'] : $search['value'];
                        $query->orFilterWhere(['like', $column['data'], $value]);
                    }
                }
                return $query;
             },
         ],
    ];
}

如果您需要获取某些关联数据，您可以在applyFilter闭包中从$query调用join或类似方法。

如果需要复杂的查询，您可以在DataTableAction配置中指定query闭包

/** ... */
'query' => function() {
    $calculatedValue = calculate_value_for_query();
    
    return Model::find()->where(['calculated_value' => $calculatedValue]);
},
/** ... */

并添加小部件选项

<?= \nullref\datatable\DataTable::widget([
    /** ... */
    'serverSide' => true,
    'ajax' => '/site/datatables',
]) ?>

额外列

如果您需要在列的渲染函数中使用某些自定义字段，可以传递extraColumns参数。

它在DataTable小部件、列和服务器端操作定义中可用

<?= \nullref\datatable\DataTable::widget([
    /** ... */
    'data' => $dataProvider->getModels(),
    'extraColumns' => ['customPrice'],
    'columns' => [
        [
            'title' => 'Custom column',
            'extraColumns' => ['customField'],
            'render' => new JsExpression($customColumnRender),
        ],
    ],
]) ?>

class SomeController extends Controller
{
    public function actions()
    {
        return [
            'datatables' => [
                'class' => 'nullref\datatable\DataTableAction',
                'query' => Model::find(),
                'extraColumns' => ['customPrice'],
            ],
        ];
    }
}

<?= \nullref\datatable\DataTable::widget([
    /** ... */
    'extraColumns' => ['customPrice'],
]) ?>

nullref / yii2-datatables

维护者

详细信息