Creating a New Particle

Creating a new Particle in Gantry 5 is a pretty straightforward process. You will need a text editor, as you will be creating two files for the Particle.

For the interest of this guide, we will create a simple Particle for a page on a site. This Particle consists of three main parts. The Title, Image, and Description. Particles can be as simple or complex as you need them to be.

Creating the YAML File

While creating your Particle, it may be easier to start with the YAML file as this acts as the blueprint for the particle. The Twig file uses this YAML file to pull information, settings, and find out which fields are being used in the administrator for variables.

Here is the body of our example Particle's YAML file:

name: Example
description: Displays a Title, Image, and Text on the front end.
type: particle

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

    title:
      type: input.text
      label: Title
      description: Customize the section title text.

    image:
      type: input.imagepicker
      label: Image
      description: Select the main image.

    description:
      type: textarea.textarea
      label: Text / HTML
      description: Create or modify your description.

    css.class:
      type: input.text
      label: Class
      description: CSS class name for the particle.

This YAML is made up of two main parts. First, the head of the file which sets the Name, Description, and Type. The Name is what appears in the administrator as the title of the Particle in the Particle Defaults and Layout Manager panels. The Type being Particle tells Gantry that this YAML file is being used to create a Particle.

The second section sets the forms/fields that appear in the administrator, as well as the default settings. These fields are what appear in the administrator and are accessible to your site managers. They give them the ability to do things like set custom text, titles, and toggle settings.

The first field block (enabled) is required. It tells Gantry to put a switch on the back end that makes it possible to enable/disable the Particle.

The rest of the fields here, title, image, description, and css.class provide fields site managers can use to configure the Particle without having to edit any files manually.

Here is a breakdown of the settings used in the example above and how they affect the file:

Creating the Twig File

The next file you will need to create will sit in the same directory as the YAML file. We recommend naming it the same way as you did the YAML file, but in the (name.html.twig) format. Ending the file name with html.twig tells Gantry that this is a Twig file, which is basically the template of the file. It controls how Particles are rendered, states the HTML, and determines how variables defined in the YAML are used.

Here is the content of the example_particle.html.twig file:

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

{% block particle %}
<div class="example_particle {{ particle.css.class }}">
    <div align="center">
        <img src="{{ url(particle.image) }}" alt="image">
        <h2>{{ particle.title }}</h2>
        <p>{{ particle.description }}</p>
    </div>
</div>
{% endblock %}

This is a very basic example of a Twig file, containing three parts.

The first part ({% extends '@nucleus/partials/particle.html.twig' %}) defines the Twig file as being for a Particle. This is a must-have element for all Particle Twig files.

The second part is the Block wrapper. {% block particle %} and {% endblock %} surround the block that contains the Particle. This is also a required component as your Particle will not render correctly without it.

The third part is the meat and potatoes of the Particle. This is the body used to determine how a Particle will look and uses the information set in the YAML. In our example, we set the div class to example_particle. This class tells Gantry that this Twig file is working with information from the custom_html.yaml companion file.

The bits that are placed between curly brackets such as {{ particle.title|e }} pull information from the fields set in the YAML and insert them into the Twig for rendering on the front end.

Once you have created these files, you should see the Particle appear in the Particle Defaults and Layout Manager administrative panels in the Gantry 5 administrator.

Pulling Gantry Configuration Data Using Twig

One of the key components of Gantry is the ability to easily set up fields and options using YAML files that can then be used by users in the Gantry 5 administrator to configure the site.

The YAML file creates the field (or option), the user configures that option, defining the variable which you can then have used during page rendering through your Twig file.

Pulling a configuration variable is pretty easy. You just need to use the gantry.config.get() command to pull this data.

One example of this would be using the line {{ gantry.config.get('styles.base.background') }} to grab the currently-set base background color for the theme.

In our current example, we are pulling the configuration option for the current particle through commands like {{ particle.header }} which pulls the value set for the header field for this specific particle.

Let's say you wanted to pull the variable that is set on another particle. For example, the Branding particle. You can fetch this information using {{ gantry.config.get('particles.branding.css.class') }} which tells Gantry to pull the CSS Class value set in the Branding particle. Doing this will grab the default value, rather than a value set in an individual particle instance from the Layout Manager or Menu Editor.

Customizing an Existing Particle