В первой части говорилось об основных проблемах с которыми пришлось столкнуться при изучении 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 для написания собственного небольшого плагина. О том что из этого получилось я расскажу в следующий раз.
Поделиться с друзьями