Drupal training 5: Theming Drupal

Embracing the power of Drupal theming will significantly enhance the visual and functional appeal of your website. For developers, a strong grasp of various systems and tools within Drupal is critical to creating exceptional themes.

Understanding the Libraries System

The libraries system in Drupal facilitates efficient management and inclusion of assets such as CSS, JavaScript, and external libraries. By leveraging libraries, developers can load these assets conditionally and ensure that they're only included when necessary, ultimately optimising site performance.

Simple example of a Drupal library

Let's imagine we have a theme called confident. We then create a file called confident.libraries.yml where we can store our different libraries. Here's an example of a library for a teaser:

teaser:
  css:
    theme:
        css/teaser.css: {}
  js:
    js/teaser.js: {}

Then to use this we can open our node--teaser.html.twig file and place {{ library_attach(confident/teaser) }} so now any time a teaser is displayed on the page, the CSS from teaser.css will be called.

There are other ways to add libraries to a Drupal theme. You can see them all on the libraries section of the Drupal.org theming guide.

Understanding Drupal's CSS and JavaScript Systems

The CSS system in Drupal enables the inclusion and management of CSS files from local and external sources, allowing developers to control the presentation of their site meticulously. Understanding how to organise and apply CSS files is crucial to maintaining a consistent design and optimising loading times. See the libraries system above. 

Drupal's CSS libraries prioritisation system follows the SMAACS methodology - base, layout, component, state, theme - but mostly just the first three parts of this are used. In our custom themes, I often use 'theme' property when defining libraries to ensure they are called last. You can read more about the CSS system on the official Drupal docs for CSS. 

Similarly, Drupal’s JavaScript system empowers developers to enhance interactive elements and client-side scripting. By adeptly managing JavaScript libraries, it becomes possible to create dynamic and responsive user interfaces. There are two major features of Drupal's JS system that you will need to understand:

1. Behaviors - which ensure that JS runs at the right time (e.g. when the page loads, but again if something is changed via Ajax), and
2. drupalSettings - JS access to Drupal's configuration settings

Lullabot wrote a great article about Drupal Behaviors. It's about 10 years old now, but still relevant. You can read more about Drupal's JavaScript system on the official Drupal docs.

Utilising Twig Templates Effectively

Twig templates form the backbone of Drupal's theming layer. As a powerful templating engine, Twig allows developers to separate logic from presentation effectively. Understanding Twig syntax, filters, and functions is key to manipulating HTML output and designing intricate layouts.

Twig is a templating language that compiles to PHP. It's quite easy to understand, and looks like this:

# Loops
{% for breadcrumb in breadcrumbs %}
	<li>{{ breadcrumb }}</li>
{% endfor %}

# Check for a value before printing it
{% if node.body is not empty %}
	<div class="node__content">{{ content.body }}</div>
{% endif %}

# Conditional logic
{% if node.field_image.value %}
	<div class="teaser__image">{{ content.field_image }}</div>
	<div class="teaser__content">{{ content|without('field_image') }}</div>
{% else %}
	<div class="teaser__content">{{ content }}</div>	
{% endif %}

Some of the twig templates you will use most often include:

• page.html.twig - the layout for your website, it renders the regions where blocks will be placed - header, main content, footer, etc.
• node.html.twig - the layout for an individual node (e.g. node--teaser.html.twig for nodes in teaser view mode)
• views-view.html.twig - layout for a views list (e.g. views-view--events.html.twig for the view that lists events)
• region.html.twig - the layout for a region (e.g. region--header.html.twig for the header region)
• field.html.twig - the layout of an individual field

Embracing Frontend PHP Techniques

An understanding of Drupal's frontend PHP - especially preprocess functions - is very handy when theming Drupal sites. For example if you wanted to add a CSS class to all nodes for the month of the year (who doesn't want a different colour scheme for each month?) you can create this in your confident.theme file using hook_preprocess_node() like this:

function confident_preprocess_node(&$variables) {
  $node = $variables['node'];
  $date = $node->getCreatedTime();
  $month = date('F', $date);
  $variables['classes'][] = 'node--' . strtolower($month);
}

Then every node will have classes like node node--type-event node--july. Nifty!

There's lots more to learn about Drupal theming, which you can read on the Drupal.org theming docs.

Filed Under:

1. LocalGov Drupal
2. Drupal
3. Drupal Training