README

重要

此包将不再接收任何更新！您仍然可以使用此包，但请准备好，该项目没有活跃的开发。

此包已被放弃，不建议用于新项目。我们建议使用Yajra的包，它提供了几乎相同的API。

简介

这是一个用于https://datatables.net.cn/的datatables服务器端和客户端的Laravel 4包

一个Laravel 5包正在接近完成。要安装它
    composer require chumper/datatable "dev-develop"
如果您发现任何问题，请在bug tracker中报告！

请注意，如果您想使用Datatable 1.10支持和Laravel 5支持，请尝试我们的最新分支！

如果您从2.1.*或更低版本升级，请确保您已调整您的app.php以使用新的别名

    // aliases array:

    //old
    //'Datatable' => 'Chumper\Datatable\Facades\Datatable',

    //new
    'Datatable' => 'Chumper\Datatable\Facades\DatatableFacade',

已知问题

目前还没有我知道的

待办事项

修复即将到来的错误
代码文档

功能

此包支持

支持集合和查询构建器
易于添加和排序列
包含简单的HTML辅助器
在您的列中使用您自己的函数和演示者
在您自定义定义的列中进行搜索（仅集合！）
为搜索和排序定义您特定的字段
为表格添加自定义javascript值
测试过！（好吧，可能不是完全，但我已经尽力了 :)）

请注意！

此包的集合部分和查询部分之间有一些差异。这些差异是

差异	集合	查询
速度	-	+
自定义字段	+	+
在自定义字段中进行搜索	+	-
按自定义字段排序	+	-
在显示数据之外进行搜索（例如）数据库	-	+

请参阅下面的视频进行详细说明。http://www.youtube.com/watch?v=c9fao_5Jo3Y

请让我知道任何问题或您希望在问题部分中拥有的功能。如果您能提供一个指向问题的测试，我将不胜感激。

安装

此包可在https://packagist.org.cn找到，只需将其添加到您的composer.json中即可

"chumper/datatable": "2.*"

或者，您可以使用composer命令安装它

    composer require chumper/datatable "2.*"

它还提供了一个ServiceProvider用于Laravel4的使用。将以下行添加到app.php中：

    // providers array:
	'Chumper\Datatable\DatatableServiceProvider',

    // aliases array:
    'Datatable' => 'Chumper\Datatable\Facades\DatatableFacade',

然后您可以在Datatable别名下访问它。

要覆盖默认配置选项，您可以发布配置文件。

php artisan config:publish chumper/datatable

现在您可以在app/config/packages/chumper/datatable/config.php中编辑这些选项。

基本用法

您可以使用两种方式使用此插件：在一个路由中或两个路由中。

两个路由

创建两个路由：一个用于向用户传递视图，另一个用于传递datatable数据，例如：

    Route::resource('users', 'UsersController');
    Route::get('api/users', array('as'=>'api.users', 'uses'=>'UsersController@getDatatable'));

您的主要路由将向用户传递一个视图。此视图应包含对您本地副本的引用datatables。在下面的示例中，文件是从datatables/media目录中复制的，并写入public/assets。请注意，脚本必须位于调用Datatable之前。

    <link rel="stylesheet" type="text/css" href="/assets/css/jquery.dataTables.css">
    <script type="text/javascript" src="/assets/js/jquery.js"></script>
    <script type="text/javascript" src="/assets/js/jquery.dataTables.min.js"></script>

    {{ Datatable::table()
    ->addColumn('id','Name')       // these are the column headings to be shown
    ->setUrl(route('api.users'))   // this is the route where data will be retrieved
    ->render() }}

创建一个控制器函数，以便以Datatables可以读取的方式返回数据。

    public function getDatatable()
    {
        return Datatable::collection(User::all(array('id','name')))
        ->showColumns('id', 'name')
        ->searchColumns('name')
        ->orderColumns('id','name')
        ->make();
    }

现在您应该在页面上有一个工作的datatable。

一个路由

在您的路由中，应使用Datatable::shouldHandle方法，该方法将检查插件是否应该处理请求。

    if(Datatable::shouldHandle())
    {
        return Datatable::collection(User::all(array('id','name')))
            ->showColumns('id', 'name')
            ->searchColumns('name')
            ->orderColumns('id','name')
            ->make();
    }

然后插件将查询相同的URL以获取信息。shouldHandle方法仅检查ajax请求和sEcho是否设置。

HTML示例

	Datatable::table()
    ->addColumn('id',Lang::get('user.lastname'))
	->setUrl(URL::to('auth/users/table'))
    ->render();

具有单独的表和脚本

		$table = Datatable::table()
        ->addColumn('Email2','Email', "Test")
        ->noScript();

        // to render the table:
        $table->render()

        // later in the view you can render the javascript:
        $table->script();

这将生成一个具有两列（id，lastname ->您的翻译）的HTML表格，并将设置ajax请求的URL。

注意：此包将不包含datatable.js，这是您的工作要做。原因是例如我使用Basset，每个人都想用自己的方式...

如果您想为表格提供自己的模板，只需以Laravel风格提供视图路径。

	Datatable::table()
        ->addColumn('id',Lang::get('user.lastname'))
    	->setUrl(URL::to('auth/users/table'))
        ->render('views.templates.datatable');

服务器示例

	Datatable::collection(User::all())
    ->showColumns('id')
    ->addColumn('name',function($model)
        {
            return $model->getPresenter()->yourProperty;
        }
    )->make();

这将从集合User::all()生成一个服务器端datatable处理器。它将添加id列到结果中，并添加一个名为name的自定义列。请注意，我们需要传递一个函数作为第二个参数，它将始终调用包含集合的对象。在这种情况下，将是User模型。

现在您也可以访问所有关系，因此对于显示作者关系的书籍模型来说很容易。

	Datatable::collection(User::all())
    ->showColumns('id')
    ->addColumn('name',function($model)
        {
            return $model->author->name;
        }
    )->make();

注意：如果您将数组集合传递给collection方法，函数中将有一个数组，而不是模型。

列的顺序始终由用户定义，并且与用户添加列到Datatable的顺序相同。

查询或集合？

query()和collection()之间存在差异。集合将在执行任何操作（如搜索或排序）之前进行编译，以便它还可以包含您自定义的字段。也就是说，集合方法在性能上不如查询方法，因为在查询数据库之前，搜索和orderBy将处理自定义字段函数。

因此，如果您有大量的条目（100k+），集合的性能将不佳，因为我们需要编译整个条目数以提供准确的数据集。另一方面，查询无法正确地对自定义字段函数执行搜索或orderBy。

TLTR：如果没有自定义字段，则使用query()会更快。如果您有自定义字段但不想在这些字段上提供搜索和/或排序，请使用query()。如果您的数据来自其他地方，则选择集合，只需将其包装到集合中即可。如果您有自定义字段并希望在这些字段上提供搜索和/或排序，则需要使用集合。

请注意，如果您使用query而不是集合，搜索和排序功能之间有显著差异。请参阅以下视频获取更多详细信息。

http://www.youtube.com/watch?v=c9fao_5Jo3Y

可用函数

此包分为两个较小的部分

Datatable::table()
Datatable::collection()
Datatable::query()

第二和第三个用于服务器端，第一个是一个辅助程序，用于生成所需的表格和javascript调用。

集合 & 查询

collection($collection)

将内部引擎设置为集合。为了进一步提高性能，您可以限制列和行的数量，例如：

$users = User::activeOnly()->get('id','name');
Datatable::collection($users)->...

query($query)

这将设置内部引擎为Eloquent查询... 例如：

$users = DB::table('users');
Datatable::query($users)->...

查询引擎比集合引擎快得多，但功能也较少，更多信息请参阅上表。

showColumns(...$columns)

这将添加命名列到结果中。

注意：您需要以您在模型或数组中访问它的格式传递名称。例如：在数据库中：last_name，在模型中 lastname -> showColumns('lastname')

您可以提供您想要的任何数量的名称

searchColumns(..$fields)

将使表格允许仅搜索指定的列。请注意，集合的行为与构建器对象不同。

注意：如果您想使用查询引擎搜索数字列，则也可以传递搜索列如下：

   //mysql
   ->searchColumns(array('id:char:255', 'first_name', 'last_name', 'address', 'email', 'age:char:255'))

   //postgree
   ->searchColumns(array('id:text', 'first_name', 'last_name', 'address', 'email', 'age:text'))

这将在此列搜索时将列转换为给定的类型

orderColumns(..$fields)

将使表格允许仅对指定的列进行排序。请注意，集合的行为与构建器对象不同。

addColumn($name, $function)

将添加一个自定义字段到结果集中，在函数中，您将获得该行的整个模型或数组。例如：

	Datatable::collection(User::all())
    ->addColumn('name',function($model)
        {
            return $model->author->name;
        }
    )->make();

您还可以添加预定义的列，如DateColumn、FunctionColumn或TextColumn。例如：

	$column = new \Chumper\Datatable\Columns\TextColumn('foo', 'bar'); // Will always return the text bar
	//$column = new \Chumper\Datatable\Columns\FunctionColumn('foo', function($model){return $model->bar}); // Will return the bar column
	//$column = new \Chumper\Datatable\Columns\DateColumn('foo', DateColumn::TIME); // Will return the foo date object as toTimeString() representation
	//$column = new \Chumper\Datatable\Columns\DateColumn('foo', DateColumn::CUSTOM, 'd.M.Y H:m:i'); // Will return the foo date object as custom representation

	Datatable::collection(User::all())
    ->addColumn($column)
    ->make();

您还可以通过使用addColumn与showColumns的组合来覆盖由QueryMethod返回的结果。您必须将列名与使用showColumns显示的数据库列名完全一致，以便此操作能够正常工作。

	$column = new \Chumper\Datatable\Columns\FunctionColumn('foo', function ($row) { return strtolower($row->foo); }
	Datatable::query(DB::table('table')->select(array('foo')))
	         ->showColumns('foo')
	         ->addColumn($column)
	         ->orderColumns('foo')
	         ->searchColumns('foo')
	         ->make()

这将允许您使用查询引擎具有可排序和可搜索的列，同时允许您修改数据库列条目的返回值。

例如：将user_id列与其页面列表相关联

	$column = new \Chumper\Datatable\Columns\FunctionColumn('user_id', function ($row) { return link_to('users/'.$row->user_id, $row->username) }
	Datatable::query(DB::table('table')->select(array('user_id', 'username')))
	         ->showColumns('user_id')
	         ->addColumn($column)
	         ->orderColumns('user_id')
	         ->searchColumns('user_id')

请查看具体列以获取更多信息。

setAliasMapping()

将建议Datatable返回与列名映射的数据。因此，而不是

	{
		"aaData":[
			[3,"name","2014-02-02 23:28:14"]
		],
		"sEcho":9,
		"iTotalRecords":2,
		"iTotalDisplayRecords":1
	}

您将得到以下响应

{
	"aaData":[
		{"id":2,"name":"Datatable","created_at":"Sun, Feb 2, 2014 7:17 PM"}
	],
	"sEcho":2,
	"iTotalRecords":2,
	"iTotalDisplayRecords":1
}

make()

这将处理请求的输入数据并提供结果集。

没有此命令则不会返回任何响应。

clearColumns()

这将重置所有列，主要用于测试和调试，对您来说并不是很有用。

如果您没有使用showColumn或addColumn提供任何列，则不会显示任何列。查询或集合中的列不会影响将显示哪个列。

getOrder()

这将返回一个数组，其中包含将要显示的列，主要用于测试和调试，对您来说并不是很有用。

getColumn($name)

根据名称获取列，主要用于测试和调试，对您来说并不真正有用。

特定的QueryEngine方法

setSearchWithAlias()

如果您想在查询引擎中使用别名列，但在搜索时没有返回正确的结果，那么您应该尝试这个标志。例如：

		Datatable::from(DB::table("users")->select(array('firstname', "users.email as email2"))->join('partners','users.partner_id','=','partners.id'))
        ->showColumns('firstname','email2')
        ->setSearchWithAlias()
        ->searchColumns("email2")

在SQL中，不允许在where部分（用于搜索）中存在别名，因此结果将无法正确计数。

使用此标志，您可以在搜索部分（searchColumns中的email2）中启用别名。

请注意，此标志将减慢您的应用程序，因为我们需要获取两次结果来手动计数。

setDistinctCountGroup($value = true)

如果您在传递给Datatable的查询中使用了GROUP BY，则可能会从SQL引擎收到不正确的总数。设置setDistinctCountGroup（这可能在MySQL上仅适用）将确保总数基于您的GROUP BY。

setSearchOperator($value = "LIKE")

使用此方法，您可以为搜索设置运算符，如PostgreSQL上的"ILIKE"（不区分大小写）。

setExactWordSearch

这将建议引擎仅搜索提供的搜索字符串。

特定的CollectionEngine方法

setSearchStrip() & setOrderStrip()

如果您使用搜索功能，则可以建议所有列在搜索此列之前删除任何HTML和PHP标签。

如果返回模型详细信息的链接，但仍然想在此列中提供搜索功能，这可能很有用。

setCaseSensitive($boolean = 'false')

设置搜索方法是否区分大小写，默认为false

表格

noScript()

设置此属性后，表格将不会渲染javascript部分。

您可以通过以下方式手动渲染：

script($view = null)

如果没有提供视图或默认视图，则将渲染javascript，并将传递类名、选项和回调函数。

示例

		$table = Datatable::table()
        ->addColumn('Email2','Email', "Test")
        ->noScript();

        // to render the table:
        $table->render()

        // later in the view you can render the javascript:
        $table->script();

setUrl($url)

将设置用于通过ajax获取内容的URL和选项。

setOptions($name, $value) OR setOptions($array)

将设置单个选项或选项数组的单个选项或数组。

您可以将类似这样的参数传递（'MyOption', 'ValueMyOption'）或参数数组，但Datatable中的某些值是JSON，因此如何传递JSON？使用另一个数组，如下所示：setOptions(array("MyOption"=> array('MyAnotherOption'=> 'MyAnotherValue', 'MyAnotherOption2'=> 'MyAnotherValue2')));

//GENERATE

jQuery(.Myclass).DataTable({
    MyOption: {
        MyAnotherOption: MyAnotherValue,
        MyAnotherOption2: MyAnotherValue2,
    }
});

建议您查看vendor/Chumper/datatable/src/views中的这两个文件javascript.blade.php && template.blade.php。您将了解所有逻辑，并了解为什么传递参数为数组很重要（json_encode和其他内容）。

setCallbacks($name, $value) OR setCallbacks($array)

将设置单个回调函数或回调函数数组的单个选项或数组。

    ->setCallbacks(
        'fnServerParams', 'function ( aoData ) {
            aoData.push( { "name": "more_data", "value": "my_value" } );
        }'
    )

addColumn($name)

将为表格添加一列，其中名称将显示在表头中。因此，您可以为要显示的字符串提供。

如果您想使用服务器端表的别名映射功能，则需要添加一个类似这样的数组

Datatable::table()
    ->addColumn(array(
        'id'            => 'ID',
        'name'          => 'Name',
        'created_at'    => 'Erstellt'
        ))
	->render();

请注意，将关联数组传递给addColumn函数将自动在表上启用别名功能

setAliasMapping(boolean)

在此处，您可以显式设置表是否应该有别名。

countColumns()

这将返回稍后要渲染的列数。主要用于测试和调试。

getData()

将返回将作为数组渲染到表格中的数据。

getOptions()

获取所有选项作为一个数组。

render($view = template.blade)

渲染表格。您可以通过传递视图名称来自定义此功能。请参阅包内的模板，以获取有关如何将数据传递到视图的更多信息。

setData($data)

期望一个数组的数组，并在表格显示时渲染此数据。

setCustomValues($name, $value) OR setCustomValues($array)

将设置单个自定义值或一组自定义值，这些值将传递到视图中。您可以在自定义视图文件中访问这些值。例如，如果您想点击表格中的任何一行以转到记录（记录ID位于表格的第一列）

在调用视图中

{{ DataTable::table()
    ->addColumn($columns)
    ->setUrl($ajaxRouteToTableData)
    ->setCustomValues('table-url', $pathToTableDataLinks)
    ->render('my.datatable.template') }}

在数据表视图中（例如，'my.datatable.template')

    @if (isset($values['table-url']))
        $('.{{$class}}').hover(function() {
            $(this).css('cursor', 'pointer');
        });
        $('.{{$class}}').on('click', 'tbody tr', function(e) {
            $id = e.currentTarget.children[0].innerHTML;
            $url = e.currentTarget.baseURI;
            document.location.href = "{{ $values['table-url'] }}/" + $id;
        });
    @endif

setOrder(array $order)

定义数据表在首次加载时按顺序排序。

{{ DataTable::table()
    ->addColumn('ID', 'First Name', 'Last Name')
    ->setUrl($ajaxRouteToTableData)
    ->setOrder(array(2=>'asc', 1=>'asc')) // sort by last name then first name
    ->render('my.datatable.template') }}

附加功能

一些附加功能，使用Datatables API。

表格工具

要使用TableTools，您需要在项目中添加一些文件（https://datatables.net.cn/extensions/tabletools/），如果您需要帮助，请下载数据表的包，并在扩展文件夹中转到/tabletools，研究示例。之后，所有文件都包含在内，不要忘记传递如下参数

//In view:

{{
    Datatable::table()
        ->addColumn('your columns here separated by comma')
        ->setUrl('your URL for server side')
        ->setOptions(
            array(
                'dom' =>"T<'clear'>lfrtip",
                'tableTools' => array(
                    "sSwfPath" => "your/path/to/swf/copy_csv_cls_pdf.swf",
                    "aButtons" => array("copy", "pdf", "xls")
                )
            )
        )
}}

如果您想获取一些属性，如“我点击了哪一行？”，请参阅javascript.blade.php中的变量 $values。

贡献者

jgoux 帮助在数据库中搜索数字列
jijoel 帮助与回调选项和文档

变更日志

2.0.0:
- 分离查询和收集引擎
- 添加单列搜索
- 代码清理

应用

https://github.com/hillelcoren/invoice-ninja（由Hillel Coren创建）

许可

此包受MIT许可证的许可

chumper / datatable

维护者

详细信息