README

由于工作量繁重，我无法继续修复和改进Filament-Tour。

但如果你愿意修补它、修改它或重写它，请不要犹豫，为项目做出贡献！

借助DriverJS的力量，为用户提供一种优雅的方式来发现你的面板！

安装

您可以通过composer安装此filament插件

对于Filament V3.x

composer require jibaymcs/filament-tour:"^3.0"

对于Filament V2.x

composer require jibaymcs/filament-tour:"^2.0"

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="filament-tour-config"

可选地，您可以使用以下命令发布视图

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

这是发布配置文件的内容

 return [    
    "only_visible_once" => true,  
];

使用方法

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

您还可以启用或禁用对本地存储上的检查，如果当前用户已经看过导览。

// default  : true  
FilamentTourPlugin::make()->onlyVisibleOnce(false)

开始导览！

让我们跟随以下示例将导览添加到仪表盘页面。

如果您还没有自定义仪表盘，请参阅以下教程：FIlamentPHP - Dashboard - 自定义仪表盘页面

使用正确的特性来注册您的导览！

<?php  
namespace App\Filament\Pages;  
  
use JibayMcs\FilamentTour\Tour\Tour;  
  
class Dashboard extends FilamentDashboard {

    use HasTour;
    // ...  

	public function tours(): array    {    
		return []; 
    	}
}

创建一个简单的导览！

public function tours(): array {
    return [
       Tour::make('dashboard')
           ->steps(
                           
               Step::make()
                   ->title("Welcome to your Dashboard !")
                   ->description(view('tutorial.dashboard.introduction')),
    
               Step::make('.fi-avatar')
                   ->title('Woaw ! Here is your avatar !')
                   ->description('You look nice !')
                   ->icon('heroicon-o-user-circle')
                   ->iconColor('primary')
           ),
    ];
}

创建一个JSON导览！

- 从直接URL

public function tours(): array {
    return [
       Tour::make(url: "https://gist.githubusercontent.com/JibayMcs/cc06efddadcfc0a0ff59e116533ee727/raw/8c5c86a3a4b92e4d0586d7a344d0e41f0c175659/TourDashboard.json")
    ];
}

- 从您的存储

public function tours(): array {
    return [
       Tour::make(json: Storage::disk('local')->get("TourDashboard.json"))
    ];
}

重要

使用Tour::make(url: "")或Tour::make(json: "")是相同的，所以如果你有错误类型，请不要担心参数的名称。
但是
如果你使用Tour::make('my-tour')它等同于Tour::make(id: 'my-tour')在这里你需要构造所有步骤。这里不读取JSON。

JSON示例文件（点击展开）或Github Gist链接

{
    "id": "dashboard",
    "route": "/admin/test-team",
    "colors": [
        "",
        ""
    ],
    "alwaysShow": true,
    "visible": true,
    "uncloseable": true,
    "ignoreRoutes": false,
    "disableEvents": true,
    "nextButtonLabel": "Next",
    "previousButtonLabel": "Previous",
    "doneButtonLabel": "Done",
    "steps": [
        {
            "title": "Woaw ! First Step !",
            "description": "Yeah ! And I'm from a json file !",
            "uncloseable": false,
            "events": {
                "clickOnNext": "body",
                "notifyOnNext": {
                    "title": "Hello World !",
                    "body": "Woaw ! I'm from a Json file !",
                    "color": "success"
                },
                "redirectOnNext": {
                    "url": "https://filamentphp.com",
                    "newTab": true
                },
                "dispatchOnNext": [
                    "open-modal",
                    {
                        "id": "edit-user"
                    }
                ]
            }
        },
        {
            "title": "An other one !",
            "description": "Yeah ! And I'm from the same json file !",
            "uncloseable": false,
            "events": {
                "clickOnNext": "body",
                "notifyOnNext": {
                    "title": "Hello World !",
                    "body": "Woaw ! I'm from a Json file !",
                    "color": "success"
                },
                "redirectOnNext": {
                    "url": "https://filamentphp.com",
                    "newTab": true
                },
                "dispatchOnNext": [
                    "open-modal",
                    {
                        "id": "edit-user"
                    }
                ]
            }
        }
    ]
}

Tour.php

Tour方法参考

// Instanciate a tour, and provide an id, to trigger it later
Tour::make(string $id)

// Since 3.1.0.1, JSON Support update
Tour::make(... $params)

    // Define a custom url to trigger your tour 
    ->route(string $route)
    
    //Register the steps of your tour
    ->steps(Step ...$steps)
    
    // Define a color of your hightlight overlay for the dark and light theme of your filament panel
    ->colors(string $light, string $dark)
    
    //Set the tour as always visible, even is already viewed by the user.
    ->alwaysShow(bool|Closure $alwaysShow = true)
    
    // Set the tour visible or not
    ->visible(bool|Closure $visible = true)
    
    // Set the 'Next' button label
    ->nextButtonLabel(string $label)
    
    // Set the 'Previous' button label
    ->previousButtonLabel(string $label)
    
    // Set the 'Done' button label
    ->doneButtonLabel(string $label)
    
    // Set the whole steps of the tour as uncloseable
    ->uncloseable(bool|Closure $uncloseable = true)
    
    // Disable all tour steps events
    ->disableEvents(bool|Closure $disableEvents = true)
    
    // Bypass route check to show the tour on all pages
    // Maybe useless, but who knows ?
    ->ignoreRoutes(bool|Closure $ignoreRoutes = true)

Step.php

Step方法参考

// If no element provided, the step act like a modal
Step::make(string $element = null)

    // Define the title of your step
    // Mandatory
    ->title(string|Closure $title)
    
    // Define the description of your step
    // Also accept HTML
    // Mandatory
    ->description(string|Closure|HtmlString|View $description)
    
    // Define an icon next to your step title
    ->icon(string $icon)
    
    // Define the color of the title icon
    ->iconColor(string $color)
    
    // Step your step closeable or not
    // Default: true
    ->uncloseable(bool|Closure $uncloseable = true)
    
    //Simulate a click on a CSS selected element when you press the next button
    ->clickOnNext(string|Closure $selector)
    
    // Send a notification when you press the next button
    ->notifyOnNext(Notification $notification)
    
    //Redirect you to a custom url or a route() when you press the next button
    ->redirectOnNext(string $url, bool $newTab = false)
    
    // Dispatch an event like `$dispatch()` when you press the next button
    ->dispatchOnNext(string $name, ...$args)

突出显示

与导览相同，使用正确的特性！

使用正确的特性来注册您的突出显示！

<?php

namespace App\Filament\Pages;  
  
use JibayMcs\FilamentTour\Highlight\HasHighlight;  
  
class Dashboard extends FilamentDashboard {

    use HasHighlight;
    // ...  
  
    public function highlights(): array {    
	    return []; 
    }
}

创建一个简单的突出显示元素！

public function highlights(): array {

    return [
	 
        Highlight::make('.fi-header-heading')
            ->element('.fi-header-heading')
            ->title('Whoaw ! You highlighted the title of the page !')
            ->description('"Dashboard"'),
	
        Highlight::make('.fi-avatar')
            ->element('.fi-avatar')
            ->title("Pssst ! That's your avatar")
            ->icon('heroicon-o-user-circle')
            ->iconColor('primary'),
            	
    ];
}

Highlight.php

Highlight方法参考

// Instanciate a highlight with a CSS select of the element where the icon button is next to
Highlight::make(string $parent)

    // Define the element to be highlighted
    ->element(string $element)

    // Set the title of your highlight
    ->title(string|Closure $title)

    // Set the description of your highlight
    ->description(string|Closure|HtmlString|View $description)

    // Define a custom icon for your highlight button
    // Default: heroicon-m-question-mark-circle
    ->icon(string $icon)

    // Define the color of the highlight icon button
    // Default: gray
    ->iconColor(string $color)

    // Define a color of your hightlight overlay for the dark and light theme of your filament panel
    ->colors(string $light, string $dark)

    // Set the position of your icon button around the parent
    // Default: top-left
    // Available: top-left, top-right, bottom-left, bottom-right
    ->position(string $position)

事件

可用事件

filament-tour::open-highlight string id
通过id打开特定的突出显示。
filament-tour::open-tour string id
通过id打开特定的导览。

Filament Tour通过触发一些事件来显示导览和突出显示。因此，您可以从自己的代码中触发它们。

基本上，如果您想使用自定义按钮来触发导览或突出显示，您可以进行如下操作

// ======== Highlights
// AlpineJS
<button x-on:click="Livewire.dispatch('filament-tour::open-highlight', 'title')">Show title highlight</button>

// Livewire
<button wire:click="$dispatch('filament-tour::open-highlight', 'title')">Show title highlight</button>

// ======== Tours
//AlpineJS
<button x-on:click="Livewire.dispatch('filament-tour::open-tour', 'title')">Show Dashboard tour</button>

// Livewire
<button wire:click="$dispatch('filament-tour::open-tour', 'dashboard')">Show Dashboard tour</button>

ℹ️
不要忘记使用filament-tour::作为事件的前缀来触发正确的事件。

开发工具

重要

在生产模式下，此工具始终处于禁用状态。APP_ENV=production

Filament Tour嵌入了一个简单的工具，可以帮助您开发导览和突出显示。

让我向您展示如何使用它！

启用工具

要启用工具，只需在插件声明中使用FilamentTourPlugin::make()->enableCssSelector()即可。

键盘快捷键

Ctrl|Cmd + Space 打开工具。

Escape 退出工具。

Ctrl|Cmd + C 复制突出显示元素的CSS选择器。

Capture.video.du.23-08-2023.13.56.25.webm

额外资源

DriverJS

DriverJS 网站页面
DriverJS GitHub (给作者一些支持！)

这个插件的核心！
不要犹豫，查看文档以了解更多关于这个插件的功能。
目前我还没有实现DriverJS的所有功能，但我正在努力工作！

更新日志

有关最近变更的详细信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞，请审查我们的安全策略。

鸣谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

jibaymcs / filament-tour

维护者

详细信息