README

简介

将 Tabulator 集成到 SilverStripe。因为 GridField 并非总是适用。这在前端和 CMS 中都适用。

此模块用在我的替代管理模块中，并在一个使用相当复杂的前端可编辑表格的生产项目中使用。这意味着我可能已经遇到了你可能在你的项目中遇到的大部分问题 :-)

它提供了许多开箱即用的功能

行内编辑
批量操作
表格或编辑表单中的自定义操作
通过拖放移动行
筛选、排序、分页...

配置详细字段

在编辑或查看记录时，默认使用 getCMSFields。这不一定总是理想的（字段可能有 gridfields 或依赖于某些实现）。要返回一个自定义列表，可以使用 tabulatorCMSFields。为了帮助你获得一组合理的字段，这里提供了 TabulatorScaffolder 类来帮助。

public function tabulatorCMSFields(array $_params = [])
{
    $fields = TabulatorScaffolder::scaffoldFormFields($this, [
        // Don't allow has_many/many_many relationship editing before the record is first saved
        'includeRelations' => ($this->ID > 0),
        'tabbed' => true,
        'ajaxSafe' => true
    ]);
    $this->extend('updateCMSFields', $fields);
    return $fields;
}

你可能愿意或不愿意触发 updateCMSFields。好处是它将帮助那些不知道 tabulator 的扩展。坏处是它可能会破坏，因为它最有可能在每个地方都期望有 gridfields。

配置列

此模块根据摘要和可搜索字段构建了一些默认列。

对于更高级的用法，请定义一个返回所有列的 tabulatorColumns 方法，根据 Tabulator 定义。

JS 初始化

默认情况下，Tabulator 将通过由 formidable elements 提供的自定义元素进行初始化

选项

您可以使用 setOption 调用来配置任何可用选项。

动态回调

对于动态回调，您可以使用全局命名空间中可用的函数指定一个命名空间函数，以避免作用域污染。这些回调与 formidable elements 的相同，意味着它们具有形式 {"__fn" : "app.callback"}。

在 SSTabulator 下提供了一些默认回调。

例如

$grid->registerJsNamespace('MyApp');
$grid->addColumn('MyCell', 'My Cell', [
    'headerSort' => false,
    'editable' => '_editable',
    'editor' => ["__fn" => 'SSTabulator.externalEditor'],
    'mutatorEdit' => ["__fn" => 'MyApp.mutateValue'],
]);

使用向导

该类包含一些“向导”函数，可以以一致的方式设置一组选项。请检查源代码以获取更多信息。

主题化

该类默认使用 Bootstrap 5 主题，并添加了一些自定义改进，使其更加“silverstripy”。

您可以使用 theme 配置选项选择您的主题，或将它设置为 null 以包含您自己的主题。禁用 bootstrap5 主题也将禁用自定义 CSS。

编辑

您可以使任何列可编辑。只需调用 makeColumnEditable 并传递相关的编辑器详细信息即可。

当失去焦点时，如果设置了 editUrl 端点，它将触发一个 ajaxEdit 请求。

只读

默认情况下，表格期望记录可编辑。您可以使用 setViewOnly 禁用添加和编辑按钮，并使详细表单只读。

关系

默认情况下，表格不编辑关系（无链接/解除链接）。

按钮

行按钮

您可以使用 makeButton 函数创建按钮列。在底层，它将使用 buttonFormatter 和 buttonHandler。

您还可以通过将 ajax 参数设置为 true/1 或字符串来启用 Ajax 模式。使用 true/1 将使用内置的 Ajax 处理程序，或者您可以选择选择任何全局函数名称

$btn = $grid->makeButton("myaction/{ID}", "", "Confirm");
$btn['width'] = '100';
$btn['tooltip'] = '';
$btn['formatterParams']['classes'] = "btn btn-primary d-block";
$btn['formatterParams']['ajax'] = "*MyApp.handleAjax";
$grid->addButtonFromArray("MyBtn", $btn);

您自定义的处理程序看起来就像这样，并返回一个承诺

var handleAjax = function (e, cell, btn, formData) {
    // do something here
    // return promise
};

按钮默认情况下不是响应式的。如果需要，只需取消设置响应式键即可

unset($btn['responsive']);

CMS 中的行操作

为了将操作转发到记录（首选方式），请为您记录添加一个 tabulatorRowActions。

public function tabulatorRowActions()
{
    return [
        'doTabulatorAction' => [
            'title' => 'Do This',
            'icon' => 'favorite_border',
            'ajax' => true, // submitted through xhr
            'reload' => true, // reload table data after action
            'refresh' => true, // refresh the whole page after action
        ],
    ];
}

这将调用您的记录上的 doTabulatorAction 方法。

工具

Tabulator 支持可添加到网格上方的 "工具"。例如，添加新按钮就是这样的。所有工具都继承自 AbstractTabulatorTool 类。

工具可以通过在 TabulatorGrid 字段上调用 /tools/$ID 来处理操作。

通用工具

由于为每个工具创建一个类很麻烦，您可以这样做

$grid->addToolEnd(new GenericTabulatorTool('my_unique_action', 'Do something unique', function () {
    return $this->doSomethingUnique();
}));

批量操作

您可以使项目可选并传递一个操作数组。操作必须扩展 AbstractBulkAction 类。

$grid->wizardSelectable([
    new BulkDeleteAction()
]);

请参阅 /src/BulkActions 以获取操作的全列表。这些大致相当于您在 BulkManager 模块中可以找到的操作。

通用批量操作

由于为每个简单操作创建一个类很麻烦，您可以这样做

$grid->wizardSelectable([
    new GenericBulkAction('bulk_cancel', 'Cancel', function (MyRecord $record, $grid) {
        return $record->doCancel();
    }),
    new GenericBulkAction('bulk_approve', 'Approve', function (MyRecord $record, $grid) {
        return $record->doApprove();
    }),
]);

监听事件

您可以添加自定义监听器，这些监听器应存在于全局命名空间中。

$grid->addListener('tableBuilt', 'MyApp.onTableBuilt');

数据属性与选项

Tabulator 的一些设置使用数据属性设置。这样做是为了避免将自定义行为与 Tabulator 的内置选项混合。函数名称应该是常规字符串，因为它们被 json 编码并由我们的自定义代码解析。

通知

有一个内置的 notify 辅助函数，默认支持多种通知类型。

如果需要，您可以注册一个全局 SSTabulator.notify 函数，该函数将调用默认函数。

一个字段

如果您正在使用 silverstripe-hasonefield，我有一个好消息要告诉您，因为这个模块包括对简单的单字段编辑按钮的基本（目前）支持。只需将 HasOneButtonField 的实例替换为 HasOneTabulatorField 即可！

额外的格式器和辅助工具

SSTabulator.boolGroupHeader：用于根据布尔值分组
SSTabulator.isCellEditable：基于约定的回调，用于检查行是否可编辑

全局搜索

按列搜索并不总是可能或方便。也许您想要一个全局搜索功能。

这真的很简单，只需这样做。它将创建一个顶部的搜索栏，您可以输入任何内容！

   $grid->setGlobalSearch(true);

默认情况下，它将对字符串进行部分匹配。对于大型表格，您可能不希望这样做，以正确使用您的索引。您还可以使用快捷语法进行筛选

您可以使用 setWildcardFields 设置搜索字段。否则，它将默认为 searchableFields。

快速筛选

当启用全局搜索时，您还可以提供自定义的 "快速筛选" 列表。

$grid->setQuickFilters([
        'blacklist' => [
            'label' => 'Blacklisted Companies',
            'callback' => function (&$list) {
                $blacklistedIDS = DB::query('SELECT ID FROM Company WHERE `Status` = \'Blacklisted\'')->column();
                $list = $list->filter('ID', $blacklistedIDS);
            }
        ]
    ]);

模型选项

如果您添加了一个 tabulatorOptions 方法，您可以为 Tabulator 自动配置模型的方式配置。

它可以提供以下键

summaryFields：如果没有提供，则默认使用 summaryFields()
searchableFields：如果没有提供，则默认使用 searchableFields
可排序：是否可排序？（如果有排序字段，默认为true）
rowDelete：在行级别删除（默认为false）
addNew：如果允许则显示添加新条目（默认为true）
export：如果已配置则显示导出（默认为true）
searchAliases：将搜索字段别名为显示的列（例如：当显示标题时使用SearchTitle）

对于自定义列，请使用tabulatorColumns。对于自定义操作，请使用tabulatorRowActions。

从GridFields迁移

如果您正在使用GridFields的项目中，有几种方法可以逐步迁移到Tabulator。一种方法是将Tabulator注入到GridField中，以便所有GridField::create调用都返回一个TabulatorGrid。为了方便起见，Tabulator定义了一个getConfig方法，该方法返回一个空的GridFieldConfig，这样代码就不会崩溃。

另一种方法是使用TabulatorGrid::replaceGridfield方法，该方法尽力用适当的和配置好的TabulatorGrid替换您的GridField实例。

没有GridFieldConfig

TabulatorGrid不使用配置对象的概念。这通常会使架构更复杂，并且不容易处理各个组件和谐共处。相反，TabulatorGrid有一个有偏见的配置系统，尽管它仍然非常灵活，但只适用于预期的用例。

可选依赖项

Last Icon：用于漂亮的图标
Luxon：用于格式化日期

兼容性

4.10+

待办事项

翻译

维护者

LeKoala - thomas@lekoala.be

lekoala / silverstripe-tabulator

维护者

详细信息