PHP

Drupal theme development

OxfordBy No Comments6 Mins Read

https://www.drupal.org/docs/theming-drupal/defining-a-theme-with-an-infoyml-file

To create a Drupal 8 or later theme you need to first create a THEMENAME.info.yml file that provides meta-data about your theme to Drupal. This is similar to how modules and installation profiles are being defined, and as such, it is important to set the ‘type’ key in the file.info.yml to ‘theme’ in order to differentiate it.

This page provides an example fileTHEMENAME.info.yml and an overview of the information that the file can contain.

Name your theme

The first step in creating a theme is to choose a human-readable name for it, and a corresponding machine name. The machine name will be used as the name for files, folders, and functions in your theme, and is used by core Drupal programmatically to refer to your theme. The machine name is usually the human-readable name, converted to lower-case and with underscores instead of spaces. For example, if your theme is named “Fluffiness”, then the machine name is “fluffiness/”. If your theme name is longer, like “Very Fluffy”, your machine name would be “very_fluffy”.

There are some important rules to follow when selecting a machine name:

  • It must start with a letter.
  • It must contain only lower-case letters, numbers and underscores.
  • It must not contain any spaces.
  • It must not be longer than 50 characters.
  • It must be unique. Your theme should not have the same short name as any other module, theme, theme engine, or installation profile you will be using on the site.
  • It should not be any of the reserved terms (folders in the Drupal distribution): src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, drupal.

Create an .info.yml file

Create the .info.yml file in the root of your themes folder. The folder name is the machine name, and the info file name is machine_name.info.yml. For the rest of this page, we’ll create a theme whose human-readable name is “Fluffiness” and machine name is “fluffiness”, so the folder is named “fluffiness/” and the .info.yml file is named “fluffiness/fluffiness.info.yml“. If the file is present with the minimum required properties (name, type, base theme and core/core_version_requirement) your theme will be visible on your website at Manage > Appearance (http://example.com/admin/appearance).

If you are not familiar with the YAML file structure, read the quick introduction to the YAML file format.

  • Tabs are NOT allowed. Use spaces ONLY.
  • Properties and lists MUST be indented by two (2) spaces.

Example

name: Fluffiness
type: theme
description: 'A cuddly theme that offers extra fluffiness.'
core_version_requirement: ^8 || ^9
libraries:
  - fluffiness/global-styling
base theme: classy
regions:
  header: Header
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer

In your Drupal website, you can find more examples of .info.yml files by looking at the themes provided by core. For example, open the folder andcore/themes/stark look for the file stark.info.yml.

Key/value pairs

The following key/value pairs provide meta-data about your theme and define some of the basic functionality. (See \Drupal\Core\Extension\InfoParserInterface::parse().)

name (required)
The human-readable name. This will appear on the “Appearance” page where the theme is activated.

name: Fluffiness
type (required)
Indicates the type of extension, i.e., “module”, “theme”, or “profile”. For themes this should always be set to “theme”. This value is case-sensitive.

type: theme
description (optional)
The description, displayed on the “Appearance” page.

description: An extra cuddly Drupal theme available in grey and blue.
dependencies (optional)

Introduced in 8.9.x

See change record.

An array of dependency strings.

dependencies:
  - drupal:views
  - paragraphs:paragraphs
  - components:components (>=8.x-2.x)
package (optional)
Specifies a “package” that allows you to group themes together.

package: Core
core (required)
Specifies the version of Drupal core that the theme is compatible with.

core: 8.x

It can be omitted if you specify core_version_requirement and don’t support Drupal 8.7.7 and below. See change record.

php (optional)
The minimum version of PHP required. Defaults to the value of DRUPAL_MINIMUM_PHP constant.

php: 5.5.9
version (optional)
Specifies a version. For themes hosted on drupal.org, the version number will be filled in by the packaging script. Do not specify it manually, but leave out the version line entirely.

version: 8.x-1.0

or

version: '1.0'
libraries (optional)
A list of libraries (which can contain both CSS and JavaScript assets) to add to all pages where the theme is active. Read more about themes and asset libraries.

libraries:
  - fluffiness/global-styling
libraries-override (optional)
A collection of libraries and assets to override. Read more at Overriding and extending libraries.

libraries-override:
  contextual/drupal.contextual-links:
    css:
      component:
        /core/themes/stable/css/contextual/contextual.module.css: false
libraries-extend (optional)
A collection of libraries and assets to add whenever a library is attached. Read more at Overriding and extending libraries.

libraries-extend:
  core/drupal.user: 
    - classy/user1
    - classy/user2
base theme (required)
A theme can inherit the resources from another theme by specifying it as a base theme. It is recommended to use classy or stable9 (or stable if using Drupal 8). If set to false, no base theme is being used.

base theme: classy
hidden (optional)
Indicates whether or not to hide the theme from the “Appearance” page so that it cannot be enabled/disabled via the UI.

hidden: true
engine (optional)
The theme engine. Defaults to “twig”.

engine: twig

Introduced in 8.6.x

See change record.

The path to logo relative to the theme’s .info.yml file. By default, Drupal will look for a file named “logo.svg” in the root of your theme folder and use that as the theme’s logo.

logo: images/logo.png
screenshot (optional)
The path to screenshot relative to the theme’s .info.yml file. Screenshots should be 588 pixels wide and 438 pixels high, though they are displayed at a smaller size. By default, Drupal will look for a file named “screenshot.png” in the root of your theme folder and use that as the theme image on the “Appearance” page.

screenshot: fluffiness.png
regions (optional)
A list of theme regions. (Note that region keys are not preceded by a dash.) A content region is required. Read more about adding regions to a theme.

regions:
  header: Header
  content: Content
  sidebar_first: 'First sidebar'
regions_hidden (optional)
A list of inherited regions to remove.

regions_hidden:
  - sidebar_last
features (optional)
A list of features to expose on the theme “Settings” page.

features:
  - comment_user_verification
  - comment_user_picture
  - favicon
  - logo
  - node_user_picture
stylesheets-remove (deprecated)
A list of stylesheets from other modules or themes to remove from all pages where the theme is active. Each value must be a full path relative to the docroot to resolve ambiguity when more than one file with the same name exists. In cases where the file is part of a library that belongs to a module or theme, a token in the form @module_or_theme_name can be used in place of the full path. Note that when using the token the value must be quoted because “@” is a reserved indicator in YAML. Note: This key is deprecated and will be removed in Drupal 9. In most cases libraries-override should be used.

stylesheets-remove:
  - core/assets/vendor/normalize-css/normalize.css
  - '@classy/css/components/tabs.css'
ckeditor_stylesheets (optional)
A list of stylesheets to add to the CKEditor frame.

ckeditor_stylesheets:
  - https://fonts.googleapis.com/css?family=Open+Sans
  - css/base/elements.css

More information

Related Content

How to create a basic Drupal 8 theme

How to create a basic Drupal 8 theme if you are a beginner in Drupal. This tutorial explains the basics to start theming your Drupal 8 site.

 

Share.
Avatar photo

Related Posts