README

介绍

Filament横幅是一个强大的Filament插件，允许您将动态横幅无缝集成到基于Filament的应用程序中。使用此插件，您可以轻松创建、管理和显示引人入胜的横幅，这些横幅可以定制以满足您的特定需求。

演示

创建横幅

创建范围横幅

范围横幅仅在所选资源页面上可见。

功能

创建多个横幅：在您的Filament应用程序中轻松创建和管理多个横幅。
自定义横幅外观：根据您的品牌和设计定制横幅的外观。
可选用户关闭：允许用户根据需要关闭横幅。
横幅调度：安排横幅在特定时间显示。
范围可见性：通过针对Filament应用程序中的特定页面或资源来控制横幅的可见性。
渲染位置控制：选择横幅将在应用程序中显示的位置。
编程横幅创建：使用BannerManager外观编程创建横幅。

入门

在我们开始之前，重要的是要知道横幅可以以两种方式存储：缓存和数据库。

默认情况下，插件将横幅存储在缓存中。如果您想将横幅持久化到数据库中，您需要遵循额外的说明。

仅缓存

缓存选项提供了一种快速简单的方法来入门。它适合显示偶尔或临时的横幅，因为它可以更快地开始，不需要额外的设置。然而，存储在缓存中的横幅如果清除缓存将会丢失。

数据库

数据库选项适用于需要更广泛使用横幅或需要持久存储的用户。将横幅存储在数据库中确保它们不会丢失，允许更好的管理，并且随着应用程序的增长提供了更多的可扩展性。通过提供这两种选项，插件让您可以根据应用程序的需求选择最佳的存储方法。

安装

通过composer安装包
```
composer require kenepa/banner
```
设置自定义主题

Filament v3建议您创建一个自定义主题，以便更好地支持插件额外的Tailwind类。在创建您的自定义主题后，您应该在新的主题的tailwind.config.js文件中添加横幅插件的视图，该文件通常位于resources/css/filament/admin/tailwind.config.js。
```
  content: [
        ...
        './vendor/kenepa/banner/resources/**/*.php',
    ]
```
将横幅的CSS样式表导入到主题的CSS文件中，位于resources/css/filament/admin/theme.css。（注意，这可能在您的项目中有所不同）
```
@import '../../../../vendor/kenepa/banner/resources/css/index.css';
```
编译您的主题
```
npm run build
```
运行filament升级命令
```
php artisan filament:upgrade
```

将插件添加到您的面板

use Kenepa\Banner\BannerPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
return $panel
       // ...
     ->plugins([
        BannerPlugin::make()
     ]);
}

在数据库中持久化横幅（可选）

如果您想使用数据库存储选项，可以按照以下步骤操作

注意：您的数据库必须支持JSON列类型

发布并运行迁移您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="banner-migrations"
php artisan migrate

配置插件

将 persistsBannersInDatabase() 添加到横幅插件。

 use Kenepa\Banner\BannerPlugin;
 use Filament\Panel;
  
 public function panel(Panel $panel): Panel
 {
 return $panel
 // ...
 ->plugins([
     BannerPlugin::make()
         ->persistsBannersInDatabase()
 ]);
 }

用法

使用 UI 创建横幅

本包提供了一个全面的横幅管理系统，允许您创建、查看、更新和删除将在整个应用程序中显示的横幅。

程序化创建横幅

如果您想程序化创建横幅，可以使用 BannerManager 门面。BannerManager 使用横幅值对象。因为这个包允许您选择如何存储横幅，所以我希望有一种方法可以代表横幅与 BannerManager 交互。想了解更多关于值对象是什么以及为什么它们可能很有用，请参考这篇文章。

注意：由于这只是项目所需，因此 BannerManager 的功能有限。但请随时提交 PR 来扩展其功能。

您首先需要创建一个值对象来表示横幅。

$bannerData = new BannerData(
    id: 'banner_123',
    name: 'Promotional Banner',
    content: 'Check out our latest sale!',
    is_active: true,
    active_since: '2024-06-01',
    icon: 'heroicon-m-wrench',
    background_type: 'gradient',
    start_color: '#FF6B6B',
    end_color: '#FFD97D',
    start_time: '09:00',
    end_time: '18:00',
    can_be_closed_by_user: true,
    text_color: '#333333',
    icon_color: '#FFFFFF',
    render_location: 'header',
    scope: []
);

您需要自己生成横幅的 ID。提示：使用 uniqid()

创建

现在您可以使用 bannerData 对象创建横幅。

use Kenepa\Banner\Facades\BannerManager;

BannerManager::store($bannerData);

获取所有

use Kenepa\Banner\Facades\BannerManager;

$banners = BannerManager::getAll();

删除

use Kenepa\Banner\Facades\BannerManager;

BannerManager::delete('banner_id_123');

更新

use Kenepa\Banner\Facades\BannerManager;

$updatedBannerData = \Kenepa\Banner\ValueObjects\BannerData::fromArray([
    // ID must be the same
    'id' => 'banner_id',
    'name' => 'updated title'
    // ... all other properties of the banner 
]);

BannerManager::update($updatedBannerData);

配置横幅插件

由包提供的 BannerPlugin 类允许您自定义横幅管理系统的各个方面。这包括插件的标题、副标题、导航设置等。

要自定义插件，您可以使用静态 BannerPlugin::make() 方法并将各种配置方法链接在一起。

标题和副标题

您可以使用 title() 和 subheading() 方法分别设置横幅管理器页面的标题和副标题。

BannerPlugin::make()
    ->title('My Banner Manager')
    ->subheading('Manage your website banners');

导航设置

插件还允许您自定义导航设置，例如图标、标签、组和排序顺序。

BannerPlugin::make()
    ->navigationIcon('heroicon-o-megaphone')
    ->navigationLabel('Banners')
    ->navigationGroup('Marketing')
    ->navigationSort(1);

navigationIcon()：设置用于导航菜单的图标。
navigationLabel()：设置用于导航菜单的标签。
navigationGroup()：设置插件应在导航菜单中放置的组。
navigationSort()：设置插件在导航菜单中的排序顺序。

禁用横幅管理器 您可以完全禁用横幅管理器。例如，如果您想禁用不同面板的横幅管理器，而无需为该页面设置权限。

BannerPlugin::make()
    ->disableBannerManager()

授权

步骤 1。

默认情况下，横幅管理器对所有人可用。要限制访问，您需要添加能力（在 Spatie Permission 包的上下文中称为“权限”），如下所示

BannerPlugin::make()
    ->bannerManagerAccessPermission('banner-manager')

步骤 2。

使用 Laravel gates 在您提供者的 boot() 方法中定义一个具有与插件相同名称的 gate。

// app/Providers/AppServiceProvider.php

   public function boot()
    {
        Gate::define('banner-manager', function (User $user) {
           return $user->email === 'admin@mail.com';
        });
    }

使用 spatie permission 包 此示例显示了如何创建权限并将其分配给用户

$permission = Permission::create(['name' => 'banner-manager'])
auth()->user()->givePermissionTo($permission)

在创建并分配了正确的能力/权限之后，横幅管理器将仅对一组选定的用户可用。

可选

发布视图

php artisan vendor:publish --tag="banner-views"

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全漏洞

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

致谢

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。

kenepa / banner

维护者

详细信息