Updating themes to Drupal 8 #2 – Folder structure and Twig

Drupal 8’s beta version was released a few month ago and now it is time to start porting themes. In this series we are going to discuss  the most noteworthy changes in Drupal 8 about theming. Quite significant changes were introduced in the theme system between Drupal 8 and 7. This guide contains information that applies to Drupal 8 and refers sometimes to Drupal 7 in order to explain new concepts and approaches.

Theme templates and Twig. Welcome to the Twig World!

Twig is a templating language for PHP, which is a boring way of saying that it’s a tool used to output variables inside HTML :).
Without doubt Twig gives Drupal great advantages to the theme system including: Simplified markup and declarations, Filters, and extensibility. Furthermore it’s easy to learn, powerful and a joy to work with :P.

What does all this mean? For one, you can no longer use PHP code in a theme template, it’s all about Twig. Twig simplifies the theme layer and is easy to understand. In a Drupal 8 theme, the old template.php file now becomes your theme’s .theme file that holds any special PHP code that’s then rendered with Twig variables in twig theme templates.

Twig syntax is also easy to understand. So for example in Drupal 7’s page.tpl.php, we have basic code that renders a block region:

<?php if (!empty($page['preface_first'])): ?>
  <?php print render($page['preface_first']); ?>
<?php endif; ?>

With Twig and Drupal 8, in our page.html.twig template, we can do this as

{% if page.preface_first %}
  {{ page.preface_first }}
{% endif %}

One big change in templates is that attributes and classes arrays have been combined together into an attribute object. Before you could render global classes and attributes for body, nodes and comments as:

class="<?php print $classes; ?>"<?php print $attributes; ?>

… which if converted verbatim to Twig would be:

class="{{ classes }}"{{ attributes }}

To learn more about Twig, you can go to its documentation page

Theme folder structure

This is an example of the files and folders that are found in typical theme folder structure:

  |-my_theme.breakpoints.yml
  |-my_theme.info.yml
  |-my_theme.libraries.yml
  |-my_theme.theme
  |-config
  |  |-install
  |  |  |-my_theme.settings.yml
  |  |-schema
  |  |  |-my_theme.schema.yml
  |-css
  |  |-style.css
  |-js
  |  |-my_theme.js
  |-images
  |  |-buttons.png
  |-logo.png
  |-screenshot.png
  |-templates
  |  |-maintenance-page.html.twig
  |  |-node.html.twig

Here are the key file naming conventions that have changed in Drupal 8:
Drupal 7 > Drupal 8

my_theme.info > my_theme.info.yml
theme's template.php > my_theme.theme
template_name.tpl.php > template_name.html.twig

 

Folders and files in Drupal 8

*.info.yml
A theme must contain an .info.yml file to define the theme. Among other things the .info.yml files defines meta data, style sheets, and block regions. This is the only required file in the theme.

*.libraries.yml
The .libraries.yml file is used to define JavaScript libraries that can be loaded by the theme.

*.breakpoints.yml
Breakpoints define where a responsive design needs to change in order to respond to different devices. Breakpoints are defined in a .breakpoints.yml file

*.theme
The .theme file is a PHP file that contains all the conditional logic and data (pre)processing of the output.

css
It is good practice to store .css files in the ‘css’ sub folder. Drupal 8 core themes organize CSS files following the SMACCS style guide. For a theme to load CSS files they must be defined in .info.yml file.

js
Theme specific JavaScript files are stored in the ‘js’ folder. For a theme to load JavaScript files they must be defined in .libraries.yml file.

images
It is good practice to store images in the ‘images’ sub folder.

Screenshot
If a screenshot.png file is found in the theme folder then it will be used on the Appearance page. Alternatively you can define a screenshot in .info.yml file.

Logo
If a logo.png file is found in the theme folder and no other logo is defined in the settings, than it will be used in the header of the website.

Templates
Templates usually provide HTML markup and some logic. Contrary to Drupal 7, in Drupal 8 templates (*.html.twig files) must be stored in the ‘templates’ sub folder. If you follow particular naming conventions, then Drupal will replace the default templates by the ones you provide, allowing you to override the default output.

Sources Drupal.org, dannyenglander.com

Conclusion

Drupal 8 introduces Twig, which takes the place of the PHPTemplate-based theme system in Drupal 7 and below. Twig, like many similar popular templating engines from other projects, allows designers with HTML/CSS knowledge to modify markup without needing to be an expert in PHP. For example, instead of needing to understand the syntax differences between deeply-nested arrays vs. objects and when to use each, a simple {{ foo.bar }} statement does the trick.

Use the recommended Drupal 8 theme folder structure provides a better organization for our files in which generally we will use some YAML files such as .info.yml, .breakpoints.yml, .settings.yml, schema.yml and .libraries. In the next chapter we are going to discuss a little more about libraries an assets. Hope see you there!

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s