آموزش Filament، به ویژه در مورد ویجتها (Widgets) در Filament، میتواند به شما کمک کند تا داشبوردهای قدرتمند و کاربردی برای پروژههای خود بسازید. در این مقاله، تمامی جنبههای ویجتها (Widgets) در Filament را از سطح مبتدی تا پیشرفته پوشش خواهیم داد. با ما همراه باشید تا با استفاده از زبان ساده و مثالهای عملی، مفاهیم را به خوبی درک کنید.
ویجتها (Widgets)
ویجتها (Widgets) در Filament ابزارهایی هستند که به شما امکان میدهند اطلاعات و دادههای مختلف را به صورت بصری و تعاملی در داشبوردهای خود نمایش دهید. این ویجتها میتوانند انواع مختلفی از اطلاعات مانند آمار، نمودارها، لیستها، جداول و غیره را نمایش دهند و به شما کمک میکنند تا دادهها را به شکل بهینهتری مدیریت و تحلیل کنید. استفاده از ویجتها (Widgets) در Filament باعث میشود که داشبوردهای شما نه تنها زیبا و جذاب باشند بلکه اطلاعات مهم را به صورت سریع و قابل فهم به کاربران ارائه دهند.
ویژگیهای کلیدی ویجتها (Widgets) در Filament
تنوع بالا: Filament انواع مختلفی از ویجتها را به صورت پیشفرض ارائه میدهد که میتوانید بسته به نیاز پروژه از آنها استفاده کنید.
قابلیت سفارشیسازی: علاوه بر ویجتهای پیشفرض، میتوانید ویجتهای سفارشی خود را ایجاد کنید تا دقیقاً مطابق با نیازهای پروژه شما باشند.
یکپارچگی با Laravel: ویجتها (Widgets) در Filament به خوبی با فریمورک Laravel یکپارچه شدهاند و از قدرت آن بهرهمند میشوند.
کاربرپسندی: طراحی رابط کاربری ساده و کاربرپسند Filament، استفاده و مدیریت ویجتها را برای توسعهدهندگان و کاربران نهایی آسان میکند.
کاربردهای رایج ویجتها (Widgets) در Filament
نمایش آمارها: نمایش تعداد کاربران، فروشها، بازدیدها و سایر آمارهای کلیدی.
نمودارها: نمایش روندها و الگوهای دادهها به صورت نمودارهای مختلف مانند خطی، میلهای و دایرهای.
لیستها و جداول: نمایش لیستهای دادهای مانند آخرین سفارشات، مقالات منتشر شده و غیره.
فرمهای تعاملی: ایجاد فرمهایی که به کاربران اجازه میدهند دادههای جدیدی را وارد کنند یا دادههای موجود را ویرایش کنند.
با توجه به این ویژگیها و کاربردها، ویجتها (Widgets) در Filament ابزاری قدرتمند برای ایجاد داشبوردهای حرفهای و کارآمد محسوب میشوند.
ویجتهای پیشفرض
ویجتهای پیشفرض در Filament مجموعهای از ویجتها هستند که به صورت آماده در این فریمورک ارائه شدهاند و میتوانید به سرعت از آنها استفاده کنید تا داشبوردهای خود را غنیتر و متنوعتر کنید. این ویجتها به گونهای طراحی شدهاند که نیازهای عمومی بسیاری از پروژهها را برآورده کنند و توسعهدهندگان بتوانند بدون نیاز به ایجاد ویجتهای سفارشی، اطلاعات مهم را به کاربران خود ارائه دهند.
مزایای استفاده از ویجتهای پیشفرض
سرعت بالا در توسعه: با استفاده از ویجتهای پیشفرض، میتوانید به سرعت داشبوردهای خود را ایجاد کرده و زمان توسعه را کاهش دهید.
پشتیبانی و بهروزرسانی: این ویجتها توسط تیم توسعه Filament پشتیبانی و بهروزرسانی میشوند، بنابراین همیشه از جدیدترین امکانات بهرهمند خواهید بود.
سازگاری و یکپارچگی: ویجتهای پیشفرض به گونهای طراحی شدهاند که با دیگر قسمتهای Filament و Laravel به خوبی یکپارچه شوند.
در این بخش، به بررسی دو نوع از ویجتهای پیشفرض در Filament میپردازیم: StatsWidget و ChartWidget. همچنین به معرفی برخی دیگر از ویجتهای پیشفرض میپردازیم که ممکن است در پروژههای مختلف مورد استفاده قرار گیرند.
ویجتهای پیشفرض دیگر در Filament
علاوه بر StatsWidget و ChartWidget، Filament ویجتهای متنوع دیگری را نیز ارائه میدهد که برخی از آنها عبارتند از:
RecentPostsWidget: نمایش آخرین پستها یا مقالات منتشر شده.
RecentOrdersWidget: نمایش سفارشات اخیر در فروشگاههای آنلاین.
UserActivityWidget: نمایش فعالیتهای اخیر کاربران.
TaskProgressWidget: نمایش پیشرفت وظایف مختلف در پروژهها.
این ویجتها میتوانند بسته به نیاز پروژههای شما مورد استفاده قرار گیرند و به افزایش کارایی و جذابیت داشبوردهای شما کمک کنند.
نحوه استفاده از ویجتهای پیشفرض
برای استفاده از ویجتهای پیشفرض در Filament، کافی است کلاس ویجت مربوطه را در داشبورد خود ثبت کنید. به عنوان مثال، برای استفاده از StatsWidget و ChartWidget، میتوانید به روش زیر عمل کنید:
use Filament\Widgets\StatsWidget;
use Filament\Widgets\ChartWidget;
class Dashboard extends Page
{
protected static string $view = 'filament.pages.dashboard';
protected function getWidgets(): array
{
return [
DashboardStats::class,
SalesChart::class,
// سایر ویجتهای پیشفرض
];
}
}
در این مثال، دو ویجت DashboardStats و SalesChart به داشبورد اضافه شدهاند که هر کدام از این ویجتها میتوانند StatsWidget و ChartWidget را به عنوان پایه خود داشته باشند.
StatsWidget
ویجت StatsWidget یکی از ابزارهای قدرتمند ویجتها (Widgets) در Filament برای نمایش آمارهای کلیدی و مهم در داشبورد است. این ویجت به شما اجازه میدهد تا به سرعت اطلاعاتی مانند تعداد کاربران، فروشها، بازدیدها و سایر آمارهای مهم را به صورت بصری و قابل فهم نمایش دهید. StatsWidget به دلیل سادگی و کارایی بالا، یکی از پرکاربردترین ویجتهای پیشفرض در Filament محسوب میشود.
ویژگیهای StatsWidget
نمایش چند آمار به صورت همزمان: امکان نمایش چندین آمار مختلف در یک ردیف یا ستون.
قابلیت سفارشیسازی بالا: امکان تنظیم رنگها، آیکونها و قالببندی هر آمار.
پشتیبانی از دادههای داینامیک: نمایش آمارها بر اساس دادههای پویا و بهروز.
استفاده از قالبهای از پیش تعریف شده: Filament قالبهای آمادهای برای نمایش آمارها ارائه میدهد که میتوانید از آنها استفاده کنید یا آنها را تغییر دهید.
نحوه استفاده از StatsWidget
برای استفاده از StatsWidget، باید یک کلاس جدید ایجاد کرده و متد getStats را برای تعریف آمارهای مورد نظر پیادهسازی کنید. در ادامه، به یک مثال عملی برای نمایش تعداد کل محصولات، سفارشات و کاربران در یک فروشگاه آنلاین میپردازیم.
مثال عملی:
فرض کنید شما یک فروشگاه آنلاین دارید و میخواهید تعداد کل محصولات، سفارشات و کاربران را نمایش دهید. با استفاده از StatsWidget میتوانید سه آمار مختلف را در یک ردیف نمایش دهید:
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\StatsWidget;
use App\Models\Product;
use App\Models\Order;
use App\Models\User;
class DashboardStats extends StatsWidget
{
protected function getStats(): array
{
return [
[
'label' => 'محصولات',
'value' => Product::count(),
'icon' => 'heroicon-o-shopping-bag',
'color' => 'primary',
],
[
'label' => 'سفارشات',
'value' => Order::count(),
'icon' => 'heroicon-o-truck',
'color' => 'success',
],
[
'label' => 'کاربران',
'value' => User::count(),
'icon' => 'heroicon-o-users',
'color' => 'warning',
],
];
}
}
در این مثال:
label: نام آمار که به فارسی نمایش داده میشود.
value: مقدار آمار که از پایگاه داده دریافت میشود.
icon: آیکونی که همراه با آمار نمایش داده میشود.
color: رنگ آمار که میتواند از پیش تعریف شدههای Filament مانند primary، success و warning باشد.
نمای Blade مربوط به StatsWidget
Filament به صورت خودکار نمای Blade مربوط به StatsWidget را مدیریت میکند، اما در صورتی که نیاز به سفارشیسازی بیشتر دارید، میتوانید نمای Blade ویجت را در مسیر resources/views/filament/widgets/dashboard-stats.blade.php ایجاد و تغییر دهید.
<x-filament::widget>
<div class="grid grid-cols-1 md:grid-cols-3 gap-4">
@foreach ($this->getStats() as $stat)
<div class="p-4 bg-white rounded-lg shadow">
<div class="flex items-center">
<x-dynamic-component :component="$stat['icon']" class="h-6 w-6 text-{{ $stat['color'] }}-500" />
<div class="ml-4">
<div class="text-sm font-medium text-gray-500">
{{ $stat['label'] }}
</div>
<div class="text-xl font-semibold text-gray-900">
{{ $stat['value'] }}
</div>
</div>
</div>
</div>
@endforeach
</div>
</x-filament::widget>
سفارشیسازی بیشتر StatsWidget
StatsWidget امکان سفارشیسازیهای بیشتری را نیز فراهم میکند:
تغییر آیکونها: میتوانید از آیکونهای مختلفی استفاده کنید تا با برند یا تم پروژه شما هماهنگ شوند.
افزودن لینک به آمارها: با افزودن لینک به هر آمار، کاربران میتوانند به صفحات مرتبط هدایت شوند.
استفاده از دادههای داینامیکتر: میتوانید آمارها را بر اساس فیلترها یا بازههای زمانی خاص نمایش دهید.
مثال پیشرفتهتر:
فرض کنید میخواهید تعداد سفارشات را فقط برای ماه جاری نمایش دهید:
public function getStats(): array
{
return [
[
'label' => 'سفارشات ماه جاری',
'value' => Order::whereMonth('created_at', now()->month)->count(),
'icon' => 'heroicon-o-truck',
'color' => 'success',
],
// سایر آمارها
];
}
این تغییر باعث میشود که تنها سفارشاتی که در ماه جاری ایجاد شدهاند، نمایش داده شوند.
بهترین روشها برای استفاده از StatsWidget
انتخاب آمارهای کلیدی: فقط آمارهایی را نمایش دهید که برای کاربران و مدیران پروژه مهم و کاربردی هستند.
استفاده از آیکونهای معنادار: آیکونها باید به وضوح نشاندهنده آمار مورد نظر باشند تا کاربران به سرعت مفهوم را درک کنند.
بروزرسانی منظم دادهها: اطمینان حاصل کنید که آمارها به صورت منظم و در زمان واقعی بروزرسانی میشوند تا اطلاعات دقیق و بهروز را ارائه دهند.
سازگاری با طراحی کلی داشبورد: رنگها و سبکهای استفاده شده در StatsWidget باید با طراحی کلی داشبورد هماهنگ باشند.
ChartWidget
ویجت ChartWidget برای نمایش دادههای بصری به صورت نمودارها استفاده میشود. این ویجت میتواند انواع مختلفی از نمودارها مانند خطی، میلهای، دایرهای و غیره را نمایش دهد و به شما کمک میکند تا روندها و الگوهای دادههای خود را بهتر درک کنید. ChartWidget به دلیل قابلیت نمایش اطلاعات پیچیده به صورت گرافیکی، یکی دیگر از ویجتهای پیشفرض پرکاربرد در ویجتها (Widgets) در Filament است.
ویژگیهای ChartWidget
پشتیبانی از انواع مختلف نمودارها: امکان انتخاب بین نمودارهای خطی، میلهای، دایرهای و سایر انواع نمودارها.
سفارشیسازی بالا: امکان تنظیم رنگها، برچسبها، محورها و سایر عناصر نمودار.
تعاملپذیری: برخی از نمودارها قابلیت تعامل با کاربران مانند بزرگنمایی و نمایش اطلاعات بیشتر را دارند.
پشتیبانی از دادههای داینامیک: نمایش دادههای بهروز و داینامیک از پایگاه داده یا منابع دیگر.
نحوه استفاده از ChartWidget
برای استفاده از ChartWidget، باید یک کلاس جدید ایجاد کرده و متد getCharts را برای تعریف نمودارهای مورد نظر پیادهسازی کنید. در ادامه، به یک مثال عملی برای نمایش فروش ماهانه در یک نمودار خطی میپردازیم.
مثال عملی:
فرض کنید میخواهید فروش ماهانه خود را در یک نمودار خطی نمایش دهید. میتوانید از ChartWidget به صورت زیر استفاده کنید:
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\ChartWidget;
use Filament\Widgets\Chart;
class SalesChart extends ChartWidget
{
protected function getCharts(): array
{
return [
'monthlySales' => Chart::make()
->type('line')
->datasets([
[
'label' => 'فروش',
'data' => [150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700],
'backgroundColor' => 'rgba(75, 192, 192, 0.2)',
'borderColor' => 'rgba(75, 192, 192, 1)',
'borderWidth' => 1,
],
])
->options([
'scales' => [
'y' => [
'beginAtZero' => true,
],
],
'plugins' => [
'legend' => [
'display' => true,
'position' => 'top',
],
'tooltip' => [
'enabled' => true,
],
],
]),
];
}
}
در این مثال:
type: نوع نمودار که در اینجا خطی (line) انتخاب شده است.
datasets: مجموعه دادههای نمودار که شامل برچسب، دادهها، رنگ پسزمینه، رنگ خط و عرض خط هستند.
options: تنظیمات اضافی برای نمودار مانند شروع محور Y از صفر، نمایش افسانه (legend) و فعالسازی ابزارکهای تعاملی.
نمای Blade مربوط به ChartWidget
Filament به صورت خودکار نمای Blade مربوط به ChartWidget را مدیریت میکند، اما در صورتی که نیاز به سفارشیسازی بیشتر دارید، میتوانید نمای Blade ویجت را در مسیر resources/views/filament/widgets/sales-chart.blade.php ایجاد و تغییر دهید.
<x-filament::widget>
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">فروش ماهانه</h2>
<canvas id="{{ $this->getId('monthlySales') }}" width="400" height="200"></canvas>
</div>
</x-filament::widget>
@push('scripts')
<script>
var ctx = document.getElementById('{{ $this->getId('monthlySales') }}').getContext('2d');
new Chart(ctx, {!! json_encode($this->getCharts()['monthlySales']) !!});
</script>
@endpush
سفارشیسازی بیشتر ChartWidget
ChartWidget امکانات زیادی برای سفارشیسازی دارد که میتواند به شما کمک کند تا نمودارهایی دقیقاً مطابق با نیازهای خود ایجاد کنید:
تغییر نوع نمودار: به جای نمودار خطی، میتوانید از نمودار میلهای، دایرهای، رادیال و غیره استفاده کنید.
->type('bar') // نمودار میلهای
افزودن چندین مجموعه داده (datasets): امکان نمایش چندین خط یا میله در یک نمودار برای مقایسه دادهها.
->datasets([
[
'label' => 'فروش سال جاری',
'data' => [150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700],
'backgroundColor' => 'rgba(75, 192, 192, 0.2)',
'borderColor' => 'rgba(75, 192, 192, 1)',
'borderWidth' => 1,
],
[
'label' => 'فروش سال گذشته',
'data' => [100, 150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650],
'backgroundColor' => 'rgba(153, 102, 255, 0.2)',
'borderColor' => 'rgba(153, 102, 255, 1)',
'borderWidth' => 1,
],
])
تنظیمات محورها: تنظیم ویژگیهای مختلف محورها مانند نمایش برچسبها، خطوط راهنما و غیره.
->options([
'scales' => [
'x' => [
'title' => [
'display' => true,
'text' => 'ماهها',
],
],
'y' => [
'beginAtZero' => true,
'title' => [
'display' => true,
'text' => 'مقدار فروش',
],
],
],
])
بهترین روشها برای استفاده از ChartWidget
انتخاب نوع نمودار مناسب: نوع نمودار باید با نوع دادهای که میخواهید نمایش دهید هماهنگ باشد. برای نمایش روندها از نمودار خطی، برای مقایسهها از نمودار میلهای و برای نسبتها از نمودار دایرهای استفاده کنید.
استفاده از رنگهای متناسب: رنگها باید به گونهای انتخاب شوند که نمودار قابل فهم و زیبا باشد و با طراحی کلی داشبورد هماهنگ باشد.
اضافه کردن برچسبها و عناوین: افزودن برچسبها و عناوین به نمودارها باعث میشود که کاربران به راحتی مفهوم و اطلاعات نمودار را درک کنند.
بروزرسانی منظم دادهها: اطمینان حاصل کنید که دادههای نمودار به صورت منظم و در زمان واقعی بروزرسانی میشوند تا اطلاعات دقیق و بهروز را ارائه دهند.
بهینهسازی عملکرد: در صورت استفاده از نمودارهای پیچیده و دارای دادههای زیاد، بهینهسازی عملکرد و کاهش بارگذاری صفحه را مد نظر قرار دهید.
نمایش چندین نمودار در یک ویجت
در برخی موارد، ممکن است نیاز باشد چندین نمودار را در یک ویجت نمایش دهید. برای این منظور، میتوانید چندین نمودار را در متد getCharts تعریف کنید و آنها را به ترتیب در نمای Blade نمایش دهید.
مثال:
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\ChartWidget;
use Filament\Widgets\Chart;
class CombinedSalesChart extends ChartWidget
{
protected function getCharts(): array
{
return [
'monthlySales' => Chart::make()
->type('line')
->datasets([
[
'label' => 'فروش',
'data' => [150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700],
'backgroundColor' => 'rgba(75, 192, 192, 0.2)',
'borderColor' => 'rgba(75, 192, 192, 1)',
'borderWidth' => 1,
],
])
->options([
'scales' => [
'y' => [
'beginAtZero' => true,
],
],
]),
'yearlySales' => Chart::make()
->type('bar')
->datasets([
[
'label' => 'فروش سال',
'data' => [1800, 2000, 2200, 2400, 2600, 2800, 3000, 3200, 3400, 3600, 3800, 4000],
'backgroundColor' => 'rgba(153, 102, 255, 0.2)',
'borderColor' => 'rgba(153, 102, 255, 1)',
'borderWidth' => 1,
],
])
->options([
'scales' => [
'y' => [
'beginAtZero' => true,
],
],
]),
];
}
}
و نمای Blade مربوطه:
<x-filament::widget>
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">فروش ترکیبی</h2>
<canvas id="{{ $this->getId('monthlySales') }}" width="400" height="200"></canvas>
<canvas id="{{ $this->getId('yearlySales') }}" width="400" height="200" class="mt-6"></canvas>
</div>
</x-filament::widget>
@push('scripts')
<script>
var ctx1 = document.getElementById('{{ $this->getId('monthlySales') }}').getContext('2d');
new Chart(ctx1, {!! json_encode($this->getCharts()['monthlySales']) !!});
var ctx2 = document.getElementById('{{ $this->getId('yearlySales') }}').getContext('2d');
new Chart(ctx2, {!! json_encode($this->getCharts()['yearlySales']) !!});
</script>
@endpush
این روش به شما امکان میدهد تا چندین نمودار مختلف را در یک ویجت نمایش دهید و اطلاعات متنوعتری را به کاربران ارائه دهید.
ایجاد ویجت سفارشی
ویجتها (Widgets) در Filament به شما این امکان را میدهند که داشبوردهای خود را با نمایش اطلاعات دقیق و متناسب با نیازهای پروژهتان سفارشیسازی کنید. اگر ویجتهای پیشفرض Filament نتوانند نیازهای خاص شما را برآورده کنند، ایجاد ویجتهای سفارشی میتواند راهحل مناسبی باشد. در این بخش، به تفصیل مراحل ایجاد یک ویجت سفارشی در ویجتها (Widgets) در Filament را بررسی خواهیم کرد و نکات پیشرفتهای را برای بهبود و ارتقای ویجتهای خود ارائه میدهیم.
مراحل ایجاد ویجت سفارشی
ایجاد یک ویجت سفارشی در ویجتها (Widgets) در Filament شامل چندین مرحله است که هر کدام نقش مهمی در عملکرد نهایی ویجت دارند. در ادامه به هر یک از این مراحل با جزئیات بیشتر میپردازیم:
۱. ایجاد کلاس ویجت
اولین قدم در ایجاد ویجت سفارشی، ایجاد یک کلاس جدید است که از کلاس پایه Widget ارثبری میکند. این کلاس مسئول مدیریت منطق تجاری و دادههای مورد نیاز ویجت است.
مثال: ایجاد کلاس ویجت برای نمایش آخرین مقالات
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use App\Models\Article;
class LatestArticlesWidget extends Widget
{
// مسیر نمای Blade مربوط به ویجت
protected static string $view = 'filament.widgets.latest-articles-widget';
// متغیری برای ذخیره مقالات دریافت شده
public $articles;
/**
* متد mount برای بارگذاری دادهها هنگام ایجاد ویجت
*/
public function mount()
{
$this->articles = Article::latest()->take(5)->get();
}
}
توضیحات:
namespace: مشخصکننده فضای نام کلاس است که باید با ساختار پروژه شما هماهنگ باشد.
use Filament\Widgets\Widget;: ارثبری از کلاس پایه Widget که امکانات لازم برای ایجاد ویجت را فراهم میکند.
protected static string $view: مسیر فایل Blade مربوط به ویجت که در مرحله بعدی ایجاد میشود.
public $articles: متغیری که مقالات دریافت شده را ذخیره میکند و به نمای Blade ارسال میشود.
mount(): متدی که هنگام بارگذاری ویجت اجرا میشود و دادههای مورد نیاز را از مدل Article دریافت میکند.
۲. ایجاد نمای ویجت
پس از ایجاد کلاس ویجت، نیاز است که یک فایل Blade برای نمایش دادههای ویجت ایجاد کنید. این فایل شامل ساختار HTML و نمایش دادههای دریافت شده از کلاس ویجت است.
مثال: ایجاد نمای Blade برای LatestArticlesWidget
فایل: resources/views/filament/widgets/latest-articles-widget.blade.php
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">آخرین مقالات منتشر شده</h2>
<ul class="space-y-2">
@foreach($articles as $article)
<li class="flex justify-between items-center">
<span class="text-gray-700">{{ $article->title }}</span>
<span class="text-sm text-gray-500">{{ $article->created_at->format('Y-m-d') }}</span>
</li>
@endforeach
</ul>
<a href="{{ route('articles.index') }}" class="mt-4 text-blue-500 hover:underline">نمایش همه</a>
</div>
توضیحات:
ساختار HTML: استفاده از کلاسهای Tailwind CSS برای طراحی زیبا و واکنشگرا ویجت.
عنوان ویجت: نمایش عنوان “آخرین مقالات منتشر شده”.
لیست مقالات: حلقه @foreach برای نمایش عناوین و تاریخ انتشار هر مقاله.
لینک نمایش همه: ارائه پیوندی به صفحه اصلی مقالات برای دسترسی به مقالات بیشتر.
۳. ثبت ویجت در داشبورد
پس از ایجاد کلاس ویجت و نمای Blade آن، نوبت به ثبت ویجت در داشبورد میرسد تا ویجت در صفحه داشبورد نمایش داده شود.
مثال: ثبت LatestArticlesWidget در داشبورد
فایل: App\Filament\Pages\Dashboard.php
<?php
namespace App\Filament\Pages;
use Filament\Pages\Page;
use App\Filament\Widgets\LatestArticlesWidget;
class Dashboard extends Page
{
protected static string $view = 'filament.pages.dashboard';
/**
* متد getWidgets برای اضافه کردن ویجتهای داشبورد
*/
protected function getWidgets(): array
{
return [
LatestArticlesWidget::class,
// سایر ویجتهای سفارشی یا پیشفرض
];
}
}
توضیحات:
use App\Filament\Widgets\LatestArticlesWidget;: وارد کردن کلاس ویجت سفارشی.
getWidgets(): array: متدی که لیست ویجتهای نمایش داده شده در داشبورد را برمیگرداند. شما میتوانید هر تعداد ویجت دلخواه را به این لیست اضافه کنید.
مثال عملی پیشرفتهتر: ایجاد ویجت سفارشی با قابلیت جستجو
برای ارتقای ویجت سفارشی خود و افزودن قابلیتهای بیشتر مانند جستجو و فیلتر کردن دادهها، میتوانید از Livewire استفاده کنید که با ویجتها (Widgets) در Filament به خوبی یکپارچه شده است.
مرحله ۱: ایجاد کلاس ویجت با قابلیت جستجو
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use App\Models\Article;
use Livewire\Component;
class SearchableArticlesWidget extends Widget
{
protected static string $view = 'filament.widgets.searchable-articles-widget';
public $articles;
public $search = '';
/**
* بارگذاری دادهها هنگام mount
*/
public function mount()
{
$this->loadArticles();
}
/**
* متد برای بهروزرسانی مقالات بر اساس جستجو
*/
public function updatedSearch()
{
$this->loadArticles();
}
/**
* متد کمکی برای بارگذاری مقالات
*/
protected function loadArticles()
{
if ($this->search) {
$this->articles = Article::where('title', 'like', '%' . $this->search . '%')
->latest()
->take(5)
->get();
} else {
$this->articles = Article::latest()->take(5)->get();
}
}
/**
* متد render برای Livewire
*/
public function render()
{
return view(static::$view);
}
}
توضیحات:
public $search: متغیری برای ذخیره عبارت جستجو.
updatedSearch(): متدی که هنگام تغییر مقدار $search اجرا میشود و مقالات را بر اساس عبارت جستجو بهروزرسانی میکند.
loadArticles(): متدی برای بارگذاری مقالات بر اساس وضعیت جستجو.
render(): متدی که نمای Blade را بارگذاری میکند.
مرحله ۲: ایجاد نمای Blade برای ویجت با قابلیت جستجو
فایل: resources/views/filament/widgets/searchable-articles-widget.blade.php
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">جستجوی مقالات</h2>
<input
type="text"
wire:model.debounce.300ms="search"
placeholder="عنوان مقاله را جستجو کنید..."
class="w-full p-2 border border-gray-300 rounded mb-4"
/>
<ul class="space-y-2">
@forelse($articles as $article)
<li class="flex justify-between items-center">
<span class="text-gray-700">{{ $article->title }}</span>
<span class="text-sm text-gray-500">{{ $article->created_at->format('Y-m-d') }}</span>
</li>
@empty
<li class="text-gray-500">مقالهای یافت نشد.</li>
@endforelse
</ul>
<a href="{{ route('articles.index') }}" class="mt-4 text-blue-500 hover:underline">نمایش همه</a>
</div>
توضیحات:
فیلد جستجو: استفاده از wire:model.debounce.300ms برای بهروزرسانی مقدار $search با تاخیر ۳۰۰ میلیثانیه.
لیست مقالات: نمایش مقالات بر اساس عبارت جستجو شده. در صورت عدم وجود مقالات، پیام مناسبی نمایش داده میشود.
لینک نمایش همه: ارائه پیوندی به صفحه اصلی مقالات.
مرحله ۳: ثبت ویجت با قابلیت جستجو در داشبورد
فایل: App\Filament\Pages\Dashboard.php
<?php
namespace App\Filament\Pages;
use Filament\Pages\Page;
use App\Filament\Widgets\SearchableArticlesWidget;
class Dashboard extends Page
{
protected static string $view = 'filament.pages.dashboard';
protected function getWidgets(): array
{
return [
SearchableArticlesWidget::class,
// سایر ویجتهای سفارشی یا پیشفرض
];
}
}
افزودن قابلیتهای پیشرفته به ویجت سفارشی
برای ایجاد ویجتهای سفارشی پیچیدهتر و تعاملیتر، میتوانید از امکانات پیشرفتهای که Filament و Livewire ارائه میدهند بهره ببرید:
۱. افزودن قابلیت فیلتر و دستهبندی
میتوانید ویجتهای خود را با قابلیت فیلتر کردن دادهها بر اساس دستهبندیهای مختلف ارتقا دهید. به عنوان مثال، نمایش مقالات بر اساس دستهبندیهای مختلف یا تاریخ انتشار.
مثال: افزودن فیلتر دستهبندی به ویجت مقالات
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use App\Models\Article;
use App\Models\Category;
use Livewire\Component;
class CategorizedArticlesWidget extends Widget
{
protected static string $view = 'filament.widgets.categorized-articles-widget';
public $articles;
public $category_id = '';
public function mount()
{
$this->loadArticles();
}
public function updatedCategoryId()
{
$this->loadArticles();
}
protected function loadArticles()
{
if ($this->category_id) {
$this->articles = Article::where('category_id', $this->category_id)
->latest()
->take(5)
->get();
} else {
$this->articles = Article::latest()->take(5)->get();
}
}
public function render()
{
return view(static::$view, [
'categories' => Category::all(),
]);
}
}
نمای Blade:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">مقالات بر اساس دستهبندی</h2>
<select wire:model="category_id" class="w-full p-2 border border-gray-300 rounded mb-4">
<option value="">همه دستهبندیها</option>
@foreach($categories as $category)
<option value="{{ $category->id }}">{{ $category->name }}</option>
@endforeach
</select>
<ul class="space-y-2">
@forelse($articles as $article)
<li class="flex justify-between items-center">
<span class="text-gray-700">{{ $article->title }}</span>
<span class="text-sm text-gray-500">{{ $article->created_at->format('Y-m-d') }}</span>
</li>
@empty
<li class="text-gray-500">مقالهای یافت نشد.</li>
@endforelse
</ul>
<a href="{{ route('articles.index') }}" class="mt-4 text-blue-500 hover:underline">نمایش همه</a>
</div>
توضیحات:
فیلد انتخاب دستهبندی: امکان انتخاب یک دستهبندی خاص برای فیلتر کردن مقالات.
بارگذاری مقالات بر اساس دستهبندی: ویجت مقالات را بر اساس دستهبندی انتخاب شده بهروز میکند.
۲. استفاده از JavaScript و CSS سفارشی
برای افزودن افکتها یا قابلیتهای تعاملی بیشتر به ویجتهای سفارشی خود، میتوانید از JavaScript و CSS سفارشی استفاده کنید. به عنوان مثال، افزودن انیمیشنهای ورود به ویجت یا تعاملات دکمهها.
مثال: افزودن انیمیشن به ویجت مقالات
فایل Blade:
<div class="p-4 bg-white rounded-lg shadow transition-transform duration-300 transform hover:scale-105">
<h2 class="text-xl font-bold mb-4">آخرین مقالات منتشر شده</h2>
<ul class="space-y-2">
@foreach($articles as $article)
<li class="flex justify-between items-center">
<span class="text-gray-700">{{ $article->title }}</span>
<span class="text-sm text-gray-500">{{ $article->created_at->format('Y-m-d') }}</span>
</li>
@endforeach
</ul>
<a href="{{ route('articles.index') }}" class="mt-4 text-blue-500 hover:underline">نمایش همه</a>
</div>
توضیحات:
کلاسهای Tailwind CSS برای انیمیشن: استفاده از کلاسهای transition-transform, duration-300, و transform hover:scale-105 برای افزودن افکت بزرگنمایی هنگام قرار گرفتن موس روی ویجت.
۳. ادغام با APIهای خارجی
اگر نیاز دارید دادههای ویجت خود را از APIهای خارجی دریافت کنید، میتوانید درخواستهای HTTP را در کلاس ویجت انجام دهید و دادهها را به ویجت ارسال کنید.
مثال: دریافت داده از API خارجی
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use Illuminate\Support\Facades\Http;
class ExternalDataWidget extends Widget
{
protected static string $view = 'filament.widgets.external-data-widget';
public $externalData;
public function mount()
{
$response = Http::get('https://api.example.com/data');
$this->externalData = $response->json();
}
public function render()
{
return view(static::$view);
}
}
نمای Blade:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">دادههای خارجی</h2>
<ul class="space-y-2">
@foreach($externalData as $data)
<li class="text-gray-700">{{ $data['name'] }}: {{ $data['value'] }}</li>
@endforeach
</ul>
</div>
توضیحات:
استفاده از Http Facade: ارسال درخواست GET به API خارجی و دریافت دادهها.
نمایش دادههای دریافتی: نمایش دادههای دریافت شده در نمای Blade.
بهترین روشها برای ایجاد ویجتهای سفارشی
برای ایجاد ویجتهای سفارشی کارآمد و قابل نگهداری، رعایت بهترین روشها ضروری است:
تعیین دقیق نیازها: قبل از شروع به ایجاد ویجت سفارشی، به دقت نیازها و اهداف آن را مشخص کنید تا از ایجاد ویجتهای غیرضروری جلوگیری کنید.
استفاده از استانداردهای کدنویسی: رعایت استانداردهای کدنویسی Laravel و Filament برای افزایش خوانایی و نگهداری کد.
سازگاری با طراحی کلی داشبورد: اطمینان حاصل کنید که ویجتهای سفارشی با طراحی کلی داشبورد هماهنگ هستند و از نظر ظاهری با دیگر ویجتها سازگارند.
بهینهسازی عملکرد: از بارگذاری غیرضروری دادهها جلوگیری کنید و عملکرد ویجت را بهینه کنید تا بارگذاری صفحه سریع باشد.
تست و بازبینی: پس از ایجاد ویجت، آن را به دقت تست کنید تا از عملکرد صحیح و بدون خطا آن اطمینان حاصل شود.
مستندسازی کد: کدهای ویجتهای سفارشی را مستند کنید تا در آینده برای سایر توسعهدهندگان یا خودتان قابل فهم باشد.
نکات پیشرفته برای ویجتهای سفارشی
برای ارتقای کیفیت و قابلیتهای ویجتهای سفارشی، میتوانید از نکات پیشرفته زیر استفاده کنید:
۱. استفاده از کامپوننتهای Livewire
Livewire به شما امکان میدهد تا ویجتهای تعاملی و داینامیک ایجاد کنید که بدون نیاز به بارگذاری مجدد صفحه، بهروز شوند.
مثال: افزودن دکمه برای بارگذاری بیشتر مقالات
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use App\Models\Article;
use Livewire\Component;
class LoadMoreArticlesWidget extends Widget
{
protected static string $view = 'filament.widgets.load-more-articles-widget';
public $articles;
public $limit = 5;
public function mount()
{
$this->loadArticles();
}
public function loadMore()
{
$this->limit += 5;
$this->loadArticles();
}
protected function loadArticles()
{
$this->articles = Article::latest()->take($this->limit)->get();
}
public function render()
{
return view(static::$view);
}
}
نمای Blade:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">مقالات</h2>
<ul class="space-y-2">
@foreach($articles as $article)
<li class="text-gray-700">{{ $article->title }}</li>
@endforeach
</ul>
<button wire:click="loadMore" class="mt-4 px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
بارگذاری بیشتر
</button>
</div>
توضیحات:
متد loadMore(): افزایش تعداد مقالات نمایش داده شده و بارگذاری مجدد مقالات.
دکمه بارگذاری بیشتر: با کلیک بر روی دکمه، متد loadMore اجرا میشود و مقالات بیشتری بارگذاری میشوند.
۲. ادغام با APIهای خارجی
برای نمایش دادههای پیچیدهتر و متنوعتر، میتوانید ویجتهای سفارشی خود را با APIهای خارجی ادغام کنید. به عنوان مثال، نمایش نرخ ارز، وضعیت آب و هوا یا دادههای مالی از منابع مختلف.
مثال: نمایش نرخ ارز از API خارجی
<?php
namespace App\Filament\Widgets;
use Filament\Widgets\Widget;
use Illuminate\Support\Facades\Http;
class CurrencyRatesWidget extends Widget
{
protected static string $view = 'filament.widgets.currency-rates-widget';
public $rates;
public function mount()
{
$response = Http::get('https://api.exchangerate-api.com/v4/latest/USD');
$this->rates = $response->json()['rates'];
}
public function render()
{
return view(static::$view);
}
}
نمای Blade:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">نرخ ارز</h2>
<table class="w-full table-auto">
<thead>
<tr>
<th class="px-4 py-2">ارز</th>
<th class="px-4 py-2">نرخ</th>
</tr>
</thead>
<tbody>
@foreach($rates as $currency => $rate)
<tr>
<td class="border px-4 py-2">{{ $currency }}</td>
<td class="border px-4 py-2">{{ $rate }}</td>
</tr>
@endforeach
</tbody>
</table>
</div>
توضیحات:
دریافت دادهها از API خارجی: استفاده از Http::get برای ارسال درخواست به API نرخ ارز و دریافت دادهها.
نمایش دادهها در جدول: نمایش نرخ ارزها به صورت جدول برای خوانایی بهتر.
۳. افزودن قابلیتهای چندزبانه
اگر پروژه شما چندزبانه است، مطمئن شوید که ویجتهای سفارشی شما از ترجمهها پشتیبانی میکنند. این کار به کاربران نهایی اجازه میدهد تا اطلاعات را به زبان مورد نظر خود مشاهده کنند.
مثال: افزودن پشتیبانی از زبان به ویجت مقالات
فایل Blade با استفاده از ترجمهها:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">{{ __('آخرین مقالات منتشر شده') }}</h2>
<ul class="space-y-2">
@foreach($articles as $article)
<li class="text-gray-700">{{ $article->title }}</li>
@endforeach
</ul>
<a href="{{ route('articles.index') }}" class="mt-4 text-blue-500 hover:underline">{{ __('نمایش همه') }}</a>
</div>
توضیحات:
استفاده از تابع __(): برای ترجمه متون به زبانهای مختلف استفاده میشود.
فایلهای ترجمه: اطمینان حاصل کنید که متون مورد استفاده در ویجتها در فایلهای ترجمه مربوطه تعریف شدهاند.
نکات پیشرفته برای ویجتهای سفارشی
برای ایجاد ویجتهای سفارشی با عملکرد بالا و تجربه کاربری بهتر، میتوانید از نکات پیشرفته زیر بهره ببرید:
۱. استفاده از کامپوننتهای جاوااسکریپت
با افزودن کامپوننتهای جاوااسکریپت به ویجتهای خود، میتوانید قابلیتهای تعاملی و گرافیکی بیشتری به ویجتها اضافه کنید. به عنوان مثال، افزودن نمودارهای تعاملی، اسلایدرها یا مودالها.
مثال: افزودن نمودار تعاملی به ویجت سفارشی
فایل Blade:
<div class="p-4 bg-white rounded-lg shadow">
<h2 class="text-xl font-bold mb-4">نمودار تعاملی فروش</h2>
<canvas id="salesChart" width="400" height="200"></canvas>
</div>
@push('scripts')
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
var ctx = document.getElementById('salesChart').getContext('2d');
var salesChart = new Chart(ctx, {
type: 'bar',
data: {
labels: {!! json_encode($chartData['labels']) !!},
datasets: [{
label: '{{ __("فروش ماهانه") }}',
data: {!! json_encode($chartData['data']) !!},
backgroundColor: 'rgba(54, 162, 235, 0.2)',
borderColor: 'rgba(54, 162, 235, 1)',
borderWidth: 1
}]
},
options: {
responsive: true,
plugins: {
legend: {
display: true,
position: 'top',
},
tooltip: {
enabled: true,
}
},
scales: {
y: {
beginAtZero: true
}
}
}
});
</script>
@endpush
توضیحات:
استفاده از Chart.js: افزودن کتابخانه Chart.js برای ایجاد نمودارهای تعاملی.
دادههای نمودار: ارسال دادههای نمودار از PHP به جاوااسکریپت با استفاده از json_encode.
افزودن افکتهای تعاملی: مانند ابزارکهای نمایش اطلاعات بیشتر هنگام قرار گرفتن موس روی نمودار.
۲. بهینهسازی عملکرد ویجتها
برای اطمینان از عملکرد بهینه ویجتهای سفارشی، نکات زیر را رعایت کنید:
کاهش تعداد درخواستهای پایگاه داده: از تکنیکهای بهینهسازی مانند eager loading استفاده کنید تا تعداد درخواستهای به پایگاه داده کاهش یابد.
استفاده از کشینگ: دادههای پرتکرار را در کش ذخیره کنید تا سرعت بارگذاری ویجت افزایش یابد.
فشردهسازی دادهها: دادههای ارسال شده به نمای Blade را فشرده کنید تا حجم صفحه کاهش یابد.
مثال: استفاده از کشینگ در ویجت مقالات
public function loadArticles()
{
$this->articles = cache()->remember('latest_articles', now()->addMinutes(10), function () {
return Article::latest()->take(5)->get();
});
}
توضیحات:
کش کردن مقالات: با استفاده از متد cache()->remember، مقالات آخرین ۱۰ دقیقه در کش ذخیره میشوند و از ارسال درخواستهای مکرر به پایگاه داده جلوگیری میشود.
ایجاد ویجتهای سفارشی در ویجتها (Widgets) در Filament به شما این امکان را میدهد تا داشبوردهای خود را به شکل دقیق و متناسب با نیازهای پروژهتان سفارشیسازی کنید. با استفاده از مراحل و نکات پیشرفتهای که در این بخش ارائه شد، میتوانید ویجتهای سفارشی با قابلیتهای متنوع و عملکرد بالا ایجاد کنید که تجربه کاربری بهتری را برای کاربران نهایی فراهم میکنند.
نتیجهگیری
در این مقاله به بررسی جامع و کامل ویجتها (Widgets) در Filament پرداختیم و تمامی جنبههای این موضوع را از سطح مبتدی تا پیشرفته پوشش دادیم. ویجتها (Widgets) در Filament ابزارهای قدرتمندی هستند که به شما امکان میدهند داشبوردهای تعاملی و بصریتری را برای پروژههای خود ایجاد کنید. با استفاده از ویجتهای پیشفرض مانند StatsWidget و ChartWidget، میتوانید به سرعت آمارهای کلیدی و نمودارهای متنوعی را در داشبورد خود نمایش دهید.
علاوه بر ویجتهای پیشفرض، یاد گرفتیم که چگونه ویجتهای سفارشی ایجاد کنیم تا نیازهای خاص پروژههای خود را برآورده کنیم. مراحل ایجاد ویجت سفارشی شامل ایجاد کلاس ویجت، طراحی نمای Blade و ثبت ویجت در داشبورد بود که با مثالهای عملی توضیح داده شد. همچنین، با معرفی قابلیتهای پیشرفته مانند افزودن قابلیت جستجو، فیلتر کردن دادهها، ادغام با APIهای خارجی و استفاده از کامپوننتهای جاوااسکریپت، توانستیم به شما نشان دهیم چگونه ویجتهای سفارشی خود را بهبود بخشید و عملکرد آنها را ارتقا دهید.
ویجتها (Widgets) در Filament به دلیل تنوع بالا، قابلیت سفارشیسازی و یکپارچگی بینظیر با فریمورک Laravel، ابزار مناسبی برای توسعهدهندگان جهت ایجاد داشبوردهای حرفهای و کارآمد محسوب میشوند. با رعایت بهترین روشها مانند تعیین دقیق نیازها، بهینهسازی عملکرد و مستندسازی کد، میتوانید ویجتهای سفارشی با کیفیت بالا و قابل نگهداری ایجاد کنید.
برای ارتقای بیشتر دانش خود در زمینه ویجتها (Widgets) در Filament، توصیه میکنیم از منابع معرفی شده در این مقاله استفاده کنید و به صورت عملی پروژههای خود را با استفاده از ویجتها توسعه دهید. همکاری با دیگر توسعهدهندگان و شرکت در انجمنهای آنلاین نیز میتواند به افزایش مهارتها و تبادل تجربیات کمک شایانی کند.
با تسلط بر ویجتها (Widgets) در Filament، قادر خواهید بود داشبوردهایی جذاب، تعاملی و متناسب با نیازهای کاربران خود ایجاد کنید که به بهینهسازی مدیریت و تحلیل دادهها در پروژههای شما کمک خواهد کرد.
