16.05.2017 14:08
TutmeeAgency 0 1900 Источник
В первой части говорилось об основных проблемах с которыми пришлось столкнуться при изучении Gantry 5. Здесь я постараюсь рассказать о вещах на которые стоит обратить внимание перед написанием своего шаблона.

image

Плагин


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

Комментарии (0)