Advanced

CardsBuilder

Расширяет MoonShineComponent

  • имеет те же функции

Основы

С помощью CardsBuilder вы можете отображать список элементов в виде карточек.
Вы также можете использовать CardsBuilder на своих собственных страницах или даже за пределами MoonShine.

CardsBuilder::make(
    Fields|array $fields = [],
    protected iterable $items = []
)
CardsBuilder::make(
    Fields|array $fields = [],
    protected iterable $items = []
)
  • $fields - поля,
  • $items - значения полей.
CardsBuilder::make(
    [
        ['id' => 1, 'title' => 'Заголовок 1'],
        ['id' => 2, 'title' => 'Заголовок 2'],
    ],
    [
        ID::make(),
        Text::make('title')
    ]
)
CardsBuilder::make(
    [
        ['id' => 1, 'title' => 'Заголовок 1'],
        ['id' => 2, 'title' => 'Заголовок 2'],
    ],
    [
        ID::make(),
        Text::make('title')
    ]
)

Элементы и поля для CardsBuilder можно указать с помощью соответствующих методов.

Элементы и поля

Метод items() позволяет передать CardsBuilder данные для заполнения карточек.

items(iterable $items = [])
items(iterable $items = [])

Метод fields() позволяет передать CardsBuilder список полей для построения карточки.

fields(Fields|Closure|array $fields)
fields(Fields|Closure|array $fields)
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items([['text' => 'Значение']])
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items([['text' => 'Значение']])

Соответствие данных с полями осуществляется через значение column полей!

Приведение типов

Метод cast() используется для приведения значений таблицы к определенному типу.
Поскольку по умолчанию поля работают с примитивными типами:

use MoonShine\TypeCasts\ModelCast;
 
CardsBuilder::make(items: User::paginate())
    ->fields([Text::make('Email')])
    ->cast(ModelCast::make(User::class))
use MoonShine\TypeCasts\ModelCast;
 
CardsBuilder::make(items: User::paginate())
    ->fields([Text::make('Email')])
    ->cast(ModelCast::make(User::class))

В этом примере мы приводим данные к формату модели User с помощью ModelCast.

Для более подробной информации обратитесь к разделу TypeCasts

Метод header() позволяет установить заголовок для карточек.

header(Closure|string $value)
header(Closure|string $value)
  • $value - column или замыкание, возвращающее html код.
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->header(static fn() => Badge::make('new', 'success'))
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->header(static fn() => Badge::make('new', 'success'))

Содержимое

Методы content() используются для добавления произвольного содержимого в карточку.

content(Closure|string $value)
content(Closure|string $value)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->content('Пользовательское содержимое')
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->content('Пользовательское содержимое')

Название

Метод title() позволяет установить название карточки.

title(Closure|string $value)
title(Closure|string $value)
  • $value - column или замыкание, возвращающее название.
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')

Ссылка

С помощью метода url() можно установить ссылку на заголовок.

url(Closure|string $value)
url(Closure|string $value)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
    ->url(fn($data) => (new ArticleResource())->formPageUrl($data))
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->title('title')
    ->url(fn($data) => (new ArticleResource())->formPageUrl($data))

Подзаголовок

Метод subtitle() позволяет установить подзаголовок карточки.

subtitle(Closure|string $value)
subtitle(Closure|string $value)
  • $value - column или замыкание, возвращающее подзаголовок.
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->title('title')
    ->subtitle(static fn() => 'Подзаголовок')
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->title('title')
    ->subtitle(static fn() => 'Подзаголовок')

Миниатюра

Чтобы добавить изображение в карточку, можно использовать метод thumbnail().
В качестве аргумента методы принимают значение поля колонки или замыкание, возвращающее url изображения.

thumbnail(Closure|string $value)
thumbnail(Closure|string $value)
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->thumbnail('thumbnail')
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
    ->thumbnail('thumbnail')

Кнопки

Для добавления кнопок на основе ActionButton используйте метод buttons().

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->cast(ModelCast::make(Article::class))
    ->buttons([
        ActionButton::make('Удалить', route('name.delete')),
        ActionButton::make('Редактировать', route('name.edit'))->showInDropdown(),
        ActionButton::make('Перейти на главную', route('home'))->blank()->canSee(fn($data) => $data->active)
    ])
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->cast(ModelCast::make(Article::class))
    ->buttons([
        ActionButton::make('Удалить', route('name.delete')),
        ActionButton::make('Редактировать', route('name.edit'))->showInDropdown(),
        ActionButton::make('Перейти на главную', route('home'))->blank()->canSee(fn($data) => $data->active)
    ])

Режим наложения

Режим overlay позволяет разместить заголовок и названия поверх изображения карточки.
Этот режим активируется одноименным методом overlay().

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Text::make('Text')])
    ->cast(ModelCast::make(Article::class))
    ->thumbnail('thumbnail')
    ->header(static fn() => Badge::make('new', 'success'))
    ->title('title')
    ->subtitle(static fn() => 'Подзаголовок')
    ->overlay()
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Text::make('Text')])
    ->cast(ModelCast::make(Article::class))
    ->thumbnail('thumbnail')
    ->header(static fn() => Badge::make('new', 'success'))
    ->title('title')
    ->subtitle(static fn() => 'Подзаголовок')
    ->overlay()

Пагинатор

Метод paginator() для работы таблицы с пагинацией.

$paginator = Article::paginate();
 
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items($paginator->items())
    ->paginator($paginator)
$paginator = Article::paginate();
 
CardsBuilder::make()
    ->fields([Text::make('Text')])
    ->items($paginator->items())
    ->paginator($paginator)

Или напрямую передать пагинатор:

CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])
CardsBuilder::make(
    items: Article::paginate()
)
    ->fields([Text::make('Text')])

Асинхронный режим

Если вам нужно получать данные асинхронно (например, при пагинации), то используйте метод async().

async(
    ?string $asyncUrl = null,
    string|array|null $asyncEvents = null,
    ?string $asyncCallback = null
)
async(
    ?string $asyncUrl = null,
    string|array|null $asyncEvents = null,
    ?string $asyncCallback = null
)
  • asyncUrl - url запроса (по умолчанию запрос отправляется на текущий url),
  • asyncEvents - события, вызываемые после успешного запроса,
  • asyncCallback - js функция обратного вызова после получения ответа.
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->async()
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->async()

После успешного запроса вы можете вызывать события, добавив параметр asyncEvents.

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('crud')
    ->async(asyncEvents: ['cards-updated-crud'])
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->name('crud')
    ->async(asyncEvents: ['cards-updated-crud'])

MoonShine уже имеет набор готовых событий:

  • table-updated-{name} - асинхронное обновление таблицы по имени
  • cards-updated-{name} - асинхронное обновление группы карточек по имени,
  • form-reset-{name} - сброс значений формы по имени,
  • fragment-updated-{name} - обновление blade фрагмента по имени.

Для срабатывания события необходимо указать уникальное имя компонента!

Атрибуты

Вы можете установить любые html-атрибуты для таблицы с помощью метода customAttributes():

CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->customAttributes(['class' => 'custom-cards'])
CardsBuilder::make()
    ->items(Article::paginate())
    ->fields([ID::make(), Switcher::make('Active')])
    ->customAttributes(['class' => 'custom-cards'])

Колонки

Метод columnSpan() позволяет задать ширину карточек в Grid.

columnSpan(
    int $columnSpan,
    int $adaptiveColumnSpan = 12
)
columnSpan(
    int $columnSpan,
    int $adaptiveColumnSpan = 12
)
  • $columnSpan - значение для десктопной версии,
  • $adaptiveColumnSpan - значение для мобильной версии.
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->columnSpan(3)
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->columnSpan(3)

В админ-панели MoonShine используется 12-колоночная сетка.

Пользовательский компонент

Компонент CardsBuilder позволяет переопределить компонент для построения списка элемента.
Для этого нужно воспользоваться методом customComponent().

CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->customComponent(function (Article $article, int $index, CardsBuilder $builder) {
        return Badge::make($index + 1 . "." . $article->title, 'green');
    })
CardsBuilder::make(
    fields: [Text::make('Text')],
    items: Article::paginate()
)
    ->customComponent(function (Article $article, int $index, CardsBuilder $builder) {
        return Badge::make($index + 1 . "." . $article->title, 'green');
    })