Gantry 5: A Template Developer's Point of View

To be a template developer these days is quite exciting! You express your ideas and emotions with the products you release, you learn new things every day, and all this in a very big and competitive industry!

But the good template developer should always be up-to-date with the latest technologies and tools in order to stay competitive and develop modern, optimized products.

One of these tools is the Gantry 5 Framework, and as a template developer, I would like to share my experience with it, how it makes my day-to-day job easier, how it helps me to develop great templates, and the features in it that I love the most!

As the guys at RocketTheme say, "Gantry 5 is built with the modern Web in mind." It really is! It incorporates the latest Web technologies, such as: HTML5, CSS3, SCSS, the Flexbox model, and so on and so forth. All of these things give the developers amazing flexibility, and allow them to quickly build great sites.

Below, I will outline some of the things that I love most in Gantry 5, and how they incorporate into my Joomla! template development business.

SCSS (and Twig) Variables Being Automatically Created

With Gantry 5, you no longer need to declare your variables in the PHP, SCSS, TWIG, XML or similar files. Once you write your YAML code, Gantry 5 takes the parameters and does everything for you. It's as simple as that.

To demonstrate this feature, we will add a menu item font size option in the administrator as an example:

The following steps are intended to serve as an example for template developers. Editing default template files is an advanced process, and users editing existing templates would likely use custom override files to accomplish this. More details on that process are available in the Gantry 5 documentation.

First, open the base.yaml file (root/templates/g5_hydrogen/blueprints/styles) and add the following code on line 24, just above the favicon block:

    menu-font-size:
      type: input.text
      label: Menu Font Size
      description: Specify the default Menu font size in rem, em or px units.
      default: "1rem"
      pattern: '\d+(\.\d+){0,1}(rem|em|px)'

That's it! Now you have the base-menu-font-size SCSS variable available, and you can start using it.

You do want to set a default value (fallback) for your SCSS variables. In this case, open the _typography.scss file (root/templates/g5_hydrogen/scss/configuration) and add the following code at the bottom:

// Menu Sizes
$base-menu-font-size:       1rem !default;

Now you just need to hook the Menu Font Size option in your SCSS so the value you enter in the administrator appears on the front end. Open the _typography.scss file (root/templates/g5_hydrogen/scss/hydrogen) and add the following code:

.g-main-nav {
    font-size: $base-menu-font-size;
}

And while we are on SCSS, I would like to mention that the awesome Bourbon mixin library is already built in to the Gantry 5 core!

THE PARTICLES SYSTEM

No more Custom HTML modules!

Now, we have user-friendly particles that enable the user to do pretty much everything from the administrative panel without the need to touch any code. Thanks to the Input Fields that come with Gantry 5, you can create any type of particle and the users will just set the options they want via the GUI.

Let's build a "Call-to-action Button" particle as an example:

First, create a new file in root/templates/g5_hydrogen/particles and call it ctabutton.yaml. In this YAML file, we list all of the parameters and input fields, so they can render as nice options in the administrator, and later on render in Twig. This will then generate the final HTML output on the front end.

Paste the following YAML code in the file:

name: CTA Button
description: Displays a Call-to-action button.
type: particle

form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Globally enable to the particles.
      default: true

    introtext:
      type: input.text
      label: Intro Text
      description: Enter the Intro Text

    buttontext:
      type: input.text
      label: Button Text
      description: Enter the Button Text

    buttonicon:
      type: input.icon
      label: Button Icon
      description: Select the Button Icon

    buttonlink:
      type: input.text
      label: Button Link
      description: Enter the link address

Next, you will want to create a new file in root/templates/g5_hydrogen/particles and call it ctabutton.html.twig. Here, you define the markup.

Paste the following Twig code in the file:

{% extends '@nucleus/partials/particle.html.twig' %}

{% block particle %}
    <div class="g-cta">
        <div class="g-cta-intro">
            {% if particle.introtext %}<h2>{{ particle.introtext|raw }}</h2>{% endif %}
        </div>
        <div class="g-cta-button">
            {% if particle.buttontext %}
                <a href="{{ particle.buttonlink|e }}" class="button">
                    {% if particle.buttonicon %}
                        <i class="{{ particle.buttonicon }}"></i>
                    {% endif %}
                    {{ particle.buttontext|raw }}
                </a>
            {% endif %}
        </div>
    </div>
{% endblock %}

3. Style the particle as you wish via SCSS.

You will find more details about particle creation in the Gantry 5 documentation.

And while we are on particles and Twig, I would like to mention that Gantry 5 comes with some very handy, predefined Twig blocks which allow you to load your style sheets and scripts in different elements on the website:

Load Stylesheet in the <head>.

{% block stylesheets %}
    {{ parent() }}
    // Your stylesheet goes here
{% endblock %}

Load JavaScript in the <head>.

{% block javascript %}
    {{ parent() }}
    // Your script goes here
{% endblock %}

Load JavaScript before </body>.

{% block javascript_footer %}
    {{ parent() }}
    // Your script goes here
{% endblock %}

Streams for File Locations

Gantry 5 comes with some predefined streams that template developers can use while coding. It speeds up the development process, and at the same time keeps the code nice and clean:

• gantry-assets (for example gantry-assets://js/) points to root/media/gantry5/assets/js/.

• gantry-engine (for example gantry-engine://scss/) points to root/media/gantry5/engine/nucleus/scss/.

• gantry-theme (for example gantry-theme://scss/) points to root/templates/current_theme(g5_hydrogen)/scss/.

• gantry-admin (for example gantry-admin://images/) points to root/templates/current_theme(g5_hydrogen)/admin/images/.

Multi-level Overrides

This is another great feature of Gantry 5, especially for the template developers.

What I mean by "multi-level overrides" is that you can override the core Gantry 5 files, the default Joomla files, or the extensions files in your template. Then the user can override your overrides. Here's an example:

1. In order to override the page.html.twig file (root/media/gantry5/engines/nucleus/templates/) you need to copy it in root/templates/g5_hydrogen/engine. If the engine directory does not exist you need to create it.

2. Then the user can override your page.html.twig by copying it from root/templates/g5_hydrogen/engine and pasting it in root/templates/g5_hydrogen/custom/engine. Any changes they make there will become the dominant override, and will remain safe from being overwritten in the event of a template update.

The Revolutionary Layout Manager

And last, but definitely not least, the awesome Layout Manager. It is such an amazing feature in Gantry 5 that it extends the CMS functionality tremendously!

The users are the ones that will experience the great power of the Layout Manager.

It includes features like drag-and-drop functionality for particles, module positions, and atoms. There is also a virtually unlimited number of module positions you can create, the adjustable block width, and more.

There are some very nice things for template developers, as well. You can add custom classes and attributes to every single section and block. This is very handy in case you want to add on-scroll animation, for example.

There are many, many other awesome features in Gantry 5. For example, the new Menu Editor and the Outlines system, but these are out of the scope of this blog post.

As you can see, Gantry 5 is a really powerful tool that eases the developers life greatly. You basically have everything you need to develop great products, and at the same time, you also get an incredible performance.

Just give it a try and I'm sure you'll love it!

This has been a guest blog post submitted by Ivo Valkov (JoomFX), a Web developer and member of the Gantry community.

Next Post Previous Post