Drupal Theme -- Import Default Configuration on Theme Install

Theme Import Configuration on Install

Firstly before we proceed to importing some default configuration on theme enabling, we must know what default configuration to import. In Drupal, this is usually defined as a YML file with certain schema, for instance, below an example of a node’s configuration, specified in its corresponding schema node.type.article.yml: FILE node.type.example_mytype.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

type: example_mytype
name: Example
description: 'Use <em>example</em> content to get to Drupal 8 development better.'
help: ''
new_revision: false
display_submitted: true
preview_mode: 1
status: true
langcode: en
dependencies:
  module:
    - example
  enforced:
    module:
      - example

Though you can write it manually like the above example, it is both trivial to write and check to ensure its schema aligns with what Drupal consider as valid. I would much more recommend using the drush cex command to export the configuration and sanitise them to be available importable configuration yml files.

I propose a 3 step the “SET + RETRIEVE + TEST” method, that is:

1. SET: actually set the configuration in Drupal Backend (e.g. place a title block in certain region)
2. RETRIEVE: using drush cex command to export the configuration and copy it to the config/option (OR config/install) folder
3. TEST: remove/delete the configuration you’ve set previously (e.g. delete the title block), and uninstall the theme, then install it back again, then verify if the configuration has been imported (e.g. check if the title block exists, and has been placed on the right region)

You can find more details about this in the below example.

Example: Default Theme Block in Region

Let’s say I want to place some Blocks in the Regions when I install the theme, what should I do?

Firstly, prepare the <root>/sites/default/files/sync, by exporting all the existing configuration using drush cex.

Secondly, login to the Drupal backend and actually place the blocks in region as you wish (SET)

Thirdly, export the configuration again using drush cex again, to export the new configuration files to <root>/sites/default/files/sync.

Notice when you run dursh cex, it will tell you what files have changed, you’ll copy those files from the config sync directory to your theme’s config/optional (OR config/install) folder; after the copy/paste, you’ll need to sanitise them via removing the uuid and hash related lines. (RETRIEVE)

Finally, remove the blocks you’ve added previously, uninstall the theme, then install back the theme and set as default, to verify that the configuration is taking effect (TEST):

*in the above GIF you can see that: after we brought back the theme, the empty regions becomes filled with blocks

Difference between configuration in config/install and config/optional ?

• config/install/: Contains the default configuration files (in YAML format) that are imported into the site’s active configuration when the theme is first installed:

  • Use this for mandatory settings like default theme settings

    (e.g. config/install/olivero.settings.yml in Drupal Core’s Olivero theme: link)

    (e.g. config/install/gin.settings.yml in Gin theme: link)

    (e.g. config/install/mercury.settings.yml in Mercury theme: link)

  • Use this for block placements specific to your theme.

    (e.g. config/install/block.block.civictheme_content.yml in Civic Theme: link)

• config/optional/: Contains configuration files that are only imported if their dependencies (such as a specific module the configuration relies on) are already met at the time of theme installation:

  • Use this for settings that are dependent on other modules

    (e.g. config/optional/search_api.settings.yml in Civic Theme theme: link –> dependency: search_api)

  • Some of the blocks also consider system as a dependency for blocks:

    (e.g. config/optional/block.block.bootstrap_site_branding.yml in Bootstrap theme: link –> dependency: system)

    (e.g. config/optional/block.block.gin_page_title.yml in Gin theme: link –> dependency: system

• Note that both config/optional and config/install are imported during the theme installation (not enabling) !!!!!!!

Reference & Extension

• Drupal Documentation – Include default configuration in your Drupal module/theme: link
• Drupal Documentation – Creating sub-themes, Inheriting Block Placement: link
• Drupal Answers – What is the purpose of the config/install directory: link
• Drupal Documentation – Defining and using your own configuration in Drupal: link