Основы

Полям отводится важнейшая роль в админ-панели MoonShine.
Они используются в FormBuilder для построения форм, в TableBuilder для создания таблиц, а также в формировании фильтра для ModelResource. Их можно использовать в ваших кастомных страницах и даже вне админ-панели.
Поля в MoonShine не привязаны к модели (за исключением поля Slug, ModelRelationFields, Json в режиме asRelation), поэтому спектр их применения ограничивается только вашей фантазией.

Для удобства у полей реализован fluent интерфейс.

# Make

Для создании экземпляра поля используется статический метод make().

Text::make(Closure|string|null $label = null, ?string $column = null, ?Closure $formatted = null)
  • $label - лейбл, заголовок поля,
  • $column - поле в базе (например name) или отношение (например countries),
  • $formatted - замыкание для форматирования значения поля при превью (везде кроме формы).

Если не указать $column, то поле в базе данных будет определено автоматически на основе $label.

# Форматирование значения

//...
 
public function fields(): array
{
return [
Text::make(
'Name',
'first_name',
fn($item) => $item->first_name . ' ' . $item->last_name
)
];
}
 
//...

Поля не поддерживающие formatted: Json, File, Range, RangeSlider, DateRange, Select, Enum, HasOne, HasMany.

# Label

Если необходимо изменить Label, можно воспользоваться методом setLabel()

setLabel(Closure|string $label)
//...
 
public function fields(): array
{
return [
Slug::make('Slug')
->setLabel(
fn(Field $field) => $field->getData()?->exists
? 'Slug (do not change)'
: 'Slug'
)
];
}
 
//...

Для перевода Label необходимо в качестве названия передать ключ перевода и добавить метод translatable()

translatable(string $key = '')
//...
 
public function fields(): array
{
return [
Text::make('Title')->translatable('ui')
];
}
 
//...

или

//...
 
public function fields(): array
{
return [
Text::make('ui.Title')->translatable()
];
}
 
//...

# Атрибуты

Основные html атрибуты, такие как required, disabled и readonly, у поля необходимо задавать через соответствующие методы.

disabled(Closure|bool|null $condition = null)
hidden(Closure|bool|null $condition = null)
required(Closure|bool|null $condition = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->disabled()
->hidden()
->readonly()
];
}
 
//...

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

customAttributes(array $attributes)
//...
 
public function fields(): array
{
return [
Password::make('Title')
->customAttributes(['autocomplete' => 'off'])
];
}
 
//...

Метод customWrapperAttributes() позволяет добавить атрибуты для wrapper поля.

customWrapperAttributes(array $attributes)
//...
 
public function fields(): array
{
return [
Password::make('Title')
->customWrapperAttributes(['class' => 'mt-8'])
];
}
 
//...

# Подсказка

Полю можно добавить подсказку с описанием вызвав метод hint()

hint(string $hint)
//...
 
public function fields(): array
{
return [
Number::make('Rating')
->hint('From 0 to 5')
->min(0)
->max(5)
->stars()
];
}
 
//...

Полю можно добавить ссылку (например с инструкциями) link().

link(
string|Closure $link,
string|Closure $name = '',
?string $icon = null,
bool $withoutIcon = false,
bool $blank = false
)
//...
 
public function fields(): array
{
return [
Text::make('Link')
->link('https://cutcode.dev', 'CutCode', blank: true)
];
}
 
//...

# Nullable

Если необходимо у поля по умолчанию сохранять NULL, то необходимо использовать метод nullable().

nullable(Closure|bool|null $condition = null)
//...
 
public function fields(): array
{
return [
Password::make('Title')
->nullable()
];
}
 
//...

# Сортировка

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

sortable(Closure|string|null $callback = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->sortable()
];
}
 
//...

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

//...
 
public function fields(): array
{
return [
BelongsTo::make('Author')->sortable('author_id'),
 
Text::make('Title')->sortable(function (Builder $query, string $column, string $direction) {
$query->orderBy($column, $direction);
})
];
}
 
//...

# Badge

Для отображения поля в режиме preview в виде badge, необходимо воспользоваться методом badge().

badge(string|Closure|null $color = null)

Доступные цвета:

primary secondary success warning error info

purple pink blue green yellow red gray

//...
 
public function fields(): array
{
return [
Text::make('Title')
->badge(fn($status, Field $field) => 'green')
];
}
 
//...

# Отображение

В ресурсе модели поля отображаются на странице со списком (главная страница) и на страницах создания/редактирования/просмотра.

Чтобы исключить вывод поля на какой-либо странице, можно воспользоваться соответствующими методами hideOnIndex(), hideOnForm(), hideOnDetail() или обратные методы showOnIndex(), showOnForm(), showOnDetail().

Чтобы исключить только со страницы редактирования или добавления - hideOnCreate(), hideOnUpdate(), а также обратные showOnCreate(), showOnUpdate.

Для того чтобы исключить поле на всех страниц можно воспользоваться методом hideOnAll().

hideOnIndex(Closure|bool|null $condition = null)
showOnIndex(Closure|bool|null $condition = null)
hideOnForm(Closure|bool|null $condition = null)
showOnForm(Closure|bool|null $condition = null)
 
hideOnCreate(Closure|bool|null $condition = null)
showOnCreate(Closure|bool|null $condition = null)
 
hideOnUpdate(Closure|bool|null $condition = null)
showOnUpdate(Closure|bool|null $condition = null)
hideOnDetail(Closure|bool|null $condition = null)
showOnDetail(Closure|bool|null $condition = null)
hideOnAll(Closure|bool|null $condition = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->hideOnIndex()
->hideOnForm(),
 
Switcher::make('Active')
->hideOnAll()
->showOnIndex(static fn() => true)
];
}
 
//...

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

# Динамическое отображение

Может возникнуть потребность отображать поле только в том случае, если значение у другого поля в форме имеет определенное значение (Например: отображать телефон, только если стоит галочка, что телефон есть).
Для этих целей используется метод showWhen().

showWhen(
string $column,
mixed $operator = null,
mixed $value = null
)

Доступные операторы:

= < > <= >= != in not in

Если оператор не указан, то будет использоваться =

//...
 
public function fields(): array
{
return [
Checkbox::make('Has phone', 'has_phone'),
Phone::make('Phone')
->showWhen('has_phone','=', 1)
];
}
 
//...

Если оператор имеет значение in или not in, то в $value необходимо передать массив

//...
 
public function fields(): array
{
return [
Select::make('List', 'list')->multiple()->options([
'value 1' => 'Option Label 1',
'value 2' => 'Option Label 2',
'value 3' => 'Option Label 3',
]),
 
Text::make('Name')
->showWhen('list', 'not in', ['value 1', 'value 3']),
 
Textarea::make('Content')
->showWhen('list', 'in', ['value 2', 'value 3'])
];
}
 
//...

В методе showWhen() для полей Json и BelongsToMany получить доступ к вложенным значениям можно через .:

->showWhen('data.content.active', '=', 1)

# Изменение отображения

Когда необходимо изменить view с помощью fluent interface можно воспользоваться методом customView().

customView(string $customView)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->customView('fields.my-custom-input')
];
}
 
//...

Метод changePreview() позволяет переопределить view для превью (везде кроме формы).

changePreview(Closure $closure)
//...
 
public function fields(): array
{
return [
Text::make('Thumbnail')
->changePreview(function ($value, Field $field) {
return view('moonshine::ui.image', [
'value' => Storage::url($value)
]);
})
];
}
 
//...

Метод forcePreview() укажет что поле должно быть всегда в режиме preview

Text::make('Label')->forcePreview()

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

requestValueResolver(Closure $closure)
//...
 
public function fields(): array
{
return [
Text::make('Thumbnail')
->requestValueResolver(function (string $nameDot, mixed $default, Field $field) {
return request($nameDot, $default);
})
];
}
 
//...

Методы beforeRender() и afterRender() позволяют вывести какую-то информацию перед и после поля соответственно.

beforeRender(Closure $closure)
afterRender(Closure $closure)
//...
 
public function fields(): array
{
return [
Image::make('Thumbnail')
->beforeRender(function (Field $field) {
return $field->preview();
})
];
}
 
//...

# Методы по условию

Метод when() реализует fluent interface и выполнит callback, когда первый аргумент, переданный методу, имеет значение true.

when($value = null, callable $callback = null)
//...
 
public function fields(): array
{
return [
Text::make('Slug')
->when(fn() => true, fn(Field $field) => $field->locked())
];
}
 
//...

Экземпляр поля, будет передан в функции callback.

Методу when() может быть передан второй callback, он будет выполнен, когда первый аргумент, переданный методу, имеет значение false.

when($value = null, callable $callback = null, callable $default = null)
//...
 
public function fields(): array
{
return [
Text::make('Slug')
->when(
auth('moonshine')->user()->moonshine_user_role_id === 1,
fn(Field $field) => $field->locked(),
fn(Field $field) => $field->readonly()
)
];
}
 
//...

Метод unless() обратный методу when() и выполнит первый callback, когда первый аргумент имеет значение false, иначе будет выполнен второй callback, если он передан методу.

unless($value = null, callable $callback = null, callable $default = null)
//...
 
public function fields(): array
{
return [
Text::make('Slug')
->unless(
auth('moonshine')->user()->moonshine_user_role_id === 1,
fn(Field $field) => $field->readonly()->hideOnCreate(),
fn(Field $field) => $field->locked()
)
];
}
 
//...

# Заполнение

Поля можно заполнить значениями использую метод fill().

fill(mixed $value, mixed $casted = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->fill('Some title')
];
}
 
//...

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

fill(mixed $value, mixed $casted = null)
//...
 
public function fields(): array
{
return [
Text::make('Categories')
->changeFill(
fn(Article $data, Field $field) => $data->categories->implode('title', ',')
)
];
}
 
//...

Поля отношений не поддерживают метод changeFill

# Apply

У каждого поля реализован метод apply(), который трансформирует данные с учетом request и resolve методов. Например, трансформирует данные модели для сохранения в базе данных или формирует запрос для фильтрации.

Существует возможность переопределить действия при выполнении метода apply(), для этого необходимо воспользоваться методом onApply() который принимает замыкание.

onApply(Closure $onApply)
//...
 
public function fields(): array
{
return [
Text::make('Thumbnail by link', 'thumbnail')
->onApply(function(Model $item, $value, Field $field) {
$path = 'thumbnail.jpg';
 
if ($value) {
$item->thumbnail = Storage::put($path, file_get_content($value));
}
 
return $item;
})
];
}
 
//...

Если поле используется для построения фильтра, то в замыкание будет передан Query Builder.

use Illuminate\Contracts\Database\Eloquent\Builder;
 
//...
 
public function filters(): array
{
return [
Switcher::make('Active')
->onApply(fn(Builder $query, $value, Field $field) => $query->where('active', $value))
];
}
 
//...

Если вы не хотите чтобы поле выполняло какие-то действия, то можно воспользоваться методом canApply().

canApply(Closure|bool|null $condition = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->canApply()
];
}
 
//...

# События

Иногда может возникнуть потребность переопределить resolve методы, которые выполняются до и после apply(), для этого необходимо воспользоваться соответствующими методами.

onBeforeApply(Closure $onBeforeApply)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->onBeforeApply(function(Model $item, $value, Field $field) {
//
return $item;
})
];
}
onAfterApply(Closure $onAfterApply)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->onAfterApply(function(Model $item, $value, Field $field) {
//
return $item;
})
];
}
onAfterDestroy(Closure $onAfterDestroy)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->onAfterDestroy(function(Model $item, $value, Field $field) {
//
return $item;
})
];
}

# Assets

Для поля есть возможность загрузить дополнительные css стили и js скрипты, используя метод addAssets().

addAssets(array $assets)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->addAssets(['custom.css', 'custom.js'])
];
}

# Wrapper

Поля при отображении в формах используют специальную обертку wrapper для заголовков, подсказок, ссылок и тд. Иногда может возникнуть ситуация, когда требуется отобразить поле без дополнительных элементов.
Метод withoutWrapper() позволяет отключить создание wrapper.

withoutWrapper(mixed $condition = null)
//...
 
public function fields(): array
{
return [
Text::make('Title')
->withoutWrapper()
];
}

# Реактивность

Метод reactive() позволяет реактивно изменять поля.

reactive(
?Closure $callback = null,
bool $lazy = false,
int $debounce = 0,
int $throttle = 0,
)
  • $callback - callback функция,
  • $lazy - отложенный вызов функции,
  • $debounce - время между вызовами функций (ms.),
  • $throttle - интервал вызова функций (ms.).
Callback

Callback функция в методе reactive() принимает параметры, которыми вы можете воспользоваться для построения своей логики.

function(Fields $fields, ?string $value, Field $field, array $values)
  • $fields - реактивные поля,
  • $value - значение поля которе инициирует реактивность,
  • $field - поле инициирующее реактивность,
  • $values - значения реактивных полей.

Поля поддерживающие реактивность: Text, Checkbox, Select и их наследующие.

FormBuilder::make()
->name('my-form')
->fields([
Text::make('Title')
->reactive(function(Fields $fields, ?string $value): Fields {
return tap($fields, static fn ($fields) => $fields
->findByColumn('slug')
?->setValue(str($value ?? '')->slug()->value())
);
}),
 
Text::make('Slug')
->reactive()
])

В данном пример реализовано формирование slug-поля на основе заголовка.
Slug будет генерироваться в процессе ввода текста.

Реактивное поле может менять состояние других полей, но не изменяет свое состояние!

Для изменения состояния поля инициирующего реактивность удобно воспользоваться параметрами callback функции.

Select::make('Category', 'category_id')
->reactive(function(Fields $fields, ?string $value, Field $field, array $values): Fields {
$field->setValue($value);
 
return tap($fields, static fn ($fields) =>
$fields
->findByColumn('article_id')
?->options(
Article::where('category_id', $value)
->get()
->pluck('title', 'id')
->toArray()
);
);
})

# Методы onChange

C помощью методов onChangeMethod() и onChangeUrl() можно добавить логику при изменении значений полей.

Методы onChangeUrl() или onChangeMethod() присутствуют у всех полей, кроме полей отношений HasOne и HasMany.

onChangeUrl()

Метод onChangeUrl() позволяет асинхронно отправить запрос при изменении поля.

onChangeUrl(
Closure $url,
string $method = 'PUT',
array $events = [],
?string $selector = null,
?string $callback = null,
)
  • $url - url запроса,
  • $method - метод асинхронного запроса,
  • $events - вызываемые события после успешного запроса,
  • $selector - selector элемента у которого будет изменяться контент,
  • $callback - js callback функция после получения ответа.
//...
 
public function fields(): array
{
return [
Switcher::make('Active')
->onChangeUrl(fn() => '/endpoint')
];
}

Если требуется заменить область с html после успешного запроса, вы можете в ответе вернуть HTML контент или json с ключом html.

//...
 
public function fields(): array
{
return [
Switcher::make('Active')
->onChangeUrl(fn() => '/endpoint', selector: '#my-selector')
];
}
onChangeMethod()

Метод onChangeMethod() позволяет асинхронно вызывать метод ресурса или страницы при изменении поля без необходимости создавать дополнительные контроллеры.

onChangeMethod(
string $method,
array|Closure $params = [],
?string $message = null,
?string $selector = null,
array $events = [],
?string $callback = null,
?Page $page = null,
?ResourceContract $resource = null,
)
  • $method - наименование метода,
  • $params - параметры для запроса,
  • $message - сообщения,
  • $selector - selector элемента у которого будет изменяться контент,
  • $events - вызываемые события после успешного запроса,
  • $callback - js callback функция после получения ответа,
  • $page - страница содержащая метод,
  • $resource - ресурс содержащий метод.
//...
 
public function fields(): array
{
return [
Switcher::make('Active')
->onChangeMethod('someMethod')
];
}
public function someMethod(MoonShineRequest $request): void
{
// Logic
}

Пример сортировки компонента CardsBuilder в разделе Recipes

# Схема работы поля