README

Laravel Filament Flexible Content Blocks

Laravel Filament Flexible Content Blocks 包可以帮助您轻松为任何模型在 Filament 中创建内容，包括预定义块，以及可扩展的 Blade 视图组件。

您可以使用这个具有观点的包来创建基本的 CMS，通过设置自己的页面模型并实现预定义的特质来选择所需的功能，然后快速设置 Filament 资源，通过实现现成的字段。或者，您可以为特定的业务场景向模型添加灵活的内容，例如允许灵活地创建产品描述。每个项目都不同，为了满足不断变化的需求，重点在于构建块而不是类似 CMS 页面的默认实现。

此包的关键目标是

提供一种快速添加内容到模型的方法，通过可重用字段和内容块
快速设置前端，并为每个块提供不同的前端样式
提供完全工作并可扩展的 Blade 视图组件，并带有基本的 Tailwind 样式
允许您根据需求选择所需的字段和块
提供轻松的配置，以覆盖字段、块和图像转换的行为
支持 SEO
支持概览字段，以自定义标题、图片和描述的方式显示内容列表
支持内容翻译
提供一组内容块，以满足大多数通用需求

升级

升级到 v2

由于 spatie-medialibrary v11 的重构，配置文件中的图像转换已更改。请查看升级指南以获取详细信息。

升级到 v1

如果您需要升级到 v1.0.0，则非常重要要仔细阅读升级指南，因为内容块的数据库模式已更改，需要通过命令升级。

安装

您可以通过 composer 安装此包

composer require statikbe/laravel-filament-flexible-content-blocks

您可能需要编辑广泛的配置，因此可以使用以下命令发布配置文件

php artisan vendor:publish --tag="filament-flexible-content-blocks-config"

可选地，您可以使用以下命令发布视图（例如，如果您想调整内容块）

php artisan vendor:publish --tag="filament-flexible-content-blocks-views"

由于您可以将灵活的内容块应用于任何视图，因此我们不提供必需或默认迁移。但是，我们提供两个示例迁移，一个用于可翻译的页面，另一个用于单语言页面。您可以使用这些迁移作为示例来创建自己的迁移。（见待办事项）您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="filament-flexible-content-blocks-migrations"
#first edit the migrations and then run:
php artisan migrate

依赖关系

这是一个具有内置电池的意见包。因此，我们选择了一组依赖关系来构建。以下是选择的一些概述

filament/filament：显然；-
spatie/laravel-medialibrary & filament/spatie-laravel-media-library-plugin：所有图像处理都使用 spatie/medialibrary
spatie/laravel-sluggable：用于生成缩略名
spatie/laravel-translatable：用于翻译，因为它与 Filament 的第一方翻译包一起使用。
dereuromark/media-embed：支持嵌入各种媒体服务的视频。
openai-php/laravel：生成内容并添加其他智能功能 ;-)。

使用方法

有一个示例项目包含了所有包功能，包括

迁移文件
默认和可翻译页面的数据模型
Filament 资源和页面
HTTP 控制器
视图
一个数据种子来生成测试页面

您可以用这个作为起点来了解如何将包用于 CMS 页面。以下我们将简要讨论如何通过四个步骤设置迁移、模型和 Filament 资源。在将来，我们希望添加基于问题的命令来创建这些，请参阅路线图。

1. 设置迁移

您可以从可以发布的示例迁移开始。然后根据您的需求修剪并选择字段，请注意，某些模型特性需要字段的组合，例如，英雄图片需要hero_image_copyright和hero_image_title。在迁移中注释了集群或查看模型特性以获得灵感。

2. 设置模型

如果您还没有模型，可以使用php artisan make:model创建一个，然后通过特性添加接口及其默认实现。以下是提供的接口和特性的概述及其功能：

HasPageAttributes:

此接口添加了标题和发布开始和结束日期变量，以及帮助查找已发布模型的函数和作用域。使用HasPageAttributesTrait或HasTranslatedPageAttributesTrait实现此接口以支持可翻译内容。

HasIntroAttribute:

此接口添加了一个简介文本变量。使用HasIntroAttributeTrait或HasTranslatedIntroAttributeTrait实现此接口。

HasCode:

添加了一个代码变量，以便在源代码中通过字符串而不是变化的 ID 或 slug 来选择特定的内容模型。例如，这有助于查找主页。使用HasCodeTrait实现。

HasHeroImageAttributes:

添加了英雄图片以及标题（例如，在alt标签中的可访问性）和版权变量到模型中。这可以通过HasHeroImageAttributesTrait和HasTranslatedHeroImageAttributesTrait实现。

HasContentBlocks:

在您的模型中添加了一个 JSON 列来存储灵活内容块的数据。如果您想使用灵活内容块，则需要实现它。HasContentBlocksTrait或HasTranslatedContentBlocksTrait。

HasMediaAttributes:

这提供了一些处理媒体的辅助函数。您无需添加属性，因为处理图像的其他属性将自动包含。

HasTranslatableMedia:

如果您想支持可翻译的媒体（例如，每个地区使用不同的图像），请包含此接口。实现由HasTranslatedAttributesTrait.php属性完成。实现可翻译图像的属性将使用此实现来跟踪需要翻译的媒体。

HasOverviewAttributes:

概述字段可以用于在列表中显示内容模型作为简短的片段，例如新闻文章列表。使用HasOverviewAttributesTrait或HasTranslatedOverviewAttributesTrait实现此功能。

HasSEOAttributes:

这添加了新的标题、描述、图像和关键词以支持SEO。如果没有完成SEO字段，则提供备用常规标题、简介和英雄图像。实现HasSEOAttributesTrait或HasTranslatedSEOAttributesTrait以支持可翻译内容。

Linkable:

如果您想使用模型在操作中创建动态URL，或想使用Filament表格中的视图操作，请添加此接口。该接口要求您实现两个函数：一个用于获取内容可以公开查看的URL，另一个用于查看未发布的内容。没有默认实现属性，因为此包不了解使用的路由和控制器。

Slugs

要支持缩略语，您可以包含HasSlugAttributeTrait或HasTranslatedSlugAttributeTrait以支持可翻译的缩略语。如果您使用可翻译的缩略语，请更改页面路由Filament资源。

父子内容或子页面

要支持分层内容，您可以包含HasParent接口，实现由HasParentTrait完成。

如果您想实现嵌套URL结构，请参阅此文档。

3. 设置Filament资源

使用filament命令创建filament资源及其页面。

设置表格

该包提供了一些列字段和一个选择已发布/未发布模型的过滤器。以下是一个代码示例中所有可用列的概述

public static function table(Table $table): Table {
    return $table->columns([
            TitleColumn::create(),
            PublishedColumn::create(),
        ])
        ->filters([
            PublishedFilter::create(),
        ])
        ->actions([
            Tables\Actions\EditAction::make(),
            PublishAction::make(),
        ])
        ->bulkActions([
            Tables\Actions\DeleteBulkAction::make(),
        ]);
}

(可选) 向表格添加查看操作

如果您的模型使用Linkable接口，您还可以在表格中使用提供的ViewAction。此操作将简单地打开由模型上的getViewUrl()方法返回的URL。

use Statikbe\FilamentFlexibleContentBlocks\Filament\Table\Actions\ViewAction;

->actions([
    Tables\Actions\EditAction::make(),
    PublishAction::make(),
    ViewAction::make(), // <-- Add this
])

设置表单

然后您可以使用该包提供的 Filament 字段实现 form() 函数。下面是一个带有标签的示例。请注意，我们有时会使用 create() 静态函数，因为我们希望将名称设置为在模型中使用的固定变量。示例中的一些字段被组合在一起（例如 SEOFields），如果您想创建自定义布局，也可以使用单个字段。

public static function form(Form $form): Form {
    return $form
        ->schema([
            Tabs::make('Heading')
                ->columnSpan(2)
                ->tabs([
                    Tab::make('General')
                        ->schema([
                            TitleField::create(true),
                            SlugField::create(),
                            PublicationSection::create(),
                            AuthorField::create(),
                            HeroImageSection::create(),
                            IntroField::create(),
                            ParentField::create(),
                        ]),
                    Tab::make('Content')
                        ->schema([
                            ContentBlocksField::create(),
                        ]),
                    Tab::make('Overview')
                        ->schema([
                            OverviewFields::make(1),
                        ]),
                    Tab::make('SEO')
                        ->schema([
                            SEOFields::make(1),
                        ]),
                ]),    
        ]);
}

如果您有可翻译的内容，您需要将 filament/spatie-laravel-translatable-plugin 的特质和语言切换字段包含到资源以及其页面中。
重要：在编辑页面上，如果您使用可翻译的图片，则需要使用 EditRecord\Concerns\TranslatableWithMedia 特质。在创建页面上使用 CreateRecord\Concerns\TranslatableWithMedia。

关于翻译的别名说明

如果您在模型上使用翻译的别名，则可能在没有翻译别名的情况下创建新的模型实例。当您切换到没有翻译别名的语言时，Filament 使用模型类中定义的别名作为路由绑定键。这将导致错误，因为别名翻译尚不存在。为了解决这个问题，在 Filament 中使用 ID 作为路由绑定键而不是别名是最简单的。您可以通过更改 Filament 资源类中的页面 URL 来实现这一点，以便它们不尝试解析 /{record}/edit 的对象，而是使用 ID 属性 /{record:id}/edit。然后设置 Filament 资源的 $recordRouteKeyName 为 id。

protected static ?string $recordRouteKeyName = 'id';

public static function getPages(): array
{
    //note: replace the page classes!
    return [
        'index' => Pages\ListArticles::route('/'),
        'create' => Pages\CreateArticle::route('/create'),
        'edit' => Pages\EditArticle::route('/{record:id}/edit'),
    ];
}

4. 设置控制器和 Blade 视图

现在您需要创建一个控制器和 GET 路由，该路由返回一个 Blade 视图以显示您的内容。请参阅控制器示例。

我们为所有字段（除 SEO 字段外）提供 Blade 组件。下面是一个简单的 Blade 模板示例，其中将模型作为 $page 变量传递给此视图。`<x-flexible-hero>` 组件渲染默认的英雄，包含标题和全屏图片，`<x-flexible-content-blocks>` 组件渲染每个块的所有内容。

注意： `x-flexible-hero` 组件需要 Alpine.js。

<x-layouts.flexible title="{{ $page->title }}" wide="true">
    <x-flexible-hero :page="$page" />
    <div>
        <x-flexible-content-blocks :page="$page">
        </x-flexible-content-blocks>
    </div>
</x-layouts.flexible>

如果您想自定义这些组件视图，可以发布视图。

您可以使用您偏好的 SEO 库在页面上渲染 SEO 标签，例如使用 artesaos/seotools。

AI 功能

我们正在构思一些令人兴奋的新基于 AI 的功能，以简化内容创建和翻译。第一个已经到来

SEO 字段生成

有一个表单操作 SEOAIAction，可以根据模型的内容生成 SEO 标题、描述和标签。

要启用此功能，您应该完成 OpenAI 库的配置。不要忘记运行安装命令

php artisan openai:install

创建一个 OpenAI API 密钥，并在您的项目中的 .env 文件中设置它。

OPENAI_API_KEY=sk-...
OPENAI_ORGANIZATION=org-...

您将找到 SEO AI 动作已经设置在 SEOFields 组中。

块

要构建您的内容，该软件包提供了以下默认块。

文本块

一个包含标题和文本的基本块。

文本加图片块

除了文本块外，您还可以添加一个带有标题和版权的图片。图片可以放在文本的左侧或右侧，并且可以设置块的图片转换和背景颜色。还可以添加一个配置了按钮样式的调用到行动按钮。您可以链接到 URL，也可以动态链接到其他模型或路由。

图片块

这显示了一个带有版权信息的图片，您可以设置图片转换、页面上的图片位置和宽度。

视频块

您可以从众多媒体服务嵌入视频，并设置一个叠加图片，点击图片后会导致视频嵌入懒加载。

引言块

一个显示引言及其作者的块。

HTML 块

一个用于插入自定义 HTML 的块。

调用到行动块

此块专注于添加带有图片和文本的调用到行动。

概述块

此块可用于显示其他模型记录的概述字段和图片，例如用于显示相关博客文章。可以配置网格列和背景颜色。

卡片块

此块与概述块类似，但是您可以为每个卡片添加标题、描述、图片和 CTA。可以配置图片转换、背景颜色和网格列。

模板块

您可以选择要包含的 Blade 模板。这对于添加小型表单或交互式组件很有用，例如新闻通讯注册表单或地图。

创建您自己的自定义块

您可以通过扩展 AbstractContentBlock 简单地创建自己的内容块。

注意：不要使用 AbstractFilamentFlexibleContentBlock.php 来扩展，因为这个超级类包含向自定义块添加软件包自身命名空间的逻辑。

配置

许多内容块的定制和它们的行为都可以通过配置文件来完成。请参阅配置文档。

路线图

以下是一个想法和缺失功能的列表。PR 受欢迎！

生成迁移的命令
生成模型的命令
生成 Filament 资源和页面的命令
集成图片资产管理器
在富编辑器中存储对模型的链接
重定向
可重用块。名称：全局块？
图片缩放的焦点

变更日志

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

贡献

请通过 Github 问题提交错误或功能请求。欢迎拉取请求！谢谢！

安全漏洞

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

鸣谢

许可证

麻省理工学院许可证（MIT）。请参阅许可文件获取更多信息。

statikbe / laravel-filament-flexible-content-blocks

维护者

详细信息