Базовая структура модуля Drupal

Часть II практического руководства по созданию базовых модулей Drupal 8
От .info к тестам, только основы

Базовая структура

loremipsum.info.yml

name: Lorem ipsum
type: module
description: 'Lorem ipsum generator for Drupal'
package: Development
core: 8.x
configure: loremipsum.form

Инфо-файлы теперь отформатированы как YML, и есть разница между модулями и темами, которая должна быть понятна через объявление типа. Объявление config указывает на маршрут (подробнее об этом позже), но кроме этого, больше ничего нет. Фактически, это единственный файл, который вам понадобится для вашего модуля. После сохранения этого (в папке root/modules) вы можете включить свой модуль в /admin/modules, не нарушая ваш сайт. Но, как вы увидите дальше, этого недостаточно.

loremipsum.module

<?php

use Drupal\Core\Routing\RouteMatchInterface;

/**
 * Implements hook_help().
 */
function loremipsum_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    case 'help.page.loremipsum':
      return t('
        <h2>Lorem ipsum generator for Drupal.</h2>
        <h3>Instructions</h3>
        <p>Lorem ipsum dolor sit amet... <strong>Just kidding!</strong></p>
        <p>Unpack in the <em>modules</em> folder (currently in the root of your Drupal 8 installation) and enable in <strong>/admin/modules</strong>.</p>
        <p>Then, visit <strong>/admin/config/development/loremipsum</strong> and enter your own set of phrases to build random-generated text (or go with the default Lorem ipsum).</p>
        <p>Last, visit <strong>www.example.com/loremipsum/generate/P/S</strong> where:</p>
        <ul>
          <li><em>P</em> is the number of <em>paragraphs</em></li>
          <li><em>S</em> is the maximum number of <em>sentences</em></li>
        </ul>
        <p>There is also a generator block in which you can choose how many paragraphs and
phrases and it\'ll do the rest.</p>
        <p>If you need, there\'s also a specific <em>generate lorem ipsum</em> permission.</p>
        <h3>Attention</h3>
        <p>Most bugs have been ironed out, holes covered, features added. But this module is a work in progress. Please report bugs and suggestions, ok?</p>
      ');
  }
}

Хорошей практикой является поместить здесь хотя бы вызов hook_help (). Также обратите внимание на оператор использования, указывающий на класс RouteMatchInterface. В основном это происходит потому, что hook_menu () больше нет.

... И по мере продвижения вы заметите, что файл .module также будет использоваться для хранения тематической информации. Так что держи это.

loremipsum.install

<?php

/**
 * @file
 * Installation functions for Lorem ipsum module.
 */

use Drupal\user\RoleInterface;

/**
 * Implements hook_install().
 */
function loremipsum_install() {
  user_role_change_permissions(RoleInterface::ANONYMOUS_ID, array(
    'generate lorem ipsum' => TRUE,
  ));
}

Здесь мы используем другой класс: RoleInterface. По сути, этот файл сообщает Drupal: «как только этот модуль включен, найдите разрешение на создание lorem ipsum и включите его».

Но где это разрешение определено?

loremipsum.permissions.yml

generate lorem ipsum:
  title: 'Generate Lorem ipsum'

Как видите, это намного проще, чем вызов hook_permission (). Полный синтаксис находится в документации PermissionHandler.

loremipsum.routing.yml

loremipsum.generate:
  path: '/loremipsum/generate/{paragraphs}/{phrases}'
  defaults:
    _controller: '\Drupal\loremipsum\Controller\LoremIpsumController::generate'
  requirements:
    _permission: 'generate lorem ipsum'

loremipsum.form:
  path: '/admin/config/development/loremipsum'
  defaults:
    _form: '\Drupal\loremipsum\Form\LoremIpsumForm'
    _title: 'Lorem ipsum settings'
  requirements:
    _permission: 'administer site configuration'

Файл маршрутизации заменяет вызов hook_menu (). Каждая запись (без отступа) указывает на маршрут с последующими строками с отступом, детализирующими конкретные настройки.

Маршрут loremipsum.generate указывает на страницу, которая принимает два аргумента между {}; он соответствует контроллеру (подробнее об этом позже), в отличие от loremipsum.form, который указывает на (настройки) форму с заголовком.

Для обоих маршрутов требуются разрешения, но вы можете заменить их на _access: 'TRUE' для неограниченного доступа.

loremipsum.services.yml

Позволяет объявить таможенный сервис.

loremipsum.links.menu.yml

loremipsum.form:
  title: 'Lorem Ipsum settings'
  description: 'Configure settings for the Lorem Ipsum module.'
  route_name: loremipsum.form
  parent: 'system.admin_config_development'

Пока файл маршрутизации создает страницу в /admin/config/development/loremipsum, эти определения необходимы для добавления страниц в меню Администрирование.

loremipsum.links.task.yml

Определения для создания дополнительных локальных задач (вкладок) для определенного маршрута.

loremipsum.links.action.yml

Определения для создания дополнительных локальных действий (кнопок) для определенного маршрута.

loremipsum.links.contextual.yml

Определения для создания дополнительных контекстных действий для определенного элемента пользовательского интерфейса.

loremipsum.libraries.yml

Используется для записи зависимостей для библиотек CSS и Javascript. Подробнее в соответствующем разделе.

README.md

Распакуйте в папку * modules * (в данный момент находится в корне вашей установки Drupal 8) и включите в `/admin/modules`.

Затем зайдите в `/admin/config/development/loremipsum` и введите свой собственный набор
фразы для построения произвольно сгенерированного текста (или идут с Lorem ipsum по умолчанию).

Наконец, посетите `www.example.com/loremipsum/generate/P/S`, где:
- * P * - количество * абзацев *
- * S * - максимальное количество * предложений *

Существует также блок генератора, в котором вы можете выбрать, сколько абзацев и
фразы, и это сделает все остальное.

Если вам нужно, есть также специальное разрешение * generate lorem ipsum *.

Внимание
---------

Большинство ошибок исправлено, дырки закрыты, добавлены новые функции. Но этот модуль это работа в процессе. Пожалуйста, сообщайте об ошибках и предложениях, хорошо?

Да, файлы README теперь записываются в формате уценки. Довольно круто, если вы спросите меня.

Теперь давайте углубимся в папки для более детального изучения конкретных деталей.

LICENSE.TXT

Не включайте файл LICENSE.txt (или аналогичный). Скрипт упаковки добавит это.

/config/install/loremipsum.settings.yml

loremipsum:
   page_title: 'Lorem ipsum'
   source_text: "Lorem ipsum dolor sit amet, consitteur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua". в представлении в завитке велит esse cillum dolore eu fugiat nulla pariatur. \ nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est labour. "

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

loremipsum:
  page_title: 'Lorem ipsum'
  source_text: "Lorem ipsum dolor sit amet, consectetur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. \nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. \nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. "

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

/config/schema/loremipsum.schema.yml

loremipsum.settings:
  type: config_object
  label: 'Lorem Ipsum settings'
  mapping:
    loremipsum:
      type: mapping
      mapping:
        page_title:
          type: text
          label: 'Lorem ipsum generator page title:'
        source_text:
          type: text
          label: 'Source text for lorem ipsum generation:'
block.settings.loremipsum_block:
  type: block_settings
  label: 'Lorem ipsum block'
  mapping:
    loremipsum_block_settings:
      type: text
      label: 'Lorem ipsum block settings'

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

При разработке этого кода я обнаружил, что заполнение полей «из коробки» было одной из самых сложных задач. Но, к счастью, для этого есть модуль: инспектор конфигурации для Drupal 8, который поможет вам отладить настройки по умолчанию.

Кроме того, файл схемы YML очень полезен во многих отношениях.

/src/Controller/LoremIpsumController.php

<?php

namespace Drupal\loremipsum\Controller;

// Change following https://www.drupal.org/node/2457593
// See https://www.drupal.org/node/2549395 for deprecate methods information
// use Drupal\Component\Utility\SafeMarkup;
use Drupal\Component\Utility\Html;
// use Html instead SAfeMarkup

/**
 * Controller routines for Lorem ipsum pages.
 */
class LoremIpsumController {

  /**
   * Constructs Lorem ipsum text with arguments.
   * This callback is mapped to the path
   * 'loremipsum/generate/{paragraphs}/{phrases}'.
   * 
   * @param string $paragraphs
   *   The amount of paragraphs that need to be generated.
   * @param string $phrases
   *   The maximum amount of phrases that can be generated inside a paragraph.
   */
  public function generate($paragraphs, $phrases) {

Мы добрались до сути этого модуля, класса с единственным методом, который генерирует текст-заполнитель. Как видите, метод, сгенерированный внутри класса LoremIpsumController, относится к записи в файле маршрутизации YML:

На белой рамке изображен код файла: loremipsum.routing.yml и фон файла, с которым мы работаем.

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

    // Default settings.
    $config = \Drupal::config('loremipsum.settings');
    // Page title and source text.
    $page_title = $config->get('loremipsum.page_title');
    $source_text = $config->get('loremipsum.source_text');

Указанные выше параметры (loremipsum.page_title и loremipsum.source_text) берутся из файла настроек YAML:

Затем мы разбиваем фразы из $ source_text на один массив:

$repertory = explode(PHP_EOL, $source_text);

И используйте этот массив для построения абзацев текста:

    $element['#source_text'] = array();

    // Generate X paragraphs with up to Y phrases each.
    for ($i = 1; $i <= $paragraphs; $i++) {
      $this_paragraph = '';
      // When we say "up to Y phrases each", we can't mean "from 1 to Y".
      // So we go from halfway up.
      $random_phrases = mt_rand(round($phrases / 2), $phrases);
      // Also don't repeat the last phrase.
      $last_number = 0;
      $next_number = 0;
      for ($j = 1; $j <= $random_phrases; $j++) {
        do {
          $next_number = floor(mt_rand(0, count($repertory) - 1));
        } while ($next_number === $last_number && count($repertory) > 1);
        $this_paragraph .= $repertory[$next_number] . ' ';
        $last_number = $next_number;
      }
      //$element['#source_text'][] = SafeMarkup::checkPlain($this_paragraph);
        $element['#source_text'][] = Html::escape($this_paragraph);

    }

Обратите внимание, что ['#source_text'] является массивом визуализации, передаваемым шаблону, и что каждый элемент в этом массиве проходит через Html :: escape () для безопасности.

Наконец, мы даем нашему массиву визуализации заголовок, назначаем функцию темы и возвращаем ее:

    //$element['#title'] = SafeMarkup::checkPlain($page_title);
    $element['#title'] = Html::escape($page_title);
     
    // Theme function.
    $element['#theme'] = 'loremipsum';
    
    return $element;
  }

}

Но прежде чем мы передадим эту переменную в наш шаблон, нужно позаботиться о них.

Следующий шаг;

Тематический модуль.

С последующим;

Добавление формы настроек.

Определение блока для этого модуля.

Написание тестов для этого модуля.