Rethinking markup. First steps with Gantry 5
Competent layout layout on CMS WordPress is an important task (after several projects it became clear to me that this takes a lot of time). To speed up the process, I started looking for a framework for writing WordPress themes. About Gantry 5 found out from a colleague who runs sites on Joomla. He said that there is an engine that can work, as well as on WordPress, and on Joomla (and for some time on Grav). So I decided to learn more about it. After all, you will agree that it is good: to work with one system and, switching to another, continue to use the same tools.
Almost nothing was found in the Russian part of the Internet - neither reviews, nor documentation, and the articles were superficial. The only complete information - only on the official site.
After reading everything I could find on the Russian-language Internet and partially the documentation, I decided to study Gantry 5. Using twig as a template maker, and storing configs in the yaml format became an additional advantage (since I had been looking for symfony for a long time, but I couldn’t find the time ).
There are several articles about the main features of Gantry 5. They describe them in insufficient detail, but what is responsible for what can be understood (albeit from the user's point of view). Alas, about how to build a template, they did not find a single line. Therefore, I will try to describe the tools, based on the development of the topic.
')
Particle is the main building material. Easier - this is 1 module. They are of three types:
Gantry 5 uses a large number of native field types. You can get acquainted with their list and functionality here (alas, only English documentation)
Hydrogen is a basic Gantry 5 template that can be downloaded here . Talking about the structure of the template, I will focus on it (you should create your own templates according to the given image and likeness).
/ admin / - redefinition of system files (highly discouraged) and some materials that can be used in the admin area (for example, images).
/ blueprints / - directory can contain three directories style, content, page.
Here, files with the .yaml extension store data about the fields, information from which can later be used as variables when compiling scss or for controlling a template.
/ config / - like some configs, but how many did not try to experiment, could not determine for what they are and what role they carry.
/ fonts / - fonts to be used. By default, Gantry 5 pulls them from Google. To avoid this, you can put used fonts here.
/ gantry / - directory where theme description files are stored in .yaml format (theme description and color scheme variations).
/ images / - directory with images of the theme, they can be used to customize the theme.
/ includes / - directory with files responsible for the interaction of the theme with Gantry 5.
/ install / - long tried to understand what configs in this directory are responsible for. From the content it seems that this is a description of the markup that is created in the subject when it is installed at the time of activation.
/ layouts / - directory for storing markup templates. By default, there are 3 mandatory templates “Body only”, “Error” and “Offline”.
/ particles / - directory for storing your own particles. To define a new particle, it must contain 2 files {name} .yaml and {name} .html.twig. The first describes the configuration of the particle, the second is responsible for its render.
/ scss / - directory for scss files that Gantry 5 will compile.
/ views / - directory with twig templates.
On the Internet I could find 2 ways to work with templates on Gantry 5:
Thanks to the old adage (if you want to do well, do it yourself) the third way was chosen .
I created a separate clean topic and taught her how to work with Gantry 5 (the benefit is not very difficult). In addition, this approach has an advantage: I stitched the TGM Plugin Activation theme, turned on the Gantry 5 plugin and made it mandatory. Thus, when the theme is activated, the necessary plug-in will be installed immediately (plus, you can put a lot more useful here).
Initialization
Create a directory for the WP theme and there are three files in it index.php , style.css , functions.php . We copy from the hydrogen theme the folders includes and gantry (there are two files in this directory - one with persets, the second with theme options, use them as the basis for describing our configs). In the style.css we initialize the theme, and add the following code to the functions.php file:
After that, the theme will already work with Gantry 5.
Yes, I collected the topic myself, but I studied at Hydrogen and used it as a base. And now I'm sure in the subject and its efficiency, I know where to look, if something breaks.
Development mode
The first thing you should pay attention to when opening the administrative panel of Gantry 5, is the developer mode. When developing a theme, it should always be included.
Gantry 5 incorporates the scss preprocessor, which allows you to compile style files on the fly. Moreover, the compilation is designed in such a way that the preprocessor can use Gantry 5 field values ​​as variables. For example, in /blueprints/styles/body.yaml there is a field responsible for color, and you need to change the background from the body with it. In scss code is written:
When compiling, if the admin color is set, the background will be repainted into it, if not, the default one set in our file will be used.
If it is necessary to use such settings in particles, they should be specified in the twig-pattern of the particle through the style attribute.
Ideally, there should be as many configuration fields as there are variables involved in the scss file. This will create a highly customizable theme.
In addition, Gantry 5 allows you to create several predefined color styles. There is nothing to add: one scheme is chosen - the colors are one, another is chosen - the colors change.
So, when compiling, Gantry 5 creates a css-file that it uses in the future (in development, it is inconvenient to constantly re-compile the file, as many actions are required). This is what the development mode is for. Every time he refreshes the page, he collects a new style file.
The second advantage of the design mode are error messages and more complete information about them. For example, if it is not possible to output the template file .twig or other problems arise, Gantry 5 will notify you about it and tell you what's broken.
Markup Templates
Adaptability in Gantry 5 is built on the Nucleus markup system. Style files are located at “ROOT / wp-content / plugins / gantry5 / engines / nucleus /”. In the template, in scss it is necessary to include 4 files:
At the same time, it is not necessary to override them; they will be pulled from the plugin when compiled.
Thanks to the previously connected styles, you can create page layout templates for the subsequent layout of particles on them.
The markup templates are described in the {theme directory} / layouts directory . After configuring the page layout, the template appears in the Administrative Panel, and it can be used to compose particles.
Here is an example of the default.yaml template description:
One important feature should be noted - the inheritance of particle parameters from one markup template to another. By default, there is a basic markup. It also sets up the main parts - for example, the menu, the cap, the basement. And in other templates, these elements can be inherited (but if necessary, inheritance can be turned off).
More about particles
When installing the Gantry 5 plugin, 11 particles, 5 positions, 4 preset atoms are available by default. If we are not satisfied with their behavior, we can always redefine them and teach them what we need.
Simple particles
The particle itself is a separate independent module that can be displayed anywhere on the page template.
In most cases, the usual set of particles is enough, but what if you need to create something unlike any particle (for example, the output of an address or phone)? All you need to do is create two files in the particles directory (for example, phone.yaml and phone.html.twig ). The first describes the configuration of the particle, the second - the output pattern. In phone.yaml, you must describe the particle, indicate its name, description, type of particle ( atom , position ) and icon ( Font Awesome ).
As for positions and atoms, they should not be redefined. If you need a similar particle, it is better to copy and create a new one on its basis.
Responsiveness, particles, a comfortable admin panel, interesting solutions, high speed of work (because all configs are stored in files), the ability to work on WordPress, Joomla, Grav and technologies that would not seem to be used in WordPress made this framework just a discovery .
After an in-depth acquaintance with technology, I don’t understand why so little is known about it.
At the moment, the only disadvantages of Gantry 5 that I was able to see are the English documentation (although which side to look at) and the lack of information about the framework in our segment of the Internet.
I understand that this article does not say too much, but if you go into the details of the design and operation of each aspect of Gantry 5, perhaps it will turn out too long. I intend to study the topic thoroughly and continue the conversation.
Almost nothing was found in the Russian part of the Internet - neither reviews, nor documentation, and the articles were superficial. The only complete information - only on the official site.
After reading everything I could find on the Russian-language Internet and partially the documentation, I decided to study Gantry 5. Using twig as a template maker, and storing configs in the yaml format became an additional advantage (since I had been looking for symfony for a long time, but I couldn’t find the time ).
Opportunities
There are several articles about the main features of Gantry 5. They describe them in insufficient detail, but what is responsible for what can be understood (albeit from the user's point of view). Alas, about how to build a template, they did not find a single line. Therefore, I will try to describe the tools, based on the development of the topic.
')
Basic terms
Particle is the main building material. Easier - this is 1 module. They are of three types:
- Standard particle - modules that allow you to display data on the page, taking into account the parameters of the particle itself (what data it will output, depends on the particle itself).
- Position - particles that contain basic information returned by the system in the query. For example, the text of the article or a list of goods store.
- Atoms - hidden items, scripts. For example, Google Analytics.
Gantry 5 uses a large number of native field types. You can get acquainted with their list and functionality here (alas, only English documentation)
File Structure (Hydrogen)
Hydrogen is a basic Gantry 5 template that can be downloaded here . Talking about the structure of the template, I will focus on it (you should create your own templates according to the given image and likeness).
/ admin / - redefinition of system files (highly discouraged) and some materials that can be used in the admin area (for example, images).
/ blueprints / - directory can contain three directories style, content, page.
Here, files with the .yaml extension store data about the fields, information from which can later be used as variables when compiling scss or for controlling a template.
/ config / - like some configs, but how many did not try to experiment, could not determine for what they are and what role they carry.
/ fonts / - fonts to be used. By default, Gantry 5 pulls them from Google. To avoid this, you can put used fonts here.
/ gantry / - directory where theme description files are stored in .yaml format (theme description and color scheme variations).
/ images / - directory with images of the theme, they can be used to customize the theme.
/ includes / - directory with files responsible for the interaction of the theme with Gantry 5.
/ install / - long tried to understand what configs in this directory are responsible for. From the content it seems that this is a description of the markup that is created in the subject when it is installed at the time of activation.
/ layouts / - directory for storing markup templates. By default, there are 3 mandatory templates “Body only”, “Error” and “Offline”.
/ particles / - directory for storing your own particles. To define a new particle, it must contain 2 files {name} .yaml and {name} .html.twig. The first describes the configuration of the particle, the second is responsible for its render.
/ scss / - directory for scss files that Gantry 5 will compile.
/ views / - directory with twig templates.
How to create a template
On the Internet I could find 2 ways to work with templates on Gantry 5:
- Create a child theme based on the lightweight Hydrogen, which was developed by the RocketTheme themselves. This way they propose to use.
- Describe the entire topic within the / custom / directory, which appears after the first save of the Hydrogen topic. This directory is not updated when a new version of the topic is released, and its data will not be lost. But I consider it unprofessional, because / custom / is essentially a cache of our data, all our settings are saved there. It turns out that in fact the work goes in temporary storage, and it’s somehow ugly to give such a customer.
Thanks to the old adage (if you want to do well, do it yourself) the third way was chosen .
I created a separate clean topic and taught her how to work with Gantry 5 (the benefit is not very difficult). In addition, this approach has an advantage: I stitched the TGM Plugin Activation theme, turned on the Gantry 5 plugin and made it mandatory. Thus, when the theme is activated, the necessary plug-in will be installed immediately (plus, you can put a lot more useful here).
Let's start in order
Initialization
Create a directory for the WP theme and there are three files in it index.php , style.css , functions.php . We copy from the hydrogen theme the folders includes and gantry (there are two files in this directory - one with persets, the second with theme options, use them as the basis for describing our configs). In the style.css we initialize the theme, and add the following code to the functions.php file:
//*****************************// //Gantry //*****************************// { // Gantry 5 $requiredGantryVersion = '5.4.0'; // Gantry 5 $gantry_include = get_stylesheet_directory() . '/includes/gantry.php'; // if ( ! file_exists( $gantry_include ) ) { $gantry_include = get_template_directory() . '/includes/gantry.php'; } $gantry = include_once $gantry_include; if ( ! $gantry ) { return; } // Gantry if ( ! $gantry->isCompatible( $requiredGantryVersion ) ) { $current_theme = wp_get_theme(); $error = sprintf('Please upgrade Gantry 5 Framework to v%s (or later) before using %s theme!', strtoupper( $requiredGantryVersion ), $current_theme->get( 'Name' ) ); if ( is_admin() ) { add_action( 'admin_notices', function () use ( $error ) { echo '<div class="error"><p>' . $error . '</p></div>'; }); } else { wp_die( $error ); } } /** @var \Gantry\Framework\Theme $theme */ $theme = $gantry['theme']; // $helpers = array( 'includes/helper.php', // ); foreach ( $helpers as $file ) { if ( ! $filepath = locate_template( $file ) ) { trigger_error( sprintf( 'Error locating %s for inclusion', $file ), E_USER_ERROR ); } require $filepath; } } After that, the theme will already work with Gantry 5.
Yes, I collected the topic myself, but I studied at Hydrogen and used it as a base. And now I'm sure in the subject and its efficiency, I know where to look, if something breaks.
Development mode
The first thing you should pay attention to when opening the administrative panel of Gantry 5, is the developer mode. When developing a theme, it should always be included.
Gantry 5 incorporates the scss preprocessor, which allows you to compile style files on the fly. Moreover, the compilation is designed in such a way that the preprocessor can use Gantry 5 field values ​​as variables. For example, in /blueprints/styles/body.yaml there is a field responsible for color, and you need to change the background from the body with it. In scss code is written:
// body , // $body-color-1: #ffffff; body{ background: $body-color-1; } When compiling, if the admin color is set, the background will be repainted into it, if not, the default one set in our file will be used.
If it is necessary to use such settings in particles, they should be specified in the twig-pattern of the particle through the style attribute.
Ideally, there should be as many configuration fields as there are variables involved in the scss file. This will create a highly customizable theme.
In addition, Gantry 5 allows you to create several predefined color styles. There is nothing to add: one scheme is chosen - the colors are one, another is chosen - the colors change.
So, when compiling, Gantry 5 creates a css-file that it uses in the future (in development, it is inconvenient to constantly re-compile the file, as many actions are required). This is what the development mode is for. Every time he refreshes the page, he collects a new style file.
The second advantage of the design mode are error messages and more complete information about them. For example, if it is not possible to output the template file .twig or other problems arise, Gantry 5 will notify you about it and tell you what's broken.
Markup Templates
Adaptability in Gantry 5 is built on the Nucleus markup system. Style files are located at “ROOT / wp-content / plugins / gantry5 / engines / nucleus /”. In the template, in scss it is necessary to include 4 files:
@import "vendor/bourbon/bourbon"; @import "configuration/nucleus/base"; @import "nucleus/functions/base"; @import "nucleus/mixins/base"; At the same time, it is not necessary to override them; they will be pulled from the plugin when compiled.
Thanks to the previously connected styles, you can create page layout templates for the subsequent layout of particles on them.
The markup templates are described in the {theme directory} / layouts directory . After configuring the page layout, the template appears in the Administrative Panel, and it can be used to compose particles.
Here is an example of the default.yaml template description:
version: 2 # preset: image: gantry-admin://images/layouts/default.png // /admin/ # . layout: /header/: - [logo 30, position-header 70] /navigation/: - menu /main/: - position-breadcrumbs - system-messages - system-content /footer/: - position-footer - [copyright 40, spacer 30, branding 30] offcanvas: - mobile-menu One important feature should be noted - the inheritance of particle parameters from one markup template to another. By default, there is a basic markup. It also sets up the main parts - for example, the menu, the cap, the basement. And in other templates, these elements can be inherited (but if necessary, inheritance can be turned off).
More about particles
When installing the Gantry 5 plugin, 11 particles, 5 positions, 4 preset atoms are available by default. If we are not satisfied with their behavior, we can always redefine them and teach them what we need.
Simple particles
The particle itself is a separate independent module that can be displayed anywhere on the page template.
In most cases, the usual set of particles is enough, but what if you need to create something unlike any particle (for example, the output of an address or phone)? All you need to do is create two files in the particles directory (for example, phone.yaml and phone.html.twig ). The first describes the configuration of the particle, the second - the output pattern. In phone.yaml, you must describe the particle, indicate its name, description, type of particle ( atom , position ) and icon ( Font Awesome ).
As for positions and atoms, they should not be redefined. If you need a similar particle, it is better to copy and create a new one on its basis.
General impressions
Responsiveness, particles, a comfortable admin panel, interesting solutions, high speed of work (because all configs are stored in files), the ability to work on WordPress, Joomla, Grav and technologies that would not seem to be used in WordPress made this framework just a discovery .
After an in-depth acquaintance with technology, I don’t understand why so little is known about it.
At the moment, the only disadvantages of Gantry 5 that I was able to see are the English documentation (although which side to look at) and the lack of information about the framework in our segment of the Internet.
Small conclusion
I understand that this article does not say too much, but if you go into the details of the design and operation of each aspect of Gantry 5, perhaps it will turn out too long. I intend to study the topic thoroughly and continue the conversation.
Source: https://habr.com/ru/post/325744/
All Articles