گاهی اوقات طراحی قسمت front یک سایت کامل شده و می‌خواهیم با صرف کمترین هزینه و زمان قسمت Back را هم پیاده‌ سازی کنیم. قطعا راه‌های بسیار زیادی پیش‌رویمان قرار دارد و اغلب اوقات انتخاب بهینه‌ترین راه، از میان آن‌ها وقت زیادی از ما می‌گیرد. برای ساخت پنل ادمین با لاراول ما Voyagerرا به شما پیشنهاد می‌کنیم. Voyager یک رابط کاربری (Interface) از پیش ساخته شده و کاملا رایگان است که برای ساخت پنل ادمین با لاراول مدیریت قسمت Admin یا Back سایتمان تحت freamwork لاراول است که به راحتی و در کمترین زمان در اختیار ما قرار می‌گیرد‌.

آشنایی با laravel voyager:

در ابتدا می‌خواهیم یک پیش‌زمینه‌ای برای یادگیری هر‌چه بهتر این آموزش کسب کنیم. پس در ادامه همراه ما باشید.

ویژگی‌ها:

Voyager قطعا یکی از ساده‌ترین راه‌ها برای اضافه کردن، حذف کردن و ویرایش هر نوع اطلاعاتی می‌باشد، همچنین اگر تا حدودی با Freamwork لاراول آشنایی داشته باشید می‌دانید که ایجاد ارتباط بین داده ها، به طور مثال ارتباط‌های Many-to-Many کمی زمانگیر است. اما با Voyager ایجاد این ارتباط تنها چند ثانیه زمان می‌برد. در Voyager هنگام کار با database معمولا با عبارتی به نام BREAD روبرو می‌شوید. این عبارت مخفف ۵ عملی است که هنگام استفاده از  Voyager قادر به اعمال بر روی database است. یعنی Browse, Read, Edit, Add, Delete که در قسمت دوم آموزش Voyager به‌طور کامل با آنها آشنا خواهید شد.

پیش نیاز‌ها :

حداقل پیش‌نیاز‌ها برای نصب آخرین نسخه، Laravel 6  و PHP 7.3 است. (در صورتی که نسخه ی لاراول شما Laravel5 باشد به‌صورت خودکار ورژن ۱.۳ Voyager نصب خواهد شد.)

Voyager یک CMS است ؟

توجه کنید که Voyager به‌ خودی‌ خود یک CMS یا platform برای وبلاگ‌ نویسی نیست. ولی می‌توانیم برای ساخت یک CMS یا platform وبلاگ نویسی از آن استفاده کنیم. همچنین Voyager کاملا با Wordpress متفاوت می‌باشد.

نحوه‌ی نصب

در ادامه مقاله‌ی ساخت پنل ادمین با لاراول ، نحوه‌ی نصب Voyager  را توضیح می‌دهیم. به‌طور کلی نصب Voyager شامل ۳ مرحله‌ی زیر می‌باشد:

۱. نصب پکیج‌های لازم توسط Composer :

برای نصب این پکیج‌ها کافیست در پوشه‌ای که پروژه‌ی لاراول خود را ایجاد کردید دستور زیر را اجرا کنید.

composer require tcg/voyager

۲. ساخت database و سفارشی‌سازی آن :

ابتدا یک database در هاست می‌سازیم. سپس فایل env. را با توجه به database به‌صورت زیر ویرایش می‌کنیم :

APP_URL=https://localhost
DB_HOST=localhost
DB_DATABASE=databasename
DB_USERNAME=root
DB_PASSWORD=

۳. نصب Voyager :

نصب Voyager دو حالت دارد. در حالت اول تعدادی داده که شامل ۱ اکانت ادمین (در صورت وجود نداشتن کاربری دیگر در database و جدول user)، یک صفحه‌ی دمو، ۴ پست، ۲ دسته بندی و ۷ فیلد تنظیمات است، به‌صورت پیش فرض وجود دارد و حالت دوم بدون امکانات پیش‌فرض است. برای نصب voyager با امکانات حالت اول یا dummy data دستور زیر را را اجرا کنید :

php artisan voyager:install --with-dummy

برای نصب Voyager بدون امکانات پیش‌فرض دستور زیر را اجرا کنید :

php artisan voyager:install

اگر در هنگام نصب با ارور Specified key was too long روبرو شدید بدین معناست که نسخه Mysql شما قدیمی است. پس از بروز‌‌رسانی آن، دوباره مرحله‌ی قبل را انجام دهید.

حال voyager نصب شده است و کافیست دستور زیر را اجرا کنید تا سرور شما run شود.:

php artisan serve

سپس وارد آدرس https://localhost:8000/admin شوید.

ورود به پنل کاربری :

در ادامه‌ی مقاله‌ی ساخت پنل ادمین با لاراول ، نحوه‌ی ورود به پنل کاربری را توضیح می‌دهیم. ۱. در صورتی که Voyager را با حالت اول یعنی همراه با داده‌های پیش فرض نصب کردید، همان‌طور که گفتیم، کاربر ساخته شده است و با مشخصات زیر می‌توانید وارد شوید:

email: admin@admin.com

password: password

۲.در صورتی که Voyager را با حالت دوم یعنی بدون داده‌های پیش فرض نصب کردید، باید توسط دستور زیر ابتدا یک Admin بسازید.

php artisan voyager:admin your@email.com –create

پس از اجرای دستور بالا از شما یک username و password دلخواه خواسته می‌شود. حال می‌توانید با email و password خود وارد پنل کاربری‌ خود شوید.

بروزرسانی Voyager :

در صورتی که از قبل Voyager را نصب کرده بودید و تنها می‌خواهید آن را بروزرسانی کنید این قسمت مقاله‌ی ساخت پنل ادمین با لاراول ، را مطالعه کنید در غیر این صورت می‌توانید از این قسمت بگذرید.

بروز‌رسانی composer.json :

برای بروزرسانی ابتدا در composer.json مقدار tcg/voyager را به‌صورت زیر وارد کنید. سپس دستور composer update را اجرا کنید.

Tcg/voyager”: “1.4.*

بروز‌رسانی roles Bread :

ابتدا وارد آدرس https://localhost:8000/admin/bread/roles/edit شوید. سپس قسمت Controller Name را به TCG\Voyager\Http\Controllers\VoyagerRoleController تغییر دهید.

کانفیگ‌ها :

در این قسمت از مقاله‌ی ساخت پنل ادمین با لاراول ، به توضیح نحوه‌ی کانفیگ voyager می‌پردازیم. پس از نصب Voyager فایل جدیدی به پوشه config با نام voyager.php افزوده می‌شود. (config/voyager.php) در این فایل امکانات مختلفی قابل مشاهده است که به صورت جداگانه به توضیح هر کدام می‌پردازیم. توجه : در صورت cache شدن فایل کانفیگ دستور زیر را اجرا کنید.

php artisan config:clear

 Users :

<?php
'user' => [
    'add_default_role_on_register' => true,
    'default_role'                 => 'user',
    'admin_permission'             => 'browse_admin',
    'namespace'                    => App\User::class,
    'redirect'                     => '/admin'
]

add_default_role_on_register : مشخص می‌کند که آیا مایلید به هر کاربر جدیدی که ایجاد می‌شود نقش پیش‌فرضی بدهید. default_role : نقش پیش فرض هر کاربر admin_permission : برای دیدن داشبورد Admin به admin_permission نیازمندیم. namespace :  namespace کلاس User برنامه‌های ما را مشخص می‌کند. redirect : آدرسی که کاربر پس از Log in به آن صفحه می‌رود.

Controller :

<?php
'controllers' => [
    'namespace' => 'TCG\\Voyager\\Http\\Controllers',
]

namespace : این قسمت مشخص کننده namespace برای controller است. در صورتی که بخواهیم تغییراتی در توابع هسته‌ا‌‌ی Voyager ایجاد کنیم می‌توانیم namespace را از controller اصلی به controller سفارشی خود تعییر دهیم.

Model :

<?php
'models' => [
    //'namespace' => 'App\\',
]

namespace : namespace یا مسیر Model ‌های برنامه‌ی ما را مشخص می‌کند.

Assets :

<?php
'assets_path' => '/vendor/tcg/voyager/assets',

assets_path : در برخی شرایط لازم است که مسیر asset را تغییر دهیم . به‌طور مثال زمانی که سایت ما در پوشه ای درون پوشه‌‌ اصلی اجرا شده باشد باید نام آن پوشه را به assets_path اضافه کنیم، همچنین فرض کنید می‌خواهید تغییراتی در فایل asset اصلی خود ایجاد کنید در این صورت می‌توانید از فایل asset اصلی کپی گرفته و فایل کپی شده را تغییر دهید. سپس باید assets_path را به مسیر فایل جدیدی که ساختیم تغییر دهیم.

Storage :

<?php
'storage' => [
    'disk' => 'public',
]

disk : به‌صورت پیش فرض Voyager از public local storage استفاده می‌کند که می‌توانیم آن را به هر driver دیگری که در config/filesystems.php وجود دارد مانند  S3 یا Google Cloud Storage  تغییر بدهیم.

Database :

<?php
'database' => [
    'tables' => [
        'hidden' => ['migrations', 'data_rows', 'data_types', 'menu_items', 'password_resets', 'permission_role', 'settings'],
    ],
    'autoload_migrations' => true,
]

hidden : ممکن است بخواهیم برخی از جداول database را در بخش پایگاه داده (Voyager (database مخفی کنیم. برای این‌کار نام جدول مورد نظر را در این قسمت می‌آوریم. autoload_migrations : در صورت true بودن، پس از اجرای دستور php artisan migrate تمامی migration‌ها اجرا و جداول database ساخته می‌شوند.

Multilingual :

<?php
'multilingual' => [
    'enabled' => false,
    'default' => 'en',
    'locales' => [
        'en',
        //'pt',
    ],
]

enabled : اگر 'enabled => 'true باشد یعنی می‌خواهیم سایتی چندزبانه داشته باشیم. default : زبان پیش فرض را انتخاب می‌کنیم. locals : زبان‌ها را انتخاب می‌کنیم. به‌طور مثال 'fa'

Dashboard :

<?php
'dashboard' => [
    'navbar_items' => [
        'Profile' => [
            'route'         => 'voyager.profile',
            'classes'       => 'class-full-of-rum',
            'icon_class'    => 'voyager-person',
        ],
        'Home' => [
            'route'         => '/',
            'icon_class'    => 'voyager-home',
            'target_blank'  => true,
        ],
        'Logout' => [
            'route'      => 'voyager.logout',
            'icon_class' => 'voyager-power',
        ],
    ],
    'widgets' => [
        'TCG\\Voyager\\Widgets\\UserDimmer',
        'TCG\\Voyager\\Widgets\\PostDimmer',
        'TCG\\Voyager\\Widgets\\PageDimmer',
    ],
]

در بخش dashboard می‌توانیم navbar_items را اضافه کنیم، جدول داده‌ها (data_tables) را responsive کنیم و widget‌ها را مدیریت کنیم. navbar_items : در این قسمت می‌توانیم یک item جدید با یک route جدید برای dropdown موجود در navbar بسازیم. data_tables : اگر ‘responsive’ را true کنیم، در این صورت database ما responsive می‌شود. widgets : می‌توانیم تمام widgets موجود در قسمت dashboard را مدیریت کنیم. همچنین می‌توانید نگاهی به widget ها‌ی فعلی‌تان در بخش tcg/voyager/src/widgets بیاندازید.

Primary color :

<?php
'primary_color' => '#22A7F0',

primary_color : رنگ پیش‌ فرض primary_color برای داشبورد ادمین آبی روشن می‌باشد و با تغییر مقدار آن می‌توانید داشبورد خود را به همان‌گونه که می‌پسندید مشاهده نمایید.

Show developer tips :

<?php
’show_dev_tips' => true,

در بخش admin همیشه تعدادی نکته یا اطلاعیه برای توسعه دهندگان نمایش داده می‌شود. در صورتی که مقدار show_dev_tips برابر با false باشد این نوع نکات و اطلاعیه‌ها دیگر نشان داده نمی‌شوند.

Additional stylesheets :

<?php
'additional_css' => [
//'css/custom.css',
]

additional_css : می‌توانید stylesheet‌های دلخواه خود را که در داشبورد ادمین نمایش داده می‌شود، اضافه کنید. این بدان معناست که شما از لحاظ فنی می‌توانید با اضافه کردن stylesheet سفارشی خود، قالب یا theme کاملاً جدیدی را برای Voyager ایجاد کنید.

Additional Javascript :

<?php
'additional_js' => [
    //'js/custom.js',
]

additional_js : همانند بالا می‌توانید فایل‌های javascript دلخواه خود را که در داشبورد ادمین اجرا می‌شود، اضافه کنید.

Google Maps :

<?php
'googlemaps' => [
    'key'    => env('GOOGLE_MAPS_KEY', ''),
    'center' => [
        'lat' => env('GOOGLE_MAPS_DEFAULT_CENTER_LAT', '32.715738'),
        'lng' => env('GOOGLE_MAPS_DEFAULT_CENTER_LNG', '-117.161084'),
    ],
    'zoom' => env('GOOGLE_MAPS_DEFAULT_ZOOM', 11),
]

یک نوع داده‌ی جدید به نام coordinates وجود دارد که به شما امکان می‌دهد یک نقشه‌ی گوگل یا همان Google map را به عنوان یک داده اضافه کنید. کاربر می‌تواند یک pin را در نقشه drag and drop کند تا مقدار طول و عرض جغرافیایی آن را در database ذخیره نماید.

Allowed Mimetypes :

برای مجاز کردن یا نکردن mimetype فایل‌هایی که می‌خواهیم بتوانند از طریق media-manager آپلود شوند، آن‌ها را در آرایه‌ی allowed_mimetypes به‌صورت زیر وارد می‌کنیم.

<?php
'allowed_mimetypes' => [
     'image/jpeg',
     'image/png',
     'image/gif',
     'image/bmp',
     'video/mp4',
]

کاربران فقط می‌تواند فایل‌هایی با mimetype بالا را آپلود نمایند. اگر می‌خواهید همه نوع فایل‌ها مجاز باشند، می‌توانید دستور زیر را وارد کنید :

<?php
'allowed_mimetypes' => '*',

BREAD :

هنگام افزودن یا ویرایش BREAD فعلی برای یک جدول database، ابتدا اطلاعات BREAD را مشاهده می‌کنیم که به شما این اجازه را می‌دهد که نام، اسلاگ (slug)، آیکون (namespace ،(icon مدل و کنترلر و نام خط مشی یا Policy Name را تنظیم کنید. همچنین می‌توانید مجوزهایی را برای BREAD ایجاد کنید. اگر کمی پایین‌تر بیایید با منویی دیگر روبرو می‌شوید. در این منو تعیین می‌کنید که در چه جاهایی می‌خواهید به‌طور مثال field‌های updated_at ,created_at ,name ,id نمایش داده شود. field : Browse‌ها هنگام مرور داده‌ها نمایش داده می‌شوند. field : Read‌ها هنگامی که برای مشاهده‌ی اطلاعات یک داده بر ‌روی آن کلیک می‌کنیم نمایش داده می‌شوند. field : Edit‌ها هنگام ویرایش یک داده‌ نمایش داده می‌شوند. field : Add‌ها زمان اضافه کردن یک داده‌ نمایش داده می‌شوند. Delete : این قسمت به delete مربوط نمی‌شود. پس می‌تواند تیک خورده یا نخورده باشد. همچنین می‌توانید مشخص کنید که برای هر field از چه نوع فرمی می‌خواهید استفاده کنید. این فرم‌ها می‌توانند یک TextBox TextArea ،Checkbox ،Image و یا فرم‌های دیگری باشد. هر field دارای جزییات یا Option‌های اضافی دیگری است که می‌تواند به آن اضافه شود. این Option‌ها عبارتند از dropdown ،radio button و تصاویر.

مثال:

فرض کنید می‌خواهید در بخش Menu و هنگام Edit، نام و شناسه‌ی Menu نمایش داده نشود. برای این‌کار کافیست از قسمت field‌ها و بخش name و id ، تیک Edit را برداریم.

اعتبار‌سنجی (Validation) :

اگر توجه کرده‌ باشید در تصویر قبل و هنگام سفارشی‌ سازی field‌ها به‌طور مثال در بخش name با قسمتی به‌نام Optional Details روبرو می‌شویم که می‌توانیم در این قسمت قوانین خاصی را با فرمت JSON تعریف کنیم. فرض کنید می‌خواهید یک field مانند name بیش از ۱۲ حرف یا خالی نباشد. کافیست کد زیر را در قسمت Optional Details آن وارد کنید :

{
    "validation": {
        "rule": "required|max:12"
    }
}

همچنین می‌توانیم قوانین بالا را به به‌صورت زیر تعریف کنیم :

{
    "validation": {
        "rule": [
            "required",
            "max:12"
        ]
    }
}

حال می‌خواهیم چند error سفارشی اضافه کنیم که به‌صورت زیر انجام می‌شود :

{
    "validation": {
        "rule": "required|max:12",
        "messages": {
            "required": "This :attribute field is a must.",
            "max": "This :attribute field maximum :max."
        }
    }
}

اعتبارسنجی برای بیش از یک field :

به‌صورت زیر می‌توانیم برای بیش از یک field به تعداد دلخواه قانون تعیین کنیم :

{
    "validation": {
        "rule": "min:3",
        "edit": {
            "rule": "nullable"
        },
        "add": {
            "rule": "required"
        }
    }
}

می توانید لیستی از کلیه قوانین موجود در لاراول برای اعتبارسنجی را در Laravel Docs مشاهده نمایید.

Tagging

فرآیند Tagging یا برچسب زدن این امکان را به شما می‌دهد که هنگام ویرایش یا اضافه کردن BREAD، موارد جدیدی را به یک رابطه Belongs-To-Many اضافه کنید. برای فعال کردن این عملکرد، باید Tagging را در relationship details فعال کنید. حال می‌توانید متنی را در قسمت select وارد کنید و Enter را کلیک کنید تا یک relation جدید ایجاد شود.

توجه : حتما تمام field‌ها دارای مقداری پیش‌فرض یا nullable باشند.

مرتب‌سازی item‌ها در BREAD :

ما می‌توانیم ترتیب نمایش item‌ها را توسط drag and drop به‌صورت دلخواه انتخاب کنیم. برای این‌کار ابتدا وارد قسمت Edit در BREAD می‌شویم . Order column : یک field در جدول شما که محل ذخیره‌سازی odrer‌ها به‌صورت integer یا عدد صحیح است. Order display column : یک field که در لیست drag and drop نمایش داده می‌شود.  Order direction : نحوه‌ی مرتب‌سازی item‌ها را تعیین می‌کند. (صعودی یا نزولی) حال به صفحه‌‌ی Browse در قسمت BREAD می‌رویم. همان‌طور که مشاهده می‌کنید بخشی به نام Order وجود دارد. با کلیک کردن دکمه‌ی Order به بخش مرتب‌سازی item‌ها می‌رویم. که در این بخش توسط drag and drop به این کار می‌پردازیم.

سفارشی‌‌سازی داده‌های

اگر می‌خواهید نتایج Browse را برای یک BREAD فیلتر کنید، کافیست یک Scope در Model خود ایجاد کنید. به عنوان مثال اگر می‌خواهید فقط پست‌هایی را که توسط کاربر فعلی ایجاد شده است نشان دهید، یک Scope به‌صورت زیر تعریف کنید :

<?php
public function scopeCurrentUser($query)
{
    return $query->where('author_id', Auth::user()->id);
}

سپس به تنظيمات BREAD برای Posts رفته و از قسمت currentUser ،Scope را انتخاب کنید . با انتخاب Submit، از این به بعد تنها پست‌های کاربر فعلی نمایش داده می‌شود.

ارتباط‌ها (Relationships)

با استفاده از BREAD builder می‌توانیم بین table‌ها ارتباط برقرار کنیم. که در این بخش از مقاله‌ی ساخت پنل ادمین با لاراول ، به توضیح این مورد می‌پردازیم.  البته اگر هنوز BREAD را برای جدول ایجاد نکرده اید، ابتدا باید یک BREAD برای جدولتان بسازید، سپس به قسمت ویرایش BREAD یا Edit بروید و در پایین صفحه با کلیک برروی Create a Relationship به صفحه‌ی ساخت Relationships بروید. برای ایجاد relation، ابتدا در قسمت Post نوع ارتباط، در قسمت User نام جدول مورد نظر، در قسمت namespace ,App\User جدول و در قسمت author_id سطری از جدول که به‌صورت مستقیم با جدولی که با آن relation ایجاد می‌کنید در ارتباط است، را انتخاب می‌کند. همچنین می‌توانید مشخص کنید که کدام ستون را در dropdown یا multi-select می‌خواهید مشاهده کنید. حال به‌راحتی می‌توانید هر کدام از ارتباطات hasOne ,belongsTo ,belongsToMany و hasMany را با کلیک برروی Add New relationship ایجاد کنید.

تنظیمات پیشرفته :

اگر می‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌خواهید تنظیمات پیشرفته‌ای برروی ارتباطات belongsToMany اعمال کنید. کافیست پس از ساخت relationship، دستورات زیر را در قسمت Relationship Details وارد کنید.

{
    "foreign_pivot_key": "user_id",
    "related_pivot_key": "role_id",
    "parent_key": "id"
}

مرتب‌سازی relation ها:

می توانید با اضافه کردن sort به دستورات، نتایج را به‌صورت صعودی یا نزولی مرتب کنید :

{
    "sort": {
        "field": "my_field",
        "direction": "asc"
    }
}

یا :

{
    "sort": {
        "field": "my_field",
        "direction": "desc"
    }
}

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

فیلتر کردن relation ها:

شما می‌توانید با ساخت یک scope همان‌گونه که می‌خواهید relation‌ها را مشاهده کنید. به‌طور مثال فرض کنید می‌خواهید فقط ورودی‌های active را مشاهده کنید. برای این‌کار دستور زیر را در بخش Relationship Details وارد می‌کنیم:

public function scopeActive($query)
{
    return $query->where('active', 1);
}

همچنین دستور زیر را به relationship options اضافه کنید:

{
    "scope": "active",
}

Formfields :

فرم‌ها بخش مهمی از Voyagers BREAD هستند. که در ادامه‌ی مقاله‌ی ساخت پنل ادمین با لاراول ، آن را توضیح می‌دهیم. هر فرم یک field در جدول database و یک ورودی (یا خروجی) در BREAD نمایش می‌دهد. که برای کار با آن‌ها می‌توانید دستورات JSON را که در ادامه به شرح آن می‌پردازیم، اجرا کنید.

توضیحات:

همه‌ی فرم‌ها می‌توانند شامل توضیحات به منظور کمک به خود یا سایر کاربرانی که از پنل مدیریتی Voyager شما استفاده می‌کنند باشد. برای این‌کار دستور زیر را در قسمت Optional Details وارد می‌کنیم.

{
    "description": "A helpful description text here for your future self."
}

تنظيمات نحوه‌ی نمايش:

همچنین گزینه هایی برای تغییر نحوه‌ی نمایش BREAD شما وجود دارد. برای این‌کار می‌توانید یک display را به کد JSON خود اضافه کنید.

{
    "display": {
        "width": "3",
        "id": "custom_id"
    }
}

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

شما می‌توانید برای فرم‌های خود مقدار پیش‌فرضی تعیین کنید.

{
    "default" : "Default text"
}

مقدار Null :

گاهی اوقات می‌خواهید یک field در صورت نداشتن مقدار به‌صورت Null یا خالی ذخیره شود. برای این کار عبارت Null را به‌صورت زیر وارد می‌کنیم.

{
    "null": ""
}

کد بالا یک رشته خالی را به یک مقدار Null تبدیل می‌کند. اما ممکن است بخواهید هم، رشته‌ای خالی و هم مقدار Null را به database برای field موردنظر اضافه کنید. در این صورت باید یک مقدار جایگزین برای مقدار Null انتخاب کنید. به عنوان مثال اگر می‌خواهید حتی زمانی که مقدار Hello بود، به یک مقدار null تبدیل شود، می‌توانید عبارت Null را به‌صورت زیر وارد کنید.

{
    "null": "Nothing"
}

سفارشی‌سازی View :

شما می‌توانید یک View سفارشی را برای form‌ها استفاده کنید. برای این‌کار دستور زیر را وارد می‌کنیم.

{
    "view": "my_view"
}

دستور بالا my_view را از resources/views می‌گیرد و بر روی form اعمال می‌کند.

Checkbox :

برای ساخت یک Multiple Checkbox از دستور زیر استفاده می‌کنیم.

{
    "checked" : true,
    "options": {
        "checkbox1": "Checkbox 1 Text",
        "checkbox2": "Checkbox 2 Text"
    }
}

Radio Button :

{
    "default" : "radio1",
    "options" : {
        "radio1": "Radio Button 1 Text",
        "radio2": "Radio Button 2 Text"
    }
}

Radio button دقیقا همان dropdown است.

Date & Time :

برای تعیین فرمت تاريخ و زمان از دستور زیر استفاده می‌کنیم.

{
    "format" : "%Y-%m-%d"
}

[lsubtitle]Dropdown :[/lsubtitle]

{
    "default" : "option1",
    "options" : {
        "option1": "Option 1 Text",
        "option2": "Option 2 Text"
    }
}

default : در صورت نداشتن مقدار، با توجه به کد بالا option1 نمایش داده می‌شود. option : options هایی که dropdown شامل آن می‌باشد.

Images:

تصاوير option‌های مختلفی دارند. البته که اگر option‌ها را وارد نکنیم هم مشکلی پیش نمی‌آید. اما در صورتی که بخواهیم تصویرمان را تغییر سایز دهیم، تصویر بندانگشتی برای آن مشخص کنیم یا کیفیت آن را تغییر دهیم نیاز به اضافه کردن option داریم.

{
    "resize": {
        "width": "1000",
        "height": null
    },
    "quality" : "70%",
    "upsize" : true,
    "thumbnails": [
        {
            "name": "medium",
            "scale": "50%"
        },
        {
            "name": "small",
            "scale": "25%"
        },
        {
            "name": "cropped",
            "crop": {
                "width": "300",
                "height": "250"
            }
        }
    ]
}

resize : اگر می‌خواهید برای تصویرتان اندازه‌ای تعیین کنید، آن را در resize وارد کنید. در صورت تنظیم نکردن یکی از بخش‌های height (ارتفاع) یا width (عرض)، نسبت ابعاد تصویر را بر اساس ارتفاع یا عرض تصویر اصلی حفظ می‌کند. به‌طور مثال در بالا عرض روی 1000 پیکسل و ارتفاع Null تنظیم شده است، در این صورت عرض تصویر را به 1000 پیکسل و ارتفاع را به نسبت ابعاد تصویر اصلی تغییر اندازه می‌دهد. quality : اگر می‌خواهید تصویر را فشرده سازی کنید می‌توانید درصد فشرده‌سازی را در قسمت quality مشخص کنید. به‌طور معمول کیفیت تصویر بین ٪70 تا ٪100 تقریبا یکیست، اما size تصویر ممکن است به طرز چشمگیری کاهش یابد. upsize : این option فقط در صورتی معتبر است که بخواهید تصویر خود را resize کنید. همچنین اگر بخواهید تصویر خود را به 1000 پیکسل تغییر اندازه دهید و به‌طور پیش فرض تصویرتان از 1000 پیکسل کوچکتر باشد، این امکان قابل استفاده نمی‌باشد. thumbnail : thumbnails ها یک آرایه را می‌گیرند. هر object یک تصویر بندانگشتی جدید است که ایجاد می‌شود. هر object حاوی ۲ مقدار name و scale (درصد مقیاس) است. name به تصویر بندانگشتی شما پیوست می‌شود. (به‌طور مثال می‌گوید تصویری که آپلود کردید 7learn.jpg است پس با توجه به نام تصویر بندانگشتی، نام نهایی آن 7learn-medium.jpg است) همچنین thumbnail بخش دیگری با نام scale را شامل می‌شود که در این قسمت مقیاس تبدیل تصویر اصلی به تصویر بندانگشتی را مشخص می‌کنیم.

Media Picker :

توسط Media Picker می‌توانیم به‌صورت مستقیم و با استفاده از media-manager فایل‌های مختلف را آپلود، ویرایش یا انتخاب کنیم.

{
    "max": 10,
    "min": 0,
    "expanded": true,
    "show_folders": true,
    "show_toolbar": true,
    "allow_upload": true,
    "allow_move": true,
    "allow_delete": true,
    "allow_create_folder": true,
    "allow_rename": true,
    "allow_crop": true,
    "allowed": [],
    "hide_thumbnails": false,
    "quality": 90,
    "watermark": {
        "source": "...",
        "position": "top-left",
        "x": 0,
        "y": 0
    }
}

base_path : مسیر شروع نسبت به filesystem | مقدار پیش‌فرض /bread-slug/ و نوع String rename : تغییر نام خودکار فایل‌های آپلود شده به مقداری که در rename وارد می‌کنیم. | مقدار پیش‌فرض Orginal name (نام اصلی) و نوع String delete_files: در صورت true بودن، با حذف BREAD فایل‌های مربوط به آن BREAD حذف می‌شود. | مقدار پیش‌فرض false و نوع bool show_as_images : هنگام Browse، داده‌های ذخیره شده را به‌صورت تصویر نمایش می‌دهد. | مقدار پیش‌فرض false و نوع bool min : حداقل تعداد فایل‌هایی که قابل انتخاب هستند. | مقدار پیش‌فرض 0 و نوع int max : حداکثر تعداد فایل‌هایی که قابل انتخاب هستند. | مقدار پیش‌فرض 0 به معنی بی‌نهایت و نوع int expended : در صورت true بودن media-picker باید به طور پیش‌فرض expended باشد. | مقدار پیش‌فرض true و نوع bool show_folders : نمایش زیر پوشه‌ها | مقدار پیش‌فرض true و نوع bool show_toolbar : نمایش toolbar‌ها | مقدار پیش‌فرض false و نوع bool allow_upload : در صورت true بودن کاربران می‌توانند فایل جدید آپلود کنند. | مقدار پیش‌فرض true و نوع bool allow_move : در صورت true بودن کاربران می‌توانند فایل‌ها را جابجا کنند. ilesystem | مقدار پیش‌فرض true و نوع bool allow_delete : در صورت true بودن کاربران می‌توانند فایل‌ها را حذف کنند. |  مقدار پیش‌فرض true و نوع bool allow_create_folder : در صورت true بودن کاربران می‌توانند folder (پوشه) جدید بسازند. | مقدار پیش‌فرض true و نوع bool allow_rename : در صورت true بودن کاربران می‌توانند فایل‌ها را تغییر نام بدهند. |  مقدار پیش‌فرض true و نوع bool allow_crop : در صورت true بودن کاربران می‌توانند تصاویر را crop کنند. |  مقدار پیش‌فرض true و نوع bool hide_thumbnails : در صورت true بودن thumbnail‌ها مخفی می‌شوند و به عنوان زیرمجموعه‌ای از تصویر اصلیشان نشان داده می‌شوند. | مقدار پیش‌فرض true و نوع bool quality : می‌توانیم کیفیت عکس‌ها و thumbnail هایی که آپلود می‌شوند، را در این قسمت تعیین کنیم. | مقدار پیش‌فرض 90 و نوع int allowed : در این قسمت انواع فایلی که مجاز به آپلود یا انتخاب هستند، را وارد می‌کنیم. | مقدار پیش‌فرض [ ] به معنی اینکه تمام فایل‌ها مجاز است و نوع Object.

Number :

{
    "step" : 0.1,
    "min" : 0,
    "max" : 10
}

در کد بالا مقدار حداقل و حداکثر را برای ورود‌های عدد تعیین می‌کنیم. در صورت تعیین نکردن همان مقدار پیش‌فرض باقی می‌ماند.

مسیریابی (Routing) :

پس از نصب Voyager یک route در مسیر routes/web.php به شکل زیر ایجاد می‌شود.

Route::group(['prefix' => 'admin'], function () {
    Voyager::routes();
});

ما می‌توانیم route را تغییر دهیم یعنی به‌طور مثال به آن middleware یا domain اضافه کنیم.

Media Manager :

در این بخش از مقاله‌ی ساخت پنل ادمین با لاراول ، به توضیح Media Manager می‌پردازیم. Voyager دارای یک Media Manager تمام عیار است که به شما امکان می‌دهد فایل‌ها را آپلود، حذف یا تغییر نام دهید. همچنین می‌توانید پوشه‌های جدیدی اضافه کنید و آن‌ها را جابجا کنید. در کل هر کاری را که می‌توانید در Media Manager‌های پیشرفته‌ی مختلف انجام دهید، می‌توانید در Voyager Media Manager نیز انجام دهید. برای آپلود فایل می‌توانید از صفحه‌ی خود یک فایل را بکشید و بر روی upload رها کنید. همچنین Voyager Media Manager علاوه بر امکاناتی همچون ساخت thumbnail از تصویر اصلی می‌تواند بر روی عکس‌های شما watermark بزارد. برای تنظیمات پیشرفته به قسمت Media Picker مراجعه نمایید.

اگر هنگام آپلود فایل با حجم بالا، با ارور مواجه شدید.قسمت max_file_upload و file_upload_size را ویرایش کنید.

Menus and Menu Builder :

توسط Voyager به‌راحتی می‌توانید منو‌ی جدید ایجاد کنید یا منوهای قبلی را ویرایش یا حذف کنید. برای مشاهده‌ی منو‌های فعلی برروی Tools و سپس Menu Builder کلیک می‌کنیم. همچنین می‌توانیم منو‌ها را برای قسمت مشخصی از سایت مانند sidebar یا footer ایجاد کنیم. با کلیک برروی Builder به Menu Builder می‌رویم. پس از ساخت و کانفیگ Menu می‌توانید آن را به سایت خود اضافه کنید. به‌طور مثال می‌خواهیم منوی main را در تمام فایل‌های View اعمال کنیم تا نمایش داده شود. برای این‌کار در  View‌ها دستور زیر را وارد می‌کنیم.

menu('main');

کد بالا منوی شما را نامرتب و در یک ليست Ul نمایش می‌دهد. اگر می‌خواهید برای استایل دهی منو از Bootstrap استفاده کنید، می‌توانید به کد بالا به‌صورت زیر قسمت دومی هم اضافه کنید.

menu('main', 'bootstrap');

همچنین شما می‌توانید نحوه‌ی نمایش Menu را به‌صورت دستی تغییر دهید. برای این‌کار به resources/views/my_menu.blade.php رفته و کد زیر را وارد کنید.

<ul>
    @foreach($items as $menu_item)
        <li><a href="{{ $menu_item->link() }}">{{ $menu_item->title }}</a></li>
    @endforeach
</ul>

سپس برای نمايش منو بجای استفاده از Bootstrap، به‌صورت زیر از my_menu استفاده می‌کنیم.

menu('main', 'my_menu');

Menu as JSON:

اگر هیچ کدام از دو روش بالا مورد نظر شما نیست، می‌توانید با استفاده از JSON خروجیه منو را به یک آرایه تبدیل کنید.

menu('main', '_json')

 Database Manager :

Voyager ابزار‌های متفاوتی برای مدیریت database دارد. ابزار‌هایی که با استفاده از آن‌ها می‌توانیم جداولمان را ویرایش، حذف یا اضافه کنیم. همچنین به هر کدام از جداول database می‌توانیم BREAD اضافه کنیم. درون پنل مدیریت می‌توانید قسمت Tools-> Database و تمام جداول فعلی خود در database را مشاهده نمایید. همچنین می‌توانید بر روی "Create a New Table" کلیک کنید تا جدول جدیدی در database خود ایجاد کنید. اگر روی table name کلیک کنید می‌توانید طرح (schema) فعلی را مشاهده کنید. همچنین می‌توانید بر روی دکمه‌های Edit ،View یا Delete کلیک کنید تا آن عملکرد را برای جدول انجام دهید. یکی از امکانات دیگر این است که می‌توانید BREAD را به هر یک از جداول database خود اضافه کنید. در صورتی که جدولی از قبل BREAD داشته باشد، می‌توانید آن را ویرایش یا حذف کنید.

Setting:

بخش تنظیمات به شما این امکان را می‌دهد که تنظیمات گسترده‌ای را برای سایت خود اعمال کنید. در این بخش می‌توانید تنظیمات آپلود تصاویر برای لوگوی سایت خود یا textbox برای عنوان صفحه اصلی را تغییر دهید. در نسخه‌ی جدید Voyager توانایی اضافه کردن گروه‌های مختلف برای تنظیمات مختلف را دارید. به‌طور مثال، اگر تنظیمات جدیدی را در  گروه site ایجاد کنید و این تنظیمات دارای title باشند، می‌توانید با استفاده از دستورات زیر این تنظیمات را در هرجایی از سایت خود اعمال کنید :

<?php
echo setting('site.title');

یا درون blade‌ها دستور زیر را وارد می‌کنیم:

{{ setting('site.title') }}

Compass :

بخش compass مکانیست که در ‌آن می‌توانیم به reference‌های مختلف لینک‌ها و فونت‌ها دسترسی پیدا کنیم. همچنین می‌توانیم به  اجرای برخی از دستورات یا مشاهده log‌ها بپردازیم. در صفحه‌ی اول Compass شما تعدادی لینک را مشاهده می‌کنید. همچنین می‌توانید تمام فونت‌هایی که می‌توانید در Voyager استفاده کنید را ببینید. در بخش Command می‌توانید بعضی از دستورات artisan را به‌ طور از Voyager اجرا کنید. و سرانجام، در بخش Logs می‌توانید تمام گزارشات مربوط به برنامه‌ی خود را مشاهده کنید.

Roles and Permissions:

در Voyager می‌توانیم برای هر کاربر مجوزها یا permission‌های خاصی اضافه کنیم. از نسخه‌ی ۱.۰ به بعد در Voyager نحوه‌ی authorization پیشرفت چشم‌گیری داشته است. همچنین از این نسخه به بعد permission‌ها را به روش‌های بیشتری می‌توانید چک کنید.

// via user object
$canViewPost = $user->can('read', $post);
$canViewPost = Auth::user()->can('read', $post);
// via controller
$canViewPost = $this->authorize('read', $post);

علاوه بر مجوزهای قبلی، permission‌های دیگری نیز وجود دارد که می‌توانید بهصورت پیش فرض از آنها استفاده کنید: browse_admin : مشخص می‌کند که آیا کاربر می‌تواند در پنل مدیریت Browse کند. browse_database : مشخص می‌کند که آیا کاربر می‌تواند در Browse (پایگاه داده) database کند. browse_bread : مشخص می‌کند که آیا کاربر می‌تواند در BREAD‌ها Browse کند. browse_media : مشخص می‌کند که آیا کاربر می‌تواند در رسانه‌ها Browse کند. browse_menu : مشخص می‌کند که آیا کاربر می‌تواند در منو‌ها Browse کند. browse_settings : مشخص می‌کند که آیا کاربر می‌تواند در تنظیمات Browse کند. read_settings : مشخص می‌کند که آیا کاربر می‌تواند تنظیمات را مشاهده کند. edit_settings : مشخص می‌کند که آیا کاربر می‌تواند تنظیمات را تغییر دهد. add_settings : مشخص می‌کند که آیا کاربر می‌تواند در تنظیمات جدیدی اضافه کند. delete_settings : مشخص می‌کند که آیا کاربر می‌تواند تنظیمات را حذف کند. علاوه بر این می‌توانید برای BREAD‌ها نیز permission تعریف کنید. در این صورت مجوز‌های browse ,read ,edit ,add و delete ایجاد می‌شوند. به‌طور مثال ،فرض کنید می‌خواهید یک BREAD جدید برای جدول products ایجاد کنید و بر‌روی آن permission اعمال کنید. بخش‌های مختلف مجوز ما browse_products ،read_products ،edit_products ،add_products و remove_products خواهند بود.

مجوزها به‌ترتيب چک می‌شوند و اگر یک کاربر تنها مجوز browse را نداشته باشد تنها همان بخش برایش مخفی می‌شود.

ساخت مجوز برای صفحه‌ی custom :

اگر یک صفحه custom ایجاد کردید و می‌خواهید تنها کاربران خاصی به آن دسترسی پیدا کنند، می‌توانید از permission‌ها استفاده کنید.

این مجوز‌ها تنها در صورتی کار می‌کند که slug شما دقیقا پس از /admin/ آمده باشد. بنابراین برای یک صفحه custom از فرم  admin/sub/foo منوها مخفی نمی‌شوند.

ساخت مجوز :

ابتدا، در جدول permissions یک مجوز ایجاد کنید. به‌طور مثال می‌توانید از BREAD استفاده کنید که نام مدل آن TCG\Voyager\Models\Permission است .توجه کنید که ستون Table_name باید null باشد. همچنین ستون key باید از فرم browse_slug باشد که در آن باید slug را با slug فعلی از صفحه‌ی custom جایگزین کنید. به‌طور مثال برای محدود کردن دسترسی به صفحه custom خود با آدرس /admin/create_bill می‌توانید مجوز browse_create_bill را ایجاد کنید.

سفارشی‌سازی Controller :

ممكن است که شما Gate خود را ایجاد کرده باشید.

Gate::define(`browse_create_bill`, function ($user) {
    return $user->hasPermission(`browse_create_bill`);
});

برای استفاده‌ی authorize در Controller به‌صورت زیر عمل می‌کنیم :

public function index()
{
  $this->authorize('browse_create_bill');
  //..

پس از انجام مرحله‌ی بالا باید به‌صورت زیر یک guard به Controller اضافه کنید :

  /**
   * Get the guard to be used during authentication.
   *
   * @return \Illuminate\Contracts\Auth\StatefulGuard
   */
  protected function guard()
  {
      return Auth::guard(app('VoyagerGuard'));
  }

استفاده‌ی مجوز‌ها در فایل‌های Blade Template :

همچنین می‌توانیم مجوزها را با استفاده از blade syntax بررسی کنیم. به‌طور مثال می‌خواهیم بررسی کنیم که آیا کاربر می‌تواند برنامه‌ها را Browse کند، برای این‌کار از دستور زیر استفاده می‌کنیم:

@can('browse', $post)
    I can browse posts
@endcan

اگر بخواهیم یک بخش else هم تعریف کنیم به‌صورت زیر این بخش را اضافه می‌کنیم:

@can('browse', $post)
    I can browse posts
@else
    I cannot browse posts
@endcan

روش‌های کمک کننده (Helper Methods) :

Voyager چندین تابع کمکی دارد که می‌توانیم از آن‌ها استفاده کنیم. در اینجا می‌توانید لیستی از توابع موجود را پیدا کنید که می‌تواند سرعت کار شما را افزایش دهد.

آدرس Thumbnail‌ها :

پس از ایجاد thumbnail ها، ممکن است بخواهید آن‌ها را در View نمایش بدهید یا نشانی اینترنتی thumbnail‌ها را به دست آورید. برای انجام این کار، شما باید Resizable trait را به model خود اضافه کنید.

use TCG\Voyager\Traits\Resizable;
class Post extends Model
{
    use Resizable;
}

نمایش یک تصویر :

برای نمايش یک تصوير می‌توانید از Helper‌های زیر کمک بگیرید.

@foreach($posts as $post)
    <img src="{{Voyager::image($post->thumbnail('small'))}}" />
@endforeach

یا می‌توانید نام پیش‌فرض field تصویر را مشخص کنید.

@foreach($posts as $post)
    <img src="{{Voyager::image($post->thumbnail('small', 'photo'))}}" />
@endforeach

نمایش چند تصویر :

برای نمايش چند تصوير می‌توانید از Helper زیر کمک بگیرید.

@foreach($posts as $post)
    $images = json_decode($post->images);
    @foreach($images as $image)
        <img src="{{ Voyager::image($post->getThumbnail($image, 'small')) }}" />
    @endforeach
@endforeach

Multilanguage:

یکی از امكانات Voyager، پشتیبانی از حالت چند‌زبانه می‌باشد. برای این‌کار ابتدا باید بعضی از کانفیگ‌ها را اعمال کنیم.

Setup:

در ابتدا باید یک بخش locals در config/voyager.php ایجاد کنیم. سپس multilanguage را enable کنیم.

'multilingual' => [
        'enabled' => true,
        'default' => 'en',
        'locales' => [
            'en',
            'da',
        ],
    ],

سپس باید Translatable را use کنیم.

use TCG\Voyager\Traits\Translatable;
class Post extends Model
{
    use Translatable;
    protected $translatable = ['title', 'body'];
}

حال پس از ورود به بخش BREAD با language-selection روبرو می‌شویم.

نحوه‌ی استفاده :

ترجمه‌های Eager-load :

// Loads all translations
$posts = Post::with('translations')->get();
// Loads all translations
$posts = Post::all();
$posts->load('translations');
// Loads all translations
$posts = Post::withTranslations()->get();
// Loads specific locales translations
$posts = Post::withTranslations(['en', 'da'])->get();
// Loads specific locale translations
$posts = Post::withTranslation('da')->get();
// Loads current locale translations
$posts = Post::withTranslation('da')->get();

دریافت زبان پیش‌فرض :

echo $post->title;

دریافت مقدار translated :

echo $post->getTranslatedAttribute('title', 'locale', 'fallbackLocale');

اگر locale را مشخص نکنید، locale فعلی برنامه استفاده خواهد شد. اگر شما fallbackLocale را تعریف نکنید، از fallbackLocale برنامه استفاده می‌شود. می‌توانید محلی خود را به صورت رشته منتقل کنید. همچنین اگر می‌خواهید fallbackLocale غیرفعال باشد، مقدارش را false کنید. اگر برای locale و fallbackLocale هیچ مقداری تعریف نکنیم، به‌صورت پیش‌فرض ۰ می‌شوند.

ترجمه‌ی کل Model :

با استفاده از دستورات زیر می‌توانیم  Model خود را ترجمه کنیم.

$post = $post->translate('locale', 'fallbackLocale');
echo $post->title;
echo $post->body;
// You can also run the `translate` method on the Eloquent collection
// to translate all models in the collection.
$posts = $posts->translate('locale', 'fallbackLocale');
echo $posts[0]->title;

بررسی قابل ترجمه بودن Model :

// with string
if (Voyager::translatable(Post::class)) {
    // it's translatable
}
// with object of Model or Collection
if (Voyager::translatable($post)) {
    // it's translatable
}

تعیین attribute ترجمه :

$post = $post->translate('da');
$post->title = 'foobar';
$post->save();

Query Translatable Models :

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

$page = Page::whereTranslation('slug', 'my-translated-slug');
// Is the same as
$page = Page::whereTranslation('slug', '=', 'my-translated-slug');
// Search only locale en, de and the default locale
$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en', 'de']);
// Search only locale en and de
$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en', 'de'], false);

whereTranslation پارامترهای زیر را قبول می‌کند: field: فیلدی که در آن می‌خواهیم جست‌و‌جو کنیم. operator: عمل‌کننده یا operator که به‌صورت پیش‌فرض = است و مقدار‌های دیگری مانند where را می‌پذیرد. value : مقداری که دنبالش می‌گردیم. locale : locales مورد نظری که در آن جست‌و‌جو می‌کنیم. اگر می‌خواهید در تمام locale‌ها جست‌و‌جو شود مقدار آن را null بگذارید. جمع بندی: در مقاله‌ی ساخت پنل ادمین با لاراول ، به آموزش کامل Laravel Voyager پرداختیم. و تصمیم گرفتیم که شما را تا بیشترین حد امکان با Laravel Voyager و تمام امکانات آن از مبتدی تا پیشرفته آشنا کنیم. اگر سوالی داشتید در قسمت نظرات حتما با ما در میان بگذارید تا در اسرع وقت جواب داده شود. اگر به یادگیری بیشتر لاراول علاقه داری می‌تونی در دوره آموزش لاراول کاربردی (بسته پروژه محور) شرکت کنی، این دوره شامل ۱۲ پروژه کاربردی و پر استفاده در دنیای واقعی است، که تمامی پروژه‌ها به صورت کامل برنامه‌ نویسی خواهند شد، تا دانشجو بتواند با روند ایجاد و تکمیل پروژه به صورت کامل آشنا شود.