Друпал 8: Routing, links, permissions, tabs или "Hello YML"

Просыпайтесь, друзья! Новый год Друпал 8 шагает по стране!
Приятно наблюдать как статьи по Друпал 8 постепенно наполняют русскоязычный сегмент сети... Ну что ж, пора и мне вносить свой вклад в это дело. Первые шаги конечно даются нелегко, но на то они и первые. Придется много читать, пробовать, ошибаться и снова искать ответы в сети.
Пример первого модуля на Друпал 8 в сети можно найти без особого труда (например). Вот и я пошел по известному маршруту - Hello World, дамы и господа! 
Создадим первый модуль testpage и на нем будем тестировать работу с путями. Структуру модуля описывать уже нет смысла. Смотрите ссылку выше. Там все мега-подробно описано. Просто приведу листинг кода с небольшими комментариями:

#1 - Просто страница HelloWorld

Файл testpage.info.yml

name: Test page
description: 'Hello World - is my first module!'
type: module
core: 8.x
version: 1.0
package: Frantsuzzz

Зарегистрием путь для будущей страницы в файле testpage.routing.yml

testpage.helloworld1:
  path: '/helloworld'
  defaults:
    _title: 'Hello World'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'view content'

И выведем заветное приветствие на странице. Файл src/Controller/TestPageController.php

/**
 * @file
 * Contains \Drupal\testpage\Controller\TestPageController.
 */

/**
 * Пространство имен нашего контроллера.
 */
namespace Drupal\testpage\Controller;

/**
 * Используем друпальный класс ControllerBase.
 */
use Drupal\Core\Controller\ControllerBase;

/**
 * Объявляем наш класс-контроллер.
 */
class TestPageController extends ControllerBase {

  //Метод, который возвращает render array с содержимым страницы
  public function renderPage() {
    $output = array();
    $output['#title'] = 'Hello world title';
    $output['#markup'] = 'Hello World!';
    return $output;
  }
}

Теперь на странице /helloworld можно увидеть заветный текст :-)

Пойдем дальше: теперь определим в своем модуле свои собственные права на данную страницу:

#2 - Страница HelloWorld с настройкой прав

Раньше мы использовали hook_permission. Угадайте, где нужно объявлять права в Друпал 8? Снова создаем .yml файл в корне нашего модуля c названием имя_модуля.permissions.yml.

Файл testpage.permissions.yml:

view testpage:
  title: 'View testpage'
  description: 'View test page "Hello world".'
  restrict access: TRUE

'view testpage' - системное название новых прав доступа. Не должно совпадать с именем модуля, иначе поломается верстка на странице управления правами доступа.
'restrict access' - опция указывает на то, связаны ли данные права с безопасностью сайта. В случае TRUE к описанию прав будет добавлено соответствующее предупреждение.
Незабудьте сбросить кеш на сайте, что бы увидеть изменения на странице admin/people/permissions:

 Теперь мы можем внести изменения в маршрут testpage.testpage1:

testpage.testpage1:
  path: '/helloworld'
  defaults:
    _title: 'Hello World'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    #Новые права доступа
    _permission: 'view testpage'

Подробнее про разрешения можно почитать на drupal.org

#3 - Страница HelloWorld в разделе конфигурации

Замечательно. А теперь представим, что на самом деле страница "Hello World!" - это какая-то страница админки и попробуем вывести ее в разделе конфигурации 'admin/config' в существующем контейнере, например 'Разработка'. Для тестирования данной задачи, я зарегистрирую новый путь, что бы не путаться в примерах.

Файл  testpage.routing.yml

testpage.testpage3:
  path: '/admin/config/development/helloworld'
  defaults:
    _title: 'Admin Hello World'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'access administration pages'

На данный момент у нас появилась страничка helloworld по адресу '/admin/config/development/helloworld'.

Но на панели администрирования ее нет. Дело в том, что список ссылок на данной панели строится на основе иерархии пунктов меню. Наш маршрут - это просто путь. Нет никакой привязки к меню. Поэтому система не может найти данную страницу и не отображает ее в админке. Покажем Друпалу, откуда ноги растут где следует вывести данную страницу. Создадим в корне модуля новый файл testpage.links.menu.yml

testpage.testpage3:
  #Заголовок пункта меню
  title: 'Hello world admin'
  #Описание пункта меню
  description: 'Weloworld page for admin page'
  #Маршрут (определяет путь ссылки)
  route_name: testpage.testpage3
  #родительский маршрут (system.admin_config_development - определен в модуле system)
  parent: system.admin_config_development
  #Вес ссылки в меню
  weight: 10

После сброса кеша система добавит новый пункт меню в меню "Управление" (manage). И при формировании страницы конфигурации /admin/config будет найден наш пункт и добавлен на панель:

#4 - Страница HelloWorld в разделе конфигурации в новом разделе

Не останавливаемся на достигнутом. Продолжаем эксперименты. Сейчас я хочу, что бы моя ссылка администрирования была не в разделе "Разработка", а в новом разделе, например "Custom settings". Для этого нам нужно создать новый раздел в меню и туда добавить новую ссылку.
В файле testpage.routing.yml добавим новые маршруты:

#Наш новый раздел на панели конфигурации
testpage.admin_config_custom:
  path: '/admin/config/custom'
  defaults:
#Контроллер для таких разделов уже определен в модуле system
    _controller: '\Drupal\system\Controller\SystemController::systemAdminMenuBlockPage'
    _title: 'Custom settings'
  requirements:
    _permission: 'access administration pages'

#Что бы не путаться в примерах, мы добавим новый маршрут для страницы HelloWorld
testpage.testpage4:
  path: '/admin/config/custom/helloworld'
  defaults:
    _title: 'Admin Custom Hello World'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'access administration pages'

И сейчас добавим данные пункты в меню "Управление"
Добавим в файл testpage.links.menu.yml

testpage.admin_config_custom:
  title: 'Custom settings'
  route_name: testpage.admin_config_custom
  parent: system.admin_config
  description: 'Custom panel'
  weight: -10

testpage.testpage4:
  title: 'Hello world admin (custom)'
  description: 'Weloworld page for admin page'
  route_name: testpage.testpage4
  parent: testpage.admin_config_custom
  weight: 10

Незабываем сбросить кеш, что бы увидеть изменения. Цель достигнута. Сейчас в разделе конфигурации появилась новая панель "Custom settings", на которой выводится наша страница "Heloworld".

#5 - Вкладки (Tabs)

Неплохое начало. Теперь попробуем разобраться, как делать вкладки (Tabs). Итак, сейчас мы добавим на страницу #4 новую вкладку "Tab2". Для начала зарегистриуем новый путь для вкладки:

В файле testpage.routing.yml добавим новый маршрут:

testpage.testpage5:
  path: '/admin/config/custom/helloworld/tab2'
  defaults:
    _title: 'Hello World Tab2'
#в качестве контроллера не будем ничего придумывать, просто используем все тот-же helloworld :-)
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'access administration pages'

За регистрирование вкладок отвечает файл имя_модуля.links.task.yml в корне модуля. Создадим его.

Файл testpage.links.task.yml:

#Опишем вкладку по умолчанию
testpage.tabdefault:
#Имя маршрута (путь для вкладки по умолчанию)
  route_name: testpage.testpage4
#Родительский маршрут. Т.к. вкладка по-умолчанию, то используем тот-же маршрут
  base_route: testpage.testpage4
  title: 'Tab default'

#Вторая вкладка
testpage.tab2:
#Маршрут для второй вкладки
  route_name: testpage.testpage5
  title: 'Tab2'
#Родительский маршрут - указываем ИМЯ МАРШРУТА, который у нашей основной вкладки
  base_route: testpage.testpage4

Ну вот и все чудеса. Сбрасываем кеш и переходим на страницу 'admin/config/custom/helloworld'

#6 - Вкладки второго уровня!

Этот процесс походу уже не остановить. Хочу новую вкладку, на которой будут еще вкладки!
Регистрируем новые маршруты.

В файле testpage.routing.yml добавим новые маршруты:

testpage.testpage6:
  path: '/admin/config/custom/helloworld/tab3/subtab1'
  defaults:
    _title: 'Hello World Tab2'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'access administration pages'

testpage.testpage7:
  path: '/admin/config/custom/helloworld/tab3/subtab2'
  defaults:
    _title: 'Hello World Tab2'
    _controller: '\Drupal\testpage\Controller\TestPageController::renderPage'
  requirements:
    _permission: 'access administration pages'

В файле testpage.link.task.yml опишем новые элементы в структуре вкладок:

#Добавляем третью вкладку
testpage.tab3:
  route_name: testpage.testpage6
  title: 'Tab3'
  base_route: testpage.testpage4

#Регистрируем вкладки второго уровня
testpage.tab3sub1:
  route_name: testpage.testpage6
  title: Sub1
#Имя (id) родительской вкладки
  parent_id: testpage.tab3

testpage.tab3sub2:
  route_name: testpage.testpage7
  title: Sub2
  parent_id: testpage.tab3

Результат:

Вот сейчас я пожалуй закончу данный пост. Впереди нас ждет еще много интересного!

P.S. И да, я попробовал третий уровень. Нет такого :-)