Разработка пользовательского плагина для October CMS

В прошлом году я провел небольшое исследование новых систем CMS на PHP, чтобы найти хорошую альтернативу WordPress. В идеале это должно было быть решение с открытым исходным кодом и чистой и современной кодовой базой.

Одна из них меня заинтересовала: October CMS. Я попробовала и почти сразу мне понравилось. Структура кода была действительно приятной, и было легко писать собственные плагины.

Эта статья призвана дать вам обзор того, чего ожидать от платформы, и дать вам представление о ней, прежде чем вы решите использовать ее.

Почему стоит выбрать October в качестве платформы CMS?

Есть несколько основных причин, по которым я лично решил использовать его для своих проектов.

Работает на Ларавеле

October создан на основе самого мощного PHP-фреймворка для создания современных веб-приложений: Laravel. Могу с уверенностью сказать, что он лучший. Он очень прост в использовании и понимании и обладает всеми функциями, необходимыми современной среде, включая маршрутизацию, объектно-реляционное сопоставление (ORM), авторизацию, кэширование и многие другие, которые обеспечивают красивую и понятную структуру MVC. Поскольку он работает на Laravel, October унаследовал все эти функции от своего старшего брата.

Чистый код и документация

В отличие от многих других CMS-решений, October имеет очень чистую и хорошо документированную кодовую базу. Он написан с использованием объектно-ориентированной парадигмы. Вместо старого доброго PHP October использует Twig в качестве механизма шаблонов, что упрощает работу разработчиков. Техническая документация также хорошо написана и поможет вам быстро найти ответы на большинство ваших вопросов.

Большое сообщество

Несмотря на то, что сообщество October еще не такое большое, оно очень полезное и отзывчивое. Вы можете присоединиться к общедоступному каналу Slack, где вы найдете разработчиков, которые будут рады помочь вам решить вашу проблему.

Большой рынок

Как и в WordPress и других CMS, в October есть рынок тем и плагинов. Несмотря на то, что хороших тем на выбор не так много, сейчас существует более 700 плагинов, поэтому вполне вероятно, что вы сможете добавить функциональность, просто найдя и установив один из них. Отличительной особенностью плагинов является то, что их можно легко синхронизировать между всеми вашими проектами, если вы просто добавите идентификатор своего проекта в панель администратора.

Плагины и компоненты

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

Плагин обычно создается в каталоге plugins/ проекта. Поскольку многие подключаемые модули представлены на рынке для использования другими, у каждого подключаемого модуля должно быть собственное пространство имен, которое обычно начинается с названия компании или разработчика, создавшего подключаемый модуль. Так, например, если вас зовут Acme и вы создали замечательный плагин под названием Blog, ваш плагин будет жить в пространстве имен Acme\Blog .

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

Как видите, есть также файл с именем plugin.php , который отвечает за регистрацию плагина и всех его компонентов в October CMS.

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

Чаще всего один плагин создается для добавления только одной функции. Например, плагин «Переводчик» предназначен для того, чтобы помочь вам перевести содержимое вашего веб-сайта на разные языки и обеспечить многоязычную поддержку для пользователей.

October CMS имеет отличную торговую площадку, где вы можете найти то, что вам нужно.

В отличие от WordPress и других популярных CMS, плагины October также могут иметь компоненты. Согласно документации October, компоненты — это «настраиваемые строительные элементы, которые можно прикрепить к любой странице, части или макету». Примеры могут включать: контактную форму, навигацию, список часто задаваемых вопросов и ответы на них; в основном все, что имеет смысл объединить в один строительный блок, который можно повторно использовать на нескольких страницах.

Компоненты создаются как часть плагина и находятся в подкаталоге components/ :

У каждого компонента есть файл PHP, такой как componentName.php , который определяет компонент, а также необязательный подкаталог для частей компонента. Папка частей компонента должна иметь то же имя в нижнем регистре, что и сам компонент.

Чтобы продемонстрировать, как работает компонент, давайте предположим, что наш компонент отвечает за отображение сообщений в блоге.

 namespace Acme\Blog\Components; class BlogPosts extends \Cms\Classes\ComponentBase { public function componentDetails() { return [ 'name' => 'Blog Posts', 'description' => 'Displays a collection of blog posts.' ]; } // This array becomes available on the page as {{ component.posts }} public function posts() { return ['First Post', 'Second Post', 'Third Post']; } }

Как мы видим, у компонента две основные функции. Первый, componentDetails() , предоставляет информацию о компоненте администратору, который будет добавлять и использовать компоненты на своих веб-страницах.

Вторая функция, posts() , возвращает фиктивные сообщения, которые затем можно использовать внутри партиала компонента ( файл blogposts/default.htm ) следующим образом:

 url = "/blog" [blogPosts] == {% for post in blogPosts.posts %} {{ post }} {% endfor %}

Чтобы October CMS знала, что наш компонент существует, мы должны зарегистрировать его, используя наш основной файл плагина внутри функции с именем registerComponents() :

 public function registerComponents() { return [ 'October\Demo\Components\Todo' => 'demoTodo' ]; }

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

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

• Форма будет иметь следующие поля: Имя, Фамилия, Электронная почта, Сообщение.
• Данные будут отправлены на сервер с помощью Ajax.
• После отправки данных администратор получит электронное письмо с сообщением, отправленным пользователем.

Для целей этого урока мы будем использовать новую установку October CMS:

Давайте начнем создавать наш плагин, запустив в терминале команду, которая создаст структуру плагина: php artisan create:plugin progmatiq.contactform

Аргумент progmatiq.contactform содержит имя автора (progmatiq) и название плагина (contactform).

Теперь нам нужно открыть наш файл plugin.php и изменить детали плагина следующим образом:

 public function pluginDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form plug-in', 'author' => 'progmatiq', 'icon' => 'icon-leaf' ]; }

Вот еще несколько методов, на которые стоит обратить внимание:

• registerComponents()
  Здесь вы можете определить набор компонентов, которые предоставляет ваш плагин.
• registerPermissions()
  Вы можете зарегистрировать настраиваемые разрешения, которые впоследствии сможете использовать в других областях приложения.
• registerNavigation()
  Вы можете добавить пользовательский пункт меню с URL-адресом в меню панели администратора.

Теперь давайте создадим наш компонент ContactForm :

1. Создайте новую папку с именем components/ внутри корневого каталога вашего плагина.
2. Создайте файл с именем contactForm.php внутри папки component/ .



3. Вставьте следующий код, который сообщит October, что делает наш компонент. Мы можем сделать это, создав внутри нашего компонента метод с именем componentDetails() .

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } }

Теперь нам нужно зарегистрировать наш компонент внутри плагина. Для этого модифицируем метод registerComponents() :

 public function registerComponents() { return [ 'Progmatiq\Contactform\Components\ContactForm' => 'contactForm', ]; }

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

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

1. В панели администратора перейдите в CMS (1) > Страницы (2) и нажмите + Добавить (3).
2. Дайте вашей странице имя и URL-адрес (4).
3. Назовите свой файл (5) и выберите макет по умолчанию (6).

Давайте добавим наш новый компонент на страницу:

1. Нажмите « Компоненты » в левом меню (1), а затем выберите наш компонент «Контактная форма». Как только вы нажмете на него (2), он должен быть добавлен на страницу.
2. Нам нужно разместить фрагмент кода, который даст нашей странице заголовок, а также отобразит компонент с помощью директивы Twig {% component 'contactForm' %} :

 <div class="container"> <h1> Contact </h1> {% component 'contactForm' %} </div>

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

Это потому, что в нашей контактной форме нет HTML для отображения.

Нам нужно создать файл contactform/default.htm внутри нашей папки component/ .

И добавьте в файл следующий HTML-код:

 <form method="POST" data-request="onSend" data-request-validate data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" > <div> <label for="first_name">First Name</label> <input type="text" name="first_name" class="form-control"> <p data-validate-for="first_name" class="text-danger"></p> </div> <div> <label for="last_name">Last Name</label> <input type="text" name="last_name" class="form-control"> <p data-validate-for="last_name" class="text-danger"></p> </div> <div> <label for="email">Email</label> <input type="text" name="email" class="form-control"> <p data-validate-for="email" class="text-danger"></p> </div> <div> <label for="content">Content</label> <textarea rows="6" cols="20" name="content" class="form-control"></textarea> <p data-validate-for="content" class="text-danger"></p> </div> <div> <button type="submit" class="btn btn-primary" data-attach-loading>Send</button> </div> </form>

Большая часть этого кода довольно проста. Однако он приправлен специальными атрибутами data-*, которые October позволяет нам использовать:

1. Тег <form> имеет три специальных атрибута:
   • data-request="onSend" . Этот атрибут сообщает October, что функция onSend из нашего компонента (который мы собираемся создать далее) должна вызываться при отправке формы с использованием Ajax.
   • data-request-validate включит проверку формы Ajax с использованием ошибок, которые будут отправлены с сервера, если форма недействительна.
   • data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" очищает форму, а затем запускает предупреждающее сообщение, если запрос был успешным и не было ошибок проверки или серверной стороны.
2. У каждого ввода есть следующий блок, который отвечает за отображение ошибок проверки, возвращаемых сервером для данного ввода:

 <p data-validate-for="content" class="text-danger"></p>

3. Кнопка отправки имеет атрибут data-attach-loading , который добавит счетчик и отключит кнопку, пока запрос обрабатывается сервером. Это делается для того, чтобы пользователь не отправил форму снова, пока предыдущий запрос не будет завершен.

А вот как наша страница выглядит сейчас:

Вернемся к нашему компоненту contactForm.php и создадим onSend() и validate() , которые будут отвечать за обработку отправки формы:

 public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } }

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

Если проверка пройдет успешно, мы отправим электронное письмо нашему администратору.

Примечание . Для простоты я предположил, что адрес электронной почты, на который мы хотим отправить заявку, — [email protected]. Обязательно используйте свою электронную почту!

Вот полный код вашего плагина contactForm.php :

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; use October\Rain\Exception\ValidationException; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } } }

Как видите, первый аргумент, который принимает функция Mail::send() , — это имя шаблона электронной почты, который будет отображаться для тела электронной почты. Нам нужно создать его в панели администратора. Перейдите в « Настройки» > «Шаблоны почты» и нажмите кнопку « Новый шаблон ». Затем заполните форму, как показано на экране ниже:

Вот тело письма, которое мы будем использовать:

 You have received a new contact inquiry **First Name**: {{ first_name }} *** **Last Name**: {{ last_name }} *** **Email**: {{ email }} *** **Message**: {{ content }} ***

Теперь сохраните шаблон электронной почты. Следующее, что нам нужно сделать, это настроить SMTP-сервер, который будет отправлять электронные письма.

Перейдите в « Настройки»> «Конфигурация почты» и заполните все настройки.

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

На этом этапе у нас есть все готово, чтобы приступить к тестированию нашего компонента контактной формы.

Во-первых, давайте проверим, работает ли проверка, когда мы оставляем поле «Содержание» пустым и вводим недопустимый адрес электронной почты:

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

Вот письмо, которое получит [email protected] :

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

Заключение

В этом руководстве мы рассмотрели, что такое плагин и компонент и как их использовать с October CMS.

Не бойтесь создавать собственный плагин для своего проекта, если вы не можете найти существующий, который соответствует вашим потребностям. Это не так сложно, и у вас есть полный контроль над этим, и вы можете обновить или расширить его в любое время. Даже создание простого плагина контактной формы, как мы сделали сегодня, может быть полезным, если вы хотите затем интегрировать его с другими сервисами, такими как Mailchimp или HubSpot.

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