Rethinking markup. First steps with Gantry 5. Part 2
In the first part, we talked about the main problems that had to be encountered when studying Gantry 5. Here I will try to talk about things that you should pay attention to before writing your template.
Gantry 5 uses Twig as a template engine. By default, a framework is built into the plug-in that you should rely on when creating your own theme (it is located at / plug-in / engines / nucleus / ).
Most of the twig templates that will be created later in the theme should be inherited from one of the files presented here. This will allow you to maintain a single structure, and using the twig principles, you can adjust any blocks described here. Inside there are already basic twig patterns. Here are some of them:
')
templates / page.html.twig - basic page layout. All twig patterns created in the theme must be inherited from this file to maintain a single structure.
The blocks described in the template:
These blocks can be redefined in the template after inheritance on the theme side.
The very structure of the page looks like this:
It is worth noting that when studying Gantry 5, I ran into a small problem. When rendering a page, a lot of empty lines appear in the code (it looks ugly). As a solution, I recommend using the twig-design {% spaceless%} {% endspaceless%} in the theme templates. It turns out the minified code.
templates / page_head.html.twig - website header template. Called in the page_head block of the templates / page.html.twig file.
The blocks described in the template:
Atoms are set in the same pattern.
templates / partials / particle.html.twig - file for inheritance when creating particles. The blocks described in the template (initially all the blocks are only defined and there is no code in them):
It should be noted that to connect styles and scripts in templates / partials / particle.html.twig and templates / page_head.html.twig , the following construction is used.
where head is the name of the block in which the styles will be connected. Read more here .
Alas, but with such work with scripts, the ability to use third-party plug-ins to minimize them is completely lost.
With the proper construction of the theme, Gantry 5 will independently connect the style files described in the plugin ( nucleus.scss and wordpress.scss ). Thus, there is no need to redefine them in the template (respectively, and you do not need to include them in your style file). But be careful when overriding the base templates since the styles are connected directly to them.
Collected the main types. They can be used as examples to create your own templates in the theme. At the same time, during the rendering, the plugin first searches for the template file in the / views / themes directory, and if it does not find it, then further search goes in the plugin.
Consider an example of the index.php file from the theme template:
This way, all files that wordpress can invoke are described. If you look from the outside, it may seem that now classic wordpress theme files become kind of controllers in which we can perform some actions and then output the template.
There is a slight difference from the classic construction of the topic. It is not always necessary to create footer.php and header.php because they can be created in twig files (I will say more, I could not create the conditions under which the templates would be derived from these files).
Timber function :: render (); renders a twig file from the / views / directory. Here is the simplest example of a template:
In most cases, when creating page templates, it is enough to inherit the template from the base one, but if you need it, you can create your own markup file.
The / gantry / directory contains technical files that describe the topic.
presets.yaml is a file for describing color schemes. In it, you can describe several color presets for the theme, to quickly switch between them in the admin panel.
theme.yaml - file to describe the theme.
Little about styles
When studying the device of the basic theme, hydrogen noticed “rules of good tone”. In the / scss / directory you should create:
● the configuration directory in which to locate files with the definition of variables that will be changed through the admin area;
● catalogs to store your own styles;
● catalog for styles describing particles. The style sheet for each particle should be placed in a separate file.
A deeper dive into Gantry 5 made you try using YAML and Twig to write your own little plugin. I will tell you about what came out of it next time.
Plugin
Nucleus - templates (/ templates /)
Gantry 5 uses Twig as a template engine. By default, a framework is built into the plug-in that you should rely on when creating your own theme (it is located at / plug-in / engines / nucleus / ).
Most of the twig templates that will be created later in the theme should be inherited from one of the files presented here. This will allow you to maintain a single structure, and using the twig principles, you can adjust any blocks described here. Inside there are already basic twig patterns. Here are some of them:
')
templates / page.html.twig - basic page layout. All twig patterns created in the theme must be inherited from this file to maintain a single structure.
The blocks described in the template:
- content;
- page_offcanvas;
- page_layout;
- page_top;
- page_bottom;
- body_top;
- body_bottom;
- page_head;
- page_footer
These blocks can be redefined in the template after inheritance on the theme side.
The very structure of the page looks like this:
{# #} {%- 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 -%} It is worth noting that when studying Gantry 5, I ran into a small problem. When rendering a page, a lot of empty lines appear in the code (it looks ugly). As a solution, I recommend using the twig-design {% spaceless%} {% endspaceless%} in the theme templates. It turns out the minified code.
templates / page_head.html.twig - website header template. Called in the page_head block of the templates / page.html.twig file.
The blocks described in the template:
- head_meta;
- head_title;
- head_application;
- head_ie_stylesheets;
- head, head_custom.
Atoms are set in the same pattern.
<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 - file for inheritance when creating particles. The blocks described in the template (initially all the blocks are only defined and there is no code in them):
- stylesheets;
- javascript;
- javascript_footer;
- particle.
It should be noted that to connect styles and scripts in templates / partials / particle.html.twig and templates / page_head.html.twig , the following construction is used.
{# #} {% assets in<b> 'head'</b> %}{% endassets %} {{ gantry.styles(<b>'head'</b>)|join("\n")|raw }} {# #} {{ gantry.scripts(<b>'head'</b>)|join("\n")|raw -}} {# #} where head is the name of the block in which the styles will be connected. Read more here .
Alas, but with such work with scripts, the ability to use third-party plug-ins to minimize them is completely lost.
Nucleus - styles (/ scss /)
With the proper construction of the theme, Gantry 5 will independently connect the style files described in the plugin ( nucleus.scss and wordpress.scss ). Thus, there is no need to redefine them in the template (respectively, and you do not need to include them in your style file). But be careful when overriding the base templates since the styles are connected directly to them.
Nucleus - views (/ views /)
Collected the main types. They can be used as examples to create your own templates in the theme. At the same time, during the rendering, the plugin first searches for the template file in the / views / themes directory, and if it does not find it, then further search goes in the plugin.
Template
Theme files
Consider an example of the index.php file from the theme template:
<?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); This way, all files that wordpress can invoke are described. If you look from the outside, it may seem that now classic wordpress theme files become kind of controllers in which we can perform some actions and then output the template.
There is a slight difference from the classic construction of the topic. It is not always necessary to create footer.php and header.php because they can be created in twig files (I will say more, I could not create the conditions under which the templates would be derived from these files).
Kinds
Timber function :: render (); renders a twig file from the / views / directory. Here is the simplest example of a template:
{# (<b>//engines/nucleus/views/partials/page.html.twig</b>) #} {% extends "partials/page.html.twig" %} {# #} {%- block content -%} {%- endblock -%} In most cases, when creating page templates, it is enough to inherit the template from the base one, but if you need it, you can create your own markup file.
Theme description
The / gantry / directory contains technical files that describe the topic.
presets.yaml is a file for describing color schemes. In it, you can describe several color presets for the theme, to quickly switch between them in the admin panel.
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 - file to describe the theme.
# 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 Little about styles
When studying the device of the basic theme, hydrogen noticed “rules of good tone”. In the / scss / directory you should create:
● the configuration directory in which to locate files with the definition of variables that will be changed through the admin area;
● catalogs to store your own styles;
● catalog for styles describing particles. The style sheet for each particle should be placed in a separate file.
Conclusion
A deeper dive into Gantry 5 made you try using YAML and Twig to write your own little plugin. I will tell you about what came out of it next time.
Source: https://habr.com/ru/post/328808/
All Articles