Рождение идеи.

Так получилось, что некоторые из последних проектов в нашей компании были выполнены как REST-like API на OctoberCMS + фронтенд на Nuxt.js.

Я разрабатывал первую часть и мне надо было как-то рассказывать frontend-разработчику какие роуты есть у нас в API. Для этого я поддерживал коллекцию роутов в Postman. Всё шло не плохо, пока мне, наконец, это не надоело. Тогда меня посетила мысль: "зачем мне поддерживать коллекцию в постмане, если у меня в коде уже всё есть?".

Так родилась идея создания плагина для OctoberCMS, про который я расскажу в этой статье.

Плагин GromIT.RoutesBrowser

Итак GromIT.RoutesBrowser - это плагин, который отображает в админке на отдельной странице все роуты вашего приложения (за исключением системных, и роутов темы) с документацией, собираемой из кода и докблоков с помощью Reflection API.

Самый простой способ понять, как с этим работать - это создать плагин с файлом routes.php и добавить какой-нибудь роут.

Например, что-то такое:

Далее, открываем страницу плагина в админке сайта и видим следующую картину:

Как видно из скриншота, информация о роуте заполнилась следующим образом:

• HTTP-метод и URI роута - из самого описания роута в файле route.php
• комментарий - из докблока к обработчику роута
• тип и комментарий к параметру name из него же
• параметры запроса с описанием типов и комментариями - из докблока к классу запроса

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

Вот, собственно, и всё.

Вместо заключения

Данный плагин - не замена Postman или Swagger и он точно не предназначен для публичных API. Это скорее аналог php artisan route:list для тех, кому лень идти в терминал.

Скачать плагин:

• GitHub
• Packagist

Плагин интеграции подсказок сервиса Dadata в OctoberCMS v.2

Установка

composer require gromit/oc-dadatawidgets-plugin

Настройка

Для использования плагина, необходимо получить токен сервиса Dadata. Получить токен можно бесплатно - необходимо зарегистрироваться на сайте https://dadata.ru/ и скопировать его в профиле.

Полученный токен (он же АПИ КЛЮЧ) вставляем в настройки плагина через Настройки -> Dadata Widgets

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

В конфиге формы указываем тип поля dadataSuggestions, тип подсказки suggestion и привязку данных к полям формы.

Пример конфига поля:

Маппер

В конфиге поля можно указать соответствие данных, получаемых из сервиса Dadata, и полей формы, куда эти данные вставить.

Структура возвращаемых данных сервиса Dadata зависит от типа подсказки:

suggestion: company -> https://dadata.ru/api/suggest/party/#response

suggestion: bank -> https://dadata.ru/api/suggest/bank/#response

suggestion: address -> https://dadata.ru/api/suggest/address/#response

suggestion: email -> https://dadata.ru/api/suggest/email/#response

suggestion: fio -> https://dadata.ru/api/suggest/name/#response

Соответственно в маппере используем описанные выше структуры данных.

Примеры

Небольшие примеры использования виджета для разных ситуаций

Поиск контрагента и заполнение нужных полей

Поиск банка

Ввод адреса и его последующий разбор

Помощь при вводе email-адреса и его разбор

Помощь при вводе ФИО и разбор

С появлением поддержки Vue.js в новом October, открылись новые возможности по созданию виджетов и прочих интересных вещей в админке нашей любимой CMS.

Так как документации по поводу использования Vue.js в настоящий момент еще нет и автор не претендует на звание Кунг-Vue мастера, то публикуем этот гайд исходя из опыта, полученного в процессе изучения исходников новой системы.

Задача

Задача простая, бесполезная, но сгодится для примера - это создание formWidget'а для получения адреса, с использованием Яндекс.Карт

Подготовка

Перед тем как начать - создадим тестовый плагин, назовем его Address.
Данный материал предполагает, что читатель знаком с базовыми командами по созданию плагинов, моделей и пр. в OctoberCMS.

Далее ускоренный прогон - миграция, модель, контроллер.

Не забываем обновить файл updates/version.yaml

и выполнить:

Не стану описывать, что и как - мы только что создали простой скелет, для того, чтобы было куда "прицепить" наш formWidget.

Создание виджета

Пробежимся по созданию виджета - следуя документации. Назовем наш виджет MapPicker

В итоге у нас будет создан шаблон нашего виджета, с ним и будем работать.

Сразу зарегистрируем виджет (согласно документации) в файле Plugin.php нашего плагина SandBox:

И добавим поле address с типом mapPicker в yaml-файл sandbox/address/models/address/fields.yaml

Теперь в браузере перейдем на страницу /backend/sandbox/address/addresses/create и увидим стандартный сгенерированный шаблон виджета. С ним и будем работать.

Итак, что мы хотим здесь видеть:

1. Поле ввода адреса
2. Кнопку, которая откроет в модальном окне карту
3. Собственно карту, при клике по которой, мы получим адрес и вставим его в поле ввода

Поле и кнопка

Поправим стандартный шаблон партиалки, добавив в него кнопку и немного css.

Получили примерно то, что надо =)

Далее используем стандартный компонент <backend-component-modal>, немного покопавшись в исходниках модуля editor и подглядев, как его вызывать.

Немного модифицируем нашу партиалку:

Проверяем:

Ура, получилось! Дело за малым, наполнить модалку картой и функционалом.

Яндекс.Карты

Достаточно просто и красиво всё описано тут - https://vue-yandex-maps.github.io/

Немного модифицируем файл виджета, добавив в метод загрузки ассетов одну строку

Ну вот и всё - согласно документации, мы подключили плагин карт напрямую, и теперь дело техники, подпилить нашу партиалку для работы с ним.

Долго описывать не будем - покажем результат модифицированной партиалки

И немного докинем стилей в css

Результат

Собственно, чтобы не придумывать велосипед - небольшое видео-демонстрация

Исходники виджета можно скачать тут https://github.com/gromitsoft/sandbox-formwidget

В данном уроке мы рассмотрим разработку REST API на основе OctoberCMS.

Для чего это может понадобиться? Например, для создания роутов для последующего обращения к ним через AJAX.

Тут читатель может возразить, что в October для этого есть встроенный
AJAX-фреймворк, работающий с компонентами и методами, находящимися прямо в файле страницы и будет прав. Но в некоторых случаях встроенный
AJAX-фреймворк может быть не удобен или совсем не подходить. Особенно, при внедрении сторонних библиотек с динамической подгрузкой данных, таких как Select2.

Также, как показала практика, OctoberCMS отлично подходит как основа для headless решений, предоставляющих REST API для SPA или мобильных приложений, с удобной админкой в комплекте.

Приступая к работе

Как известно, OctoberCMS основан на Laravel. Из этого следует, что разработка REST API на OctoberCMS будет очень похожа на разработку REST API на Laravel.

Данный урок подразумевает, что Вы уже умеете создавать плагины для OctoberCMS. Также нам понадобится развернутый проект и немного свободного времени.

Начало

Для начала необходимо создать плагин. Для этого, как обычно, пойдем в консоль и попросим artisan создать нам пустой плагин.

Или создадим всё вручную (или даже через Builder), кому как больше нравится.

Далее, для объявления роутов нашего REST API создадим файл /plugins/sandbox/restapi/routes.php и объявим в нем наш первый роут.

Теперь, если обратиться к этому роуту, то мы увидим ответ - hello rest api. Для этого мы обычно используем Postman.

Далее - все как и в случае с Laravel. Только папку для контроллеров нам придется создать самостоятельно. Создадим наш контроллер, например, в файле /plugins/sandbox/restapi/http/controllers/HelloController.php, и добавим роут для него:

Теперь обратимся к роуту /api/hello/John%20Doe и увидим, что наш API отвечает соответствующим образом.

Главное здесь - наследовать контроллеры от Illuminate\Routing\Controller, то есть от базового контроллера Laravel. А не от Backend\Classes\Controller, так как последний предназначен для создания страниц в админ-панели OctoberCMS и плохо подходит для нашей задачи.

Особенности

OctoberCMS - это, в первую очередь, система предназначенная для разработки сайтов с классическим роутингом и генерацией HTML-страниц на сервере, а не REST API, поэтому некоторые вещи для разработки REST API подготовлены не очень хорошо.

Основные вопросы - обработка исключений и CORS.

Обработка исключений

В Laravel, если мы запросим роут страницы через браузер и в процессе обработки запроса будет выброшено исключение - мы увидим красивую страницу с кучей полезной информации. В случае же с XHR запросом - получим json с текстом ошибки, кодом и стеком вызовов. И происходит это автоматически, то есть стандартный обработчик ошибок в Laravel сам понимает, какой ответ нам нужен. В случае с OctoberCMS это не так.

Чтобы в этом убедиться, создадим роут, который, просто выбросит ошибку валидации, а затем обратимся к этому роуту.

Откроем Postman и запросим наш роут, не забывая при этом добавить заголовок X-Requested-With со значением XMLHttpRequest, чтобы приложение понимало, что у нас тут AJAX-запрос и отправлять отрендеренную страницу не нужно.

Не густо! Что ж, значит нам придется сделать обработку исключений самим.

Согласно документации, для этого надо в методе boot класса Plugin нашего плагина добавить конструкцию вида:

Теперь попробуем обратиться к роуту еще раз.

Уже лучше. Но теперь появилась другая проблема: так как мы переопределили обработку для ошибок валидации, то у нас теперь не будет работать стандартная валидация в админке и на фронте.

Для проверки этого утверждения, создадим пустой контроллер для админки, добавим в него метод index и бросим ошибку валидации.

Теперь откроем эту страницу в браузере.

Да - это не то, что мы привыкли видеть в браузере, в случае ошибки.

Для решения этой проблемы мы перенесем регистрацию хэндлера ошибок валидации в новый middleware.

Создадим класс ExceptionsMiddleware, разместим его в /plugins/sandbox/restapi/http/middleware/ExceptionsMiddleware.php и добавим следующий код:

Добавим наш новый middleware в файл routes.php

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

CORS

Следующий интересный вопрос - CORS.

Если Вы не знаете, что такое CORS, то CORS (Cross-Origin Resource Sharing) - это механизм, позволяющий с помощью дополнительных заголовков запросов и ответов получать доступ к ресурсам других доменов. Подробнее можно почитать здесь.

В Laravel, начиная с 7-ой версии, есть встроенный middleware для работы с CORS. В OctoberCMS же его нет. А это значит, что этот вопрос нам придется решить самим.

В Laravel встроенный middleware работает на основе пакета fruitcake/laravel-cors. Не будем изобретать велосипед и поступим так же.

Про особенности работы с composer в OctoberCMS рекомендую ознакомиться с документацией. В нашем случае, будем считать, что разрабатываемый плагин предназначен исключительно для текущего проекта, а значит все зависимости будем добавлять в корневой composer.json.

Идем в консоль и просим composer установить нам этот пакет.

Данный пакет требует конфига. Следуя рекомендациям из документации OctoberCMS создем конфиг не в общей папке проекта, а в папке плагина /plugins/sandbox/restapi/config/cors.php

А затем регистрируем конфиг в методе boot класса Plugin нашего плагина, а также зарегистрируем ServiceProvider пакета и добавим глобальный middleware.

Заключение

Вещи описанные в статье, на самом деле, не обязательные, и разрабатывать REST API на OctoberCMS можно и без них, однако обработка исключений не плохо упрощает жизнь, а CORS - необходимая вещь, если вы разрабатываете API обращение к которому будет происходить с домена отличного от того, на котором это API находится.

Код из статьи можно найти в репозитории

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

Решение очень простое, для этого необходимо добавить пункты, которые вы хотите видеть в этом меню в метод registerSettings() вашего плагина.

Пример добавления своего пункта:

То есть, необходимо всего лишь указать контекст для вашего пункта, и, чтобы он отобразился в выпадающем меню, значение контекста должно быть равно mysettings.

Результат будет таким:

Свершилось, дождались =)

Помимо косметики в бэке разработчики добавили, но пока не задокументировали новый набор иконок.

Иконки вытащили и собрали в pdf, собирать в страницу лень =)

Скачать можно тут - https://github.com/gromitsoft/sandbox/blob/master/new-icons.pdf

Давайте разберемся - в чем разница.

Двойные кавычки VS Одинарные кавычки

Двойные кавычки позволяют вставлять переменные и специальные символы, а одинарные нет - вот и вся концептуальная разница.

Какие преимущества?

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

Для тех, кто не в теме - ребята из spatie.be сделали отличный видеокурс по новинкам в PHP 8.

Ссылка на видеокурс - https://spatie.be/videos/front-line-php

На чем мы остановились в предыдущей части? Мы создали следующее:

• плагин landing и миграцию
• проработали модель Page
• настроили поля формы и колонки для списка

В итоге на финальном этапе первого урока у нас была следующая картина:

Мы сделали один вариант страницы лендинга и заполнили его тестовым содержимым.

Компонент

Компоненты, в рамкам OctoberCms это настраиваемые элементы, которые могут быть прикреплены к любой странице или шаблону. Мы можем создавать любое количество компонентов для любых задач, которые могут быть использованы на фронте.

Тут снова без выкрутасов - всё очень подробно расписано в документации OctoberCms - https://octobercms.com/docs/plugin/components

Для нашей задачи нам предстоит создать всего один компонент. Назовем его Page.

Для создания компонента воспользуемся следующей командой:

php artisan create:component sandbox.landing page

В результате выполнения команды в директории нашего плагина будет создан компонент Page с подобной структурой

Поправим файл Page.php под наши нужды

И самое главное - не забыть зарегистрировать компонент в нашем плагине, для этого откроем Plugin.php и добавим следующее:

Итак, мы создали простейший компонент, который берет из настроек идентификатор страницы и отдает ее в переменную landing.

На самом деле, даже этот вариант можно улучшать и улучшать, но цель уроков - ознакомление с возможностями.

Тема для лендинга.

Для нашей лендинговой темы, мы не будем изобретать велосипед и возьмем, уже полюбившуюся всем, стартовую тему demo - просто скопируем ее в папку landing.

Поправим файл themes/landing/theme.yaml

Далее подправим файл шаблона themes/landing/pages/home.htm, подготовив его для дальнейшей работы.

Готово. Теперь наш сайт выглядит примерно так:

Не очень круто =)

Подключение компонента и еще немного правок шаблона.

В панели управления переходим в раздел CMS, открываем шаблон нашей темы и бросаем туда компонент Landing.

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

Страницу South Park: The Fractured but Whole мы создали и наполнили контентом в первой части этого повествования.

Компонент подключен к шаблону, соответственно свойства и методы его теперь доступны на всех страницах, которые используют этот шаблон.

Далее отредактируем файл themes/landing/partials/site/header.htm

Удалим всё - добавим такое содержимое:

{{ landing.title }} - это название нашей страницы

После чего, наш сайт стал выглядеть так:

Уже лучше!

Группы контента

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

Группы мы определили при создании модели и формы - это:

• text
• image
• features
• slider

Чтобы убедиться - вернемся к файлу plugins/sandbox/landing/models/page/groups.yaml

В нашей теме в разделе в themes/landing/partials создадим папку content, где сложим шаблоны для каждой группы контента.

В папке themes/landing/partials/content создадим следующие файлы:

• text.htm
• image.htm
• features.htm
• slider.htm

Должна получиться такая структура:

Далее вернемся в файлу themes/landing/pages/home.htm и отредактируем его следующим образом.

Что означает эта конструкция:

В цикле мы перебираем содержимое landing.content, это содержимое состоит из именованных групп и содержимого этих групп.

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

Партиалим!

text.htm

Начнем с файла themes/landing/partials/content/text.htm

Приведем его к следующему виду:

image.htm

Партиалку для отображения картинки themes/landing/partials/content/image.htm приведем к следующему виду:

features.htm

Партиалку для отображения преимуществ themes/landing/partials/content/features.htm тоже модифицируем:

slider.htm

И наконец слайдер themes/landing/partials/content/slider.htm мы поправим в два этапа.

Для примера слайдера используем библиотеку https://github.com/kenwheeler/slick

Как и написано в документации, подключим стили в файл шаблона themes/landing/layouts/default.htm в раздел head

и в конец шаблона добавим js-библиотеку:

Далее отредактируем файл themes/landing/partials/content/slider.htm и приведем его к следующему виду:

Немного CSS

Мы не зря добавили css-классы в наши partial-файлы. Приправим наш урок небольшой порцией css.

В конец файла themes/landing/assets/css/theme.css добавим немного своего:

Что в итоге?

В итоге у нас должно получиться следующее:

Выглядит вполне приемлемо!

Немного универсализации

Что же мы хотим - мы хотим в дальнейшем посадить на один движок OctoberCMS несколько лендингов, чем больше - тем лучше!

Можно заморочиться и написать свой плагин для мультисайта, но в рамках урока используем готовые наработки из маркетплейса OctoberCms - плагин Multiple Websites Manager Lite - простой, понятный и бесплатный.

Что нужно сделать:

• установить плагин Briddle.Multisite
• суметь настроить домен третьего уровня (об этом не в этом уроке)
• отредактировать конфиг плагина /plugins/briddle/multisite/config

Для примера мы скопируем нашу тему landing и назовем ее landing2

Не забываем отредактировать файл themes/landing2/theme.yaml

Далее отредактируем /plugins/briddle/multisite/config

В админке сайта добавляем новый материал:

Теперь заходим в админку сайта, но уже по адресу landing2.sandbox.test

Переходим в раздел CMS и отредактируем файл шаблона layouts/default.htm

Выбираем новую созданную страницу.

Результат

По итогу этого небольшого гайда у нас должно быть в наличии:

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

Ссылки

https://github.com/gromitsoft/sandbox - репозиторий с исходным кодом
https://blog.grom-it.ru/N9epRWxGX - первая часть урока

Заметка из разряда - "Всякие интересности в OctoberCMS"

В ноябре 2020 г. был замечен интересный pull-request в репозиторий OctoberCMS.

This PR adds support for defining quick actions in the main navigation in the Backend. Quick actions in this case are defined as the single-purpose icon links located to the left of the user menu - the only one currently available in an October CMS install is the link to preview the website.

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

Небольшой How-To

Для того, чтобы новая фича заработала - нам нужна новая установка OctoberCMS из композера:

composer create-project october/october myoctober

и обновиться до последней версии через тот же composer:

composer update

Создадим тестовый плагин для эксперимента

Для создания тестового плагина QuickActions выполним в консоли:

php artisan create:plugin sandbox.quickactions

Далее, отредактируем файл Plugin.php, добавим в него следующее:

public function registerQuickActions()
{
    return [
        'help' => [
            'label' => 'Read the documentation ',
            'icon' => 'icon-question-circle',
            'url' => Backend::url('read-the-docs'),
        ],        
    ];
}

Voila, теперь в панели управления мы увидим такое новшество:

Пойдем дальше, добавим кастомную svg-иконку. Очень часто в проектах мы используем ресурс https://www.svgrepo.com/ как источник иконок.

Добавим быструю ссылку для связи с разработчиками сайта. Для иконки возьмем первую попавшуюся из этого набора https://www.svgrepo.com/vectors/mail/multicolor/ и добавим ее в наш плагин в папку:

plugins/sandbox/quickactions/assets/svg

Далее отредактируем метод registerQuickActions() в файле Plugin.php

public function registerQuickActions()
{
    return [
        'help' => [
            'label' => 'Read the documentation',
            'icon' => 'icon-question-circle',
            'url' => Backend::url('read-the-docs'),
        ],
        'mail' => [
            'label' => 'Send email to developers',
            'iconSvg' => '/plugins/sandbox/quickactions/assets/svg/mail.svg',
            'url' => Backend::url('mail-to-devs'),
        ],           
    ];
}

Смотрим что получилось:

В своих проектах мы пока не применяли данную возможность, но надеемся, что кому-то это пригодится!