پرش به مطلب اصلی

Filter Generator

Filter Generator ابزاری برای تعریف و تولید فیلترهای پویا و قابل سفارشی‌سازی در پنل مدیریت است. این ابزار امکان ایجاد فیلترهای چندسطحی، مدیریت مقادیر پیش‌فرض، کنترل نمایش بر اساس تب فعال و ذخیره‌سازی وضعیت فیلترها در Session را فراهم می‌کند.

ایجاد Filter​

ایجاد یک کلاس فیلتر جدید:

php artisan dornica:make-filter SampleFilter

ایجاد فیلتر در یک ماژول مشخص:

php artisan dornica:make-filter SampleFilter --module=MODULE_NAME
اطلاع

مقدار MODULE_NAME باید نام ماژول شما باشد.

کلاس ایجادشده محل اصلی تعریف فیلترها و تنظیمات آن‌هاست:

namespace App\Generators\Filters;

use Dornica\PanelKit\Generator\Filter\BaseFilter;
use Dornica\PanelKit\Generator\Filter\Builders\Filter;

class SampleFilter extends BaseFilter
{
    public function filters(): array
    {
        return [
            // تعریف فیلترها
        ];
    }
}

متدهای اصلی​

filters​

این متد اصلی است که باید در کلاس فیلتر تعریف شود و آرایه‌ای از فیلترها را بازمی‌گرداند:

public function filters(): array
{
    return [
        Filter::make("username")
            ->title("نام کاربری")
            ->placeholder("یک نام کاربری انتخاب کنید"),
        
        Filter::make("status") // تعریف فیلتر وضعیت
            ->title("وضعیت")
            ->items([
                ['id' => 1, 'title' => 'فعال'],
                ['id' => 2, 'title' => 'غیرفعال'],
                ['id' => 3, 'title' => 'معلق'],
            ]),
    ];
}

defaults​

این متد مقادیر پیش‌فرض فیلترها را تعریف می‌کند:

public function defaults(): array
{
    return [
        'status' => 1 // مقدار پیش‌فرض برای فیلتر وضعیت
    ];
}

ویژگی‌های فیلتر (Properties)​

هر فیلتر می‌تواند ویژگی‌های زیر را داشته باشد:

  • id شناسه یکتای فیلتر
  • title عنوان فیلتر
  • placeholder متن راهنما داخل فیلتر
  • visibility وضعیت نمایش فیلتر (true/false یا callback)
  • selected مقدار انتخاب شده فعلی
  • only نمایش فیلتر فقط در تب‌های مشخص شده
  • except عدم نمایش فیلتر در تب‌های مشخص شده
  • items آیتم‌های فیلترهای انتخابی
  • dependOnParentID وابستگی به فیلتر والد
  • dependOnRoute مسیر وابستگی برای لود داینامیک

کنترل نمایش فیلترها​

کنترل بر اساس visibility​

می‌توانید نمایش فیلترها را به صورت شرطی کنترل کنید:

Filter::make("admin_only")
    ->title("فیلتر مدیریتی")
    ->visibility(function() {
        return auth()->user()->isAdmin();
    }),

کنترل بر اساس تب فعال​

می‌توانید فیلترها را فقط در تب‌های خاصی نمایش دهید:

Filter::make("tab_specific")
    ->title("فیلتر مخصوص تب")
    ->only(['details', 'settings']) // فقط در تب‌های تعیین شده نمایش داده می شود
    ->except(['summary']), // در تب تعیین شده نمایش داده نمی شود

فیلترهای وابسته (Dependent Filters)​

می‌توانید فیلترهایی ایجاد کنید که مقادیرشان وابسته به انتخاب فیلتر دیگر باشد:

public function filters(): array
{
    return [
        Filter::make("province_id")
            ->title("استان")
            ->placeholder("استان را انتخاب کنید")
            ->items($this->getProvinces()),

        Filter::make("city_id")
            ->title("شهر")
            ->placeholder("شهر را انتخاب کنید")
            ->dependOnParentID("province_id")
            ->dependOnRoute('admin.locations.cities.by-province'),
    ];
}

در مثال بالا، فیلتر شهرها فقط پس از انتخاب استان لود می‌شود.

دریافت مقادیر فیلترها​

دریافت تمام مقادیر​

// دریافت تمام مقادیر فیلترها به صورت آرایه
$values = GeoFilter::values();

// یا در کنترلر
$values = BladeLayout::filter()->getCurrentValues();

دریافت مقدار یک فیلتر خاص​

// دریافت مقدار یک فیلتر خاص
$provinceId = GeoFilter::value('province_id');

// یا در کنترلر
$provinceId = BladeLayout::filter()->value('province_id');

بررسی وجود فیلتر​

if (BladeLayout::filter()->exists()) {
    // فیلترها وجود دارند
}

تنظیم مقادیر فیلترها​

تنظیم دسته‌جمعی مقادیر​

// تنظیم تمام مقادیر یک‌جا
GeoFilter::setValues([
    'province_id' => 5,
    'city_id' => 23,
    'status' => 'active',
]);

تنظیم تکی مقادیر​

// تنظیم مقدار یک فیلتر
GeoFilter::setValue('city_id', 5);

استفاده در Blade Layout​

برای استفاده از فیلترها در layout، ابتدا باید فیلتر را به BladeLayout اضافه کنید:

// در کنترلر
public function show()
{
    BladeLayout::filter(GeoFilter::class);
    
    return view('your-view');
}

سپس به صورت خودکار این فیلتر به صفحه مورد نظر اضافه می گردد

مثال کامل​

کلاس فیلتر​

<?php

namespace Modules\FilterGenerator\Generators\Filters;

use Dornica\PanelKit\Generator\Filter\BaseFilter;
use Dornica\PanelKit\Generator\Filter\Builders\Filter;

class GeoFilter extends BaseFilter
{
    public function filters(): array
    {
        return [
            Filter::make("province_id")
                ->title("استان")
                ->placeholder("استان را انتخاب کنید")
                ->items($this->getProvinces())
                ->only(['details', 'map']),

            Filter::make("city_id")
                ->title("شهر")
                ->placeholder("شهر را انتخاب کنید")
                ->dependOnParentID("province_id")
                ->dependOnRoute('admin.locations.cities.by-province')
                ->only(['details']),

            Filter::make("status")
                ->title("وضعیت")
                ->items([
                    ['id' => 'active', 'title' => 'فعال'],
                    ['id' => 'inactive', 'title' => 'غیرفعال'],
                ])
                ->visibility(function() {
                    return auth()->user()->can('view-status-filter');
                }),
        ];
    }

    public function defaults(): array
    {
        return [
            'status' => 'active',
        ];
    }

    private function getProvinces(): array
    {
        return [
            ['id' => 1, 'title' => 'تهران'],
            ['id' => 2, 'title' => 'اصفهان'],
            ['id' => 3, 'title' => 'خراسان رضوی'],
        ];
    }
}

کنترلر​

<?php

namespace Modules\FilterGenerator\Http\Controllers;

use App\Http\Controllers\Controller;
use Dornica\PanelKit\BladeLayout\Facade\BladeLayout;
use Modules\FilterGenerator\Generators\Filters\GeoFilter;

class GeoController extends Controller
{
    public function show()
    {
        // اضافه کردن فیلتر به layout
        BladeLayout::filter(GeoFilter::class);
        
        // دریافت مقادیر فیلترها
        $provinceId = GeoFilter::value('province_id');
        
        return view('filtergenerator::geo.show', compact('provinceId'));
    }
    
    public function updateFilter()
    {
        // به‌روزرسانی مقادیر فیلتر
        GeoFilter::setValues(request()->only(['province_id']));
        
        return redirect()->back();
    }
}

view​

در view نیاز به استفاده از render نیست و filter به صورت خودکار به صفحه اضافه می شود .