В первой части говорилось об основных проблемах с которыми пришлось столкнуться при изучении Gantry 5. Здесь я постараюсь рассказать о вещах на которые стоит обратить внимание перед написанием своего шаблона.
В качестве шаблонизатора Gantry 5 использует Twig. По умолчанию внутрь плагина встроен каркас на который стоит опираться при создании собственной темы (он расположен по адресу /плагин/engines/nucleus/).
Большинство twig-шаблонов которые будут созданы в дальнейшем в теме должны наследоваться от одного из представленных здесь файлов. Это позволит сохранять единую структуру, а с помощью принципов работы twig можно будет корректировать любые блоки описанные здесь. Внутри уже есть базовые twig-шаблоны. Вот некоторые из них:
templates/page.html.twig — базовая разметка страницы. Все twig-шаблоны созданные в теме, должны быть унаследованы от этого файла для сохранения единой структуры.
Блоки описанные в шаблоне:
Эти блоки могут быть переопределены в шаблоне после наследования на стороне темы.
Сама структура страницы выглядит вот так:
Стоит отметить что при изучении Gantry 5 я столкнулся с небольшой проблемой. При рендере страницы в коде появляется много пустых строк (некрасиво смотрится). В качестве решения рекомендую использовать в шаблонах темы twig-конструкцию {% spaceless %}{% endspaceless %}. Получается минифицированный код.
templates/page_head.html.twig — шаблон шапки сайта. Вызывается в блоке page_head файла templates/page.html.twig.
Блоки описанные в шаблоне:
В этом же шаблоне устанавливаются атомы.
templates/partials/particle.html.twig — файл для наследования при создания частиц. Блоки описанные в шаблоне (изначально все блоки только определены и в них нет кода):
Следует отметить что для подключение стилей и скриптов в templates/partials/particle.html.twig и templates/page_head.html.twig используется следующая конструкция.
где head название блока в который будут подключены стили. Подробнее тут.
Увы но при такой работе со скриптами напрочь пропадает возможность использовать сторонние плагины для их минимализации.
При правильном построении темы, Gantry 5 самостоятельно осуществит подключение файлов стилей описанных в плагине (nucleus.scss и wordpress.scss). Таким образом отпадает необходимость их переопределения в шаблоне (соответственно и подключать их в своём файле стилей не требуется). Но будьте осторожны при переопределении базовых шаблонов поскольку подключение стилей производится непосредственно них.
Собраны основные виды. Их можно использовать как примеры для создания собственных шаблонов в теме. При этом во время рендера плагин сначала выполняет поиск файла шаблона в каталоге /views/ темы, а если его не находит то далее поиск идёт в плагине.
Рассмотрим пример файла index.php из шаблона темы:
Таким образом описываются все файлы которые может вызвать wordpress. Если посмотреть со стороны то может показаться что теперь классические файлы темы wordpress становятся своеобразными контроллерами в которых мы можем выполнить некоторые действия а после вывести шаблон.
Есть небольшое отличие от классического построения темы. Не всегда требуется создавать footer.php и header.php ведь они могут быть созданы в файлах twig (скажу больше, я вообще не смог создать условия при которых были бы выведены шаблоны из этих файлов).
Функция Timber::render(); выполняет рендер twig-файла из каталога /views/. Вот простейший пример шаблона:
В большинстве случаев, при создании шаблонов страниц, достаточно унаследовать шаблон от базового, но если потребуется то можно создать собственный файл с разметкой.
В директории /gantry/ хранятся технические файлы которые описывают тему.
presets.yaml — файл для описания цветовых схем. В нём можно описать несколько цветовых предустановок темы, для быстрого переключения между ними в админке.
theme.yaml — файл для описания темы.
Немного о стилях
При изучении устройства базовой темы hydrogen заметил “правила хорошего тона”. В директории /scss/ следует создавать:
● каталог configuration в котором располагать файлы с определением переменных, которые будут изменяться через админку;
● каталоги для хранения собственных стилей;
● каталог для стилей описывающих частицы. Таблицу стилей для каждой частицы располагать в отдельном файле.
Более глубокое погружение в Gantry 5 заставило попробовать использовать YAML и Twig для написания собственного небольшого плагина. О том что из этого получилось я расскажу в следующий раз.
Плагин
Nucleus — шаблоны (/templates/)
В качестве шаблонизатора Gantry 5 использует Twig. По умолчанию внутрь плагина встроен каркас на который стоит опираться при создании собственной темы (он расположен по адресу /плагин/engines/nucleus/).
Большинство twig-шаблонов которые будут созданы в дальнейшем в теме должны наследоваться от одного из представленных здесь файлов. Это позволит сохранять единую структуру, а с помощью принципов работы twig можно будет корректировать любые блоки описанные здесь. Внутри уже есть базовые twig-шаблоны. Вот некоторые из них:
templates/page.html.twig — базовая разметка страницы. Все twig-шаблоны созданные в теме, должны быть унаследованы от этого файла для сохранения единой структуры.
Блоки описанные в шаблоне:
- content;
- page_offcanvas;
- page_layout;
- page_top;
- page_bottom;
- body_top;
- body_bottom;
- page_head;
- page_footer.
Эти блоки могут быть переопределены в шаблоне после наследования на стороне темы.
Сама структура страницы выглядит вот так:
{# Основной блок шаблона в котором создаётся каркас страницы #} {%- block page -%} <!DOCTYPE {{ gantry.config.page.doctype|default('html')|raw }}> <html{{ gantry.page.htmlAttributes|raw }}> {{ page_head|raw }} {% block page_body -%} <body{{ gantry.page.bodyAttributes({'class': [offcanvas_position, gantry.page.preset, 'g-style-' ~ gantry.theme.preset]})|raw }}> {{ gantry.config.page.body.body_top|raw }} {{ body_top|raw }} {{ page_offcanvas|raw }} <div id="g-page-surround"> {% if page_offcanvas|trim %} <div class="g-offcanvas-hide g-offcanvas-toggle" data-offcanvas-toggle><i class="fa fa-fw fa-bars"></i></div> {% endif %} {{ page_top|raw }} {{ page_layout|raw }} {{ page_bottom|raw }} </div> {{ body_bottom|raw }} <script type="text/javascript" src="{{ url('gantry-assets://js/main.js') }}"></script> {{ page_footer|raw }} {{ gantry.config.page.body.body_bottom|raw }} </body> {%- endblock %} </html> {% endblock -%}
Стоит отметить что при изучении Gantry 5 я столкнулся с небольшой проблемой. При рендере страницы в коде появляется много пустых строк (некрасиво смотрится). В качестве решения рекомендую использовать в шаблонах темы twig-конструкцию {% spaceless %}{% endspaceless %}. Получается минифицированный код.
templates/page_head.html.twig — шаблон шапки сайта. Вызывается в блоке page_head файла templates/page.html.twig.
Блоки описанные в шаблоне:
- head_meta;
- head_title;
- head_application;
- head_ie_stylesheets;
- head, head_custom.
В этом же шаблоне устанавливаются атомы.
<head> {% block head_meta %} <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> {% if gantry.config.page.head.meta -%} {% for attributes in gantry.config.page.head.meta -%} {%- for key, value in attributes %} <meta name="{{ key|e }}" property="{{ key|e }}" content="{{ value|e }}" /> {% endfor -%} {%- endfor -%} {%- endif -%} {% if gantry.config.page.assets.favicon %} <link rel="icon" type="image/x-icon" href="{{ url(gantry.config.page.assets.favicon) }}" /> {% endif %} {% if gantry.config.page.assets.touchicon %} <link rel="apple-touch-icon" sizes="180x180" href="{{ url(gantry.config.page.assets.touchicon) }}"> <link rel="icon" sizes="192x192" href="{{ url(gantry.config.page.assets.touchicon) }}"> {% endif %} {% endblock %} {%- block head_title -%} <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Title</title> {%- endblock %} {% block head_application -%} {{ gantry.styles('head')|join("\n")|raw }} {{ gantry.scripts('head')|join("\n")|raw }} {%- endblock %} {% block head_ie_stylesheets -%} <!--[if (gte IE 8)&(lte IE 9)]> <script type="text/javascript" src="{{ url('gantry-assets://js/html5shiv-printshiv.min.js') }}"></script> <link rel="stylesheet" href="{{ url('gantry-engine://css/nucleus-ie9.css') }}" type="text/css"/> <script type="text/javascript" src="{{ url('gantry-assets://js/matchmedia.polyfill.js') }}"></script> <![endif]--> {% endblock -%} {% block head %}{% endblock %} {% block head_custom %} {% if gantry.config.page.head.head_bottom %} {{ gantry.config.page.head.head_bottom|raw }} {% endif %} {% endblock %} </head>
templates/partials/particle.html.twig — файл для наследования при создания частиц. Блоки описанные в шаблоне (изначально все блоки только определены и в них нет кода):
- stylesheets;
- javascript;
- javascript_footer;
- particle.
Следует отметить что для подключение стилей и скриптов в templates/partials/particle.html.twig и templates/page_head.html.twig используется следующая конструкция.
{# Эта конструкция позволяет подключать скрипты и стили в определённые места#} {% assets in<b> ‘head’</b> %}{% endassets %} {{ gantry.styles(<b>'head'</b>)|join("\n")|raw }} {# Место подключения для стилей #} {{ gantry.scripts(<b>'head'</b>)|join("\n")|raw -}} {# Место подключения для скриптов #}
где head название блока в который будут подключены стили. Подробнее тут.
Увы но при такой работе со скриптами напрочь пропадает возможность использовать сторонние плагины для их минимализации.
Nucleus — стили (/scss/)
При правильном построении темы, Gantry 5 самостоятельно осуществит подключение файлов стилей описанных в плагине (nucleus.scss и wordpress.scss). Таким образом отпадает необходимость их переопределения в шаблоне (соответственно и подключать их в своём файле стилей не требуется). Но будьте осторожны при переопределении базовых шаблонов поскольку подключение стилей производится непосредственно них.
Nucleus — виды (/views/)
Собраны основные виды. Их можно использовать как примеры для создания собственных шаблонов в теме. При этом во время рендера плагин сначала выполняет поиск файла шаблона в каталоге /views/ темы, а если его не находит то далее поиск идёт в плагине.
Шаблон
Файлы темы
Рассмотрим пример файла index.php из шаблона темы:
<?php //импортируем twig use Timber\Timber; $gantry = Gantry\Framework\Gantry::instance(); $theme = $gantry['theme']; //в переменную $context будем записывать данные к которым хотим иметь доступ в twig-шаблонах $context = Timber::get_context(); $context['page_head'] = $theme->render('partials/page_head.html.twig', $context); $context['posts'] = Timber::get_posts(); //Шаблон который мы хотим использовать для рендера страницы $templates = ['index.html.twig']; //если в массиве $templates несколько элементов то будет выбран первый найденный файл if (is_front_page()) { array_unshift($templates, 'home.html.twig'); } Timber::render($templates, $context);
Таким образом описываются все файлы которые может вызвать wordpress. Если посмотреть со стороны то может показаться что теперь классические файлы темы wordpress становятся своеобразными контроллерами в которых мы можем выполнить некоторые действия а после вывести шаблон.
Есть небольшое отличие от классического построения темы. Не всегда требуется создавать footer.php и header.php ведь они могут быть созданы в файлах twig (скажу больше, я вообще не смог создать условия при которых были бы выведены шаблоны из этих файлов).
Виды
Функция Timber::render(); выполняет рендер twig-файла из каталога /views/. Вот простейший пример шаблона:
{# Наследуем шаблон (<b>/плагин/engines/nucleus/views/partials/page.html.twig</b>) #} {% extends "partials/page.html.twig" %} {# Переопределяем блок #} {%- block content -%} Наш код {%- endblock -%}
В большинстве случаев, при создании шаблонов страниц, достаточно унаследовать шаблон от базового, но если потребуется то можно создать собственный файл с разметкой.
Описание темы
В директории /gantry/ хранятся технические файлы которые описывают тему.
presets.yaml — файл для описания цветовых схем. В нём можно описать несколько цветовых предустановок темы, для быстрого переключения между ними в админке.
preset1: # изображение image: 'gantry-admin://images/preset1.png' # описание или название description: GANTRY5_PLATFORM_PRESET1 # основные цвета colors: - '#439a86' - '#354d59' - '#8f4dae' # предустановленные стили styles: base: background: '#ffffff' text-color: '#666666' accent: color-1: '#439a86' color-2: '#8f4dae'
theme.yaml — файл для описания темы.
# думаю этот блок в пояснениях не нуждается details: name: Sau version: "1.0.0" icon: paper-plane date: February 7, 2017 author: name: AkinaySau email: akinaysau@gmail.com link: http://a-sau.ru copyright: (C) 2017 AkinaySau license: GPLv2 description: Sau Theme images: thumbnail: admin/images/preset1.png preview: admin/images/preset1.png # основные настройки, не рекомендую менять без крайней необходимости (за исключением параметра textdomain) configuration: gantry: platform: wordpress engine: nucleus theme: base: gantry-theme://common file: gantry-theme://includes/theme.php class: \Gantry\Framework\Theme textdomain: a_sau # определение шрифтов fonts: roboto: 400: 'gantry-theme://fonts/roboto_regular_macroman/Roboto-Regular-webfont' 500: 'gantry-theme://fonts/roboto_medium_macroman/Roboto-Medium-webfont' 700: 'gantry-theme://fonts/roboto_bold_macroman/Roboto-Bold-webfont' # определение файлов стилей css: compiler: \Gantry\Component\Stylesheet\ScssCompiler paths: - gantry-theme://scss - gantry-engine://scss files: - sau dependencies: gantry: 5.4.0 #а вот описание этого блока я найти не смог, и на что он влияет не понял. При его редактировании никаких изменений замечено не было. block-variations: Box Variations: box1: Box 1 box2: Box 2 box3: Box 3 box4: Box 4 Effects: shadow: Shadow 1 shadow2: Shadow 2 rounded: Rounded square: Square Utility: disabled: Disabled align-right: Align Right align-left: Align Left center: Center full-width: Full Width equal-height: Equal Height nomarginall: No Margin nopaddingall: No Padding
Немного о стилях
При изучении устройства базовой темы hydrogen заметил “правила хорошего тона”. В директории /scss/ следует создавать:
● каталог configuration в котором располагать файлы с определением переменных, которые будут изменяться через админку;
● каталоги для хранения собственных стилей;
● каталог для стилей описывающих частицы. Таблицу стилей для каждой частицы располагать в отдельном файле.
Заключение
Более глубокое погружение в Gantry 5 заставило попробовать использовать YAML и Twig для написания собственного небольшого плагина. О том что из этого получилось я расскажу в следующий раз.
