Trong bài này, mình sẽ hướng dẫn các bạn cách để tùy chỉnh Filament, từ màu sắc mặc định, đường dẫn, sidebar cho tới custom theme để thêm css tùy chỉnh, để phù hợp với nhu cầu sử dụng hoặc thương hiệu như khách hàng yêu cầu.
1. Thay đổi đường dẫn Admin Panel
Để thay đổi đường dẫn mặc định khi tạo panel của Filament từ /admin sang cái mình muốn, mình sẽ vào AdminPanelProvider nằm ở thư mục app\Providers\Filament, sau đó ở function panel(), chỉnh phần id và path thành nội dung mình mong muốn, ví dụ ở đây là dashboard.
public function panel(Panel $panel): Panel
{
return $panel
->id('dashboard')
->path('dashboard');
}
Phần id là định danh của panel, mỗi panel sẽ có một id khác nhau. Phần path sẽ quyết định url của panel.
2. Đổi tên thương hiệu (brandname) và favicon
Cũng tương tự như phần url, các cấu hình của phần này nằm ở function panel() trong AdminPanelProvider.
Phần này sẽ có 2 khái niệm là brand name và brand logo. Brand name là tên thương hiệu định nghĩa bằng chữ (text), còn brand logo là hình ảnh, nếu dùng brand logo thì phần brand name sẽ bị ẩn đi.
Mặc định brand name sẽ lấy từ APP_NAME ở .env, nếu cấu hình ở admin panel, Filament sẽ ưu tiên phần tên đã cấu hình trong brandName().
public function panel(Panel $panel): Panel
{
return $panel
->brandName('Code cùng Khánh');
}
Brand logo sẽ dùng ảnh, khi có cấu hình brand logo thì brand name sẽ bị ẩn đi. Để sử dụng brand logo thì mình sẽ cấu hình bằng tùy chọn brandLogo() và gắn link ảnh mong muốn.
public function panel(Panel $panel): Panel
{
return $panel
->brandLogo(asset('images/logo.png'));
}
Tương tự, để cấu hình favicon cho panel, mình cũng sẽ dùng tùy chọn favicon() và gắn link ảnh mong muốn.
public function panel(Panel $panel): Panel
{
return $panel
->favicon(asset('images/favicon.png'));
}
3. Bật/Tắt Dark mode
Mặc định Filament sẽ có sẵn Dark mode khi bạn khởi tạo panel, nếu không muốn sử dụng thì bạn có thể tắt chế độ này đi bằng tùy chọn darkMode() với giá trị là false ở function panel() trong AdminPanelProvider.
public function panel(Panel $panel): Panel
{
return $panel
->darkMode(false);
}
4. Tùy chỉnh sidebar
Ở phần sidebar thì Filament cung cấp khá nhiều tùy chỉnh để các bạn có thể sử dụng. Các tùy chỉnh cũng được cấu hình trong function panel() của AdminPanelProvider.
sidebarCollapsibleOnDesktop(): nhận tham số là true/false, nếu là true thì Filament sẽ thêm một nút mũi tên nhỏ ở sidebar, dùng để thu gọn sidebar.sidebarFullyCollapsibleOnDesktop(): tương tự với tùy chọn ở trên, nhưng thay vì thu gọn lại còn 1 thanh chứa icon, tùy chọn này sẽ ẩn hoàn toàn sidebar (lưu ý là không dùng chung với tùy chọn ở trên).sidebarWidthvàmaxContentWidth: dùng để chỉnh độ rộng của sidebar và cả nội dung chính, các bạn có thể dùngpxđể quy định độ rộng, hoặc dùng lớp dạng enum Width (từFilament\Support\Enums\Width) để quy định độ rộng mình mong muốn.
// Thu nhỏ sidebar (có mũi tên ẩn/hiện)
->sidebarCollapsibleOnDesktop(true)
// Ẩn hoàn toàn sidebar
->sidebarFullyCollapsibleOnDesktop(true)
// Đổi độ rộng sidebar
->sidebarWidth('200px')
// Bung content full màn hình
->maxContentWidth(Width::Full)
Ngoài ra, các bạn có thể chuyển sidebar thành top menu bằng cách sử dụng topNavigation(). Tuy nhiên nếu đặt là true thì các tùy chọn như sidebarWidth hoặc collapsible sẽ không có tác dụng nữa (vì nó đâu còn là sidebar đâu).
->topNavigation(true)
5. Thay đổi icon navigation ở sidebar (hoặc top navigation)
Khi tạo các phần resource (hay CRUD), mặc định icon ở menu sẽ giống nhau làm khó phân biệt và cũng hơi nhàm chán. Để thay đổi các icon này, các bạn truy cập vào từng Resource (ví dụ như PostResource, UserResource) trong thư mục app\Filament\Resources và thay đổi cấu hình ở $navigationIcon, tại đây các bạn có thể dùng lớp enum HeroIcon (Filament\Support\Icons\Heroicon) hoặc điền tên icon để thay đổi thành icon mong muốn.
Tham khảo các icon ở https://heroicons.com/
use Filament\Support\Icons\Heroicon;
class PostResource extends Resource
{
protected static ?string $navigationIcon = Heroicon::Document;
}
Để thay đổi icon ở trang chính (trang gốc của panel) hay còn gọi là Dashboard, mình sẽ tạo 1 page Dashboard để có thể thêm $navigationIcon (vì mặc định trang này nằm trong source của Filament). Để thêm 1 page, mình dùng lệnh:
php artisan make:filament-page Dashboard
Sau đó vào page vừa tạo thay đổi phần kế thừa (extends) từ Page thành Dashboard lấy từ Filament\Pages\Dashboard (cái đang gọi bên AdminPanelProvider). Lưu ý là phải xóa phần $view để tránh gặp lỗi không mong muốn.
use Filament\Pages\Dashboard as PagesDashboard;
class Dashboard extends PagesDashboard
{
//protected string $view = 'filament.pages.dashboard';
}
Thêm $navigationIcon tương tự trong các file Resource khác.
class Dashboard extends PagesDashboard
{
protected static string|BackedEnum|null $navigationIcon = Heroicon::ComputerDesktop;
}
Thay đổi phần Dashboard được gọi ở AdminPanelProvider thành cái mình vừa tạo để thay thế cái mặc định.
use App\Filament\Pages\Dashboard; // thay cái vừa tạo
// use Filament\Pages\Dashboard; => ẩn cái mặc định
class AdminPanelProvider extends PanelProvider
{
// ...
}
Ngoài ra, các bạn có thể sử dụng thêm thuộc tính $activeNavigationIcon để khai báo icon khi trang đang ở trạng thái active, áp dụng chung cho cả Resource và Page.
class Dashboard extends PagesDashboard
{
protected static string|BackedEnum|null $navigationIcon = Heroicon::ComputerDesktop;
protected static string|BackedEnum|null $activeNavigationIcon = Heroicon::OutlinedComputerDesktop;
}
6. Thay đổi màu sắc giao diện mặc định
Phần này có thể là tùy chỉnh Filament được sử dụng nhiều nhất, tuy đơn giản nhưng rất cần thiết khi muốn thay đổi màu sắc cho phù hợp với thương hiệu hay thiết kế tổng thể của hệ thống.
Để thay đổi màu sắc giao diện, các bạn có thể dùng các màu hỗ trợ sẵn của Filament bằng cách thay đổi colors() ở function panel() trong AdminPanelProvider, mặc định Filament sẽ có các tùy chọn để thay đổi:
primarysuccesswarningdangerinfogray
Ví dụ như mình thay đổi primary từ màu mặc định là Amber sang màu Green thì sẽ thay đổi primary ở colors() như sau (Color là lớp Enum của Filament, được gọi từ Filament\Support\Colors\Color):
->colors([
'primary' => Color::Green,
])
7. Tùy chỉnh Filament nâng cao: sử dụng custom theme để thay đổi các class css
Ở phần trước, mình có thể cấu hình màu sắc theo các tùy chọn mặc định của Filament ở trong phần colors, nhưng nếu muốn tùy chỉnh sâu hơn như tới chi tiết từng class css, thì bắt buộc phải tạo 1 custom theme và khai báo nó trong AdminPanelProvider để tiếp tục tùy chỉnh.
Để tạo custom theme, mình sử dụng lệnh:
php artisan make:filament-theme
# hoặc
php artisan make:filament-theme <panel_id>
Sau khi chạy xong lệnh, file theme.css sẽ được tạo ra ở thư mục resources\filament\<panel_id>\theme.css. Panel của mình đang là dashboard nên sẽ là resources\filament\dashboard\theme.css.
Trong phần vite.config.js sẽ có thêm dòng khai báo theme.css ở phần input:
input: [
// ...
'resources/css/filament/dashboard/theme.css',
]
Tiếp theo, mình sẽ khai báo theme ở function panel() trong AdminPanelProvider:
->viteTheme('resources/css/filament/dashboard/theme.css')
Giờ mình có thể cấu hình riêng cho các phần css class mình muốn trong file theme.css, các class có thể lấy bằng cách inspect phần mình muốn thay đổi trên trình duyệt, ví dụ:
/* Thay đổi màu sắc khi hover link trên sidebar */
.fi-sidebar-item a:hover {
color: '#B82121';
}
Ngoài công dụng là tùy chỉnh từng class, custom theme còn dùng để khai báo thư mục quét các lớp sử dụng Tailwind CSS do mình tự cấu hình thêm, hoặc dùng plugins của Filament.
Tổng kết
Qua bài này, mình đã hướng dẫn các bạn các phần tùy chọn cơ bản nhưng khá cần thiết khi tùy chỉnh Filament, ngoài những nội dung này ra thì còn rất nhiều tùy chọn khác để sử dụng, nếu các bạn muốn biết thêm phần nào hoặc gặp vấn đề nào, nhớ để lại bình luận cho mình để mình có thể làm thêm nội dung hoặc hỗ trợ các bạn nhé.
Tài liệu tham khảo
- FilamentPHP: Website chính thức của Filament
- Tạo custom theme trong Filament
- Heroicon
- Hướng dẫn tùy chỉnh Filament: video gốc của bài viết
- Bài viết gốc
