Scribd
Upload
107 views33 pages

Introduction-to-Drupal-8-Theme-Development

The document provides an introduction to theme development in Drupal 8. It discusses the anatomy of a Drupal theme including important files like the .info.yml and .libraries.yml files. It covers creating a basic theme and overriding core templates by copying them to the theme's templates folder. The document also explains template suggestions and how to create template variations to handle different pages or content types. In general, it outlines some of the key concepts for building and customizing themes in Drupal 8 using the Twig templating engine.

Uploaded by

Antoniofondista
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
107 views33 pages

Introduction-to-Drupal-8-Theme-Development

The document provides an introduction to theme development in Drupal 8. It discusses the anatomy of a Drupal theme including important files like the .info.yml and .libraries.yml files. It covers creating a basic theme and overriding core templates by copying them to the theme's templates folder. The document also explains template suggestions and how to create template variations to handle different pages or content types. In general, it outlines some of the key concepts for building and customizing themes in Drupal 8 using the Twig templating engine.

Uploaded by

Antoniofondista
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 33

Introduction to Drupal 8

Theme Development
Introduction to Drupal 8 Theme Development

Jonathan Daggerhart
Technology Coordinator, Educational Partners International
No. 2, Drupal Camp Asheville 2016

Drupal.org: daggerhart
Twitter: @daggerhart

2
Introduction to Drupal 8 Theme Development
What we will cover

Part 1 ● Anatomy of theme file system


● Creating your first theme
● Twig templates, and where to find them
● Twig syntax

Part 2 ● Working with template suggestions


● Modifying content with hook_preprocess()
● Render arrays
● Custom templates with hook_theme() 3
Introduction to Drupal 8 Theme Development
Anatomy of a Theme named “trainer”
● trainer.info.yml
Drupal ● trainer.libraries.yml
● trainer.theme
● templates/
themes
● css/
○ my-style.css

trainer
● js/
○ my-js.js

4
Introduction to Drupal 8 Theme Development
Theme info file (trainer.info.yml)
A theme’s info file tells Drupal about the theme and its
configuration. It uses the YAML file format of key-value pairs and
YA lists of KV pairs.
ML
● Required Properties
trainer.info.yml ○ name: 'Trainer'
description: 'Theme example for DCAVl'
version: 8.x-0.1
type: theme
core: 8.x
● Recommended Properties
5
○ base theme: stable
Introduction to Drupal 8 Theme Development
trainer.info.yml continued...
● Regions - containers for blocks (content)
○ regions:
YA navigation: 'Navigation'
ML
header: 'Top Bar'
footer: 'Footer'
trainer.info.yml content: 'Content'
sidebar_first: 'Primary Sidebar'

● Libraries - assets or resources required by the theme


○ libraries:
- 'trainer/my-custom-assets'
6
Introduction to Drupal 8 Theme Development
Libraries (trainer.libraries.yml)
Name of asset bundle my-custom-assets:
Version version: 1.x
YA CSS by type (theme|module) css:
ML Note: file path is key and object theme:
is value
css/my-style.css: {}
trainer.libraries.yml
JS js:
Note: file path is key and object js/my-js.js: {}
is value dependencies:
Dependencies
- core/jquery
Name of asset bundles required
by this asset bundle 7
Introduction to Drupal 8 Theme Development
my-style.css -and- my-js.js
Our new theme needs some style and interactivity. What better for
style than red borders around everything, and how about a popup
CS box for interaction!?
S
● trainer/css/my-style.css -
my-style.css
div { border: 1px solid red; }

● trainer/js/my-js.js -
JS (function($){
alert('hello world - jQuery version ' + $.fn.jquery);
my-js.js
})(jQuery);
8
Introduction to Drupal 8 Theme Development
Child Theme
Creating a new theme as a “child theme” means that your theme
inherits the configuration of another theme. This allows a developer
YA to leverage another theme’s infrastructure in hopes of shorter
ML
theme development time and greater theme stability.

trainer.info.yml How to make a child theme of ‘classy’ - trainer.info.yml

base theme: classy

How to make a new base theme - trainer.info.yml

base theme: false


9
Introduction to Drupal 8 Theme Development
Templates & Twig
Templates are snippets of code that represent an HTML component
of your Drupal site. Drupal aspires to keep all HTML in templates. In
Tw Drupal 8, the Twig templating engine is used. Twig filenames end in
ig “.html.twig”

<*>.html.twig Example: some core templates

● page.html.twig - contains generic content wrapper HTML, such as


<header>, <footer>, <main>, <section id=”primary-sidebar”>
● html.html.twig - contains outer-most HTML sent to the browser, such as the
<html>, <head>, and <body> tags
● node.html.twig - contains generic “node” entity HTML wrappings, such as
<article> 10
Introduction to Drupal 8 Theme Development
Overriding templates
To override another Drupal template, copy the original template to
your theme’s templates folder.
pag
e .htm
l.tw Copy template from core module that provides it--
ig
core module
template file ● core/modules/system/templates

copy ○ page.html.twig

To your theme’s templates folder--

pag
e ● themes/trainer/templates
.htm
l.tw
ig
○ page.html.twig
custom theme
template file
11
Introduction to Drupal 8 Theme Development
Overriding templates - Child theme edition
To override a base theme’s template, copy the template from the that
theme’s templates folder to your theme’s templates folder. If the
pag
e.h
tm l.tw file doesn’t exist in base theme, look in the module for it.
ig
base theme template file Copy template from base theme if it is provided--

● core/themes/classy/templates/
copy
○ Page.html.twig

pag To your theme’s templates folder--


e.h
tm l.tw
ig
● themes/trainer/templates
custom theme template file
○ page.html.twig 12
Introduction to Drupal 8 Theme Development
Practice: Override the core twig templates in your theme

Drupal provides many templates out of the box. Some examples of


core templates are:

● html.html.twig
● page.html.twig
● region.html.twig
● node.html.twig
● block.html.twig
● field.html.twig

Using what you’ve learned, find these templates, and add them to
your theme. When in doubt, look in the “system” module. 13
Introduction to Drupal 8 Theme Development
Template suggestions
Drupal’s template discovery process is based on an array of
“template suggestions”. This array contains a list of possible
template file names, and can be modified by modules and themes.

Example: Drupal core page template suggestions

[ "page__", "page__front" ]

Example: Drupal core node template suggestions


[ "node__full", "node__article", "node__article__full",
"node__5", "node__5__full" ]

14
Introduction to Drupal 8 Theme Development
Using a Template Suggestion
Page Template Suggestions on Front page

"page__",
"page__front"

page.html.twig Copy template and rename it to new suggestion, replacing underscores with dashes--
Result:
copy
● themes/trainer/templates
○ page.html.twig

○ page--front.html.twig
page--front.html.twig

Now we have a separate page template for the site’s homepage!


15
Introduction to Drupal 8 Theme Development
Working with Twig - Syntax
In Twig there are two kinds of delimiters: {% ... %} and {{ ... }}. The first one is used to
execute statements such as for-loops, the latter prints the result of an expression to the
template. http://twig.sensiolabs.org/

Output variable values {{ my_variable }} Hello world

Output nested values {{ name.first }} or Jonathan


{{ name[‘first‘] }}

Statements with {% if name.first == ‘Jonathan‘ %} Hi Jonathan


{% … %} Hi {{ name.first }}
{% endif %}

Filter values w/ pipe | {{ name.first|lower }} jonathan

Code Comments {# this is ignored by twig #}


16
Introduction to Drupal 8 Theme Development
Twig Template Example
<main role="main">
<a id="main-content" tabindex="-1"></a>{# link is in html.html.twig #}
Comments
<div class="layout-content">
{{ page.content }}
Output </div>{# /.layout-content #}

Statements {% if page.sidebar_first %}
<aside class="layout-sidebar-first" role="complementary">
{{ page.sidebar_first }}
</aside>
{% endif %}

{% if page.sidebar_second %}
<aside class="layout-sidebar-second" role="complementary">
{{ page.sidebar_second }}
</aside>
{% endif %}
</main> 17
Introduction to Drupal 8 Theme Development
More about Twig
Variable {% set my_string = ‘The quick brown...‘ %}
Assignment {% set my_list = [ ‘three‘, 2, ‘one‘ ] %}
{% set my_object = { ‘name‘: ‘Bobby‘ } %}

Loops {% for item in my_list %}


{{ item }}
{% endfor %}

Functions {{ link(“My Link“, “http://google.com“) }}

Join & Split {{ my_list|join(‘, ‘) }}


filters {% set new_list = “five,six,seven“|split(‘,‘) %}

18
Introduction to Drupal 8 Theme Development
Twig Resources
Twig

● Documentation - http://twig.sensiolabs.org/documentation
● Template Designers Syntax - http://twig.sensiolabs.org/doc/templates.html

Twig & Drupal

● Twig in Drupal 8 - https://www.drupal.org/theme-guide/8/twig


● Twig Best Practices - https://www.drupal.org/node/1920746
● Drupal Twig Functions - https://www.drupal.org/node/2486991
19
Introduction to Drupal 8 Theme Development
Theme .theme file (trainer.theme)
A theme’s “dot theme” file (trainer.theme) is an entry point for
PHP developers to hook into Drupal and make most
.the customizations. Place custom PHP in this file. For example: hooks.
me
Most often a theme file and its dependencies will focus on
trainer.theme modifying the output of the Drupal site as HTML.

That is the whole purpose of a theme after all; to stylize the output
of a system, as opposed to governing the system with logic.

20
Introduction to Drupal 8 Theme Development
Theme .theme file continued...
Using the trainer.theme file, let’s hook into Drupal and begin making
modifications to the system! We’ll do the following things:

● Add new template suggestion for unpublished nodes using -


hook_template_suggestions_HOOK_alter().
Then implement the new suggestion.

● Preprocess the page template and alter its contents by using -


hook_preprocess_HOOK().
Create a new value that the Twig template can output.

21
Introduction to Drupal 8 Theme Development
hook_template_suggestions_HOOK_alter

Provide a template suggestion if the node is not published.

22
Introduction to Drupal 8 Theme Development
Using new template suggestion: node--unpublished.html.twig

Copy the basic node template and rename it to new suggestion, replacing
underscores with dashes, and leaving the file extension “.html.twig”--
Result:

node.html.twig ● themes/trainer/templates
○ node.html.twig
copy
○ node--unpublished.html.twig

Now we have a separate node template for unpublished nodes! This isn’t the most
node--unpublished.html.twig
practical example, but you should now have an idea of easy it can be to add a new
template suggestion when you have the right hook:
hook_template_suggestions_HOOK_alter
23
Introduction to Drupal 8 Theme Development
hook_preprocess_HOOK

Alter variables available to the template before they are sent to Twig
Q: What is
this?

A: That’s a
“render array”

24
Introduction to Drupal 8 Theme Development
Render Arrays
"Render Arrays" or "Renderable Arrays" are the foundational
components of a Drupal page. A render array is a hierarchical
associative array containing data to be rendered and properties
describing how the data should be rendered. A render array is often
returned by a function to specify markup to be sent to the web
browser or other services

Most simple example:

25
Introduction to Drupal 8 Theme Development
Render Arrays Example: item list
Create an HTML unordered bullet list of strings:

$variables['my_list'] = [ // key is twig var name


# '#theme' => 'item_list', // template
Properties of
'#list_type' => 'ul', // template property
the element '#items' => [ // template property
are prefixed
with the
'first item',
number sign, 'second item',
whereas
values are not.
'third item',
],
];
26
Introduction to Drupal 8 Theme Development
Render Array Examples in Action
PHP - trainer.theme Twig - page.html.php

Rendered Output

27
Introduction to Drupal 8 Theme Development
Render Array Resources
● Drupal 8 Render Arrays API - General overview of render arrays
https://www.drupal.org/developing/api/8/render/arrays

● Drupal 7 Form API - Though the API is technically for Drupal 7, these
properties also apply to Drupal 8.
https://api.drupal.org/api/drupal/developer%21topics%21forms_api_reference.html/7.x

● Render Array Snippets - Oldie but a goodie


https://chacadwa.com/blog/2012/12/20/drupal-7-render-array-snippets

● Drupal 7 Examples module - render_examples submodule


28
https://www.drupal.org/project/examples
Introduction to Drupal 8 Theme Development
Hook_theme - Providing new templates
All templates within Drupal have been provided by some module or
theme’s implementation of hook_theme. Providing your own new
templates is a great way to further understand render arrays, and
how Drupal works fundamentally.

function hook_theme($existing, $type, $theme, $path){


Hook
return [
Summary:
'my_new_component' => [
return an
'#template' => 'my_new_component_template_name'
array of new
'#variables' => [ 'some_var' => 'default value' ]
components
]
];
} 29
Introduction to Drupal 8 Theme Development
Hook_theme - About Node Author
This example provides a new template to Drupal that will serve as
an “about the author” component.
Key is the component’s machine safe
name

Template is the template file name


without file extension.
ie, node_author.html.twig

Variables is an array of possible


component variables and their default
values.
30
Introduction to Drupal 8 Theme Development
Hook_theme - new Twig Template
Next, we want to create a new Twig template for this component

trainer/templates/node_author.html.twig

31
Introduction to Drupal 8 Theme Development
Hook_theme - In Action
Finally, we’ll use hook_preprocess_node to add our new
element to all node pages. In trainer.theme --

32
Introduction to Drupal 8 Theme Development
Hook_theme - Results
trainer.theme node.html.twig

node_author.html.twig

33

You might also like