How to make your Drupal 7 theme fit for Drupal 9

07.12.2021 - Updated on 27.06.2024

Drupal 7 Theme Upgrade — © pixabay.com/de/

Attention "dusty"!

This article is already a little outdated and may contain information that no longer corresponds to the current status of the topic.

The theming of Drupal 9 has evolved considerably. The expiry of the Drupal 7 version in November 2022 requires an inevitable upgrade. Read our blog article to find out what steps you should follow to make your Drupal 7 theme fit for the latest version of Drupal.

The most important theming functions of Drupal 9

Some of the Drupal 9 features can greatly simplify theme updates such as.

Semantic HTML5 markupby default
Improved out-of-the-box accessibility features
Use of Twig as theme engine instead of PHP template
Former theme_* functions and *.tpl.php files are replaced by *.twig files
Standard performance-enhancing functions (such as CSS and JS aggregation)
Responsive functions OOP
Attachment of JS and CSS assets by using libraries (instead of drupal_add_css and drupal_add_js)
CSS file structure based on SMACSS & BEM
CSS3 pseudo selectors
Classy as base theme

The conversion of the theme engine to Twig is the most important change. Twig is a PHP-based compiled templating language. This means that the Twig engine converts the template into a compiled PHP template when rendering your website, which is saved in a protected directory under sites/default/files/php/twig.

Drupal 9 Theme Migration Checklist

Unfortunately, there is no tool that automatically migrates Drupal 7 themes to Drupal 9 (upgrade) or indicates what the user needs to change.

For the migration, a complete theme must be created from scratch and elements from the D7 theme must be rebuilt manually. A checklist for the migration can help to simplify the process.

The following steps should be followed when creating a new theme:

Schritt 1: Erstellen der Ordnerstruktur

Sie sollten Themes in Drupal 9 im Ordner “themes” der Drupal-Installation finden. Es ist empfehlenswert, diese zu klassifizieren, je nachdem, ob es sich um Contributed Themes oder benutzerdefinierte Themes handelt. Die Struktur sollte etwa so aussehen:

Schritt 2: Erstellen der erforderlichen Dateien

Die einzige Datei, die Drupal benötigt, um Ihr Theme zu erkennen, ist die Datei .info.yml:. Die alte .info-Datei wird nicht mehr benötigt, da sie durch .info.yml ersetzt wurde. Diese Datei folgt der yaml-Syntax. Denken Sie also daran, die Einrückung auf Leerzeichen anstelle von Tabulatoren zu setzen und diese Einrückung zu beachten.

Hier ist ein Beispiel, angenommen, wir erstellen ein Theme namens simple:

Die Einführung des "base_theme" Schlüssels ist essentiell. Mit ihm können Sie den Namen eines anderen Themes definieren, von dem Sie Eigenschaften übernehmen möchten. Wenn Sie dies nicht benötigen, müssen Sie den Schlüssel mit dem Wert "false" hinzufügen.

Schritt 3: Definieren von Regionen

Die Regionen für Drupal 9 Themes werden in der Datei theme_name.info.yml unter dem Schlüssel "regions" definiert:

Schritt 4: Erstellen und Laden von Libraries

Anstatt das alte drupal_add_js zum Hinzufügen von Javascript-Assets oder drupal_add_css zum Hinzufügen von CSS-Dateien zu verwenden, sollten Sie Libraries erstellen und laden. Um diese zu erstellen, müssen Sie eine neue Datei theme_name.libraries.yml hinzufügen und die Libraries darin definieren:

Um die Libraries zu laden, gibt es mehrere Möglichkeiten:

Schritt 5: Verschieben der Theme-Einstellungen

Haben Sie in der Drupal 7-Version Ihres Themes Breakpoints verwendet, mussten Sie das Modul Breakpoints installieren. In Drupal 9 brauchen Sie das nicht mehr, da diese Funktionalität jetzt Teil des Kerns ist. Sie müssen lediglich eine neue Datei theme_name.breakpoints.yml erstellen und dort Ihre Breakpoints hinzufügen. Zum Beispiel:

Schritt 6: Breakpoints erstellen, falls erforderlich

Haben Sie in der Drupal 7-Version Ihres Themes “Breakpoints” verwendet, mussten Sie das beigefügte Breakpoints Modul installieren. In Drupal 9 brauchen Sie das nicht mehr, da diese Funktionalität jetzt Teil des Kerns ist. Sie müssen lediglich eine neue Datei theme_name.breakpoints.yml erstellen und dort Ihre Breakpoints hinzufügen. Zum Beispiel:

Schritt 7: Konvertieren von Templates nach Twig

Die Umstellung der Theme-Engine von PHP Template auf Twig bringt einige wesentliche Änderungen bei den Templates. Einige Online-Tools können Ihnen diesen Prozess erleichtern, wie z. B. https://php2twig.com/. 

In der folgenden Tabelle haben Sie eine Liste der alten und neuen Art, Vorlagen zu schreiben:

Note on templates and preprocess functions

In Drupal 9, only the basic hook of a preprocess function exists. In D7, for example, you have a "node--event-teaser.tpl.php" and consequently a "hook_preprocess_node__event__teaser" function in your template.php file.

The template file for the event teaser is also available in D9, but you only receive the basic hook "hook_preprocess_node". To act specifically on your event teaser, you must therefore create logic within the base.

You can find more information about the differences between PHPTemplate and Twig here. https://www.drupal.org/node/1918824

Now you can get started and create your new themes! You can find more help from the following sources: