Руководство по использованию плагина OctoberCMS, часть 1

Учебник по плагину, часть 1 — Отзывы

  1. Установка плагина
    1.1. Первое, что мы должны сделать, это создать структуру папок в папке с плагинами, как подробно описано в официальной документации OctoberCMS здесь https://octobercms.com/docs/plugin/registration. Откройте папку плагинов внутри проекта October CMS и создайте новую папку. Имя папки внутри плагинов — ваше имя автора, в нашем примере она называется ideaverum. Следующим шагом в настройке является создание папки для вашего плагина. Имя этой папки должно быть строчными буквами, и это имя вашего плагина. В нашем примере это отзывы. После того, как вы создали папки, теперь мы можем создать файл Plugin.php для регистрации нашего плагина в экосистеме OctoberCMS. Внутри Plugin.php мы предоставим общую информацию о плагине, настроим пункты меню для наших контроллеров, зарегистрируем компоненты плагина. Все файлы php должны использовать пространство имен, которое состоит из имени вашего автора и имени плагина. Помните, мы говорили, что имя папки вашего плагина должно быть в нижнем регистре? Ну, в пространстве имен это немного отличается. Наше пространство имен — IdeaVerum\Testimonials, и оно будет использоваться во всем плагине как таковое. Внутри файла Plugin.php мы будем использовать 3 метода, предоставленные October, когда будем расширять PluginBase. Это pluginDetails, registerComponents и registerNavigation. Метод pluginDetails является обязательным, и именно здесь мы определяем такие вещи, как имя, описание, автора, значок, URL-адрес домашней страницы плагина. В нашем примере это выглядит так:

  1. Если вам интересно, какие значки вы можете использовать, посетите https://octobercms.com/docs/ui/icon. Метод registerComponents в настоящее время пуст, но позже он будет использоваться для отображения отзывов на главной странице вашего веб-сайта с помощью компонента.

  1. registerNavigation — это место, где мы создаем макет нашего меню. Он используется для внутренней системы меню. В нашем примере мы используем боковое меню, в котором будут пункты «Домой» и «Создать». Есть несколько вещей, на которые следует обратить внимание при создании структуры меню.

  1. Как видите, у нас есть корневой элемент, проиндексированный как домашний. У каждого элемента есть метка, URL, значок, порядок, но у первого элемента также есть элемент sideMenu, в котором мы затем определяем элементы в боковом меню. На изображении вы можете видеть, что домашняя страница дублируется, потому что мы хотели, чтобы элемент домашней страницы находился в боковом меню, потому что в противном случае нам пришлось бы щелкать элемент плагина в верхнем меню, чтобы вернуться домой к нашему плагину, а мы не хотим этого делать. Другой элемент — new_testimonial со своими данными. Важными вещами являются индексы в элементах массива sideMenu и их код и атрибуты URL. Нам нужно будет использовать эти данные в наших контроллерах, чтобы правильно связать меню с контроллером. Для получения дополнительной информации о настройке и регистрации плагина перейдите по ссылке, которую мы предоставили в начале.
  2. Детали проекта
    2.1. После быстрого погружения в настройку и регистрацию плагина мы, вероятно, должны описать, о чем этот плагин. Мы хотим создать плагин, который позволит нам создавать отзывы клиентов в области администрирования, а затем отображать их на главной странице. Один отзыв будет содержать имя клиента, веб-адрес клиента, если он существует, комментарий и изображение клиента. Мы покажем вам, как создать простой CRUD отзывов. На главной странице плагина у нас будет список уже созданных отзывов, откуда вы можете удалять и редактировать отзывы, а также будет кнопка для создания нового отзыва. После того, как мы завершим область администрирования, мы перейдем к компонентам и узнаем, что они из себя представляют, как зарегистрироваться и использовать их для отображения списка отзывов. Для разработчиков, имеющих опыт работы с Laravel, большая часть вещей должна быть знакома, и все, что вам нужно обратить внимание, это то, как работает october и его методы.
    Это все, что касается деталей проекта, давайте перейдем к структуре проекта.
  3. Структура проекта
    3.1. Отлично, теперь вы знаете, как настроить проект плагина и что мы собираемся создать в этом руководстве. Взгляните на изображение структуры папок, и мы рассмотрим каждую папку.

  1. Наша корневая папка называется так же, как и ваш плагин. Внутри корня мы можем видеть другие папки и Plugin.php, которые мы кратко рассмотрели в первой части, и вы уже должны знать, что мы будем делать в Plugin.php, но что касается других папок, давайте рассмотрим их и объясним каждую. Папка Components будет содержать все ваши компоненты, которые зарегистрированы в Plugin.php, и каждый компонент будет иметь свою собственную папку с файлом шаблона htm и файлом класса php для этого компонента. Папка Controllers будет содержать все ваши контроллеры, которые используются для создания административной части плагина. Так же, как и компоненты, у вас есть подпапка для каждого представления с файлом класса .htm и .php. Папка Models не требуется к октябрю, но нам нравится держать все в порядке, и именно там мы обычно храним все файлы наших моделей так же, как вы делаете это в Laravel. В этом уроке мы будем использовать только одну модель, потому что не хотим усложнять уже знакомые вещи и сосредоточимся больше на разработке плагинов. Папка обновлений — это отличная функция October, и нам это нравится. Внутри вы можете иметь файлы install.php, version.yaml и seed.php. Внутри файла install.php мы определяем все миграции базы данных, которые вызываются из version.yaml. В дополнение к миграции вы можете использовать сидер laravel, который также называется version.yaml. Таким образом, мы видим, что version.yaml действительно важный файл, и да, это потому, что внутри мы определяем версии плагинов, поскольку вы делаете все больше и больше работы, вы выпускаете обновления для своего плагина, и ваши пользователи должны знать, что изменилось, какие новые функции и для вас как Разработчик, вы должны каким-то образом масштабировать свой проект, чтобы пользователь даже не заметил внутренних изменений. Вот почему этот файл так важен. Например, предположим, что мы создаем 1.0.0. релизную версию плагина, и мы хотим описать это и иногда вызывать оттуда install.php и seed.php или любой другой php-файл, который вы хотите. Существуют некоторые требования к синтаксису, поскольку это файл .yaml, и мы рассмотрим его позже.
  2. Настройка проекта
    4.1. Оглядываясь назад на изображение в разделе структуры проекта, давайте углубимся в контроллеры. Посмотрите на это изображение и посмотрите на структуру плагина контроллеров, который у нас есть.

  1. Для каждого представления внутри администрирования у нас есть подпапка, а внутри у нас есть файл .htm, а затем каждая подпапка (представление) имеет свой файл класса .php. Обратите внимание на названия папок, .htm и .php, это действительно важно. Внутри файлов .htm мы определяем макет страницы, так что ничего сложного в этом нет. Файл Home.php содержит класс, который расширяет класс Controller, и пространство имен для файлов контроллера должно быть таким, как IdeaVerum\Testimonials\Controllers. Обратите внимание на имя подпапки home и файла index.htm, потому что имя подпапки должно совпадать с именем контроллера, а внутри контроллера мы отображаем index.htm с помощью метода index() внутри контроллера. То же самое касается класса Testimonial, за исключением того, что у нас нет index.htm, но есть create.htm, поэтому мы должны создать метод с именем create(), который будет возвращать страницу create.htm, когда мы нажмем backend/ideaverum/testimonials/testimonial/create внутри бэкэнда. .
    Подводя итог этому разделу, вам нужно обратить внимание на структуру папок, файлы шаблонов и файлы классов. Помните, что имя подпапки должно совпадать с именем класса, а файл шаблона внутри подпапки возвращается методом, имя которого совпадает с именем файла шаблона.
  2. Регистрация меню
    5.1. Хорошо, давайте зарегистрируем меню на наших двух контроллерах. Для регистрации меню требуется класс BackendMenu и его метод setContext. В этом методе вы должны передать три параметра: первый — имя AuthorName.Plugin, второй — код меню, а третий — код подменю, который мы используем, потому что у нас есть боковое меню, которое ведет себя как подменю. Внутри метода RegisterNavigation Plugin.php у вас есть массив, а внешние индексы — это коды меню, внутри каждого кода меню у вас есть атрибуты, и есть атрибут sideMenu, который имеет свои собственные коды подменю и свои собственные атрибуты. Внутри массива бокового меню каждый внешний индекс является вашим кодом подменю, и это важно, когда вы хотите связать класс контроллера с меню. Посмотрим еще раз на изображение registerNavigation

  1. А теперь давайте посмотрим на контроллеры Home и Testimonial изображения.
  2. Домой

  1. Отзыв

  1. Теперь вы можете четко понимать параметры, необходимые для настройки BackendMenu. Первый параметр очевиден, второй — это первый индекс внутри массива, который вы возвращаете из registerNavigation, и, наконец, третий параметр — это коды внутри массива sideMenu. Конечно, есть и другие способы структурировать свое меню, это не лучший пример того, как создать меню, но очень просто продемонстрировать, как все работает. Переходим к следующему разделу.
  2. Модели и контроллеры
    6.1. Мы уже рассмотрели несколько вещей для контроллеров, и мы считаем, что вы уже должны понимать, для чего нужен контроллер. Мы рассмотрим контроллеры глубже во второй части, где вы увидите всю логику контроллера. Модели точно такие же, как модели в Laravel. Если вы не работали с Laravel, модели представляют собой кодовые представления таблиц вашей базы данных, поэтому вам не нужно писать надоедливый SQL, а используйте хорошие методы, предоставляемые Eloquent ORM. Чтобы сделать этот учебник по плагину простым, у нас будет только одна модель, которая будет представлять наш объект отзыва. Внутри каталога плагинов просто создайте модели папок, если вы еще этого не сделали, потому что там мы будем хранить все наши модели, чтобы все было организовано. Проверьте изображение ниже

Спасибо, что прочитали! До сих пор мы рассмотрели основные строительные блоки, как создать плагин, и в следующей части мы действительно увидим некоторый код и логику в действии. Оставайтесь с нами для следующей части.