README

轻松将看板板页面添加到您的 Filament 面板。

安装

您可以通过 composer 安装此包

composer require mokhosh/filament-kanban

发布资产以正确显示样式

php artisan filament-kanban:install

开始之前

重要

您应该有一些具有 status 列的 Model。此列在数据库中可以命名为 status 或其他任何名称。

我还假设您的模型中有一个 title 列，但您可以使用 name 或任何其他列来表示标题。

我建议您创建一个基于字符串的 Enum 来定义您的状态。

您可以使用我们的 IsKanbanStatus 特性，这样您就可以通过在枚举上使用 statuses 方法来轻松地转换您的枚举案例，以用于看板板。

use Mokhosh\FilamentKanban\Concerns\IsKanbanStatus;

enum UserStatus: string
{
    use IsKanbanStatus;

    case User = 'User';
    case Admin = 'Admin';
}

我建议您将您的 Model 上的 status 属性强制转换为您创建的枚举。

提示

我还建议您在 Model 上使用 Spatie Eloquent Sortable 包，我们将神奇地将排序能力添加到您的看板板上。

用法

您可以使用以下 artisan 命令创建一个名为 UsersKanbanBoard 的新看板板

php artisan make:kanban UsersKanbanBoard

这为您的看板板提供了一个良好的起点。您可以根据自己的喜好定制看板板。

您应该覆盖 model 属性，这样我们就可以加载数据。

protected static string $model = User::class;

您还应该覆盖 statusEnum 属性，它定义了您的状态。

protected static string $statusEnum = UserStatus::class;

升级指南

如果您在应用程序上使用的是 1.x 版本，并且想要升级到 2.x 版本，以下是您的清单

您需要覆盖 $model 和 $statusEnum，如最后一部分中所述
如果您已发布了 kanban-record.blade.php 视图，您可以使用 $record 作为 Model 实例而不是数组。
如果您只是覆盖 KanbanBoard 方法以执行默认行为，现在可以安全地删除它们。如果您没有特殊要求，您应该能够通过覆盖 0 个方法来完成任务 🥳

高级用法

您可以通过覆盖 records 方法来自定义您想要在板上显示的记录或项目的检索方式。

protected function records(): Collection
{
    return User::where('role', 'admin')->get();
}

如果您不想为您的状态定义一个 Enum，或者您有特殊的检索状态逻辑，您可以覆盖 statuses 方法

protected function statuses(): Collection
{
     return [
         ['id' => 'user', 'title' => 'User'],
         ['id' => 'admin', 'title' => 'Admin'],
     ];
}

您还可以覆盖这些方法来更改记录拖放时的板的行为

onStatusChanged 定义了记录在状态之间移动时会发生什么。
onSortChanged 定义了记录在相同状态内移动时会发生什么。

public function onStatusChanged(int $recordId, string $status, array $fromOrderedIds, array $toOrderedIds): void
{
    User::find($recordId)->update(['status' => $status]);
    User::setNewOrder($toOrderedIds);
}

public function onSortChanged(int $recordId, string $status, array $orderedIds): void
{
    User::setNewOrder($orderedIds);
}

自定义状态枚举

如果您将 IsKanbanStatus 添加到您的状态 Enum 中，此特性将为您的枚举添加一个静态 statuses() 方法，该方法将按适当格式返回枚举中定义的状态。

如果您不希望枚举的所有情况都出现在板上，您可以覆盖此方法并返回一个子集

public static function kanbanCases(): array
{
    return [
        static::CaseOne,
        static::CaseThree,
    ];
}

IsKanbanStatus 使用您的情况的 value 作为状态标题。您还可以自定义标题的检索方式

public function getTitle(): string
{
    return __($this->label());
}

编辑模式

禁用模式

编辑模式默认启用，您可以通过点击记录来显示它。

如果您需要禁用编辑模态，请覆盖此属性

public bool $disableEditModal = false;

编辑模态表单模式

您可以通过覆盖此方法来定义编辑模态表单模式

protected function getEditModalFormSchema(null|int $recordId): array
{
    return [
        TextInput::make('title'),
    ];
}

如您所见，您可以访问正在编辑的记录的 id，这在构建您的模式时可能很有用。

自定义编辑表单提交动作

您可以通过覆盖此方法来定义编辑表单提交时发生的情况

protected function editRecord($recordId, array $data, array $state): void
{
    Model::find($recordId)->update([
        'phone' => $data['phone']
    ]);
}

data 数组包含表单数据，而 state 数组包含完整记录数据。

自定义模态的外观

您可以根据需要自定义模态的标题、大小和保存和取消按钮的标签，或者使用 Filament 的滑动覆盖而不是模态

protected string $editModalTitle = 'Edit Record';

protected string $editModalWidth = '2xl';

protected string $editModalSaveButtonLabel = 'Save';

protected string $editModalCancelButtonLabel = 'Cancel';

protected bool $editModalSlideOver = true;

自定义

更改导航图标

protected static ?string $navigationIcon = 'heroicon-o-document-text';

更改用作标题的模型属性

protected static string $recordTitleAttribute = 'title';

更改用作状态的模型属性

protected static string $recordStatusAttribute = 'status';

自定义视图

您可以使用此 artisan 命令发布视图

php artisan vendor:publish --tag="filament-kanban-views"

建议您删除不打算自定义的文件，并保留您想要更改的文件。这样您将获得任何可能的未来视图更新。

上述方法将替换应用程序中所有看板的所有视图。

或者，您可能想更改其中一块的视图。您可以通过覆盖以下属性来覆盖每个视图

protected static string $view = 'filament-kanban::kanban-board';

protected static string $headerView = 'filament-kanban::kanban-header';

protected static string $recordView = 'filament-kanban::kanban-record';

protected static string $statusView = 'filament-kanban::kanban-status';

protected static string $scriptsView = 'filament-kanban::kanban-scripts';

闪烁最近更新的记录

当记录刚刚更新时，您会得到一些视觉反馈。

如果您还使用 Spatie Eloquent Sortable，您可能会同时闪烁所有记录。这是因为 Eloquent Sortable 在排序更改时更新所有模型的 order_column。为了解决这个问题，发布它们的配置并将 ignore_timestamps 设置为 true。

视频教程

您是视觉学习者吗？我创建了一些 YouTube 视频来帮助您开始使用此软件包

警告

这些视频是用软件包的 1.x 版本录制的。现在使用软件包要简单得多，并且需要您编写的代码更少。

希望 2.x 版本足够简单，无需视频，但您仍然可以从中学习一些东西。

演示和示例

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG

贡献

有关详细信息，请参阅 CONTRIBUTING

安全漏洞

请查阅我们的安全策略了解如何报告安全漏洞。

TODO

删除已弃用的最近更新特性
为 recordClick 停止传递记录到视图
使用 filament 动作进行编辑模态

鸣谢

Mo Khosh
所有贡献者
此软件包的原始想法和结构大量借鉴自 David Vincent 的 filament-kanban-board

许可协议

MIT 许可协议 (MIT)。有关更多信息，请参阅许可文件

mokhosh / filament-kanban

维护者

详细信息