Customizing Theme Files

After you have downloaded and installed your Gantry-powered theme, you may want to customize it to make changes that go beyond its included Page Settings and Particle Defaults options.

As an example, you could add a text field on the back end that enables you to easily change the text in a specific area of the page. You could also add fields and functionality to Gantry 5's core Particles, as well as any included in the theme itself.

The key to overriding files is the /custom folder within the main theme folder. This folder is where you can put any overrides and additional files that you would like to add to the theme without risking breaking or losing this data during a theme update.

Customizing Theme Files

In this example, we are going to add a field to the Section settings in the Layout administrative panel that enables you to use the Image Picker to create a background image for a specific section of the site. This change requires two files to be copied over to the /custom directory and modified. In this case, we are using the free Hydrogen theme for our example.

Pictured above is the Showcase section of the site, which features the Sample Content particle, included in the Hydrogen theme. The particle itself does not define the background image anywhere in its Twig file, and in this case we want to create this capability for each section independent of its particles or positions.

In Hydrogen the first thing we want to do is add the Image Picker to the options for each section. This will enable the user to define the background image for the section.

Here is what the file looks like before our changes:

name: Section
description: Layout section.
type: section

form:
  fields:
    boxed:
      type: select.selectize
      label: Layout
      description: Select the Layout container behavior. 'Inherit' refers to Page Settings.
      isset: true
      selectize:
        allowEmptyOption: true
      options:
        '': Inherit
        0: Fullwidth (Boxed Content)
        2: Fullwidth (Flushed Content)
        1: Boxed
        3: Remove Container

    class:
      type: input.selectize
      label: CSS Classes
      description: Enter CSS class names.
      default:

    extra:
      type: collection.keyvalue
      label: Tag Attributes
      description: Extra Tag attributes.
      key_placeholder: Key (data-*, style, ...)
      value_placeholder: Value
      exclude: ['id', 'class']

To add the background option, we just need to create an input.imagepicker field. You can see our edited copy of the file below.

name: Section
description: Layout section.
type: section

form:
  fields:
    boxed:
      type: select.selectize
      label: Layout
      description: Select the Layout container behavior. 'Inherit' refers to Page Settings.
      isset: true
      selectize:
        allowEmptyOption: true
      options:
        '': Inherit
        0: Fullwidth (Boxed Content)
        2: Fullwidth (Flushed Content)
        1: Boxed
        3: Remove Container

    class:
      type: input.selectize
      label: CSS Classes
      description: Enter CSS class names.
      default:

    extra:
      type: collection.keyvalue
      label: Tag Attributes
      description: Extra Tag attributes.
      key_placeholder: Key (data-*, style, ...)
      value_placeholder: Value
      exclude: ['id', 'class']

    background:
      type: input.imagepicker
      label: Background

Here is the section.html.twig file prior to our changes:

{% set tag_type = segment.subtype|default('section') %}
{% set attr_id = segment.attributes.id ?: 'g-' ~ segment.id %}
{% set attr_class = segment.attributes.class %}
{% set attr_extra = '' %}
{% set boxed = segment.attributes.boxed %}
{% if boxed is not null %}
    {% set boxed = boxed|trim == '' ? gantry.config.page.body.layout.sections : boxed %}
{% endif %}

{% if segment.attributes.extra %}
    {% for attributes in segment.attributes.extra %}
        {% for key, value in attributes %}
        {% set attr_extra = attr_extra ~ ' ' ~ key|e ~ '="' ~ value|e('html_attr') ~ '"' %}
        {% endfor %}
    {% endfor %}
{% endif %}

{% set html %}
    {% if segment.children %}
        {% for segment in segments %}
            {% include '@nucleus/layout/' ~ segment.type ~ '.html.twig' with { 'segments':segment.children } %}
        {% endfor %}
    {% endif %}
{% endset %}

{% if html|trim %}
    {% if boxed is not null and (boxed == 0 or boxed == 2) %}
        {% set html %}
        <div class="g-container">{{ html|raw }}</div>
        {% endset %}
    {% endif %}

    {% set html %}
    {% if boxed == 2 %}{% set attr_class = attr_class ~ ' g-flushed' %}{% endif %}
    {% set attr_class = attr_class ? ' class="' ~ attr_class|trim ~ '"' %}
    <{{ tag_type }} id="{{ attr_id }}"{{ attr_class|raw }}{{ attr_extra|raw }}>
        {{ html|raw }}
    </{{ tag_type }}>
    {% endset %}

    {% if boxed == 1 %}
    <div class="g-container">{{ html|raw }}</div>
    {% else %}
    {{ html|raw }}
    {% endif %}
{% endif %}

What we would like to do for this example is add a div that surrounds the HTML, adding the background the user has added from the Image Picker field in the Section settings. In order to do this, we have to point the div to the attribute set in the section. file.

Here is the same file with the changes:

{% set tag_type = segment.subtype|default('section') %}
{% set attr_id = segment.attributes.id ?: 'g-' ~ segment.id %}
{% set attr_class = segment.attributes.class %}
{% set attr_background = segment.attributes.background %}
{% set attr_extra = '' %}
{% set boxed = segment.attributes.boxed %}
{% if boxed is not null %}
    {% set boxed = boxed|trim == '' ? gantry.config.page.body.layout.sections : boxed %}
{% endif %}

{% if segment.attributes.extra %}
    {% for attributes in segment.attributes.extra %}
        {% for key, value in attributes %}
        {% set attr_extra = attr_extra ~ ' ' ~ key|e ~ '="' ~ value|e('html_attr') ~ '"' %}
        {% endfor %}
    {% endfor %}
{% endif %}

{% set html %}
    {% if segment.children %}
        {% for segment in segments %}
            {% include '@nucleus/layout/' ~ segment.type ~ '.html.twig' with { 'segments':segment.children } %}
        {% endfor %}
    {% endif %}
{% endset %}

{% if html|trim %}
    {% if boxed is not null and (boxed == 0 or boxed == 2) %}
        {% set html %}
        <div class="g-container">{{ html|raw }}</div>
        {% endset %}
    {% endif %}

    {% set html %}
    {% if boxed == 2 %}{% set attr_class = attr_class ~ ' g-flushed' %}{% endif %}
    {% set attr_class = attr_class ? ' class="' ~ attr_class|trim ~ '"' %}
    <{{ tag_type }} id="{{ attr_id }}"{{ attr_class|raw }}{{ attr_extra|raw }}>
    {% if attr_background %}<div class="section-background" style="background-image: url({{ url(attr_background) }})">{% endif %}
        {{ html|raw }}
    {% if attr_background %}</div>{% endif %}
    </{{ tag_type }}>
    {% endset %}

    {% if boxed == 1 %}
    <div class="g-container">{{ html|raw }}</div>
    {% else %}
    {{ html|raw }}
    {% endif %}
{% endif %}

Once you have made these changes, you should now be able to access the Gantry Administrator and add an image to your section, save the change, and check it out on your site.

Theme Directory Matrix

Here is a quick reference to help you navigate the directory structure of a Gantry 5 theme, as well as where you can put your custom modifications in the custom directory.

Template Files

Engine Files

Administrator Files