README

作者 Sébastien L'haire

一个用于轻松构建表格的Laravel库，它可以与轻量级js构建器交互，并从Eloquent对象关系映射的数据库表中构建数据，也可以用于静态数据。

它使用

• 基于jQuery JavaScript框架的JavaScript表格构建器。
• Moment.js日期工具库。
• Bootstrap 4或5 CSS框架。
• FontAwesome图标

数据会自动分页，可以进行搜索和排序。您还可以轻松添加其他参数来选择数据。演示网站在此处提供。

安装

1. composer require seblhaire/tablebuilder

2. Composer会自动将包与Laravel关联。但您仍然可以显式地将提供者和外观添加到您的config/app.php文件中。

  'providers' => [
    ...
      Seblhaire\TableBuilder\TableBuilderHelperServiceProvider::class,
      ...
    ],
    'aliases' => [
        ...
        "TableBuilderHelper" => Seblhaire\TableBuilder\TableBuilderHelper::class
      ]

1. 发布包（可选）。

$ php artisan vendor:publish

1. 有关JavaScript和样式表的说明，请参阅下一节。

JavaScript和样式表

在网页上，每个JS库和CSS样式表都可以单独链接。如果您选择这种经典方式，请首先下载并安装上述提到的库。然后按照上述说明发布包文件，并在您的模板中放置以下标签

<script type="text/javascript" src="js/vendor/seblhaire/tablebuilder/tablebuilder.js"></script>
<link rel="stylesheet" type="text/css" property="stylesheet" href="css/vendor/seblhaire/tablebuilder/tablebuilder.css"/>

但网站通常使用许多库和样式表，浏览器必须下载许多文件才能正确渲染网站。现代网站包含一个单一的压缩JavaScript文件，该文件连接必要的脚本；样式表也有同样的原则。使用Laravel，您可以使用Laravel Mix来编译文件。

使用NPM包管理器：npm install bootstrap jquery moment @fortawesome/fontawesome-free

然后您的js源文件应该如下所示

global.jQuery = require('jquery');
var $ = global.jQuery;
var jQuery = global.JQuery;
window.$ = $;
window.jQuery = jQuery;
require('bootstrap');
global.moment = require('moment');
require('../../vendor/seblhaire/tablebuilder/resources/js/tablebuilder.js');

对于您的样式表

@import '~bootstrap/scss/bootstrap';
@import "~@fortawesome/fontawesome-free/scss/fontawesome";
@import "~@fortawesome/fontawesome-free/scss/regular";
@import "~@fortawesome/fontawesome-free/scss/solid";
@import "~@fortawesome/fontawesome-free/scss/brands";

@import "../../vendor/seblhaire/tablebuilder/resources/css/tablebuilder";

配置文件

表格构建器库是可定制的。默认值可以在配置文件中更改，或者在通过外观函数传递选项时更改（参见下一节）。如果您想修改默认配置文件，请发布包文件并访问config/tablebuilder.php。

用法

TableBuilder包附带一个简单的外观。

TableBuilderHelper::initTable

初始化一个可以传递给视图的表格对象。

TableBuilderHelper::initTable($objectId, $url, $options)

其中

• $objectId：必须插入表格的<div>标签的id。
• $url：用于加载数据的路由。如果使用静态数据，则设置为空。
• $options：选项数组。
  • 'searchable'：在表格顶部插入搜索字段。默认为true。
  • 'itemsperpage'：每页默认项目数。0表示不进行分页。默认为20。
  • 'pagechoices'：每页项目选择。
  • 'encoding'：数据的编码。默认为'utf8'。
  • 'additionalparams'：传递给查询的静态附加参数。
  • 'paramsFunction'：传递动态附加参数的函数名称，例如表单内容。
  • 'tableClass'：<table>的类：默认为'TableBuilder table table-condensed table-hover table-striped'。
  • 'headersclass'：在表格之前用于搜索输入和分页的 <div> 的类名。默认 'TableBuilderHeads'。
  • 'searchdivclass'：包含搜索输入的 <div> 的类名。默认：'TableBuilderSearch form-group'。
  • 'searchresetbuttondivclass'：包含搜索输入重置按钮的 <div> 的类名。默认：input-group-append。
  • 'searchresetbuttonclass'：搜索输入重置按钮的类名。默认：btn btn-outline-secondary
  • 'eltspageclass'：底部 <div> 的类名。默认：'TableBuilderEltsPage'。
  • 'paginationclass'：包含表格分页的 <div> 的类名。默认：'TableBuilderPagination'。
  • 'pagecontclass'：包含每页元素的 <div> 的类名。默认：'TableBuilderEltPageCont'。
  • 'bottomclass'：包含按钮的底部 <div> 的类名。默认：'TableBuilderBottom'。
  • 'footerclass'：在数据行之后显示的页脚的类名。默认：'TableBuilderFooter'。
  • 'buttonclass'：动作按钮的默认类名。默认：'btn btn-secondary'。
  • 'rowcontextualtrigger'：数据中触发特定行类使用的特殊字段名称。默认：trclass。详细信息见下文。
  • 'ajaximgname'：在表格数据加载时显示的沙漏图标所用的 FontAwesome 类。默认：'far fa-hourglass'。
  • 'uparrow'：在可排序列上显示的向上箭头所用的 FontAwesome 类。默认：'fas fa-arrow-up'。
  • 'downarrow'：在可排序列上显示的向下箭头所用的 FontAwesome 类。默认：'fas fa-arrow-down'。
  • 'leftarrow'：显示左侧分页箭头的 FontAwesome 类。默认：'fas fa-angle-left fa-2x'。
  • 'dblleftarrow'：显示双左分页箭头的 FontAwesome 类。默认：'fas fa-angle-double-left fa-2x'
  • 'rightarrow'：显示右侧分页箭头的 FontAwesome 类。默认：'fas fa-angle-right fa-2x'。
  • 'dblrightarrow'：显示双右分页箭头的 FontAwesome 类。默认：'fas fa-angle-double-right fa-2x'。
  • 'buttondivarrow'：按钮旁边的方块箭头的 FontAwesome 类。默认：'fas fa-level-up-alt fa-2x fa-flip-horizontal buttondivarrow'。
  • 'ajaxerrormsg'：加载错误时显示的文本。文本可以是字符串或翻译键。见下文。
  • 'nodatastr'：从数据库检索不到数据时显示的文本。文本可以是字符串或翻译键。见下文。
  • 'chkheadlabel'：选择列头部（当选中时）显示的文本。文本可以是字符串或翻译键。见下文。
  • 'searchLabel'：搜索输入中显示的文本。文本可以是字符串或翻译键。见下文。
  • 'searchresetlabel'：鼠标悬停在搜索重置按钮上时显示的文本。文本可以是字符串或翻译键。见下文。
  • 'eltLabel'：显示在元素总数旁边的文本。文本可以是字符串或翻译键。见下文。
  • 'eltsParPageLabel'：显示在每页元素选择器旁边的文本。文本可以是字符串或翻译键。见下文。
  • 'buttons'：定义多个选择的参数数组。例如：[['id' => 'toto', 'em' => 'fas fa-search', 'action' => "multiselect",'text' => 'Test multselect'], ['id' => 'toto2', 'em' => 'fas fa-bolt', 'action' => "multiselect2",'text' => 'Test multselect 2']]，其中参数包括以下内容
    • 'id'：按钮的唯一标识符。
    • 'class'：按钮的类，如果与上面的 'buttonclass' 不同
    • 'img'：按钮的图片uri。与 'em' 参数不兼容。
    • 'em'：用于显示按钮图片的 FontAwesome 类。
    • 'action'：处理行数据的函数名称，将对每行选中的行应用。
    • 'text'：按钮标签的文本。动作可以定义如下

  var multiselect = function(data){
      console.log(data);
  }
  

  • 'eltsPerPageChngCallback'：当每页元素改变时必须触发函数的名称。

  var eltspagechanged = function(iNbPages){
    alert(iNbPages + ' selected')
  }
  

  默认为空。
  • 'aftertableload'：必须在数据加载后触发的函数名称。

  var aftertableload = function(tableobject, data){
    console.log(tableobject);
    console.log(data);
  }
  

  默认为空。

总结一下，在您的控制器中插入

$oTable = TableBuilderHelper::initTable('tabtest',  route("tabletest"),  [
    'buttons' => [['id' => 'toto', 'em' => 'fas fa-search', 'action' => "multiselect", 'text' => 'Test multselect']],
    'itemsperpage' => 20,
    'eltsPerPageChngCallback' => 'eltspagechanged',
    'aftertableload' => 'aftertableload'
]);
...
return view('tablebuilder::example', array('oTable' => $oTable));

表格列定义将在下一节中解释。在您的 blade 模板中，在您希望表格出现的位置插入以下内容

{!! $oTable->output() !!}

此指令插入显示表格所需的所有元素。此外，如插入数据库或更改参数之类的操作可能需要刷新表格数据；在您的函数中插入 $oTable->outputReload()

<script type="text/javascript">
    .....
    jQuery('#user, #filter').bind('change', function(){ <?= $oTable->outputReload() ?>});
    ......
</script>    

如果您需要获取表格变量，只需使用 !!{o$Table->tablevar()}!!。

TableBuilderHelper::initColumn

初始化可以添加到表格对象的列对象。

TableBuilderHelper::initColumn($type, $dataBindTo, $options)

• $type：设置列类型为以下类型之一 'data', 'date', 'image', 'link', 'mail', 'numeric', 'status', 'checkbox', 'action'。每种类型将在下一节中描述。
• $dataBindTo：要显示的数据字段。
• $options：根据数据类型的不同，值数组

要插入一个简单的数据列，按以下步骤操作

$datacolumn = TableBuilderHelper::initColumn('data','titre', ['title' => 'Titre', 'sortable' => true]);

然后必须将其附加到表格

$oTable->addColumn($datacolumn);

您也可以使用这种紧凑语法

$oTable->addColumn(TableBuilderHelper::initColumn('data','titre', ['title' => 'Titre', 'sortable' => true]));

数据列（类型 = 'data'）

数据列是默认的、正常的单元格，用于显示数据。选项列表是

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的 CSS 类。默认：null。

日期列（类型 = 'date'）

日期列用于显示日期。在您的数据库中，日期存储为年-月-日时分秒（小时为24小时制），例如：2020-11-12 20:24:58。时间可以省略。此列只是将内部数据库格式转换为人类可读格式。日期转换基于 Moment.js 格式。选项列表是；

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的 CSS 类。默认：null。
• format：在 Moment.js 语法中的日期格式。默认：DD/MM/YYYY HH:mm:ss

图像列（类型 = 'image'）

图像列允许将表格数据转换为图像或字体图标。数据可以是图像的 URI 或字体类。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的CSS类。默认：centercell。
• tag：用于渲染数据的标签。可以是img、em、b或i。默认：em

链接列（类型 = 'link'）

链接列将URL数据转换为可点击的链接，这些链接将在新标签页或窗口中打开。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的 CSS 类。默认：null。
• shorten：在显示时缩短链接。
• maxlength：缩短的最大长度。默认：45。
• target：链接目标属性值。默认：_blank。

邮件列（类型 = 'mail'）

邮件列将电子邮件数据转换为可点击的链接，可以复制到剪贴板或打开您的邮件应用。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的 CSS 类。默认：null。
• copycell：切换单元格复制到剪贴板。如果为false，则链接打开邮件应用。默认：true。
• copytext：鼠标悬停时显示的文本。文本可以是字符串或翻译密钥。默认：tablebuilder::messages.clicktoselect。参见图下。

数字（类型 = 'numeric'）

数字列将数字字段格式化为可读的值。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的 CSS 类。默认：null。
• thousandsep：分隔每个千位组的分隔符。默认：'。
• decimals：要显示的小数位数。默认：0。
• decimalsep：小数分隔符。默认：.。
• currency：要在数字值旁边显示的货币。默认：无值。如果需要货币出现在值之前，则必须设置参数currencyposafter为false。

状态列（类型 = 'status'）

状态列允许根据列值显示图标。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的CSS类。默认：centercell。
• aIcons：用于设置图标的参数数组数组。数组键是可能的列值。例如：["0" => ['class' => 'fas fa-square', 'title' => 'no', 'style' => 'color:red'], "1" => ['class' => 'fas fa-square', 'title' => 'yes', 'style' => 'color:green']]。参数值是
  • class：用于选择Font Awesome图标的类。
  • style：附加样式，例如设置颜色。
  • title：鼠标悬停时显示的文本。

复选框列（类型 = 'checkbox'）

复选框列允许切换二进制值（开/关、真/假、是/否等）。可以触发操作来修改值。

• sortable：列可以排序。默认：false。您可能需要在多个列上排序数据（例如：姓氏和名字）。为此我们有两个参数
  • customAsc 允许设置升序排序的标准。例如：lastname:asc;firstname:asc。如果此参数设置为 null，则排序字段将是 $dataBindTo 的值。
  • customDesc 具有与降序排序相同的功能。例如：lastname:desc;firstname:desc。
• defaultOrder：允许选择表格的默认顺序（每张表一列）。选择 asc 或 desc 以使用此列，否则 null。
• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的CSS类。默认：centercell。
• action：设置值的函数名。函数有一个单独的event参数，它可以访问3个值
  • event.data.elt：访问复选框输入。event.data.elt.prop('checked')为true时复选框被选中，否则为false。
  • event.data.content：提供被点击数据的整行。
  • event.data.index：行号，从0开始。

  var checkboxclick = function(event){
                  console.log(event.data.elt.prop('checked'));
                  console.log(event.data.content);
                  console.log(event.data.index);
  }
  

  • isEnabledCallback：如果为1或true，则操作被禁用。

操作列（类型 = 'action'）

操作列提供一组操作按钮。操作按钮可以在列定义中全局定义，也可以逐行定义（见下一节）

• title：添加到列标题的标签。默认：null。
• completetitle：鼠标悬停在表头时可以显示的更长的标题。默认：null。
• width：列宽度（例如：100px）。默认：null。
• classes：附加到数据单元格的CSS类。默认：TableBuilderActions。
• actions：参数数组数组。例如：[['em' => 'far fa-edit', 'text' => '编辑用户', 'js' => "loaduser"], ['em' => 'fa fa-trash', 'text' => '处理用户', 'js' => "procesuser"]]。如果需要分隔字段组，请插入数组['placeholder' => true]。参数是
  • js：javascript操作名称。参数是当前行数据。操作可以在显示表格的页面的<script>标签中定义如下

  var loaduser = function(data){
      console.log(data);
  }
  var procesuser = function(data){
      alert(data.name); // name is a field in the data you display in your table
  }
  

  • text：鼠标悬停时显示的标题。
  • em：按钮图标的类。

TableBuilderHelper::initDataBuilder

最后一个外观函数提供了一个数据构建器助手，它有助于验证POST数据并构建Eloquent查询，以构建表格中显示的数据。

TableBuilderHelper::initDataBuilder($request, $othervalidationrules)

• $request: 控制器提供的 Illuminate\Http\Request 对象。
• $othervalidationrules: 额外数据的验证规则。默认为 []。

表传递的参数包括

• itemsperpage: 整数值。
• sortBy: 字符串：排序顺序。
• start: 整数，起始项。
• searchTerm: 搜索词。

函数的结果是 Seblhaire\TableBuilder\TableDataBuilder 类的对象。

public function loadTable(Request $request){
        $oTable = TableBuilderHelper::initDataBuilder($request);

此对象有多个方法

$oTable->addMethodToDisplay('actions', function($user){ $actions = [ ['em' => 'far fa-edit', 'text' => '编辑用户', 'js' => "loaduser"],* addLine($aLine): 向表中添加静态数据。 $aLine` 必须是一个键值对数组。

• setQuery($param): 设置用于构建表格数据的对象。 $param 是 Eloquent 模型对象或查询构建器。

  $user = new \App\User;
  //or
  $user = \App\User::where('category', 'admin');
  $oTable->setQuery($user);
  

• setWithTrashed($bval): 启用/禁用 Eloquent withTrashed 方法。
• setFields($columnslist): 设置查询需要从数据库获取的列。 $oTable->setFields('id, number, title');
• setSearchFunction($wherefn): 当搜索字段不为空时设置构建搜索查询的函数

  $search = $oTable->searchTerm();
  $wherefn = function ($query) use ($search){
      if ($search != ''){
          $query->where(function($query) use ($search){
          return $query->where('email', 'like', '%' . $search .'%')
                   ->orWhere('name', 'like', '%' . $search .'%');
          });
      }
  }
  $oTable->setSearchFunction($wherefn);
  

  对于静态数据的表

  $wherefn = function ($data){
      return (strpos($data['code'], $this->searchTerm) !== false) ||
        (strpos($data['country'], $this->searchTerm) !== false);
  }
  $oTable->setSearchFunction($wherefn);
  

• addMethodToDisplay($fieldname, $func): 你可能需要向表中添加不来自数据库的数据。$fieldname 是输出中返回的名称。$func 是一个用于构建内容的函数，表格行结果作为唯一参数。

   $oTable->addMethodToDisplay('addressurl', function($user){
       //return a link to a online map to locate address
       return AddressUrlResolver($user->address);
   })
  

  如果你想给某些行添加类，你可以使用这个方法来添加样式。你的额外列必须具有配置选项 tablebuilder.table.rowcontextualtrigger 的名称。

  $oTable->addMethodToDisplay(config('tablebuilder.table.rowcontextualtrigger'), function($user){
      if ($user->wage > 10000){
          return 'table-danger';
      }
      return '';
  });
  

  此方法显示工资超过 $10,000 的用户行。在最后一个示例中，这里是如何向数据添加操作。

  $oTable->addMethodToDisplay('actions', function($user){
        $actions = [['em' => 'far fa-edit', 'text' => 'Edit user, 'js' =>  "loaduser"]];
        if ( ... ){
              $actions[] = [....];
           }else{
               $actions[] =[ ... ];
           }
           return $actions;
       });   
  

• setFooter($txt): 在表底部添加文本，以总结数据。
• output(): 返回表格结果。
• setTotal($iTotal): 设置总值。
• nblines(): 获取每页的行数。
• start(): 获取起始编号。
• reverseOrder(): 获取反转顺序值。
• sortBy(): 获取排序参数值。
• searchTerm(): 获取搜索词参数。
• total(): 获取行数。
• footer(): 获取页脚值。
• hasFooter(): 检查是否有页脚值。

翻译键

Laravel 在处理过程中非常早地加载配置文件。因此，配置文件不能包含 __('translation.key')。为了解决这个问题，我们制作了一个助手，可以直接打印字符串或将翻译键发送到翻译助手。翻译键可以用字符 # 分隔。例如："#tablebuilder::messages.required#"。原始翻译存储在 vendor/seblhaire/tablebuilder/resources/lang 下。如果您发布包文件，您可以在 resources/lang/vendor/tablebuilder/ 中找到翻译。

请随意将键翻译成您自己的语言，并将其发送给作者或合并请求到 GitHub。

有问题？有贡献？

请随意向作者发送功能请求或合并请求，或者简单地提问。