Пишем свой модуль для Drupal 8

Пишем свой модуль для Drupal 8

Настало время научится писать модули для Drupal 8, тем более, что их написание кардинально отличается от написания модулей для 7 ветки Drupal'a.

Перед тем как мы приступим к работе, давайте взглянем на отличие разработки модулей для Drupal 7:

  • Drupal 8 - ООП. Drupal 7 - функции;
  • У каждого класса свое пространство имен. Пространства имен будут гарантировать, что классы с одинаковыми именами не будут конфликтовать между собой. Если сравнивать с файловой системой, то в одной папке не может быть двух файлов с одинаковыми именами;
  • Drupal 8 может использовать и расширяться сторонними библиотеками;
  • Drupal 8 использует .yml файлы вместо .info, для описания модуля;
  • Вам больше не нужно использовать hook_menu, чтобы привязать функцию обработчик к URL. Теперь для этого есть классы меню и маршрутизации;
  • Drupal 8 использует систему плагинов, которая предоставляет заменяемые части функциональности. За большей информацией можете обратиться к статье Drupal 8 Plugins. Объяснение;
  • Drupal 8 использует аннотации. Аннотации включены в комментарии, и содержат в себе важную информацию о классе. Система плагинов Drupal 8 использует их для описания плагинов;

Придумайте название

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

Создайте директорию для модуля

В Drupal 7 все модули ядра, лежат в паке /modules, а свои модули и contrib модули должны лежать в папке /sites/all/modules или /sites/sitename/modules. В Drupal 8 структура сайта изменилась и все что касается ядра теперь лежит в папке /core. В корне появилась папка /modules, но ее мы оставим как раз для contrib модулей, а свои пользовательские модули мы будем по старой памяти складывать в /sites/all/modules.

  • Создайте новую папку /sites и назовите ее all;
  • Внутри all создайте папку modules;
  • Создайте папку first_module внутри папки all;

Создайте информационный yaml файл

Вам нужно создать информационный yaml файл, чтобы сказать Drupal'у что ваш модуль существует. Это похож на создание .info файла в Drupal 7.

Имя файла должно быть машинным именем вашего модуля с расширением .info.yml. В нашем случае это будет first_module.info.yml.

  • Создайте first_module.info.yml в папке модуля first_module, со следующим содержанием:
    name: First Module
    description: An experimental module to build our first Drupal 8 module
    package: Custom
    type: module
    version: 1.0
    core: 8.x

    Больше информации о .yml файлах, можно получить здесь: https://www.drupal.org/node/1935708.

Создайте файл .module

В Drupal 7, файл .module необходим даже если он пустой. В восьмой версии не обязательно. Я создам этот файл, на случай если в дальнейшем нам нужно будет реализовывать hook'и.

  • Создайте в папке first_module, файл с названием first_module.module;

Создайте src директорию

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

  • Создайте в папке модуля, папку с именем src.

Создайте базовый контроллер

Контроллеры делают большую часть работы в MVC приложении.

  • Создайте подкаталог Controller в каталоге src;
  • В каталоге Controller, создайте файл с именем FirstController.php;

В FirstController.php, мы создадим простое сообщение "hello world" сообщение, чтобы проверить что контроллер на самом деле работает.

/**
@file
Contains \Drupal\first_module\Controller\FirstController.
 */
 
namespace Drupal\first_module\Controller;
 
use Drupal\Core\Controller\ControllerBase;
 
class FirstController extends ControllerBase {
  public function content() {
  return array(
      '#type' => 'markup',
      '#markup' => t('Hello world'),
    );
  }
}

Добавьте файлы маршрутов

Контроллер, который мы создали выше, ничего не делает на данном этапе. Чтобы он вывел заветную строчку "hello world", нам нужно вызвать его. Для этого подключим наш контроллер к URL.

  • Создайте файл first_module.routing.yml в папке нашего модуля;
  • Добавьте следующий код в first_module.routing.yml;
    first_module.content:
      path: '/first'
      defaults:
        _controller: 'Drupal\first_module\Controller\FirstController::content'
        _title: 'Hello world'
      requirements:
        _permission: 'access content'

Теперь если вы перейдете по адресу /first, то вы увидите "Hello World" который возвращается из контроллера.

Создайте ссылку в меню

Только что созданный маршрут теперь работает и возвращает содержимое из контроллера. Но чтобы посмотреть содержимое нам необходимо знать URL. Для того, чтобы сделать наш модуль немного полезней, давайте добавим нашу страницу к системе меню в Drupal. Я этого нам нужно создать файл menu.yml.

  • В папке модуля создайте файл first_module.links.menu.yml;
  • Добавьте в него следующие:
    first_module.admin:
      title: 'First module settings'
      description: 'A basic module to return hello world'
      parent: system.admin_config_development
      route_name: first_module.content
      weight: 100
  • Почистите кэш сайта. После этого в разделе "Конфигурация" -> "Разработка", вы можете увидеть только что созданный пункт меню.
  • Нажмите на него и вы перейдете на только что созданную нами страницу /first.

Создайте пользовательский блок

На текущий момент у нас есть пункт меню и маршрут, по которому отображается заголовок и строка "Hello world". Давайте сделаем что-нибудь по серьезней, а именно создадим свой блок в модуле.

Для начала нам нужно создать новый плагин. Плагины - это новшество Drupal 8, и они обеспечивают заменяемые части функциональности.

  • Создайте папку Plugin в каталоге src вашего модуля. Здесь будут храниться все плагины для модуля;
  • В папке Plugin создайте папку Block. Block - это Plugin Type;
  • А внутри папки Block, создайте файл с именем HelloBlock.php;

В этом файле нам нужно определить пространство имен и класс, который будет наследовать класс BlockCase.

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

Следующим шагом нужно унаследовать документацию из базового класса и добавить метод build() , который будет возвращать содержимое блока.

Полный код файла HelloBlock.php.

<?php
/**
 * @file
 * Contains \Drupal\first_module\Plugin\Block\HelloBlock.
 */
 
namespace Drupal\first_module\Plugin\Block;

use Drupal\Core\Block\BlockBase;
 
/**
 * Provides a 'Hello' Block
 *
 * @Block(
 *   id = "hello_block",
 *   admin_label = @Translation("Hello block"),
 * )
 */
class HelloBlock extends BlockBase {
  /**
   * {@inheritdoc}
   */
  public function build() {
    return array(
      '#markup' => $this->t('Hello, World!'),
    );
  }
 
}

Выведите блок

Чтобы вывести блок в регион перейдите на страницу администрирования блоков. Напротив, региона в котором вы хотите вывести блок, нажмите на кнопку "Расположить блок".

В модальном окне вы можете увидите все доступные на текущий момент блоки. Найдите наш Hello block и напротив него нажмите на кнопку "Разместить блок".

После этого появится форма настроек блока. Просто нажмите сохранить.

Вернитесь на сайт и наслаждайтесь результатом.

 

Файловая структура

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

Заключение

В этой статье мы создали простой модуль, в котором есть контроллер, возвращающий простую строку при обращении к URL. Также мы создали простой блок. Не переживайте если на данном этапе вам не все понятно, просто продолжайте практиковаться.

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

Комментарии

# 26 сентября 15:25 Ешкин Кот
Все круто, спасибо за материал, но твой сайдбар слева, который скроллит страничку в топ - высадил до белых коней. Прыгая из саблайма в браузер тыкаю автоматом слева от саблайма на пустое место браузера, что бы сменить окно - получаю скролл в топ! и мотаю обратно к месту где потерялся.. Пока display:none не поставил элементу на странице - придумал пять новых матов.
# 26 сентября 19:26 Антон Запевалов
Спасибо! Старался делать удобно... Мне почему-то показалось, что все уже привыкли к скроллу в ВК. Там если просто кликнуть слева от контент-зоны, то уже перебрасывает наверх, даже если в полоску не попадёшь...
Для того чтобы оставлять комментарии, вам необходимо авторизоваться. Вход