15.07.2020 08:22:47 |
Автор: Сегодня мы подготовили перевод еще одной статьи Leonardo Lozoviz. Данная статья посвящена созданию кастомной функциональности через плагины. Предыдущую статью, посвященную сравнению October CMS и WordPress, вы можете найти здесь.
Если вам нравится писать объектно-ориентированный и лёгкий для чтения код, то эта статья для вас. Вы узнаете, как написать свой плагин и почему October может стать хорошим вариантом для вашего следующего проекта.
В прошлом году я провёл небольшое исследование новых CMS, основанных на PHP, в поисках хорошей альтернативы WordPress. В идеале это должно было быть решение с открытым исходным кодом на современной кодовой базе.
Тогда меня заинтересовала October CMS. Я попробовал её и она почти сразу мне понравилась. У October хорошая структура кода, для неё легко писать собственные плагины.
Цель этой статьи помочь вам понять, что собой представляет платформа и чего стоит от неё ожидать, прежде чем вы решите её использовать.
Почему стоит выбрать October в качестве CMS платформы?
Есть несколько основных причин, почему я решил использовать October для своих проектов.
Написана на фреймворке Laravel
October CMS построена на основе Laravel самого мощного PHP-фреймворка для создания современных веб-приложений. Я могу точно сказать, что он лучший. Фреймворк очень прост в использовании, он исключительно понятен. Кроме того, в нём есть все возможности, необходимые современному фреймворку: роутинг (маршрутизация), объектно-реляционное отображение (ORM), авторизация, кэширование и многие другие, обеспечивающие красивую и понятную структуру в соответствии с концепцией Model-View-Controller. Поскольку October CMS написана на фреймворке Laravel, она унаследовала все эти возможности от старшего брата.
Чистый код и документация
В отличие от многих других CMS, у October очень чистая и хорошо документированная кодовая база, написанная с использованием объектно-ориентированной парадигмы.
Вместо старого доброго PHP, October использует Twig в качестве языка для создания шаблонов, что упрощает работу разработчиков. Техническая документация также хорошо написана и позволяет быстро найти ответы на большинство вопросов.
Отличное сообщество
Хотя сообщество October еще не очень большое, люди в нём отзывчивы и всегда готовы помочь. Есть канал в Slack (На данный момент официально заморожен, сообщество переезжает в Discord. Прим. перев.), к которому вы можете присоединиться, и разработчики с радостью помогут решить вашу проблему.
Большой маркетплейс
Как и у WordPress и других CMS, у October есть маркетплейс тем и плагинов. Выбор хороших тем не очень большой, но есть более 700 плагинов (По состоянию на июнь 2020 опубликовано более 900 плагинов и около 200 тем. Прим. перев.), поэтому вполне вероятно, что вы сможете расширить функциональность, просто выполнив поиск и установив один из них. Отличительной особенностью плагинов является то, что их можно легко синхронизировать между всеми вашими проектами, просто добавив свой идентификатор проекта в админке.
Плагины и компоненты
Плагины основа добавления новых функций в October CMS. Плагин может состоять из нескольких файлов и директорий, которые отвечают за регистрацию пользовательских компонентов, моделей, обновление структуры базы данных или добавление переводов. Плагин обычно создаётся в проекте в директории plugins/. Поскольку многие плагины добавляются в маркетплейс для использования другими людьми, каждый плагин должен иметь собственный неймспейс, который обычно начинается с названия компании или разработчика, создавшего плагин. Так, например, если вас зовут Acme и вы создали отличный плагин под названием Blog, ваш плагин будет называться Acme\Blog.
Покажу вам, как может выглядеть структура директорий плагина:
Как видите, есть файл с именем plugin.php, который отвечает за регистрацию плагина и всех его компонентов в October CMS.
Стоит упомянуть, что не все директории, перечисленные выше, необходимы для запуска плагина. Ваш плагин может иметь следующую структуру и тем не менее отлично работать:
Чаще всего один плагин добавляет только одну функциональность. Например, плагин Translate предназначен для того, чтобы помочь вам перевести контент вашего сайта на разные языки и обеспечить многоязычную поддержку пользователей.
У October CMS большой маркетплейс, где вы можете найти всё, что нужно.
В отличие от Wordpress и других популярных CMS, плагины October могут содержать компоненты. Согласно документации October, компоненты являются настраиваемыми модулями, которые можно прикрепить к любой странице (page), паршелу (partial) или лэйауту (layout). Например, форма обратной связи, навигация, FAQ (список часто задаваемых вопросов и ответы на них); по сути, всё, что логично объединить в один модуль, который можно повторно использовать на нескольких страницах.
Компоненты создаются как часть плагина и находятся в субдиректории components/:
У каждого компонента есть PHP-файл, например, componentName.php, который определяет компонент, а также необязательную поддиректорию для паршелов (partials). Папка паршелов (partials) для компонента должна иметь то же имя в нижнем регистре, что и сам компонент.
Чтобы понять, как функционирует компонент, давайте предположим, что наш компонент отвечает за показ сообщений в блоге.
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:
- Создаём новую папку components/ в корневой директории вашего плагина.
- Создаём файл contactForm.php в директории components/.
- Вставляем следующий код, который сообщит October, что делает наш компонент. Мы можем сделать это, создав метод componentDetails() внутри нашего компонента.
<?phpnamespace 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.
После того, как мы зарегистрировали компонент, можно создать новую страницу контактов и добавить наш компонент (номер шага совпадает с номером иллюстрации на скриншоте):
- В панели администратора перейдите в CMS (1)> Страницы (2) и нажмите + Добавить (3).
- Дайте вашей странице имя и URL (4).
- Назовите свой файл (5) и выберите макет по умолчанию (6).
Добавим наш новый компонент на страницу:
- Нажмите Components в левом меню (1), а затем выберите наш компонент Contact form. Как только вы нажмёте на него (2), он должен быть добавлен на страницу.
- Нам нужно разместить фрагмент кода, который добавит к нашей странице заголовок, а также визуализировать компонент, используя директиву Twig {% component contactForm %}:
<div class="container"> <h1> Contact </h1> {% component 'contactForm' %}</dv>
Если вы сейчас откроете страницу контактов, то не увидите ничего, кроме заголовка с надписью Контакты.
Дело в том, что у нашей формы нет HTML для отображения.
Нам нужно создать файл contactform/default.htm в папке components/.
Также нужно добавить следующий 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:
Тег имеет три специальных атрибута:
data-request="onSend"
Этот атрибут сообщает October, что функция onSend из нашего
компонента (которую мы собираемся создать дальше) должна вызываться
при отправке формы с использованием Ajax.
data-request-validate
включит валидацию формы посредством Ajax с использованием ошибок,
которые будут отправлены с сервера, если форма недействительна.
data-request-success="this.reset(); alert('Thank you for submitting your inquiry')"
очищает форму и затем выдает сообщение, если запрос был успешным и
не было никаких ошибок проверки или сервера.У каждого входа есть следующий блок, который отвечает за отображение ошибок проверки, возвращаемых сервером для данного ввода:
<p data-validate-for="content" class="text-danger"></p>
Кнопка отправки имеет атрибут 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 = 'admin@gmail.com'; \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 и сообщение о провале валидации.
Если валидация прошла успешно, мы отправим электронное письмо нашему администратору.
Примечание: для упрощения я предположил, что почта, на которую мы хотим отправить заявку admin@gmail.com. Убедитесь, что используете собственный адрес электронной почты!
Вот полный код вашего плагина 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 = 'admin@gmail.com'; \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-сервер, который будет отправлять электронные письма.
Перейдите в Настройки> Конфигурация почты и заполните все настройки.
Конечно, я не поделюсь своей конфигурацией. Используйте собственные настройки.
На этом этапе у нас всё готово для начала тестирования компонента формы обратной связи.
Во-первых, давайте проверим, работает ли валидация, когда мы оставляем поле Content пустым и вводим неверный адрес электронной почты:
Валидация работает как положено. Теперь давайте введём правильные данные и посмотрим, будет ли электронное письмо успешно отправлено нашему администратору.
Вот письмо, которое получит admin@gmail.com:
После успешной отправки формы пользователь увидит соответствующее сообщение:
Вывод
В этой статье мы рассмотрели, что такое плагин и компонент, и выяснили, как их использовать в October CMS.
Не бойтесь создавать собственный плагин для вашего проекта, если не можете найти существующий плагин, который соответствует вашим потребностям. Это не так сложно и вы можете полностью его контролировать, обновлять и расширять в любое время. Даже создание плагина для простой формы обратной связи, вроде того, что мы сделали сегодня, может быть полезно, если вы захотите потом интегрировать его с другими сервисами, например, с Mailchimp или HubSpot.
Я надеюсь, что статья была для вас полезна. Если у вас есть вопросы, не стесняйтесь задавать их в комментариях.
Категории: 