Последние полгода наше комьюнити CutCode работает над новой версией нашей open-source админ-панели MoonShine. И вот недавно состоялся релиз MoonShine 2. Давайте пройдемся по всем значимым изменениям! Конечно, в одной статье я не смогу осветить все нововведения, но попробую сделать это по-максимуму. Ну а также расскажу о ближайших планах на MoonShine 3.
Новые требования
Laravel >= 10.20
PHP >= 8.1
Новый подход
Если смотреть на MoonShine 2 чисто визуально, то отличий не так и много. Да, у нас немного изменились некоторые поля и компоненты, появилось верхнее меню, но все это мелочь по сравнению с изменениями под капотом — там мы переписали 90% кода. В MoonShine 2 полностью новое ядро, которое дает невероятное количество дополнительных возможностей для разработчиков.
Ресурсы
Ресурсы уже не будут прежними. Теперь базовый ресурс вообще ничего не знает о Eloquent моделях и может работать с любым другим хранилищем.
Мы реализовали ресурс для моделей и называется он ModelResource. Те, кто использовал MoonShine 1, даже не увидят разницы в подходе. Но здесь нужно обратить внимание на то, что ресурс теперь изолирован и вы можете написать реализацию своего хранилища: будь то данные из внешнего api или парсинг лог файлов. Тут уже вы ограничиваетесь только своей фантазией.
Страницы
Новый постоянный житель MoonShine. Теперь страницы это основа MoonShine. Да у нас уже были кастомные страницы (которых к слову теперь нет), но текущие страницы не имеют границ и могут работать даже без ресурса. Ответственность у страниц это отображение компонентов, которых может быть сколько угодно — они могут быть компонентами MoonShine, либо просто blade компонентами или даже livewire! В итоге можно сказать, что ресурс это бокс с общей логикой для набора страниц. Но и опять-таки страницы могут существовать и без ресурса. Профиль пользователя это просто MoonShine-страница, которую можно заменить на свою, тоже самое касается и дашборда (главной страницы)
public function components(): array { return [ FormBuilder::make()->fields([ Block::make([ Grid::make([ Column::make([ Heading::make('Text'), ID::make(), Hidden::make('Hidden'), ])->columnSpan(6), Column::make([ Heading::make('Textarea'), Textarea::make('Textarea'), TinyMce::make('TinyMce'), ])->columnSpan(6), ]), LineBreak::make(), ]), ])->submit('Submit', ['class' => 'btn-lg btn-primary']), ]; }Слои
Как я уже говорил ранее, для вашего удобства мы уже написали ресурс для моделей — ведь все-таки мы используем Laravel, и я думаю в 99% случаев ресурсы будут на основе моделей. Также к ресурсу мы добавили готовые страницы:
-
для листинга записей (IndexPage),
-
добавления/редактирования(FormPage) ,
-
детальная(DetailPage).
Чтобы вам удобно было располагать и наполнять компоненты на этих страницах, мы добавили подход с использованием слоев (Layers). В итоге страницы выглядят следующим образом:
public function components(): array { return array_merge( $this->topLayer(), $this->mainLayer(), $this->bottomLayer(), ); }Теперь, для того чтобы добавить компоненты сверху, достаточно переопределить метод topLayer.
public function topLayer(): array { return [ Flex::make([ Heading::make('Title') ]) ->customAttributes(['class' => 'mb-4']) ->justifyAlign('end') ]; }Поля
Всё что нужно знать сейчас о полях, это то, что они также изолированы от модели и могут работать и без нее. Более подробно мы обсудим поля чуть ниже, когда будем рассматривать новые фичи.
Компоненты
Компоненты теперь сердце MoonShine. Всё что вы видите в MoonShine сделано компонентами. Вы можете их добавлять, перемещать, добавлять свои. За счет компонентов мы получили полноценный конструктор, и теперь процесс работы с админ-панелью напоминает сборку кубиков конструктора LEGO — очень увлекательный процесс! Ну и само собой, появилось много новых компонентов и декораций из коробки, о которых вы узнаете в документации.
LayoutBuilder
Изменять структуру основного шаблона теперь проще некуда. Убирайте компоненты, добавляйте свои, используйте декорации — буквально рисуйте шаблон по-своему! Давайте рассмотрим пример, где мы убираем боковую панель и подключаем верхнее меню:
final class MoonShineLayout implements MoonShineLayoutContract { public static function build(): LayoutBuilder { return LayoutBuilder::make([ Sidebar::make([ Menu::make()->customAttributes(['class' => 'mt-2']), ]), LayoutBlock::make([ Flash::make(), Header::make(), Content::make(), Footer::make()->copyright(fn (): string => <<<'HTML' © 2021-2023 Made with ❤️ by <a href="https://cutcode.dev" class="font-semibold text-primary hover:text-secondary" target="_blank" > CutCode a> HTML)->menu([ 'https://moonshine.cutcode.dev' => 'Documentation', ]), ])->customAttributes(['class' => 'layout-page']), ]); } }ActionButtons
Те, кто уже давно используют MoonShine, помнят, что у нас для кнопок в таблице были ItemAction, для массовых действий BulkAction, а в форме FormAction, а на детальной странице DetailAction, ах да еще общие Action для главной страницы сверху. Чуть сам не запутался пока писал) Но все это в прошлом! Встречайте — теперь кнопками правит ActionButton и эти красавцы умеют гораздо больше, чем толпа предыдущих сущностей вместе взятых.
ActionButton::make('Create', $resource->route('crud.create'));Нужно вызвать модалку по клику, с любым содержимым или подтверждением действий? Не проблема, для этого есть метод — inModal или withConfirm.
ActionButton::make('Create', $resource->route('crud.create')) ->inModal(fn() => 'Create', FormBuilder::make()),Хотите открыть offcanvas — пожалуйста, воспользуйтесь методом inOffCanvas.
ActionButton::make('Filtes', '#') ->secondary() ->icon('heroicons.outline.adjustments-horizontal') ->inOffCanvas( fn (): array|string|null => __('moonshine::ui.filters'), fn (): FormBuilder => new FiltersForm() )Кнопка может переходить на любой урл, а также можно получить асинхронно контент или загрузить блейд фрагмент (об этом немного позже), а самое важное что рендерятся они где угодно в MoonShine и есть хелперы для вызова в блейд.
actionBtn('Create', route('example.url')) ->inModal(fn() => 'Create', async: true),Думаю есть те кто будет ругать js в php классе, но такая возможность присутствует и стоит о ней сказать
ActionButton::make('Create', $resource->route('crud.create')) ->onClick(fn() => 'alert()', 'prevent'),FormBuilder
Прежде чем мы поговорим о новых возможностях полей, стоит заметить, что изменена их концепция. В MoonShine 1 поля были привязаны к ресурсу и их тяжело было применять за его пределами. Теперь поля можно рендерить отдельно где угодно, но есть и места где им самое место — и это конечно же форма! С приходом MoonShine 2 мы рады представить FormBuilder, c помощью которого вы можете легко наполнить форму полями и декорациями, указать какой тип данных будет у полей (TypeCasts, подробнее в документации), а также использовать Precognition или асинхронное сохранение.
TableBuilder
Еще одно важное место для хранения полей — TableBuilder. Теперь создать таблицу в MoonShine или за её пределами — не проблема. Наполняем её любыми данными и указываем тип данных с помощью TypeCasts. Как и с формами, поддерживается асинхронный режим. Появился инструмент для управления атрибутами ячеек и строк, теперь добавлять им классы, стили, да всё что угодно — можно через ComponentAttributeBag.
Fields
Как бы там ни было, но поля — это основа MoonShine, без них точно никуда. И они всюду. Давайте разберем, что появилось нового! Для начала еще раз повторюсь, что поля ничего не знают о моделях (за исключением полей отношений, тут уж никуда без моделей) и могут наполняться любыми данными, даже за пределами MoonShine. Также появились новые поля, о которых можно почитать подробнее в документации.
Помните фильтры? Ну так вот — их больше не существует и теперь поля могут быть фильтрами, а логику фильтрации вы сможете менять “на лету”.
Теперь можно получать доступ к вложенным элементам через точку (‘user.email’):
Preview::make('Email', 'user.email');Также логику можно выносить в отдельные Apply-классы, и регистрировать в системе. О Apply классах и MoonShineRegister подробнее смотрите в документации.
Поле Enum прокачали и добавили возможность указывать заголовок и цвет бейджа прямо в Enum, достаточно просто использовать методы getColor/toString.
enum ColorEnum: string { case Red = "R"; case Black = "B"; case White = "W"; public function getColor(): string { return match ($this->value) { "R" => 'purple', "B" => 'gray', "W" => 'green' }; } public function toString(): string { return match ($this->value) { "R" => 'Purple', "B" => 'Gray', "W" => 'Green' }; } }BelongsToMany теперь работает со всеми типами полей для pivot значений.
BelongsToMany::make('Categories', 'categories', resource: new CategoryResource()) ->fields(function () { return [ Date::make('Created at')->format('d.m.Y'), ]; })Async
Select можно указать url и получать опции селекта асинхронно, достаточно только соблюдать структуру ответа, которую мы укажем в документации.
Select::make('Select') ->async(route('async-search')) ->searchable(),UpdateOnPreview
Отобразить поля теперь можно в таблице в виде элемента формы и асинхронно сохранять при изменении.
Text::make('Title') ->updateOnPreview(fn ($item) => $this->route('resource.update-column', $item->getKey()))beforeRender/afterRender/changePreview/addAssets/onApply/onBeforeApple/onAfterApple/onAfterDelete
Мы улучшили интерфейс полей и добавили больше возможностей кастомизации без создания отдельного класса. Вот как это работает:
Text::make('Thumbnail') // Добавили дополнительные скрипты и стили для поля ->addAssets(['custom.js', 'custom.css']) // В форме до элемента отобразили превью с картинкой ->beforeRender(function (Text $field) { return $field->preview(); }) // Изменили превью, вместо текста отображаем изображение ->changePreview(function ($value) { return view('moonshine::ui.image', [ 'value' => $value ? Storage::url($value) : null, ]); }) // Изменили логику сохранения, где мы не просто сохраняем текст а загружаем изображение по указанному урл ->onApply(function (Article $item, string $value) { $path = 'thumbnail.jpg'; if ($value && $value !== $path) { Storage::put($path, file_get_contents($value)); $item->thumbnail = $path; } return $item; }),Badge/link
Добавить ссылку к полю или обернуть его в badge теперь можно для всех текстовых полей
Email::make('Title') ->badge('purple') ->link(fn($value) => "mailto:$value", 'Go to'),Json
Поле прокачали по-полной, принимает любые типы полей и даже может работать как отношение, отображая форму или таблицу прямо в основной форме
Json::make('Comments') ->asRelation(new CommentResource()) ->fields([ ID::make(), BelongsTo::make('Article') ->setColumn('article_id') ->searchable(), BelongsTo::make('User') ->setColumn('user_id'), Text::make('Text')->required(), Image::make('Files') ->multiple() ->removable() ->disk('public') ->dir('comments'), ]) ->creatable() ->removable()Resource
Еще раз напомню, что в MoonShine 2 ресурс теперь может работать и не на основе моделей. Но все-таки ресурс с моделями у нас прямо в коробке. И он очень похож на тот, который мы использовали в первой версии. Но также появились и новые подходы, а именно:
-
Раздельный подход, где у нас под каждый тип полей (для главной, формы, детальной страницы) свои отдельные методы.
-
С публикацией всех страниц ресурса, которые вы сможете кастомизировать по-своему.
-
Полностью пустой ресурс для нетривиальных задач.
Иконку можно менять прямо в ресурсе через атрибут
#[Icon('heroicons.users')] class ArticleResource extends ModelResourceБыл прокачан поиск по ресурсу и по json, доступ к отношениям и многое другое (смотрим документацию).
Basic
Fragments
Появилась новая декорация Fragment, которая дает возможность использовать blade fragments, отмечать блоки на странице и подгружать их асинхронно.
Fragment::make([ TableBuilder::make(items: $this->getResource()->paginate()) ->fields($this->getResource()->getIndexFields()) ->buttons([ ...$this->getResource()->getIndexButtons(), ]), ])->withName('crud-table'),Generics
Мы стараемся улучшать интерфейс и внедрили аннотации с дженериками для нашего с вами удобства.
Произвольные правила авторизации
Будет полезно для тех, кто пишет пакеты для MoonShine. Теперь можно регистрировать собственные правила валидации и все они будут применяться в ресурсе.
public function boot(): void { MoonShine::defineAuthorization( static function (ResourceContract $resource, Model $user, string $ability, Model $item): bool { $hasUserPermissions = in_array( HasMoonShinePermissions::class, class_uses_recursive($user), true ); if (! $hasUserPermissions) { return true; } if (! $user->moonshineUserPermission) { return true; } return isset($user->moonshineUserPermission->permissions[$resource::class][$ability]); } ); }Handlers
Удобные классы для реализации логики в MoonShine.
class ExportHandler extends Handler { public function handle(): Response { // Logic } }Красота и сахар
Теперь прямо из коробки доступен компонент с верхним меню вместо левого сайдбара.
return LayoutBuilder::make([ TopBar::make([ Menu::make()->top(), ]), // ... ]);Кастомизация темы и цветовой схемы. Фон, кнопки и другие элементы запросто можно перекрасить.
protected function theme(): array { return [ 'colors' => [ 'body' => '#fff' ] ]; }Директива с ассетами MoonShine, чтобы можно было использовать возможности MoonShine за её пределами.
<head> @moonShineAssets head>Sortable прямо в коробке и уже интегрированы в поля Json/Image/File
x-data="sortable"Helpers для тех кому нравятся хелперы
moonshine() moonshineRegister() to_page() moonshineRequest() moonshineAssets() moonshineMenu() moonshineLayout() form() table() actionBtn() // ...Toasts improvements
Toasts можно вызвать в js.
Stubs для всего
Да кстати, мы интегрировали Laravel Prompts во все консольные команды. Понять структуру кастомных полей или компонентов для разработчиков теперь будет куда проще. Да и установка MoonShine теперь сводится к одной команде.
php artisan moonshine:field php artisan moonshine:component php artisan moonshine:apply php artisan moonshine:controller php artisan moonshine:layout php artisan moonshine:pageНовый домен
Проект разрастается и переехал на новый домен — https://moonshine-laravel.com
План на 3.0
-
Интеграция Laravel Echo, наконец-таки вебсокеты
-
Multi tenancy
-
Бесконечная вложенность в меню
-
Асинхронное удаление полей и записей
-
Новые шаблоны и темы
-
2FA
-
Вложенные ресурсы
Заключение
Обновление получилось очень большим и трудозатратным. И я рассказал только о самых больших изменениях. Подробнее можно посмотреть в обзорном видео:
Работая по MoonShine v.2 мы реализовали много пожеланий участников нашего комьюнити, а некоторые разработчики втягиваются в разработку, реализовывая свои же предложения. Всех Laravel-разработчиков приглашаю присоединиться — использовать MoonShine2 в своих проектах и участвовать в open source разработке.
Данил Щуцкий, автор проекта CutCode.
ссылка на оригинал статьи https://habr.com/ru/articles/774832/
Добавить комментарий