Drupal 8 development: non-content | Part 1/3: Backend configuration form

(Available as freelancer)

Joris Snoek

Business Consultant
/ Drupal Developer

Within a Drupal 8 website, there are usually a number of texts that the content manager must be able to manage but that are not real content items.

Dutch version of this blog here.

We resolve this by making a user-friendly configuration form in the backend of Drupal 8, accessible to content managers. This allows us to make sure that all non-content is easy to manage, so that content managers do not have to dig through all kinds of screens in a technical backend to find the correct settings.

An example are the texts (and background image) in this Frontpage header block:

An example of the corresponding Drupal 8 backend configuration form:

This blog series consists of three parts:

1. Building the Drupal 8 backend configuration form and defining a Twig template file.
2. Development of a custom Drupal 8 Block, in which imported texts are retrieved from the configuration form; rendered in a custom Twig template file.
3. Managing the background image via the already defined backend configuration form.

In this part 1:

1. Create a new module using Drupal Console.
2. Implement Drupal 8 backend configuration form.
3. Defining Twig template file - and variables, for facilitating dynamic html in the frontend.

1. New module with help from Drupal Console

Drupal Console is a CLI tool for boilerplate code to generate (also called skeleton code). Console also offers functions to perform and debug actions within Drupal 8.

Drupal Console also offers functions to generate Drupal forms, that is, boilerplate code. To do this, we have to start creating a new module in which the form is then implemented.

Generate a new module using Drupal Console:

1. Enter command drupal generate:module in a terminal.
2. Enter a name for the new module. We are only going to use this module for configuration purposes, so I call it 'OpenLucius Configuration'.
3. The yellow text is the default entered by Console if you press enter without entering anything. This default module machine name is fine, so press enter.
4. The same goes for the module path. It is a best practice in Drupal to subdivide the /modules folder into /contrib *, */custom and /devel.
5. Enter a description, it appears in the Drupal 8 backend on the global /config screen.
6. Yes, I want to generate a .module file. We need this later to implement a hook_theme, where we create a Twig template file known to Drupal. In that, the dynamic html will go live.
7. We indeed need a themeable template file as mentioned in (6). By default, this will not generate the correct naming, but it is useful as an example code.

2. Generate Drupal 8 backend configuration form

The following fields must be managed by content managers:

1. Frontpage header title
2. Frontpage header subtitle
3. Frontpage header intro text
4. Frontpage header read more link
5. Frontpage header background image

Now, for example, Site name and Slogan fields are already available in Drupal 8 core and may be used as Frontpage header title and Frontpage header subtitle.

But for the convenience of content managers, we do not use those Drupal core fields and we create one easy-to-use form that controls all non-content fields. Thus, no fragmentation of features across all kinds of technical administrators, which scares a content manager.

Defining fields and field names, we always do it in English, given that the Drupal 8 backend is always English and it is the language of development (code, comments, etc) as well. We always keep the backend English for consistency in, among other things, debugging and helpdesk issues from customers.

Generate the fields

We start creating the text fields, the image field we deal with in part 3 of this blog series.

I generate the required backend form in the newly created module as described above. We make the form and the text fields using the Drupal Console:

1. From the web root of your Drupal 8 installation: enter drupal generate:form:config in a terminal.
2. Specify which module you want to put in the form, so you must generate it in an existing module; Therefore we first created the Drupal 8 module above.
3. Do you want to load services? Read more about Services and dependency injection in Drupal 8. For this example it is not necessary to key enter.
4. Start building up the form fields by defining the first field, in this example I start generating the textfield 'Frontpage Header Title'.
5. Give your field a Label, this text will be above the field. Enter a clear name here, so Drupal content managers know what to enter here.
6. Configure optional values for elements associated with this field.
7. You can enter as many fields as you like, until you reach “New field type (press to stop adding fields) [ ]:” thus pressing enter without entering text. Then some final questions will be asked, after which the form will be generated in the indicated module:

1. Once you have entered all the elements, leave it blank and hit enter.
2. Enter the desired path (route), this default is fine. More about Drupal 8's routing system here
3. The default Yes is fine, we would like it to appear in the backend menu so that content managers can easily navigate to it.
4. Enter the title of this desired menu item and place it in this default parent menu: This will appear in the Drupal Backend menu.
5. Give it a description, which appears on the config overview page:

Drupal 8 Form API

Drupal 8 has an extensive Form API, which lets you see which elements and options are available. For more information see:

The folder and file structure of the generated module looks like this:

The generated code for the form:

Install module and Drupal 8 backend form

Install the module so that the generated form becomes active. This can be done with Drupal Console's command module:install :

A link is created in the configuration screen:

And the form detail page works:

The form is used directly, saving the values in the database is immediately:

3. Defining Twig template file and template variables, for facilitating dynamic html in frontend.

Drupal Console has just created a template file and defined it as hook_theme(), so that Drupal 8 recognizes this and we can call it in modules through the Render API and / or those in Drupal 8 theme can override.

But as Drupal Console has defined it, it's too generic, I'd like it more specific because more Twig template files will be added soon. Also, I want to add Twig template variables, to make the html dynamic. These variables will facilitate the input of content managers, making it completely dynamic through the backend form.

To initiate this, I make two adjustments:

1. I change the template file name so it's less generic and we can already deduce what the name is being used for.
2. I change the Twig template definition in hook_theme(), so Drupal is aware of the 'new' Twig template file. Also, I have defined template variables so that Drupal knows which variables are available. These Twig variables I will further implement and explain in the next part of this blog.

Twig and Drupal 8

Learn more about Twig templating in Drupal 8? Click Here.

Placing HTML in Twig template file

As the last action in this part of this blog series, I place the (already developed) HTML in the Twig template file:

As you can see, I immediately placed the Twig variables, which in the following section we will go to "fill in" with texts entered by the content manager in the backend form.

Wrap up part 1

Alrighty, we have now created a module and generated a Drupal 8 backend form. In addition, we have defined a Twig template file and variables, which means that Drupal 8 knows that our template file exists and which variables are used in it.

But we do not see this HTML anywhere in the front end, and the texts are not yet dynamically loaded from the configuration form.

How do we do that? That's what I describe in Part 2, so stay tuned!