README

因为有时在没有复杂 JavaScript 处理的情况下构建简单的后台办公系统很方便，Laravel Bootstrap Table List 提供了一种基于模型的、高度可定制的 PHP 表格列表生成方法，只需在视图中简单渲染表格 HTML，并通过代码侧配置。

⚠️⚠️⚠️ 此包已被替换为 https://github.com/Okipa/laravel-table。 ⚠️⚠️⚠️
⚠️⚠️⚠️ 仅合并错误修复。请考虑迁移到新包。 ⚠️⚠️⚠️

使用前

此表格列表生成器的 V2 版本已预配置为针对 Bootstrap 4 和 Fontawesome 5。
然而，此包配置深度，可以轻松设置为 Bootstrap 3 和其他版本的 FA 或其他图标库（或根本不使用图标）。
如果配置没有提供足够的可能性来满足您的定制需求，您绝对应该在项目中发布模板并自定义它们。

注意
如果有人愿意给我一个针对 bootstrap 3 的有效配置，我会将其包含在说明书中。这可能对一些开发者感兴趣。
无论如何，此包预配置的 bootstrap 3 版本已存在（功能较少）: 请检查 v1。

安装

• 使用 composer 安装包

composer require okipa/laravel-bootstrap-table-list:^2.0

• Laravel 5.5+ 使用包自动发现，因此不需要您手动添加 ServiceProvider。如果您不使用自动发现或使用 Laravel 5.4- 版本，请在您的 app/Providers/AppServiceProvider.php 中的 register() 方法中添加包服务提供者。

// laravel bootstrap table list
// https://github.com/Okipa/laravel-bootstrap-table-list
$this->app->register(Okipa\LaravelBootstrapTableList\TableListServiceProvider::class);

• 从 [path/to/composer/vendor]/okipa/laravel-bootstrap-table-list/styles 目录加载包的 CSS 或 SASS 文件到您的项目中。

包使用

基本用法

在您的控制器中，只需像以下示例那样调用包以生成您的表格列表

// we instantiate a table list in the news controller
$table = app(TableList::class)
    ->setModel(News::class)
    ->setRoutes([
        'index' => ['alias' => 'news.index', 'parameters' => []],
    ]);
// we add some columns to the table list
$table->addColumn('title')
    ->isSortable()
    ->isSearchable()
    ->useForDestroyConfirmation();

然后，将您的 $table 对象发送到您的视图中并渲染表格列表

{{ $table }}

就是这样！

注意

• 请求：无需将请求传递给 TableList：它系统性地使用由 request() 辅助函数提供的当前请求来获取要显示的行数以及搜索、排序或分页数据。但是，如果您需要将特定请求传递给 TableList，您可以使用 setRequest() 方法。
• 列标题：默认情况下，列标题采用以下值：trans('validation.attributes.[attribute])。您可以使用 setTitle() 方法设置自定义标题，尤其是在列与表属性无关时。

高级用法

如果您需要将表格列表用于更高级的应用，例如多语言项目，以下是在控制器中可以执行操作的示例

// create your tablelist instance
$table = app(TableList::class)
    // set the model namespace
    ->setModel(News::class)
    // set a custom request to the table list rather than the request() one.
    ->setRequest($request)
    // set the route that will be targetted when the create / edit / delete button will be hit.
    ->setRoutes([
        'index'      => ['alias' => 'news.index', 'parameters' => []],
        'create'     => ['alias' => 'news.create', 'parameters' => []],
        'edit'       => ['alias' => 'news.edit', 'parameters' => []],
        'destroy'    => ['alias' => 'news.destroy', 'parameters' => []],
    ])
    // set the default number of rows to show in your table list.
    ->setRowsNumber(50)
    // show the rows number selector that will enable you to choose the number of rows to show.
    ->enableRowsNumberSelector()
    // add some query instructions for the special use cases
    ->addQueryInstructions(function ($query) use ($category_id) {
        // some examples of what you can do
        $query->select('news.*');
        // add a constraint
        $query->where('category_id', $category_id);
        // get value stored in a json field
        $query->addSelect('news.json_field->>json_attribute as json_attribute');
        // get a formatted value form a pivot table
        $query->selectRaw('count(comments.id) as comments_count');
        $query->leftJoin('news_commment', 'news_commment.news_id', '=', 'news.id');
        $query->leftJoin('comments', 'comments.id', '=', 'news_commment.comment_id');
        $query->groupBy('comments.id');
        // alias a value to make it available from the column model
        $query->addSelect('users.name as author');
        $query->join('users', 'users.id', '=', 'news.author_id');
    })
    // display some lines as disabled
    ->disableLines(function($model){
        return $model->id === 1 || $model->id === 2;
    }, ['disabled', 'bg-secondary'])
    // display some line as highlighted
    ->highlightLines(function($model){
        return $model->id === 3;
    }, ['highlighted', 'bg-success']);
// you can now join some columns to your tablelist.
// display the news image from a custom HTML element.
$table->addColumn('image')
    ->isCustomHtmlElement(function ($entity, $column) {
        return $entity->{$column->attribute})
            ? '<img src="' . $entity->{$column->attribute}) . '" alt="' .  $entity->title . '">'
            : null;
    });
// display the news title that is contained in the news table and use this field in the destroy confirmation modal.
// this field will also be searchable in the search field.
$table->addColumn('title')
    ->isSortable()
    ->isSearchable()
    ->useForDestroyConfirmation();
// display an abreviated content from a text with the number of caracters you want.
$table->addColumn('content')
    ->setStringLimit(30);
// display a value from a sql alias
// in this case, you will target the `users` table and the `author` field, and make this sortable and searchable.
// this way, you tell the tablelist to manipulate the `name` attribute in the sql queries but to display the aliased `author` model attribute.
$table->addColumn('author')
    ->setCustomTable('users', 'name')
    ->isSortable()
    ->isSearchable();
// display the category with a custom column title, as a button, prefixed with an icon and with a value contained in config.
$table->addColumn('category_id')
    ->setTitle('Category custom name')
    ->setIcon('your-icon')
    ->isButton(['btn', 'btn-sm', 'btn-outline-primary'])
    ->isCustomValue(function ($entity, $column) {
        return config('news.category.' . $entity->{$column->attribute});
    });
// display a button to preview the news
$table->addColumn()
    ->isLink(function($entity, $column){
        return route('news.show', ['id' => $entity->id]);
    })
    ->isButton(['btn', 'btn-sm', 'btn-primary']);
// display the formatted release date of the news and choose to sort the list by this field by default.
$table->addColumn('released_at')
    ->isSortable()
    ->sortByDefault('desc')
    ->setColumnDateTimeFormat('d/m/Y H:i:s');

API

TableList 公共方法

public function setModel(string $tableModel): \Okipa\LaravelBootstrapTableList\TableList

设置用于生成表格列表的模型（必需）。

public function setRequest(Request $request): \Okipa\LaravelBootstrapTableList\TableList

设置用于生成表格列表的请求（必需）。

public function setRoutes(array $routes): \Okipa\LaravelBootstrapTableList\TableList

设置用于生成表格列表的路线（必需）

• 每个路线都将使用行实体 ID 生成。给定的额外参数将被添加到路线生成中。
• 必须定义 index 路由，并且必须使用它来显示包含表格列表的页面。
• 还可以定义以下路线
  • create：必须用于重定向到实体创建页面。如果定义，则在表格列表下方显示一个 创建 按钮。
  • edit：必须用于重定向到实体编辑页面。如果定义，则在表格列表的每行上显示一个 编辑 图标。
  • destroy：必须用于删除表格列表行。如果定义，则在表格列表的每行上显示一个 删除 图标。
  • 每个路线必须以下结构定义

'index' => [
    'alias' => 'news.index',
    'parameters' => [
        // set your extra parameters here or let the array empty
    ]
]

public function setRowsNumber(int $owsNumber): TableList

为表格列表设置自定义行数（可选）。

public function enableRowsNumberSelector(): TableList

启用表格列表中的行数选择（可选）

• 调用此方法将显示一个行数输入框，允许用户选择要显示的行数。

public function addQueryInstructions(Closure $queryClosure): TableList

设置在生成表格列表期间使用的查询闭包（可选）。
例如，您可以在其中定义您的联接表。
闭包允许您操作以下属性：$query`。

public function disableLines(Closure $disableLinesClosure, array $lineClass = []): TableList

设置在生成表格列表期间执行的禁用行闭包（可选）。
可选的第二个参数允许您设置应用于禁用行的类。
默认情况下，应用 config('tablelist.value.disabled_line.class') 配置值。
例如，您可以禁用当前登录用户，以防止他在表格列表中被编辑或删除。
闭包允许您操作以下属性：$model。

public function highlightLines(Closure $highlightLinesClosure, array $lineClass = []): TableList

设置在生成表格列表期间将执行的突出显示行闭包（可选）。
可选的第二个参数允许您设置应用于突出显示行的类。
默认情况下，应用 config('tablelist.value.highlighted_line.class') 配置值。
闭包允许您操作以下属性：$model。

public function addColumn(string $attribute = null) : TableList

添加将在表格列表中显示的列（必需）

• 必须向表格列表添加至少一列。
• 如果需要显示HTML元素，则可以不指定属性创建列。

TableListColumn 公共方法

public function setTitle(string $title): TableListColumn

设置列标题（可选）。

public function sortByDefault(string $direction = 'asc'): TableListColumn

设置默认排序列（必需）。

public function useForDestroyConfirmation(): TableListColumn

将列属性用于生成销毁确认消息（必需）

• 如果设置了销毁路由，则至少必须选择一个列进行销毁确认。
• 此方法只能调用一次。

public function isSortable(): TableListColumn

使列可排序（可选）。

public function isSearchable(): TableListColumn

使列可搜索（可选）。

public function setCustomTable(string $customColumnTable, string $customColumnTableRealAttribute = null): TableListColumn

为列属性定义自定义相关表（可选）。
如果定义的列作为可搜索的，并且列属性不直接属于表格列表模型表，则定义自定义相关表成为强制性的。自定义实际属性将仅用于SQL请求，并且如果定义的列属性不直接存在于定义的自定义表中，也将是必需的。

示例

$table = app(TableList::class)->setRoutes($routes)
    ->setModel(Company::class)
    ->addQueryInstructions(function($query) {
        $query->select('companies.*');
        $query->addSelect('users.name as owner');
        $query->join('users', 'users.id', '=', 'companies.owner_id');
    });
// Here, you target the `owner` attribute, which is an alias produced in the `addSelect` bellow, and which will be attached to the `Company` object.
// Displaying and sorting this alias attribute wouldn't cause any problem but here, we want to authorize the search by owner.
// As this attribute does not really exist in the users table, you have to precise which real field to use for the search sql request : the `name` attribute.
$table->addColumn('owner')
    ->setCustomTable('users', 'name')
    ->isSearchable();

public function setColumnDateTimeFormat(string $columnDateFormat): TableListColumn

为日期时间、日期或时间属性设置格式（可选）。
内部使用 Carbon::parse($value)->format($format) 方法。

public function isButton(array $buttonClass = []): TableListColumn

设置列按钮类（可选）。
将属性包装在按钮中。

public function setIcon(string $icon, $showWithNoValue = false): TableListColumn

将图标设置为在值之前显示（可选）。

public function setStringLimit(int $stringLimit): TableListColumn

设置字符串值显示限制（可选）。
当达到限制时显示"..."...ravel-bootstrap-table-list/src/Traits/RoutesValidationChecks.php

public function isLink($url = null): TableListColumn

设置链接URL。
您可以将链接声明为字符串或闭包，这将允许您操作以下属性：$entity, $column。
如果没有声明URL，它将使用列值设置。

public function isCustomValue(Closure $customValueClosure): TableListColumn

在方法闭包中设置自定义值（可选）。
闭包允许您操作以下属性：$entity, $column。

public function isCustomHtmlElement(Closure $customHtmlEltClosure): TableListColumn

在方法闭包中设置要渲染的HTML元素（可选）。
闭包允许您操作以下属性：$entity, $column。

配置

要个性化包配置，您必须首先使用以下脚本发布它

php artisan vendor:publish --tag=tablelist::config

然后，打开已发布的包配置文件（config/tablelist.php），通过设置自己的值覆盖默认的表格列表配置。

自定义翻译

您可以通过在项目中发布它们来自定义与表格列表关联的翻译

php artisan vendor:publish --tag=tablelist::translations

一旦发布，您将在您的 resources/lang 目录中找到它们。

自定义模板

在您的项目中发布包blade模板文件

php artisan vendor:publish --tag=tablelist::views

然后，更改您 resources/views/vendor/tablelist 目录中包模板的内容。

测试

composer test

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

贡献者

• Okipa
• ACID-Solutions
• Stephan de Souza

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。