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

Table Generator

Table Generator یک ویژگی متنوع و قدرتمند برای تولید جداول با قابلیت‌های سفارشی است. این ابزار به شما امکان می‌دهد تا برای داده های موجود، جداول پویا ایجاد کنید که شامل ستون‌ها، دکمه های عملیاتی، فیلترها، عملیات دسته‌ای، و دکمه‌های نوار ابزار (Toolbar) است. در مستندات زیر، تمامی امکانات این ویژگی همراه با مثال توضیح داده می‌شود.

شروع به کار​

ایجاد کلاس جدول​

برای شروع، باید یک کلاس جدید ایجاد کنید که از BaseTable ارث‌بری کند.

با دستور زیر می‌توانید یک کلاس جدول جدید ایجاد کنید:

php artisan dornica:make-table SampleTable

همچنین میتوانید برای ایجاد کلاس در ماژول خاصی از دستور زیر استفاده کنید:

php artisan dornica:make-table SampleTable --module=MODULE_NAME
نکته

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


این کلاس به شما امکان می‌دهد تا ساختار جدول را تعریف کنید و ویژگی‌های مختلف آن را سفارشی کنید.

مثال زیر، ساختار کلی یک کلاس جدول را نشان می‌دهد:

<?php

namespace App\Generators\Tables;

use Dornica\PanelKit\Generator\Table\BaseTable;

class SampleTable extends BaseTable
{
    public function __construct()
    {
        $this->setTitle('عنوان جدول');
        $this->setDriver(Driver::MODEL);
        $this->setResource(SampleModel::class);
    }

    public function columns(): void
    {
        // تعریف ستون‌ها
    }

    public function columnActions(): void
    {
        // تعریف دکمه‌های عملیاتی برای هر ستون
    }

    public function filters(): void
    {
        // تعریف فیلترها
    }

    public function toolbar(): void
    {
        // تعریف دکمه‌های نوار ابزار
    }

    public function bulkOperations(): void
    {
        // تعریف عملیات دسته‌ای
    }
}

تنظیمات اولیه​

برای تنظیمات اولیه جدول، می‌توانید در سازنده کلاس (Constructor) از متدهای زیر استفاده کنید:

  • setDriver: برای تعیین درایور جدول
  • setResource: برای تعیین منبع داده‌ها
use Dornica\PanelKit\Generator\Table\Enums\Driver;
use App\Models\Sample;

public function __construct()
{
    $this->setDriver(Driver::MODEL);
    $this->setResource(Sample::class);
}

درایور ها​

برای تعیین منبع داده‌ها، باید از درایورهای مختلف استفاده کنید. درایور به شما امکان می‌دهد تا نحوه دریافت داده‌ها را مشخص کنید.
درایورهای مختلفی برای جدول وجود دارد که هر کدام ویژگی‌های خاص خود را دارند. در ادامه به درایورها اشاره می‌شود.

درایور Model​

  • برای استفاده از مدل‌های Eloquent کاربرد دارد.
  • این درایور به شما امکان می‌دهد تا از مدل‌های Eloquent برای دریافت داده‌ها استفاده کنید.
  • این درایور به صورت پیش‌فرض استفاده می‌شود و نیازی به تنظیمات اضافی ندارد.
  • برای استفاده از این درایور، باید کلاس مدل مورد نظر را به عنوان منبع داده تعیین کنید.
use Dornica\PanelKit\Generator\Table\Enums\Driver;
use App\Models\Bank;

public function __construct()
{
    $this
        ->setDriver(Driver::MODEL) // تعریف درایور
        ->setResource(Bank::class); // تعریف مدل
}

درایور Raw​

  • این درایور اجازه می دهد تا داده های منبع را به صورت خام و بدون استفاده از مدل دریافت کنید.
  • این درایور برای دریافت داده‌ها به صورت Collection کاربرد دارد.
  • به عنوان مثال، اگر بخواهید داده‌ها را از یک API یا منبع دیگر دریافت کنید، می‌توانید از این درایور استفاده کنید.
  • با استفاده از متد setData که داده‌ها را به‌صورت Collection دریافت می‌کند، می‌توانید به دو روشی که در ادامه خواهیم پرداخت، عمل کنید.
use Dornica\PanelKit\Generator\Table\Enums\Driver;

public function __construct()
{
    $this->setDriver(Driver::RAW); // تعریف درایور

    $invoices = collect([
        [
            'id' => 1,
            'tracking_code' => '123456789',
            'created_at' => '2023-01-10 12:00:00'
        ],
        [
            'id' => 2,
            'tracking_code' => '546899999',
            'created_at' => '2023-05-21 12:00:00'
        ],
        [
            'id' => 3,
            'tracking_code' => '675785767',
            'created_at' => '2023-06-07 12:00:00'
        ]
    ]);

    $this->setData($invoices); // تعیین داده های منبع
}
مثال استفاده در Controller
use Dornica\PanelKit\BladeLayout\Facade\BladeLayout;
use App\Generators\Tables\InvoiceTable;

public function index()
{
    BladeLayout::table(InvoiceTable::class); // تعریف جدول

    $invoices = collect([
        [
            'id' => 1,
            'tracking_code' => '123456789',
            'created_at' => '2023-01-10 12:00:00'
        ],
        [
            'id' => 2,
            'tracking_code' => '546899999',
            'created_at' => '2023-05-21 12:00:00'
        ],
        [
            'id' => 3,
            'tracking_code' => '675785767',
            'created_at' => '2023-06-07 12:00:00'
        ]
    ]);

    BladeLayout::table()->setData($invoices); // تعیین داده های منبع

    return view('user.invoices.index');
}

نمایش چندتایی جدول ها در یک صفحه​

برای نمایش چند table در یک صفحه واحد می توان هر جدول را با یک نام یکتا ثبت کنید و آنها را به صورت جداگانه در بلید نمایش دهید

وضعیت مستقل هر جدول

نام یکتایی که هنگام ثبت جدول می‌دهید، در ساخت کلید منبع (resource key) آن جدول هم استفاده می‌شود. به همین دلیل مرتب‌سازی، فیلترها و اندازه‌ی صفحه‌ی هر جدول جداگانه نگه‌داری می‌شود و مرتب‌سازی یک ستون در یک جدول، جدول‌های دیگر همان صفحه را تغییر نمی‌دهد — حتی وقتی هر دو از یک کلاس ساخته شده باشند.

اگر روی چنین صفحه‌ای می‌خواهید با setTableFilters() یا clearTableFilters() فیلتر یک جدول مشخص را تنظیم کنید، همان نام یکتا را به‌عنوان آخرین آرگومان بدهید:

BladeLayout::setTableFilters(
    table: UserTable::class,
    filters: ['filter_status' => 'active'],
    tableKey: 'users',
);

Controller​

public function index()
{
    BladeLayout::table(UserTable::class, 'users');
    BladeLayout::table(ArchivedTable::class, 'archived');

    return view('users.index');
}

Blade​

<x-default-layout>
    {!! bladeLayout()->table('users')->render() !!}

    <div class="mt-10">
        {!! bladeLayout()->table('archived')->render() !!}
    </div>
</x-default-layout>

درایور API​

  • این درایور برای دریافت داده‌ها از یک API خارجی کاربرد دارد.
  • با استفاده از این درایور، می‌توانید داده‌ها را از یک API با استفاده از متدهای HTTP مانند GET, POST, PUT و DELETE دریافت کنید.
  • برای استفاده از این درایور، باید یک منبع API تعریف کنید که شامل اطلاعات اتصال به API، متد HTTP و مسیر (Path) باشد.
  • شما باید از کلاس APIResourceDTO برای تعریف منبع API استفاده کنید.
  • این کلاس شامل پارامترهای زیر است:
    • connection: نام اتصال به API
    • method: متد HTTP (GET, POST, PUT, DELETE)
    • path: مسیر API
  • برای تعریف اتصال به API، باید در فایل config/dornica-panel-kit.php در بخش table_generator.api_connections تنظیمات مربوط به اتصال را انجام دهید.
use Dornica\PanelKit\Generator\Table\Enums\Driver;
use Dornica\PanelKit\Generator\Table\DTO\APIResourceDTO;

public function __construct()
{
    $this
        ->setDriver(Driver::API)
        ->setResource(
            new APIResourceDTO(
                connection: "dornica_provider",
                method: "GET",
                path: "/customers"
            )
        );
}

امکانات و نحوه استفاده​

تعریف ستون‌ها (Column)​

برای تعریف ستون‌ها، میتوانید در متد columns از متد addColumn استفاده کنید.

مثال:​

public function columns(): void
{
    $this->addColumn(
        name: 'title',
        label: __('table.sample.title'),
        type: 'text',
        sortable: true
    );

    $this->addColumn(
        name: 'status',
        label: 'وضعیت',
        type: function ($value, $entity) {
            return $value === 'active' ? 'فعال' : 'غیرفعال';
        },
        sortable: true
    );

    $this->addColumn(
        name: 'image',
        label: 'تصویر',
        type: 'image',
        sortable: false
    );
}
پارامترهای addColumn
  • name: نام ستون
    • در صورتی که از Model Driver استفاده می‌کنید، این نام باید با نام فیلد در مدل مطابقت داشته باشد.
  • label: عنوان قابل مشاهده
    • این عنوان در هدر جدول نمایش داده می‌شود.
  • type: نوع داده
    • شامل انواع مختلفی است که می‌توانید برای نمایش داده‌ها استفاده کنید:
      • text: نمایش متن ساده
      • badge: نمایش به صورت برچسب (Badge)
      • datetime: نمایش تاریخ و زمان
      • image: نمایش تصویر
      • video: نمایش ویدیو
      • تابع سفارشی: می‌توانید یک تابع PHP برای پردازش داده‌ها تعریف کنید.
    • تابع سفارشی می‌تواند برای پردازش داده‌ها یا نمایش آن‌ها به صورت دلخواه استفاده شود.
  • sortable: امکان مرتب‌سازی
    • اگر true باشد، امکان مرتب‌سازی بر اساس این ستون فعال می‌شود.
  • sortCast: نوع داده برای مرتب‌سازی
    • این پارامتر برای تعیین نوع داده‌ای که باید برای مرتب‌سازی استفاده شود، کاربرد دارد.
    • کاربرد این مورد برای Model Driver است و Sorting بر اساس نوع داده‌ انجام می‌شود.
    • این مورد مستقیم بر روی Query تاثیر می‌گذارد و نوع داده را برای مرتب‌سازی استفاده می‌کند.
    • می‌تواند یکی از انواع زیر باشد:
      • string, integer, float, boolean, date, datetime, timestamp
    • اگر مقدار null باشد، نوع داده تعیین نمی شود.
$this->addColumn(
    ...
    sortCast: 'FLOAT'
);
  • labelClass: کلاس CSS برای عنوان ستون
    • این کلاس به شما امکان می‌دهد تا ظاهر عنوان ستون را سفارشی کنید.
  • bodyAlign: تراز متن در بدنه ستون
    • می‌توانید از left, center, یا right برای تعیین تراز استفاده کنید.
  • direction: جهت نمایش داده‌ها
    • می‌توانید از ltr یا rtl برای تعیین جهت استفاده کنید.
  • width: تعیین طول ستون
    • میتوانید به صورت پیکسلی یا درصدی مقدار طول ستون را مشخص کنید.
    • برای ستون‌هایی که با یکدیگر merge می‌شوند این مقدار را باید به ستون اول بدهید.
  • mergeGroup: گروه‌بندی ستون ها
    • سلول هایی که با یک مقدار خاص پر شده‌اند، با هم ادغام می شوند.
  • groupBreakLineSection: محدوده اعمال groupBreakLine
    • در صورتی که میخواهید قابلیت groupBreakLine فقط در header یا body اعمال شود یکی از این دو مقدار را برای آن آن تعیین کنید
  • tooltip: متن راهنما
    • این متن در هنگام قرار دادن ماوس روی ستون نمایش داده می‌شود.
  • permission: مجوز دسترسی
    • این پارامتر برای کنترل دسترسی به ستون استفاده می‌شود. اگر کاربر مجوز لازم را نداشته باشد، ستون نمایش داده نمی‌شود.
    • کلید دسترسی باید به صورت string در این پارامتر قرار گیرد.
  • visibility: قابلیت نمایش یا عدم نمایش ستون
    • این پارامتر به شما امکان می‌دهد تا تعیین کنید که آیا ستون در جدول نمایش داده شود یا خیر.
  • valueVisibility: قابلیت نمایش مقدار هر سطر در ستون
    • این پارامتر برای نمایش/عدم نمایش مقدار ستون به ازای هر رکورد استفاده می‌شود.
    • اگر مقدار آن false باشد، خود ستون حذف نمی‌شود اما مقدار آن سطر نمایش داده نمی‌شود.
    • در صورت استفاده از closure، باید یک پارامتر (entity) بگیرد.
    • این پارامتر برای سناریوهای شرطی سطری مثل نمایش image یا video بر اساس داده رکورد مناسب است.
  • centered: تراز مرکزی
    • اگر true باشد، عنوان ستون در مرکز قرار می‌گیرد.
  • options: تنظیمات اضافی - این پارامتر به شما امکان می‌دهد تا تنظیمات اضافی برای ستون را تعریف کنید.
  • width: عرض ستون - در صورتی که نیاز دارید تا عرض ستون را به صورت دستی تنظیم کنید از این پارامتر استفاده کنید.

مثال‌های valueVisibility​

نمایش تصویر یا ویدیو بر اساس پسوند فایل​

$this->addColumn(
    name: 'file_id',
    type: 'image',
    mergeGroup: 'file',
    label: __('basemodule::field.file'),
    valueVisibility: function ($entity) {
        $extension = strtolower((string) $entity->file?->extension);
        $imageExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'svg'];
        return in_array($extension, $imageExtensions, true);
    }
);

$this->addColumn(
    name: 'file_id',
    type: 'video',
    mergeGroup: 'file',
    valueVisibility: function ($entity) {
        $extension = strtolower((string) $entity->file?->extension);
        $imageExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'svg'];
        return !in_array($extension, $imageExtensions, true);
    }
);
مقادیر مجاز در پارامتر options
  • groupHeadTooltip: متن راهنمای ستون های ادغام شده
    • این متن در هنگام قرار دادن ماوس روی هر یک از سرستون های ادغام شده نمایش داده می‌شود.
    • این کلید باید برای اولین ستون از ستون های ادغام شده در همان گروه اضافه شود.
    • این مورد بر روی نام ستون ها، که در سربرگ جدول قرار دارد تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'groupHeadTooltip' => 'این ستون ها شامل اطلاعات مربوط به وضعیت است'
    ]
);
  • groupBodyTooltip: متن راهنمای بدنه ستون های ادغام شده
    • این متن در هنگام قرار دادن ماوس روی هر یک از سلول های ادغام شده نمایش داده می‌شود.
    • این کلید باید برای اولین ستون از ستون های ادغام شده در همان گروه اضافه شود.
    • این مورد بر روی محتوای سلول ها، که در بدنه جدول قرار دارد تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'groupBodyTooltip' => 'این ستون ها شامل اطلاعات مربوط به وضعیت است'
    ]
);
  • groupBreakLine: آیا ستون های ادغام شده در خط جدید نمایش داده شوند؟
    • اگر true باشد، ستون های ادغام شده در خط جدید نمایش داده می‌شوند.
    • این مورد بر روی نحوه نمایش ستون ها در جدول تاثیر گذار است.
    • ستونی که این مورد را دارد، باعث میشود ستون های بعدی در خط بعد نمایش داده شوند
$this->addFilter(
    ...
    options: [
        'groupBreakLine' => true
    ]
);
  • groupBreakLineSection: امکان انتخاب body و header برای نمایش در خط جدید
    • اگر مقدار body انتخاب شود فقط بدنه جدول به خط بعد منتقل می‌شود.
    • اگر مقدار header انتخاب شود فقط هدر جدول به خط بعد منتقل می‌شود.
    • در صورتی که مقداری داده نشود هر دو بخش جدول در خط جدید نمایش داده می‌شوند.
$this->addFilter(
    ...
    options: [
        'groupBreakLine' => true
        'groupBreakLineSection' => 'header'
    ]
);
  • theadSeparator: جداکننده سرستون ها
    • اگر سرستون های ادغام شده دارید و می‌خواهید بین آن‌ها جداکننده‌ای نمایش داده شود، از این پارامتر استفاده کنید.
    • اگر مقداری تعیین کنید، بین سرستون ها جداکننده تعریف شده نمایش داده می‌شود.
    • به صورت پیش‌فرض / به عنوان جداکننده استفاده می‌شود.
    • این مورد بر روی ظاهر جدول در سربرگ تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'theadSeparator' => '|'
    ]
);
  • tbodySeparator: جداکننده بدنه ستون ها
    • اگر سلول های ادغام شده دارید و می‌خواهید بین آن‌ها جداکننده‌ای نمایش داده شود، از این پارامتر استفاده کنید.
    • اگر مقداری تعیین کنید، بین سلول ها جداکننده تعریف شده نمایش داده می‌شود.
    • به صورت پیش‌فرض جداکننده نمایش داده نمی‌شود.
    • این مورد بر روی ظاهر جدول در بدنه تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'tbodySeparator' => '-'
    ]
);
  • groupOrientation: جهت گروه‌بندی ستون‌ها
    • این پارامتر برای تعیین جهت نمایش ستون‌های ادغام شده استفاده می‌شود.
    • می‌تواند یکی از مقادیر زیر باشد:
      • horizontal: نمایش ستون‌ها به صورت افقی (پیش‌فرض)
      • vertical: نمایش ستون‌ها به صورت عمودی
    • این مورد بر روی نحوه نمایش ستون ها در جدول تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'groupOrientation' => 'vertical'
    ]
);
  • groupHref: لینک گروه‌بندی ستون‌ها
    • این پارامتر برای تعیین لینک گروه‌بندی ستون‌ها استفاده می‌شود.
    • باید به اولین ستون از ستون های ادغام شده اضافه شود.
    • این مورد فقط برای ستون هایی که ادغام شده‌اند کاربرد دارد.
    • اگر مقداری تعیین کنید، در صورت کلیک بر روی یکی از ستون های ادغام شده، کاربر به آدرس مشخص شده هدایت می‌شود.
    • این مورد بر روی نحوه تعامل با سرستون ها تاثیر گذار است.
$this->addFilter(
    ...
    options: [
        'groupHref' => route('sample.group', ['id' => 1])
    ]
);
  • enumLabel: برچسب سفارشی برای Enum ها
    • این پارامتر برای تعیین برچسب سفارشی برای ستون‌های نوع badge که با Enum کار می‌کنند، استفاده می‌شود.
    • می‌تواند یک رشته ثابت یا یک تابع (Closure) باشد.
    • اگر تابع باشد، مقدار Enum به عنوان پارامتر ورودی ارسال می‌شود.
    • اگر تعیین نشود، از ترجمه‌های پیش‌فرض استفاده می‌شود.
// استفاده با رشته ثابت
$this->addColumn(
    name: 'status',
    label: 'وضعیت',
    type: 'badge',
    options: [
        'enumLabel' => 'وضعیت سفارشی'
    ]
);

// استفاده با تابع
$this->addColumn(
    name: 'status',
    label: 'وضعیت',
    type: 'badge',
    options: [
        'enumLabel' => function ($enumValue) {
            return match($enumValue) {
                StatusEnum::ACTIVE => 'فعال',
                StatusEnum::INACTIVE => 'غیرفعال',
                default => 'نامشخص'
            };
        }
    ]
);
  • sortQuery: تابع سفارشی برای مرتب‌سازی
    • این تابع به شما امکان می‌دهد تا منطق مرتب‌سازی ستون را به صورت کامل سفارشی کنید.
    • کاربرد اصلی آن برای مرتب‌سازی بر اساس ستون‌های رابطه‌های تودرتو (Nested Relations) است.
    • باید یک callable باشد که دو پارامتر ورودی دریافت کند: query و direction.
    • پارامتر query نماینده Query Builder است و direction جهت مرتب‌سازی (asc یا desc) می‌باشد.
    • در صورت استفاده از این پارامتر، منطق مرتب‌سازی پیش‌فرض اعمال نخواهد شد.
$this->addColumn(
    name: 'title:event',
    label: __('base::section.eventType'),
    options: [
        'sortQuery' => function ($query, $direction) {
            $query
                ->leftJoin('events as events_sort_alias',
                    'events_sort_alias.id', '=', 'objections.event_id')
                ->leftJoin('event_types as event_types_sort_alias',
                    'event_types_sort_alias.id', '=', 'events_sort_alias.event_type_id')
                ->orderBy('event_types_sort_alias.name', $direction);
        },
    ],
);

تعریف دکمه های عملیاتی (Column Action)​

برای افزودن دکمه‌های عملیاتی برای هر سطر، می‌توانید در متد columnActions با استفاده از addColumnAction اقدام کنید.

مثال:​

public function columnActions(): void
{
    $this->addColumnAction(
        type: 'link',
        title: 'نمایش',
        target: function ($entity) {
            return route('sample.show', ['entity' => $entity->id]);
        },
        iconClass: 'fa-regular fa-eye'
    );

    $this->addColumnAction(
        type: 'modal',
        title: 'ویرایش',
        target: '#editModal',
        attributes: function ($entity) {
            return ['data-id' => $entity->id];
        }
    );
    
    $this->addColumnAction(
        type: "link",
        title: 'حذف',
        target: function ($entity) {
            return route('admin.basic.banks.destroy', encryptValue($entity->id));
        },
        targetMethod: 'DELETE',
        variant: "danger",
        permission: "admin.basic.banks.destroy",
        confirmation: true,
        confirmationMessage: 'آیا از حذف این مورد اطمینان دارید ؟',
        confirmationType: "danger",
    );
}
پارامترهای addColumnAction
  • type: نوع عملیات
    • می‌تواند یکی از انواع زیر باشد:
      • link: لینک ساده که به یک URL هدایت می‌کند.
      • form: فرم که به URL تعیین شده Submit می‌شود (فقط در صورتی که style بر روی button تنظیم شده باشد).
      • modal: پنجره مودال باز می‌کند.
      • button: برای استفاده از Confirmation Callback.
  • title: عنوان دکمه
    • عنوانی که در دکمه نمایش داده می‌شود.
  • target: هدف
    • در انواع زیر، این پارامتر به صورت زیر عمل می‌کند:
      • link: آدرسی که کاربر به آن هدایت می‌شود.
      • form: آدرسی که فرم به آن ارسال می‌شود.
      • modal: شناسه مودال که باید باز شود (# باید در ابتدای شناسه باشد).
    • اگر از callable استفاده می‌کنید، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و URL برگرداند.
  • targetMethod: متد هدف
    • این پارامتر برای تعیین متد HTTP که باید برای ارسال درخواست استفاده شود، کاربرد دارد.
    • می‌تواند GET, POST, PUT, DELETE یا PATCH
  • visibility: قابلیت نمایش
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، نمایش یا عدم نمایش دکمه را تعیین کند.
    • اگر callable باشد، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و یک boolean برگرداند.
    • اگر true باشد، دکمه همیشه نمایش داده می‌شود.
  • disabled: قابلیت غیرفعالسازی
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، دکمه را غیرفعال کند.
    • اگر callable باشد، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و یک boolean برگرداند.
    • اگر false باشد، دکمه همیشه فعال است.
  • style: سبک دکمه
    • می‌تواند dropdown برای نمایش در منوی کشویی یا button برای نمایش به صورت دکمه باشد.
  • variant: تم رنگی دکمه
    • می‌تواند یک رشته باشد که نوع ظاهری دکمه را مشخص می‌کند (مانند primary, secondary, success, danger و غیره).
    • اگر مقدار null باشد، از نوع پیش‌فرض استفاده می‌شود.
    • می‌توانید از Enum موجود در زیرساخت با نام Variant برای تعیین نوع ظاهری استفاده کنید.
use Dornica\BladeComponents\Foundation\Enums\Variant;

$this->addColumnAction(
    ...
    variant: Variant::PRIMARY
);
  • appearance: نوع ظاهری دکمه
    • می‌تواند یکی از انواع زیر باشد:
      • outline: دکمه با حاشیه
      • solid: دکمه با پس‌زمینه پررنگ
      • light: دکمه با پس‌زمینه روشن
      • transparent: دکمه بدون پس‌زمینه
      • none: دکمه بدون هیچ ظاهری
    • اگر مقدار null باشد، از نوع پیش‌فرض استفاده می‌شود.
    • می‌توانید از Enum موجود در زیرساخت با نام Appearance برای تعیین نوع ظاهری استفاده کنید.
use Dornica\BladeComponents\Foundation\Enums\Appearance;

$this->addColumnAction(
    ...
    appearance: Appearance::PRIMARY
);
  • class: کلاس CSS سفارشی
    • این کلاس به شما امکان می‌دهد تا ظاهر دکمه را سفارشی کنید.
  • tooltip: متن راهنما
    • این متن در هنگام قرار دادن ماوس روی دکمه نمایش داده می‌شود.
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، متن راهنما را تعیین کند.
    • اگر callable باشد، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و یک رشته برگرداند.
  • disabledTooltip: متن راهنمای غیرفعال
    • این متن در هنگام قرار دادن ماوس روی دکمه غیرفعال نمایش داده می‌شود.
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، متن راهنمای غیرفعال را تعیین کند.
    • اگر callable باشد، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و یک رشته برگرداند.
  • permission: مجوز دسترسی
    • این پارامتر برای کنترل دسترسی به دکمه استفاده می‌شود. اگر کاربر مجوز لازم را نداشته باشد، دکمه نمایش داده نمی‌شود.
    • کلید دسترسی باید به صورت string در این پارامتر قرار گیرد.
    • کلید دسترسی همان نام Route مورد نظر است.
  • attributes: ویژگی‌های HTML سفارشی
    • این پارامتر به شما امکان می‌دهد تا ویژگی‌های اضافی برای دکمه تعریف کنید.
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، ویژگی‌ها را تعیین کند.
    • اگر callable باشد، باید تابعی باشد که یک پارامتر ورودی (شیء مدل) دریافت کند و یک آرایه از ویژگی‌ها برگرداند.
    • آرایه باید به صورت Associative باشد، به عنوان مثال:
$this->addColumnAction(
    ...
    attributes: [
        'data-id' => $entity->id,
        'class' => 'custom-class',
        'style' => 'color: red;',
    ]
);
  • iconClass: کلاس آیکون
    • این کلاس به شما امکان می‌دهد تا یک آیکون برای دکمه تعیین کنید.
    • اگر مقدار null باشد، آیکون نمایش داده نمی‌شود.
    • می‌توانید از کلاس‌های Font Awesome استفاده کنید.
$this->addColumnAction(
    ...
    iconClass: "fa-regular fa-pen-to-square"
);
  • confirmation: قابلیت تایید
    • اگر true باشد، قبل از اجرای عملیات، یک پنجره به جهت دریافت تاییدیه نمایش داده می‌شود.
  • confirmationMessage: پیام تایید
    • این پیام در پنجره تاییدیه نمایش داده می‌شود.
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، پیام تایید را تعیین کند.
  • confirmationType: نوع پنجره تایید
    • می‌تواند primary, danger, warning, success, یا info باشد.
    • این پارامتر برای تعیین ظاهر پنجره تایید استفاده می‌شود.
  • confirmationIcon: آیکون پنجره تایید
    • این آیکون در پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از آیکون پیش‌فرض استفاده می‌شود.
    • می‌توانید از کلاس‌های Font Awesome استفاده کنید.

  • confirmationConfirmCallback: تابع تایید

    • این تابع در صورت تایید کاربر اجرا می‌شود.
    • مقدار این پارامتر یک رشته است که به‌عنوان کد Javascript در مرورگر اجرا می‌شود؛ می‌تواند نامِ یک تابعِ Javascript که از قبل تعریف شده باشد (مثلاً "submitForm") یا یک عبارتِ کوتاهِ Javascript باشد (مثلاً "document.getElementById('myForm').submit()"). این کد هنگام کلیک روی دکمهٔ تایید در دیالوگ، سمتِ کلاینت اجرا می‌شود.
  • confirmButtonText: متن دکمه تایید
    • این متن در دکمه تایید پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از متن پیش‌فرض استفاده می‌شود.
  • cancelButtonText: متن دکمه لغو
    • این متن در دکمه لغو پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از متن پیش‌فرض استفاده می‌شود.

تعریف فیلترها (Filter)​

برای افزودن فیلتر‌ها که امکان جستجو و محدود کردن داده‌ها را فراهم می‌کنند، در متد filters با استفاده از متد addFilter باید اقدام شود.

مثال:​

public function filters(): void
{
    $this->addFilter(
        name: 'title',
        elementName: 'filter_title',
        elementType: 'text',
        label: 'عنوان',
        operator: '%'
    );

    $this->addFilter(
        name: 'status',
        elementName: 'filter_status',
        elementType: 'select',
        label: 'وضعیت',
        data: [
            [
                'id' => 1,
                'name' => 'فعال',
                'is_active' => true,
                'selected' => false
            ],
            [
                'id' => 2,
                'name' => 'غیر فعال',
                'is_active' => true,
                'selected' => false
            ]
        ]
    );
}
پارامترهای addFilter
  • name: نام فیلد مرتبط با فیلتر.
    • این نام باید با نام فیلدی که در مدل یا منبع داده استفاده می‌شود، مطابقت داشته باشد.
  • elementName: نام المان UI که برای فیلتر استفاده می‌شود.
    • این نام باید یکتا باشد و در فرم فیلترها استفاده می‌شود.
    • باید یک رشته باشد.
  • elementType: نوع فیلتر
    • می‌تواند یکی از انواع زیر باشد:
      • text: فیلتر متنی
      • numeric: فیلتر عددی
      • select: فیلتر انتخابی
      • multiselect: فیلتر چندانتخابی
      • datetime: فیلتر تاریخ و زمان
      • radio_group: فیلتر گروه رادیویی
      • checkbox: فیلتر چک‌باکس
  • label: عنوان فیلتر
    • این عنوان در فرم فیلترها نمایش داده می‌شود.
    • اگر مقدار null باشد، از ترجمه ها استفاده می‌شود.
    • می‌توانید از تابع ()__ برای ترجمه استفاده کنید.
  • range: آیا فیلتر محدوده‌ای است؟
    • اگر true باشد، فیلتر به صورت محدوده‌ای (مثلاً برای تاریخ) عمل می‌کند.
    • در این صورت، دو فیلد برای ورودی نمایش داده می‌شود.
  • operator: عملگر فیلتر
    • این پارامتر برای تعیین عملگر مورد استفاده در فیلتر است.
    • می‌تواند یکی از مقادیر زیر باشد:
      • =: برابر
      • %: شامل (برای جستجوی متنی)
      • in: چندین مقدار
    • اگر مقدار null باشد، از عملگر پیش‌فرض استفاده می‌شود.
  • class: کلاس CSS برای المان فیلتر
    • این کلاس به شما امکان می‌دهد تا ظاهر فیلتر را سفارشی کنید.
    • باید یک رشته باشد.
    • اگر مقدار null باشد، از کلاس پیش‌فرض استفاده می‌شود.
    • این مورد به پارامتر containerClass، مربوط به کامپوننت مورد استفاده در فیلترها اضافه می‌شود.
  • data: داده‌های فیلتر
    • این پارامتر جهت تعیین داده‌های پیش‌فرض برای انتخاب، مربوط به کامپوننت‌های انتخابی یا چندانتخابی است که در فیلترها استفاده می‌شوند.
$this->addFilter(
    name: "is_active",
    elementName: "filter_is_active",
    elementType: "select",
    data: [
        [
            'id' => 1,
            'name' => 'فعال',
            'is_active' => true,
            'selected' => false
        ],
        [
            'id' => 2,
            'name' => 'غیر فعال',
            'is_active' => true,
            'selected' => false
        ]
    ]
);
  • cast: نوع داده برای فیلتر
    • این پارامتر برای تعیین نوع داده‌ای که باید برای فیلتر استفاده شود، کاربرد دارد.
    • می‌تواند یکی از انواع زیر باشد:
      • string, integer, float, boolean, date, datetime, timestamp
    • کاربرد این مورد برای Model Driver و Raw Driver است.
    • این مورد مستقیم بر روی Query تاثیر می‌گذارد و نوع داده را برای محدودیت داده استفاده می‌کند.
    • برای Model Driver بر روی Query و برای Raw Driver بر روی Collection تاثیر می‌گذارد.
    • اگر مقدار null باشد، نوع داده تعیین نمی‌شود.
  • validator: اعتبارسنجی
    • میتوانید با استفاده از قوانین اعتبارسنجی های Laravel، مقدار فیلتر را اعتبارسنجی کنید.
$this->addFilter(
    ...
    validator: filterValidation([
        'required',
        'numeric',
        'max:9999',
        new CustomRule(),
    ]),
);
  • permission: مجوز دسترسی
    • این پارامتر برای کنترل دسترسی به فیلتر استفاده می‌شود. اگر کاربر مجوز لازم را نداشته باشد، فیلتر نمایش داده نمی‌شود.
    • کلید دسترسی باید به صورت string در این پارامتر قرار گیرد.
    • کلید دسترسی همان نام Route مورد نظر است.
  • visibility: قابلیت نمایش فیلتر
    • این پارامتر به شما امکان می‌دهد تا تعیین کنید که آیا فیلتر در فرم نمایش داده شود یا خیر.
    • می‌تواند یک callable باشد که بر اساس شرایط خاص، نمایش یا عدم نمایش فیلتر را تعیین کند.
    • اگر callable باشد، باید تابعی باشد که یک boolean برگرداند.
    • اگر true باشد، فیلتر همیشه نمایش داده می‌شود.
  • withBreakLine: آیا فیلتر در خط جدید نمایش داده شود؟
    • اگر true باشد، فیلتر در خط جدید نمایش داده می‌شود.
    • این پارامتر برای تنظیم نحوه نمایش فیلترها در فرم استفاده می‌شود.
  • options: تنظیمات اضافی
    • این پارامتر به شما امکان می‌دهد تا تنظیمات اضافی برای فیلتر را تعریف کنید.
    • می‌تواند شامل تنظیمات خاصی باشد که در نوع فیلتر مورد استفاده قرار می‌گیرد.
مقادیر مجاز در پارامتر options
  • ویژگی (Attribute) کامپوننت ها در هر نوع
    • در هر نوع فیلتر یک کامپوننت استفاده می شود، برای مثال نوع text از کامپوننت text-input یا numeric از کامپوننت number-input استفاده می کند.
    • می توانید هر یک از ویژگی (Attribute) های کامپوننت مربوط به نوع را در پارامتر options قرار دهید.
$this->addFilter(
    ...
    type: 'number',
    options: [
        'prefix' => 'ریال',
        'hint' => 'مقدار عددی را وارد کنید',
    ]
);
  • escapeSqlWildcards: نادیده گرفتن کاراکتر های خاص در کوئری ها
    • کاراکتر های ٪ و ـ، در کوئری های LIKE خطای منطقی ایجاد میکنند. با استفاده از این گزینه این مشکل برطرف میشود
    • این گزینه صرفا مقادیر true یا false میتوانند داشته باشند.
    • این گزینه صرفا زمانی عملیاتی مشوند که اپراتور کوئری در فیلتر ٪ انتخاب شده باشد.
    • در صورتی که این گزینه انتخاب شود، مقدار آن استفاده میشود در غیر اینصورت مقدار پیشفرض آن true میباشد.
$this->addFilter(
    ...
    options: [
        'escapeSqlWildcards' => false
    ]
);
  • customQuery: تابع سفارشی برای فیلتر کردن داده‌ها
    • این تابع به شما امکان می‌دهد تا یک Query Builder سفارشی برای فیلتر کردن داده‌ها تعریف کنید.
    • باید یک callable باشد که دو پارامتر ورودی دریافت کند: queryBuilder و selected.
    • پارامتر queryBuilder نماینده Query Builder است و selected مقدار انتخاب شده در فیلتر است.
    • این تابع باید Query Builder را بر اساس شرایط خاص شما تغییر دهد.
    • توجه کنید که در صورت استفاده از این پارامتر، باید خودتان منطق فیلتر کردن را در این تابع پیاده‌سازی کنید و دیگر منطق خودکار فیلترها اعمال نخواهد شد.
$this->addFilter(
    ...
    options: [
        'customQuery' => function ($queryBuilder, $selected) {
            //$queryBuilder->where('is_active', $selected);
        }
    ]
);
  • all_label: برچسب گزینه "همه"
    • در صورت عدم انتخاب فیلتر از نوع radio_group، یک گزینه انتخاب شده وجود دارد که با این کلید در options می توان برچسب آن را تعیین کرد.
    • اگر مقدار null باشد، از برچسب "همه" استفاده می‌شود.
$this->addFilter(
    ...
    elementType: "radio_group",
    options: [
        'value' => 1,
        'all_label' => 'همه وضعیت‌ها',
    ]
);
  • active_badge_label: برچسب نشان فعال
    • این برچسب زمانی نمایش داده می‌شود که فیلتر فعال باشد.
    • در صورتی که فیلتری فعال باشد، بخشی برای نمایش فیلترهای فعال به همراه مقادیر آن به صورت badge وجود دارد. این کلید برای تعیین متن badge مربوط به فیلتر از نوع checkbox استفاده می‌شود.
    • اگر مقدار آن null باشد، از مقدار label فیلتر استفاده خواهد شد.
$this->addFilter(
    name: "terms_accepted",
    elementName: "filter_terms_accepted",
    elementType: "checkbox",
    label: "قوانین",
    options: [
        'value' => 1,
        'active_badge_label' => "قبول دارم",
    ]
);
توجه

در صورت استفاده از فیلتر با نوع عددی که حالت بازه‌ای (range) دارد، به نکات زیر توجه کنید:

  • اگر برای هر یک از قسمت‌های بازه (یعنی from و to) مقادیر suffix یا prefix جداگانه‌ای تعریف کنید، باید آن‌ها را با نام‌های fromSuffix, toSuffix, fromPrefix, toPrefix مشخص نمایید.
  • در صورتی که فقط یک مقدار کلی برای suffix یا prefix تعریف کنید، همان مقدار برای هر دو بخش from و to مورد استفاده قرار می‌گیرد.
  • برای تعیین لیبل هر بخش از بازه، می‌توانید به صورت جداگانه از گزینه‌های fromLabel و toLabel استفاده کنید تا متن دلخواه برای هر طرف (شروع و پایان) نمایش داده شود. توجه داشته باشید که خصوصیت label فقط برای فیلد اول کاربرد دارد و روی فیلد دوم تأثیری ندارد. اگر fromLabel و toLabel را تعریف کنید، دیگر مقدار label اعمال نمی‌شود. به طور کلی، توصیه می‌شود برای خوانایی بهتر از همین گزینه‌ها یعنی fromLabel و toLabel استفاده نمایید.
$this->addFilter(
    name: "code",
    elementName: "filter_code",
    elementType: "numeric",
    range: true,
    class: "col-md-6 filter-dir",
    validator: filterValidation([
        new BankBranchCodeRule(),
        'numeric',
        "max:9999"
    ]),
    options: [
        'toPrefix' => 'تا',
        'fromPrefix' => 'از',
        'suffix' => 'دقیقه',
        'fromLabel' => "زمان مطالعه",
        'labelSpaceReserved' => true,
    ]
);

استفاده از Select وابسته با Infinite Scroll​

برای حالتی که لیست گزینه‌های فیلد فرزند زیاد است، می‌توانید فیلد فرزند را به‌صورت select وابسته تعریف کنید و دریافت داده‌ها را از API با اسکرول بی‌نهایت انجام دهید.

  • selectParentId: نام elementName فیلد والد که مقدار آن برای فیلد فرزند ارسال می‌شود.
  • selectRouteName: روت API برای دریافت گزینه‌های فیلد فرزند.
  • selectInfiniteScroll: با مقدار true بارگذاری گزینه‌ها به‌صورت صفحه‌ای (infinite scroll) انجام می‌شود.
  • selectSearchBarVisibility: نمایش جستجو داخل select.
مثال (Parent/Child):​
public function filters(): void
{
    $this->addFilter(
        name: "sample_parent_role",
        elementName: "filter_sample_parent_role",
        elementType: "select",
        label: "Sample Parent (Role)",
        class: "col-lg-4",
        data: prepareSelectComponentData(
            source: Doravel::getModel('role', DoravelComponent::ACCESS_HUB)::query()
                ->orderBy('sort')
                ->get()
        ),
        options: [
            'searchBarVisibility' => true
        ]
    );

    $this->addFilter(
        name: "sample_bank_dependent",
        elementName: "filter_sample_bank_dependent",
        elementType: "select",
        label: "Sample Child (Bank - Infinite)",
        class: "col-lg-4",
        options: [
            'selectParentId' => 'filter_sample_parent_role',
            'selectRouteName' => 'api.admin.api.banks.index',
            'selectInfiniteScroll' => true,
            'selectSearchBarVisibility' => true,
        ]
    );
}

تعریف دکمه‌های نوار ابزار (Toolbar Button)​

برای افزودن دکمه‌هایی در بالای جدول، در متد toolbar با استفاده از متد addToolbarButton میتوانید اقدام کنید.

مثال:​

public function toolbar(): void
{
    $this->addToolbarButton(
        title: 'افزودن آیتم جدید',
        route: route('sample.create'),
        icon: 'fa-solid fa-plus',
        disabled: false,
        tooltip: 'افزودن',
        variant: 'success'
    );
}
پارامترهای addToolbarButton
  • title: عنوان دکمه
    • عنوانی که در دکمه نمایش داده می‌شود.
  • route: لینک دکمه
    • در صورت استفاده از این پارامتر، دکمه به صورت لینک عمل می‌کند و کاربر را به آدرس مشخص شده هدایت می‌کند.
    • اگر مقدار null باشد، دکمه به صورت لینک عمل نمی‌کند.
  • class: کلاس CSS سفارشی
    • این کلاس به شما امکان می‌دهد تا ظاهر دکمه را سفارشی کنید
  • icon: کلاس آیکون
    • این کلاس به شما امکان می‌دهد تا یک آیکون برای دکمه تعیین کنید.
    • اگر مقدار null باشد، آیکون نمایش داده نمی‌شود.
  • variant: تم رنگی دکمه
    • می‌تواند یک رشته باشد که نوع ظاهری دکمه را مشخص می‌کند
    • اگر مقدار null باشد، از نوع پیش‌فرض استفاده می‌شود.
    • می‌توانید از Enum موجود در زیرساخت با نام Variant برای تعیین نوع ظاهری استفاده کنید.
use Dornica\BladeComponents\Foundation\Enums\Variant;

$this->addToolbarButton(
    ...
    variant: Variant::PRIMARY
);
  • disabled: غیر فعال کردن دکمه
    • مقدار مورد قبول این بخش boolean می باشد.
    • پیش فرض این بخش false می باشد.
    • همچنین برای این بخش می توانید از یک function که خروجی آن boolean باشد استفاده کنید .
$this->addToolbarButton(
    ...
    disabled: function(){
        return $userStatus !== 'active';
    }
);
  • tooltip
    • این بخش با دادن یک مقدار string به بالای دکمه مورد نظر یک tooltip اضافه می کند.
    • همچنین می توانید برای این بخش از یک function که خروجی آن string باشد استفاده کنید.
$this->addToolbarButton(
    ...
    tooltip: function(){
        return 'افزودن کاربر';
    }
);
  • disabledTooltip
    • این بخش همه ویژگی های tooltip عادی را دارد .
    • این بخش در صورت فعال بود disabled نمایش داده می شود.
$this->addToolbarButton(
    ...
    disabledTooltip: function(){
        if (!hasAccess('role.create')){
            return 'عدم دسترسی';
        }

        return 'این بخش غیر فعال می باشد';
    }
);
  • appearance: نوع ظاهری دکمه
    • می‌تواند یکی از انواع زیر باشد:
      • outline: دکمه با حاشیه
      • solid: دکمه با پس‌زمینه پررنگ
      • light: دکمه با پس‌زمینه روشن
      • transparent: دکمه بدون پس‌زمینه
      • none: دکمه بدون هیچ ظاهری
    • اگر مقدار null باشد، از نوع پیش‌فرض استفاده می‌شود.
    • می‌توانید از Enum موجود در زیرساخت با نام Appearance برای تعیین نوع ظاهری استفاده کنید.
use Dornica\BladeComponents\Foundation\Enums\Appearance;

$this->addToolbarButton(
    ...
    appearance: Appearance::PRIMARY
);
  • attributes: ویژگی‌های HTML سفارشی
    • این پارامتر به شما امکان می‌دهد تا ویژگی‌های اضافی برای دکمه تعریف کنید.
    • می‌تواند یک آرایه Associative باشد که ویژگی‌ها را به صورت کلید-مقدار تعریف می‌کند.
    • اگر مقدار null باشد، هیچ ویژگی اضافی اضافه نمی‌شود.
$this->addToolbarButton(
    ...
    attributes: [
        'data-bs-toggle' => 'modal',
        'data-bs-target' => '#myModal',
        'class' => 'custom-class',
    ]
);
  • permission: مجوز دسترسی
    • این پارامتر برای کنترل دسترسی به دکمه استفاده می‌شود. اگر کاربر مجوز لازم را نداشته باشد، دکمه نمایش داده نمی‌شود.
    • کلید دسترسی باید به صورت string در این پارامتر قرار گیرد.
    • کلید دسترسی همان نام Route مورد نظر است.
    • اگر مقدار null باشد، دکمه همیشه نمایش داده می‌شود.

تعریف عملیات دسته‌ای (Bulk Operation)​

برای افزودن عملیات دسته‌ای مانند حذف دسته‌جمعی، در متد bulkOperations با استفاده از متد addBulkOperationButton میتوانید اقدام کنید.

مثال:​

public function bulkOperations(): void
{
    $this->addBulkOperationButton(
        id: 'bulk-delete',
        title: 'حذف دسته‌ای',
        route: route('sample.bulk_delete'),
        icon: 'fa-solid fa-trash',
        confirmation: true,
        confirmationMessage: 'آیا مطمئن هستید؟'
    );
}
پارامترهای addBulkOperationButton
  • id: شناسه دکمه
    • این شناسه باید یکتا باشد و برای شناسایی دکمه در عملیات دسته‌ای استفاده می‌شود.
    • این شناسه در HTML به عنوان id عنصر استفاده می‌شود.
  • title: عنوان دکمه
    • عنوانی که در دکمه نمایش داده می‌شود.
  • route: لینک دکمه
    • در صورت استفاده از این پارامتر، دکمه به صورت لینک عمل می‌کند و کاربر را به آدرس مشخص شده هدایت می‌کند.
    • اگر مقدار null باشد، دکمه به صورت لینک عمل نمی‌کند.
  • elementClass: کلاس CSS سفارشی
    • این کلاس به شما امکان می‌دهد تا ظاهر دکمه را سفارشی کنید.
  • icon: کلاس آیکون
    • این کلاس به شما امکان می‌دهد تا یک آیکون برای دکمه تعیین کنید.
    • اگر مقدار null باشد، آیکون نمایش داده نمی‌شود.
    • می‌توانید از کلاس‌های Font Awesome استفاده کنید.
  • disabled: قابلیت غیرفعالسازی
    • اگر true باشد، دکمه غیرفعال می‌شود و کاربر نمی‌تواند بر روی آن کلیک کند.
  • tooltip: متن راهنما
    • این متن در هنگام قرار دادن ماوس روی دکمه نمایش داده می‌شود.
    • اگر مقدار null باشد، هیچ متنی نمایش داده نمی‌شود.
  • disabledTooltip: متن راهنمای غیرفعال
    • این متن در هنگام قرار دادن ماوس روی دکمه غیرفعال نمایش داده می‌شود.
    • اگر مقدار null باشد، هیچ متنی نمایش داده نمی‌شود.
    • این پارامتر فقط در صورتی که disabled برابر با true باشد، کاربرد دارد.
  • confirmation: قابلیت تایید
    • اگر true باشد، قبل از اجرای عملیات، یک پنجره به جهت دریافت تاییدیه نمایش داده می‌شود.
    • اگر مقدار null باشد، از وضعیت پیش‌فرض استفاده می‌شود.
  • confirmationMessage: پیام تایید
    • این پیام در پنجره تاییدیه نمایش داده می‌شود.
    • اگر مقدار null باشد، از پیام پیش‌فرض استفاده می‌شود.
    • این پارامتر فقط در صورتی که confirmation برابر با true باشد، کاربرد دارد.
  • confirmationIcon: آیکون پنجره تایید
    • این آیکون در پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از آیکون پیش‌فرض استفاده می‌شود.
    • می‌توانید از کلاس‌های Font Awesome استفاده کنید.
    • این پارامتر فقط در صورتی که confirmation برابر با true باشد، کاربرد دارد.
  • confirmationType: نوع پنجره تایید
    • می‌تواند primary, danger, warning, success, یا info باشد.
    • این پارامتر برای تعیین ظاهر پنجره تایید استفاده می‌شود.
    • اگر مقدار null باشد، از نوع پیش‌فرض استفاده می‌شود.
    • این پارامتر فقط در صورتی که confirmation برابر با true باشد، کاربرد دارد.
  • confirmButtonText: متن دکمه تایید
    • این متن در دکمه تایید پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از متن پیش‌فرض استفاده می‌شود.
    • این پارامتر فقط در صورتی که confirmation برابر با true باشد، کاربرد دارد.
  • cancelButtonText: متن دکمه لغو
    • این متن در دکمه لغو پنجره تایید نمایش داده می‌شود.
    • اگر مقدار null باشد، از متن پیش‌فرض استفاده می‌شود.
    • این پارامتر فقط در صورتی که confirmation برابر با true باشد، کاربرد دارد.
  • permission: مجوز دسترسی
    • این پارامتر برای کنترل دسترسی به دکمه استفاده می‌شود. اگر کاربر مجوز لازم را نداشته باشد، دکمه نمایش داده نمی‌شود.
    • کلید دسترسی باید به صورت string در این پارامتر قرار گیرد.
    • کلید دسترسی همان نام Route مورد نظر است.
    • اگر مقدار null باشد، دکمه همیشه نمایش داده می‌شود.
  • attributes: ویژگی‌های HTML سفارشی
    • این پارامتر به شما امکان می‌دهد تا ویژگی‌های اضافی برای دکمه تعریف کنید.
    • می‌تواند یک آرایه Associative باشد که ویژگی‌ها را به صورت کلید-مقدار تعریف می‌کند.
    • اگر مقدار null باشد، هیچ ویژگی اضافی اضافه نمی‌شود.
$this->addBulkOperationButton(
    ...
    attributes: [
        'data-bs-toggle' => 'modal',
        'data-bs-target' => '#myModal',
        'class' => 'custom-class',
    ]
);

ردیف‌های ثابت جدول (Pinned Rows)​

گاهی لازم است یک یا چند ردیف — مثلاً سطر «جمع کل» — همیشه در ابتدا یا انتهای جدول دیده شود و مرتب‌سازی ستون‌ها جای آن را عوض نکند. برای این کار از addPinnedRow() استفاده کنید؛ هر بار فراخوانی، یک ردیف اضافه می‌کند (مثل addColumn و addFilter).

BladeLayout::table()
    ->setData($rows)
    ->addPinnedRow([
        'plan_type_name' => 'جمع',
        'total_capacity' => $rows->sum('total_capacity'),
        'used_capacity' => $rows->sum('used_capacity'),
    ]);

هر ردیف را با همان کلیدهایی بسازید که ستون‌های جدول می‌خوانند؛ همان columnRenderer ستون‌ها روی آن اعمال می‌شود. لازم نیست همه‌ی ستون‌ها را پر کنید — ستون‌هایی که مقدار ندهید، خالی نمایش داده می‌شوند.

برای افزودن چند ردیف، متد را چند بار صدا بزنید:

BladeLayout::table()
    ->addPinnedRow(['plan_type_name' => 'جمع کل', 'total_capacity' => 120])
    ->addPinnedRow(['plan_type_name' => 'میانگین', 'total_capacity' => 40]);

تعیین موقعیت (بالا یا پایین)​

به‌صورت پیش‌فرض ردیف‌ها در انتهای جدول قرار می‌گیرند. برای پین‌کردن به ابتدای جدول، موقعیت را با enum مشخص کنید:

use Dornica\PanelKit\Generator\Table\Enums\PinnedRowPosition;

BladeLayout::table()
    ->setData($rows)
    ->addPinnedRow($summaryRow, PinnedRowPosition::TOP)   // ابتدای جدول
    ->addPinnedRow($totalsRow);                           // انتهای جدول (پیش‌فرض)

نتیجه به این شکل رندر می‌شود:

سرجمع        ← پین‌شده بالا
A            ┐
B            ├ رکوردهای صفحه (قابل مرتب‌سازی)
C            ┘
جمع          ← پین‌شده پایین
رفتار این ردیف‌ها

ردیف‌های ثابت اصلاً وارد داده‌ی جدول نمی‌شوند و جدا از آن به ویو داده می‌شوند. نتیجه‌اش:

  • مرتب‌سازی، فیلتر و صفحه‌بندی روی آن‌ها اثر ندارد و همیشه سر جای خود می‌مانند.
  • در شمارش رکوردها و صفحه‌بندی حساب نمی‌شوند (تعداد کل همان تعداد رکوردهای واقعی می‌ماند).
  • در انتخاب گروهی (Bulk Operation) انتخاب نمی‌شوند و دکمه‌های عملیاتی نمی‌گیرند.
  • در تمام صفحات نمایش داده می‌شوند، نه فقط صفحه‌ی اول یا آخر.

تعیین یکجای ردیف‌ها​

اگر مجموعه‌ی ردیف‌ها را از قبل آماده دارید و می‌خواهید موارد قبلیِ همان موقعیت را جایگزین کنید، از setPinnedRows() استفاده کنید:

BladeLayout::table()
    ->setPinnedRows([$totalsRow, $averageRow]);
هشدار

setPinnedRows() ردیف‌های قبلیِ همان موقعیت را پاک می‌کند. برای اضافه‌کردن به موارد موجود، addPinnedRow() را به‌کار ببرید.

متدهای در دسترس​

متدتوضیح
setPinnedRows(iterable $rows, ?PinnedRowPosition $position)تعیین ردیف‌های یک موقعیت (جایگزین موارد قبلیِ همان موقعیت)
addPinnedRow(array|object $row, ?PinnedRowPosition $position)افزودن یک ردیف به همان موقعیت
getPinnedRows(?PinnedRowPosition $position)دریافت ردیف‌های یک موقعیت به‌صورت Collection
hasPinnedRows(?PinnedRowPosition $position)آیا ردیف پین‌شده‌ای وجود دارد؟ بدون آرگومان، هر دو موقعیت را بررسی می‌کند

پارامتر $position در همه‌ی متدها اختیاری است و پیش‌فرض آن PinnedRowPosition::BOTTOM است.

استایل‌دهی​

هر ردیف ثابت در خروجی HTML کلاس x-table-pinned-row می‌گیرد، پس می‌توانید آن را متمایز کنید:

.x-table-pinned-row {
    font-weight: 600;
    background-color: var(--bs-gray-100);
}

تنظیمات اضافی​

اطلاع

در این بخش به تنظیمات اضافی و سفارشی‌سازی‌های مختلف برای جدول می‌پردازیم.
موارد زیر باید در construct کلاس جدول شما قرار گیرند.
موارد را میتوان به صورت زنجیره ای (Chained) نیز استفاده کرد.

تعیین عنوان جدول:​

  • برای تنظیم عنوان جدول، می‌توانید از متد setTitle استفاده کنید.
  • این متد به شما امکان می‌دهد تا عنوان جدول را به صورت دلخواه تنظیم کنید.
  • همچنین اگر تعیین نکنید، از عنوان صفحه استفاده می‌شود.
$this->setTitle('عنوان جدول');

سفارشی Query Builder در Model Driver:​

use Illuminate\Support\Facades\Auth;

$this->getQueryBuilder()
    ->where('user_id', '<', Auth::id());

مرتب‌سازی سفارشی:​

  • برای تنظیم مرتب‌سازی سفارشی بر اساس یک ستون خاص، می‌توانید از متد setCustomReorderQuery استفاده کنید.
  • این متد به شما امکان می‌دهد تا یک Query Builder سفارشی برای مرتب‌سازی داده‌ها تعریف کنید.
$this->setCustomReorderQuery(function ($query) {
    $query->orderBy('created_at', 'desc');
});

غیرفعال‌سازی دکمه مرتب‌سازی مجدد:​

  • برای غیرفعال‌سازی دکمه مرتب‌سازی مجدد (Reorder Button) در نوار ابزار جدول، می‌توانید از متد disableReorderButton استفاده کنید.
  • این متد به شما امکان می‌دهد تا دکمه مرتب‌سازی مجدد را غیرفعال کنید.
  • به صورت پیش‌فرض، اگر جدول دارای ستون مرتب‌سازی (sort) باشد، دکمه مرتب‌سازی مجدد به صورت خودکار نمایش داده می‌شود.
// غیرفعال کردن دکمه مرتب‌سازی مجدد
$this->disableReorderButton();

// یا به صورت صریح
$this->disableReorderButton(true);

// فعال کردن مجدد دکمه (در صورت نیاز)
$this->disableReorderButton(false);

کلاس‌های سفارشی:​

برای تنظیم کلاس‌های سفارشی برای فیلترها، می‌توانید از متد زیر استفاده کنید:

$this->setFilterContainerClass('gy-5');

ویژگی‌های سطر:​

  • برای تنظیم ویژگی‌های سطر، مانند کلاس CSS یا سایر ویژگی‌ها، می‌توانید از متد setRowAttributes استفاده کنید.
  • این متد به شما امکان می‌دهد تا ویژگی‌های HTML سفارشی برای سطرها
  • این مورد به صورت callable نیز قابل استفاده است و می‌توانید بر اساس شرایط خاص، ویژگی‌های سطر را تعیین کنید.
// Array syntax
$this->setRowAttributes([
    'class' => ['bg-secondary', 'opacity-50'],
]);

// Callable syntax
$this->setRowAttributes(function ($entity) {
    return [
        'class' => ['bg-secondary', 'opacity-50']
    ];
});

عدم نمایش داده در صورت عدم اعمال فیلتر:​

در صورت استفاده از این متد، داده‌ها تنها زمانی نمایش داده می‌شوند که فیلتری اعمال شده باشد.

$this->displayDataOnFilter()

درج گروهی:​

  • برای تعیین کلاس درج گروهی می توانید از متد setImport استفاده کنید.
  • با تنظیم این مورد دکمه درج گروهی در toolbar نمایش داده خواهد شد.
  • و همینطور با استفاده از setImportRoute نام route مربوط به فرم درج گروهی را تنظیم کنید:
$this->setImport(SampleImport::class);
$this->setImportRoute('sample.import');

برای ایجاد کنترلر مربوط به فرم درج گروهی کافی است یک کنترلر ایجاد کنید که از ImportController ارث بری کند:

namespace Modules\Book\Http\Controllers;

use Dornica\PanelKit\ImportUI\Controllers\ImportController;

class CustomImportController extends ImportController
{
}

خروجی لیست:​

  • برای تعیین کلاس خروجی لیست می توانید از متد setExport استفاده کنید.
  • با تنظیم این مورد دکمه خروجی لیست در toolbar نمایش داده خواهد شد.
  • و همینطور با استفاده از setExportRoute نام route مربوط به فرم خروجی لیست را تنظیم کنید:
$this->setExport(SampleExport::class);
$this->setExportRoute('sample.export');

برای ایجاد کنترلر مربوط به فرم خروجی لیست کافی است یک کنترلر ایجاد کنید که از ExportController ارث بری کند:

namespace Modules\Book\Http\Controllers;

use Dornica\PanelKit\ExportUI\Controllers\ExportController;

class CustomExportController extends ExportController
{
}

تعیین عدم نمایش «نمایش رکورد از / تا»:​

  • برای تنظیم عدم نمایش «نمایش رکورد از / تا» ، می‌توانید از متد setShowingRecords استفاده کنید.
$this->setShowingRecords(false);

تعیین عدم نمایش optionهای «نمایش در صفحه»:​

  • برای تنظیم عدم نمایش optionهای «نمایش در صفحه» ، می‌توانید از متد setShowingPaginationSizes استفاده کنید.
$this->setShowingPaginationSizes(false);

عدم نمایش کارت دربرگیرنده‌ی جدول:​

  • به‌صورت پیش‌فرض جدول داخل یک کارت (card) رندر می‌شود. اگر می‌خواهید جدول را بدون کارت نمایش دهید (مثلاً وقتی خودتان جدول را داخل یک <x-card> قرار می‌دهید)، می‌توانید از متد withoutCard استفاده کنید.
$this->withoutCard();

عدم نمایش badge تعداد رکورد:​

  • برای عدم نمایش badge تعداد رکورد در نوار ابزار جدول، می‌توانید از متد hideRecordCountBadge استفاده کنید.
$this->hideRecordCountBadge();