README

1. Установка

• Установить пакет composer require cdonut/vue-admin
• Добавить в файл config/auth.php в массив guards: 'vueadmin' => ['driver' => 'session', 'provider' => 'vueadmins'].
• Добавить в файл config/auth.php в массив providers: 'vueadmins' => ['driver' => 'eloquent', 'model' => App\YoursAdminModel::class].
  App\YoursAdminModel::class - класс с трейтом Authenticatable .
• Запустить php artisan vendor:publish --provider="Cdonut\VueAdmin\PackageServiceProvider" для копирования ассетов и файла настроек.
• Для Laravel 7 запустить composer require laravel/ui

  2. Настройка

Файл настроек config/vueadmin.php

• ключ menu содержит пункты меню для админки в формате:
  

  'menu' =>
         [
             [
                 'name' => 'Группа 1',                      //Название группы меню
                 'items' => [                               //Элементы группы
                     [
                         'to' => '/settings',               //Url страницы в админке (перфикс /single для одной модели без старницы списка) 
                         'label' => 'Настройки',            //Название элемента для страницы списка
                         'singleTitle' => 'Настройка',      //Название элемента для детальной страницы
                         'icon' => 'chevron-right',         //Иконка меню 
                         'model' => 'Setting',              //Привязанная модель
                         'showListActions' => false,        //Выводить кнопки добавления и удаления элементов в списке (по умолчанию true)
                         'redirectOnSave'=>false,           //Отключить редирект к саиску при сохранении (по умолчанию true)
                         'sort'=>'name',                    //Поле для начальной сортировки таблицы (по умолчанию id)
                         'order'=>'asc'                     //Направление сортировки (по умолчанию desc)
  
                     ],
                     ...
             ],
             [
                 'name' => 'Группа 2',
                 'items' => [
                     [
                         'to' => '/single/page-seo',
                         'label' => '',
                         'singleTitle' => 'Сео страницы',
                         'icon' => 'chevron-right',
                         'model' => 'Seo'
                     ],
                     ...
                 ]
             ],
        ]
  

• ключ disk содержит название диска для хранения файлов, по умолчанию public
• ключ admin_title содержит тайтл админки в левом меню, по умолчанию env('APP_NAME', 'Vue Admin'),
• ключ yandex_geo_key содержит ключ апи яндекс карт, по умолчанию env('YANDEX_GEO_KEY', '')

при использовании префикса /single в ключе url открывается страница редактирования первого найденного элемента, если элемент не найден в базе откроется страница создания

3. Использование

Основное

• В модель добавит трейт use Adminable;
• В protected $fillable модели указать поля для записи
• В докблок класса модели добавить нужные поля для вывода в админке c помощью @Field()

примеры:
вывести не редактируемое поле "Создан" с датой создания
@Field(name=created_at, label=Создан, type=datetime, editable=false, column=20, order=20)
вывести обязательное поле "Пользователь" с привязанным пользователем
@Field(name=user_id, label=Пользователь, type=relation, relationModel=User, relationCount=1, relationField=name, required=true, column=5, order=80)

Параметры Field

Общие параметры для @Field:
name - Название аттрибута модели
label - Лейбл поля в админке
type - Тип поля, по умолчанию text
default - значение по умолчанию для поля
editable - редактируемость, по умолчанию true
required - поле обязательное для заполнения, по умолчанию false
column - сортировка в таблице на странице списка элементов, если не задано, в таблице не выводится
order - сортировка на странице редактирования

Возможные значения параметра type:
text - текстовое поле
phone - телефон
email - email
textarea - многострочное текстовое поле
wysiwyg - редактор текста
number - числовое поле
date - дата
datetime - дата и время
boolean - переключатель да/нет
map - Яндекс карта
file - файл (в моделе хранится путь до файла), связанные аттрибуты:

• withSeo - true добавляет поля title и alt к файлу (в моделе хранится как массив с ключами src,alt, title), по умолчаниюfalse
  

gallery - несколько файлов (в моделе хранится как массив путей). связанные аттрибуты:

• withSeo - true добавляет поля title и alt к файлам (в моделе хранится как массив массивов с ключами src,alt, title), по умолчаниюfalse
  

select - селект, связанные аттрибуты:

• options - значения для селекта в формате id:value|id:value|... (пример 1:селект1|2:селект2|3:селект3)

relation - привязанный элемент, связанные аттрибуты:

• relationModel - название класса модели относительно \App неймспейса
• relationCount - максимальное количество элементов, если не установлено ограничения нет.
• relationField - аттрибут связанной модели выводимый в поле, по умолчанию name
• data - название статичного метода текущей модели для получения списка выбора связанных моделей (метод должен возвращать массив с ключами id, name, можно добавить ключ value для отображения в спике name:value); если параметр не передан, по умолчанию выбираются id и аттрибут указыный в relationField всех записей связанной модели
• relationMethod - название метода связи (для связи многие ко многим), используется для сохранения привязанных элементов
• saveMethod - переоперделяет способ сохранения для связей МКМ; может быть названием статичного метода текущей модели, который принимает на вход массив связанных ид, либо null - для отключения сохранения

для связи многие ко многим к нужно указать не существующий в базе аттрибут, например tags_ids

@Field(name=tags_ids, label=Теги, type=relation, relationMethod=tags, relationModel=Tag)

добавить его в массив protected $fillable

прописать метод связи

public function tags()
    {
        return $this->belongsToMany(Tag::class);
    }

прописать для него геттер возвращающий текущее значение либо все значения для выбора

protected function getTagsIdsAttribute($value)
     {
         return $value ? $value : $this->tags()->pluck('id')->toArray();
     }

Ограничение доступа

трейт Adminable содержит 3 метода определяющие возможность просматривать и редактировать модели, их можно переопределить в моделе.

• static function canView() - определяет условия для просмотра модели в админке, по умолчанию проверяет аттрибут role у пользователя который авторизовался в админке, если role<=1 просмотр разрешен
• static function canEdit() - определяет условия для редактирования модели в админке, по умолчанию вызывает canView
• static function mainActionsIsEnabled() - определяет условия отображения кнопок создания и удаления элемента на странице списка, по умолчанию вызывает canView

Валидация полей

для валидации полей в админке испоьзуются методы

• static function getValidation() - метод должен возвращать массив валидаций совместимый со стандартными методами валидации laravel
  пример:

   public static function getValidation()
    {
        return [
            'description_short' => 'string|max:50',
            'user_id' => 'required|integer',
            'name' => 'required|string',
        ];
    }
  

• static function getValidationMessages() - метод переопределяет стандартные сообщения валидации, должен возвращать массив сообщений валидаций совместимый со стандартными методами валидации laravel
  пример:

   public static function getValidationMessages()
    {
        return [
            'description_short.string' => 'Введите строку',
            'user_id.required' => 'Укажите пользователя',
            'name.required' => 'Введите название',
        ];
    }
  

Фильтры списка элементов

Блок фильтров для страницы списка задается методом static function getFilters() который возвращает массив фильтров
например:

[
    [
       'label' => 'Активность',                         //Лейбл фильтра
       'type' => 'select',                              //Тип фильтра
       'compare' => '=',                                //Тип сравнения
       'field' => 'active',                             //Аттрибут модели
       'value' => false,                                //Значение по умолчанию
       'values' => [                                    //Набор значений
           ['id' => false, 'value' => 'Не выбрано'],
           ['id' => 0, 'value' => 'Не активен'],
           ['id' => 1, 'value' => 'Активен']
       ]
    ],
    [
       'label' => 'Продавец',
       'type' => 'text',
       'compare' => 'func',
       'func' => 'searchSeller',                        //Статичный метод поиска
       'value' => ''
    ],
    [
       'label' => 'Название',
       'type' => 'text',
       'compare' => 'like',
       'field' => 'name',
       'value' => ''
    ],
    ...
]   

Возможные значения параметра type:
select - Селект, необходимо указать массив значений в ключе values в формате массива с ключами id и value
text - текстовое поле
number - числовое поле
boolean - переключатель

Возможные значения параметра compare:
=,>,=>,<,<= - операторы сравнения
like - частичное совпадение
func - фильтрация статичным методом указанным в ключе func, метод принимает 2 параметра \Illuminate\Database\Eloquent\Builder $query (стандартный билдер запроса модели) и $value (значение фильтра), метод должен вернуть измененный $query

пример метода фильтрации:

static function searchSeller($query, $value)
    {
        $ids = User::where('name', 'like', "%$value%")
            ->where('is_seller', 1)
            ->pluck('id')->toArray();

        return $query->whereHas('seller', function ($query) use ($ids) {
            $query->whereIn('id', $ids);
        });
    }

Группировка полей на странице редактирования

Поля на странице редактирования элемента по умолчанию сгруппированы на одной карточке "свойства" во всю ширину контейнера.

Для группировки полей используется метод static function getAdminCards(), он должен возвращать массив в формате:

[
    [
        'title' => 'Тайтл карточки 1',      //Тайтл карточки
        'class' => 'is-12',                 //Класс карточки ширина задается от is-1 до is-12
        'icon' => 'ballot',                 //Иконка карточки
        'fields' => [                       //Атрибуты выводимые в карточке
                        'id', 
                        'created_at', 
                        'updated_at', 
                        'active'
                    ]
    ],
    [
        'title' => 'Тайтл карточки 2',
        'class' => 'is-12',
        'icon' => 'ballot',
        'fields' => [
                        'name', 
                        'specialization', 
                        'description_short', 
                        'description_full'
                    ]
    ],
];

Дополнительные действия

Для страницы редактирования модели можно определить дополнительные действия, которые будут отображаться слева от кнопки сохранить.

Дополнительные действия определяются в переменных начинающихся с admin_customActions
например:

protected $admin_customActions_test = [
    [
        'label' => 'На test',       //Текст кнопки
        'class' => 'is-warning',    //Класс кнопки
        'link' => 'link',           //Добавляется к url для задания уникальности
        'method' => 'method',       //Название публичного метода в текущей модели 
        'fill_model' => true        //true - заполнить $this текущими значениями из админки без сохранения в базе, false - заполнить $this из базы  
    ]
];