README

为 SilverStripe 4 的 GridField 添加拖放功能

需求

• SilverStripe 4.x

安装

仅通过 composer 支持安装

composer require undefinedoffset/sortablegridfield

• 运行 dev/build?flush=all 以重新生成清单
• 在进入 CMS 并首次使用 GridFieldSortableRows 组件时，您可能需要在地址末尾添加 ?flush=all 以强制模板重新生成

用法

要在一个 has_many 关系上启用排序，在您的数据对象上设置一个整数字段。对于 has_many 关系，请确保在 DataObject 上设置 $default_sort 为此新整数字段，以确保在请求关系时应用排序顺序。对于 many_many 关系，您必须将定义关系的 $many_many_extraFields 静态添加到 DataObject 中，有关更多信息，请参阅 SilverStripe 文档。如果您正在使用 many_many 关系，您需要进行自定义获取器来设置此关系在前端上的排序顺序，以下是一个示例。同样，对于 many_many 关系，GridField 的名称必须与关系名称相同，否则将发生错误。对于新的 DataObject，您不需要在您的 DataObject 中手动增加排序顺序，GridFieldSortableRows 将在下次显示网格时自动执行此操作。

public function getMyManyManyRelationship() {
    return $this->getManyManyComponents('MyManyManyRelationship')->sort('SortColumn');
}

要启用 GridField 上的拖放排序，将以下内容添加到您的 GridField 配置中，同时确保将命名空间 UndefinedOffset\SortableGridField\Forms 添加到您的文件中。

//Namespace imports should be added to the top of your file
use UndefinedOffset\SortableGridField\Forms\GridFieldSortableRows;

$myGridConfig->addComponent(new GridFieldSortableRows('{Column to store sort}'));

要将项移动到另一页，将行拖到左侧或右侧的相应移动到页面按钮上，然后释放。

完整代码示例

• has_many 关系
• many_many 关系
• ModelAdmin 实现

事件

GridFieldSortableRows 提供了 4 个 "事件"：onBeforeGridFieldRowSort()、onAfterGridFieldRowSort()、onBeforeGridFieldPageSort() 和 onAfterGridFieldPageSort()。这些 "事件" 会传递一个 DataList 的副本，该 DataList 用于 GridFieldSortableRows，在页面排序的情况下，此列表有一个限制，显示当前页加上/减去一个对象。对于位于 ModelAdmin 后裔的 GridFieldSortableRows，如果这些事件没有所有者 DataObject，则会在 ModelAdmin 上调用这些事件。如果您在 DataObject 的关系上的 GridField 上使用 GridFieldSortableRows，则会在该 DataObject 上调用这些事件。

将记录追加到顶部而不是底部

默认情况下，GridFieldSortableRows 将记录追加到列表底部以提高大数据集的性能，但是您可以通过在您的 GridFieldSortableRows 实例上调用 setAppendToTop(true) 来将新记录追加到顶部。

//Namespace imports should be added to the top of your file
use UndefinedOffset\SortableGridField\Forms\GridFieldSortableRows;

$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
$sortable->setAppendToTop(true);

处理版本化记录

默认情况下，GridFieldSortableRows 不会更新版本化的其他阶段以外的基阶段。但是，您可以通过调用 setUpdateVersionedStage() 并传递要更新的阶段名称以及基阶段名称来启用此功能。例如，传递 "Live" 将在发生任何排序时更新 "Live" 阶段。

//Namespace imports should be added to the top of your file
use UndefinedOffset\SortableGridField\Forms\GridFieldSortableRows;

$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
$sortable->setUpdateVersionedStage('Live');

覆盖默认关系名称

默认情况下，关系名称来自 GridField 的名称，但是您可以调用 setCustomRelationName() 并传入关系的名称来覆盖此查找。这允许您在同一个表单上有多个 GridFields 与相同的 many_many 列进行交互，可能略有不同的过滤方式。

//Namespace imports should be added to the top of your file
use UndefinedOffset\SortableGridField\Forms\GridFieldSortableRows;

$myGridConfig->addComponent($sortable = new GridFieldSortableRows('SortOrder'));
$sortable->setCustomRelationName('MyRelationship');

报告问题

在报告问题时，请确保指定您正在使用的 SilverStripe 版本，例如 3.0.5、3.1beta3、3.0-master 等。同时，请确保包含您收到的任何 JavaScript 或 PHP 错误，对于 PHP 错误，请确保包含完整的堆栈跟踪。此外，请包括您的实现代码（设置网格字段的地方）以及您如何产生此问题。您可能还被要求提供一些类以帮助重现问题。坚持问题，记住您看到的是问题而不是模块的维护者，因此可能需要很多问题来找到解决方案或答案。

注意

• 当与 GridFieldManyRelationHandler 一起使用时，请确保在例如 GridFieldManyRelationHandler 之前将 GridFieldSortableRows 添加到您的配置中。

//Namespace imports should be added to the top of your file
use UndefinedOffset\SortableGridField\Forms\GridFieldSortableRows;

$config->addComponent(new GridFieldSortableRows('SortOrder'), 'GridFieldManyRelationHandler');

贡献

翻译

自然语言字符串的翻译通过第三方翻译界面 transifex.com 进行管理。新添加的字符串将定期上传到那里进行翻译，任何新的翻译都将合并回项目源代码。

请使用 https://www.transifex.com/projects/p/silverstripe-sortablegridfield 来贡献翻译，而不是发送包含 YAML 文件的拉取请求。