Инструкции по преобразованию Drupal Twig (tpl.php в html.twig)

Этот документ использовался в течение большей части процесса преобразования Twig для Drupal 8 и может быть полезен вам также для обновления ваших собственных тем и модулей для использования движка шаблонов Twig в Drupal 8.

Примечание: вся работа с Twig теперь выполняется в очереди проблем с ядром Drupal. Используйте только sandbox преобразования Twig, чтобы найти ранее преобразованные шаблоны и функции.

Шаги для основных участников:

• Найдите основные проблемы, чтобы публиковать и просматривать исправления.
• Не применять патчи к sandbox
• Не создавайте патчи для sandbox.
• Используйте sandbox только для тестирования и / или получения ранее преобразованного кода.
• Посмотрите это видео на YouTube для обзора этого процесса.

Настройка

Clone Drupal 8.0.x:

git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8

Текущая рабочая версия Drupal будет установлена в папку «d8» (назовите ее как хотите)

1. Установите Drupal как обычно (используя Стандартный установочный профиль).
2. Установите все 3 параметра Twig (debugging, cache, auto_reload) на True в services.yml.

Преобразование

Тематические функции

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

1. Определите файл, из которого пришла ваша тема (theme.inc? Core/modules/color/?)
2. Создайте файл шаблона X.html.twig для функции вашей темы:
                     - Назовите ваш новый файл соответственно
                     - Удалите theme_ из начала вашей функции и завершите имя файла в .html.twig
                     - Преобразуйте подчеркивания («_») в дефисы («-»).
                     - Примеры:
                                * theme_link() становится link.html.twig
                                * theme_user_signature() становится user-signature.html.twig

3. Поместите ваш новый шаблон Twig в папку с шаблонами в полной теме (в sandbox):
                     - для функций, которые пришли из определенного модуля, stark/templates/comment и т. д.
                     - для функций, которые пришли из theme.inc, stark/templates/theme.inc
                     - для функций, которые пришли из form.inc, stark/templates/form.inc
4. Перейдите к документации по API Drupal 8 и найдите свою функцию.
                     - (есть ссылки на все функции в электронной таблице)
5. Добавьте докблок в стиле PHP вверху файла и оберните его в комментарии Twig {# #}
                     - Добавьте строку @file в самом верху.
                     - Скопируйте определение функции чуть ниже строки @file. Перепишите «Возвращает HTML ...» как «Реализация темы по умолчанию ...». Перепишите его, чтобы он поместился на одной строке.
                     - Добавьте строку «Доступные переменные:» (замените переменные @param)
                     - Скопируйте переменные, указанные в разделе «Параметры» в документации на api.drupal.org
                     - Удалите строку @see template_preprocess(), если она существует.
                     - Добавьте строку @see template_preprocess_THEME_HOOK().
                     - Добавьте тематическую строку @ingroup (см. Пример докблока ниже).

6. Скопируйте исходный код вашей функции под блок документа (см. Пример ниже)
7. Измените код PHP в основном на HTML и операторы печати
                   - Удалить код PHP из HTML, примеры:
                               * function whatever() {
                               * // …
                               * return $output; }
                   - Удалите операторы печати PHP и замените их {{}}
                               * Преобразуйте $variables в простые имена: $variable['title'] становится {{title}}
                               * Замените синтаксис массива точечным синтаксисом: $variable['page'] ['tabs'] становится {{page.tabs}}
                   - Удалите логику PHP и замените синтаксисом ветки {%%}.
                               * <?php foreach $items as $item?> становится {% for item in items%}
                   - Замените комментарии PHP на комментарии синтаксиса веток: {# #}
                   - Замените функции t() вокруг литералов на фильтр t: {{ 'text in quotes'|t }}
                   - Переместите всю логику PHP для переменных в функцию предварительной обработки. (инструкции по предварительной обработке см. ниже.)
8. Если при этом вы заметите вещи, которые хотите улучшить, например, объедините, казалось бы, избыточные шаблоны в один или улучшите разметку или имена переменных, отметьте это в этой электронной таблице или создайте проблему в нашей песочнице. Например: http://drupal.org/node/180591

Преобразование или объединение в функции предварительной обработки

ПРИМЕЧАНИЕ:

• Функции предварительной обработки заменят все функции темы.
• Если в вашем файле шаблона есть логика PHP, которая влияет на печатаемые переменные, этот код необходимо будет перенести в функцию предварительной обработки.
• Если ваш шаблон начинался как функция темы, функцию темы нужно будет преобразовать в функцию предварительной обработки.
• В случае, если некоторые функции темы уже имеют связанные функции предварительной обработки, код обработки переменных в этих функциях темы необходимо переместить в предварительную обработку.
• Не добавляйте строку в вашу реализацию hook_theme, говорящую Drupal, использовать файл шаблона вместо функции темы.

ИНСТРУКЦИИ:

• Переименуйте theme_YOURFUNCTION в template_preprocess_YOURFUNCTION.
• Передайте $variables по ссылке, добавив амперсанд. то есть theme_select($variable) становится template_preprocess_select(&$variable).
• Отредактируйте функцию для обработки только логики обработки переменных; Удалите любую разметку (т. е. $Output).

Если в ваших шаблонах веток отсутствуют функции ...

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

ПРОСТОЙ ПРИМЕР ПРЕОБРАЗОВАНИЯ (theme_link)

PHP-код

function theme_link($variables) { return '' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . ''; } 

Шаблон Twig (имя файла: link.html.twig)

{# /** * @file * Default theme implementation to display a link. * * Available variables: * - text: The link text for the anchor tag. * - url: The complete URL being linked to, such as * "/node/34" or "http://example.com/foo". * - attributes: Remaining HTML attributes for the containing element. * * @see template_preprocess_link() * * @ingroup themeable */ #} <a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a> 

Изменения в system.module (функция предварительной обработки)

/** * Prepares variables for link templates. * * Default template: link.html.twig. * * @param array $variables * An associative array containing: * - text: The translated link text for the anchor tag. * - path: The internal path or external URL being linked to. * - options: An associative array of additional options. */ function template_preprocess_link(&$variables) { $variables['url'] = url($variables['path'], $variables['options']); } 

Комментарии:

Андрей Поданенко: http://drupal.org/node/1783130 Как переименовывать переменные
jen: Добавьте свои собственные открывающие и закрывающие маркеры комментариев Twig {# и #}.
jen: следуйте за маркерами комментариев веток со стандартными doxygen-маркерами PHP для doxygen.
jen: скопируйте и вставьте это определение из api.drupal.org
Джеймс Уилсон: Если при копировании определения из * функции * следует переписать «Возвращает HTML ...» как «Реализация темы по умолчанию»
jen: скопируйте и вставьте «Параметры» из api.drupal.org
Джеймс Уилсон: Удалите знак доллара из имен переменных, если вам нужно сослаться на другую переменную из блока doc, используйте одинарные кавычки вокруг переменной. [См. Обсуждение политики здесь http://drupal.org/node/1804710]
jen: вы «печатаете» переменные в ветке с синтаксисом {{}}
jen: атрибуты «сверлятся», так что вы можете ссылаться на такие классы
jen: Большинство функций, таких как url (), следует удалить из файла шаблона и вместо этого добавить в препроцесс.