Списки

# Введение

Список - это контроллер, используемый для отображения списка записей на странице с возможностью добавления новых, сортировки и поиска. По умолчанию действие контроллера index() отображает список, но его можно отобразить где угодно. Вы также можете отобразить несколько списков на странице.

Список зависит от столбцов и класса модели. Для того, чтобы использовать список, Вы должны указать его в свойстве $implement класса контроллера. Также должно быть определено свойство $listConfig, значение которого - YAML файл, используемый для настройки списка.

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.ListController'];

    public $listConfig = 'list_config.yaml';
}

Примечание: Очень часто список используются вместе с формами в одном контроллере.

# Настройка списка

Конфигурационный файл, на который ссылается переменная $listConfig, должен иметь YAML формат и находиться в папке с представлением контроллера. Ниже представлен типичный файл с настройками:

# ===================================
#  List Behavior Config
# ===================================

title: Blog Posts
list: ~/plugins/acme/blog/models/post/columns.yaml
modelClass: Acme\Blog\Models\Post
recordUrl: acme/blog/posts/update/:id

Следующие параметры являются обязательными:

Параметры конфигурации, перечисленные ниже, не являются обязательными.

# Тулбар

Чтобы добавить тулбар к списку, нужно добавить следующие настройки в конфигурационный YAML файл списка:

toolbar:
    buttons: list_toolbar
    search:
        prompt: Find records

Параметры тулбара:

Настройки виджета с поиском:

Тулбар может содержать в себе различные кнопки, индикаторы или графики. Пример фрагмента с кнопкой, при нажатии на которую появляется форма создания новой записи:

<div data-control="toolbar">
    <a
        href="<?= Backend::url('acme/blog/posts/create') ?>"
        class="btn btn-primary oc-icon-plus">New Post</a>
</div>

# Фильтрация

Добавьте следующие настройки в конфигурационный YAML файл списка для отображения фильтра:

filter: config_filter.yaml

Параметр filter должен указывать на файл или массив с настройками.

# Столбцы списка

Отображаемые столбцы списка задаются в YAML файле, который находится в подпапке папки models. Имя подпапки должно совпадать с именем класса модели и пишется строчными буквами. Название же самого файла может быть любым, но лучше использовать columns.yaml и list_columns.yaml. Пример:

plugins/
  acme/
    blog/
      models/                  <=== папка модели
        post/                  <=== папка с настройками модели
          list_columns.yaml    <=== файл с настройками списка
        Post.php               <=== класс модели

Следующий пример показывает типичное содержимое файла list_columns.yaml.

# ===================================
#  List Column Definitions
# ===================================

columns:
    name: Name
    email: Email

# Свойства столбцов

Для каждого столбца можно задать следующие свойства (если применимо):

# Типы столбцов

# Text

text - отображает столбец с текстом. Выравнивание по левому краю.

full_name:
    label: Full Name
    type: text

# Number

number - отображает столбец с числами. Выравнивание по правому краю.

age:
    label: Age
    type: number

# Switch

switch - отображает столбец со значениями true или false.

enabled:
    label: Enabled
    type: switch

# Date & Time

datetime - отображает столбец с временем и датой. Пример: Thu, Dec 25, 1975 2:15 PM.

created_at:
    label: Date
    type: datetime

Вы также можете указать произвольный формат даты. Например: Thursday 25th of December 1975 02:15:16 PM:

created_at:
    label: Date
    type: datetime
    format: l jS \of F Y h:i:s A

# Date

date - отображает столбец с датой M j Y

created_at:
    label: Date
    type: date

# Time

time - отображает столбец со временем g:i a

created_at:
    label: Date
    type: time

# Time since

timesince - отображает столбец с разницей во времени. Пример: 10 minutes ago

created_at:
    label: Date
    type: timesince

# Time tense

timetense - отображает столбец со временем. Пример: Today at 12:49, Yesterday at 4:00 or 18 Sep 2015 at 14:33.

created_at:
    label: Date
    type: timetense

# Select

select - позволяет создать колонку, используя произвольный SQL select запрос.

full_name:
    label: Full Name
    select: concat(first_name, ' ', last_name)

# Relation

relation - позволяет отображать связанные столбцы. Значением этого параметра должно быть Имя Активной Записи отношения Вашей модели. Пример:

group:
    label: Group
    relation: groups
    select: name

Если отношение использует аргумент count, то Вы можете отобразить число, используя параметры: valueFrom и default.

users_count:
    label: Users
    relation: users_count
    valueFrom: count
    default: 0

# Partial

partial - отображает фрагмент. Параметр path указывает на .htm файл с содержимым ячейки. Внутри фрагмента доступные следующие переменные: $value - значение ячейки по умолчанию, $record - модель и $column - экземпляр класса Backend\Classes\ListColumn.

content:
    type: partial
    path: ~/plugins/acme/blog/models/comments/_content_column.htm

# Отображение списка

Обычно списки отображаются в представлении в методе index при помощи метода listRender(). Пример:

<?= $this->listRender() ?>

# Использование нескольких списков

Вы можете использовать несколько списков в одном контроллере, если укажите в свойстве $listConfig массив, в котором ключ - название списка, а значение - ссылка на файл с настройками.

public $listConfig = [
    'templates' => 'config_templates_list.yaml',
    'layouts' => 'config_layouts_list.yaml'
];

Передайте ключ в метод listRender() для отображения нужного списка:

<?= $this->listRender('templates') ?>

# Использование фильтра

Вы можете отфильтровать элементы в списке по нужному полю. Пример:

# ===================================
# Filter Scope Definitions
# ===================================

scopes:

    category:
        label: Category
        modelClass: Acme\Blog\Models\Category
        conditions: category_id in (:filtered)
        nameFrom: name

    status:
        label: Status
        type: group
        conditions: status in (:filtered)
        options:
            pending: Pending
            active: Active
            closed: Closed

    published:
        label: Hide published
        type: checkbox
        conditions: is_published <> true

    approved:
        label: Approved
        type: switch
        conditions:
            - is_approved <> true
            - is_approved = true

    created_at:
        label: Date
        type: date
        conditions: created_at >= ':filtered'


    published_at:
        label: Date
        type: daterange
        conditions: created_at >= ':after' AND created_at <= ':before'

# Параметры фильтра

Вы можете указать следующие параметры для каждого фильтра:

# Доступные типы фильтра

Вы можете использовать следующие типы фильтров:

# Изменение списка

Вы можете изменить список следующими способами:

• Переопределить контроллер
• Изменить столбцы списка
• Изменить запрос к модели

# Переопределение контроллера

Вы можете использовать свою собственную логику в контроллере в методе index(), а затем, при необходимости, отобразить список.

public function index()
{
    //
    // Do any custom code here
    //

    // Call the ListController behavior index() method
    $this->asExtension('ListController')->index();
}

# Изменение столбцов списка

Вы можете добавить новые столбцы в список, используя метод extendListColumns. Он принимает два аргумента: $list и $model. Пример:

class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.ListController'];

    public $listConfig = 'list_config.yaml';
}


Categories::extendListColumns(function($list, $model) {

    if (!$model instanceof MyModel)
        return;

    $list->addColumns([
        'my_column' => [
            'label' => 'My Column'
        ]
    ]);

});

Также Вы можете переопределить метод listExtendColumns в классе контроллера.

class Categories extends \Backend\Classes\Controller
{
    [...]

    public function listExtendColumns($list)
    {
        $list->addColumns([...]);
    }
}

Доступные методы объекта $list:

# Изменение запроса к модели

Вы можете переопределить метод listExtendQuery, чтобы изменить запрос к модели при отображении списка внутри класса контроллера. Пример:

public function listExtendQuery($query)
{
    $query->withTrashed();
}

Вы также можете переопределить метод listFilterExtendQuery, чтобы изменить запрос к модели при фильтрации списка внутри класса контроллера. Пример:

public function listFilterExtendQuery($query, $scope)
{
    if ($scope->scopeName == 'status') {
        $query->where('status', '<>', 'all');
    }
}