Common theme hooks

In this section, we will look at three common theme hooks that come with Drupal core that you are likely to use quite often. The best way to understand them is, of course, by referring to an example of how to use them. So, let's get to it.

Lists

One of the most common HTML constructs are lists (ordered or unordered), and any web application ends up having many of them, either for listing items or for components that do not even look like lists. But for the purposes of marking up, an ul or ol fits the bill best. Luckily, Drupal has always had the item_list theme hook, which is flexible enough to allow us to use it in almost all cases.

The item_list theme hook is defined inside drupal_common_theme(), is preprocessed (by default) in template_preprocess_item_list(), uses the item-list.html.twig template by default, and has no default theme hook suggestions (because it's so generic and registered outside the context of any business logic). If we inspect its definition, we'll note that it takes a number of variables that build up its flexibility. Let's take a look at an example of how to use it.

Imagine that we have the following array of items:

$items = [

  'Item 1',

  'Item 2'

];

The simplest way we can render this as an <ul> is as follows:

return [

  '#theme' => 'item_list',

  '#items' => $items

];

Do note that the respective <ul> is wrapped in a <p class="item_list"> and that the items in our array can also render arrays themselves.

If we want to change the list into an <ol>, we set the #list_type variable to ol. We can even have a title heading (<h3>) before the list if we set the #title variable. Moreover, we can add more attributes on the <p> wrapper. For more information on how the other options work, I suggest that you inspect the template file and preprocessor function. However, these are the ones you'll most often use.

Links

In Chapter 2, Creating Your First Module, we briefly looked at how we can work with links programmatically and how to build and render them in two different ways. We also noted that it's better to use the #link render element (and we now understand what this is) if we want the link to be alterable somewhere down the line. Now, let's take a look at how we can build a list of links using the helpful links theme hook.

The links theme hook takes an array of links to be rendered, optional attributes, an optional heading, and a flag to set the active class dynamically. It then uses the links.html.twig template to construct a <ul>, much like the item_list hook.

The most important variable here is the array of links, as it needs to contain inpidual arrays with the following keys: title (the link text), url (a Url object), and attributes (an array of attributes to add to each link item). If you look inside the template_preprocess_links preprocessor, you'll see that it takes each of these items and transforms them into a render array with the #type => 'link' (the render element).

In addition to the array of links, we can also pass a heading (just like with item_list) and a flag for setting the active class—set_active_class. The latter will make it add an is-active class onto the <li> item in the list and the link itself if the link matches the current route. Handy stuff, isn't it? However, for more information, check out the documentation above the template_preprocess_links() implementation. Now, let's see a quick example of using this in practice:

$links = [

  [

    'title' => 'Link 1',

    'url' => Url::fromRoute('<front>'),

  ],

  [

    'title' => 'Link 1',

    'url' => Url::fromRoute('hello_world.hello'),

  ]

];

return [

  '#theme' => 'links',

  '#links' => $links,

  '#set_active_class' => true,

];

That is all. We build an array of link data and then construct the render array using the links theme hook. We also use the set_active_class option just for kicks. This means that the is-active class will be present on the first link if this is rendered on the home page or on the second link if rendered on the Hello World page. As simple as that.

Tables

The last common theme hook we will look at now will help you build tables. It has always been a Drupal best practice to use the theme hook when building tables rather than creating the markup yourself. This is also, in part, because it has always been very flexible. So, let's take a look.

The table theme hook takes a bunch of variables, many of them optional. The most important, however, are the header (an array of header definitions) and rows (a multidimensional array of row definitions). It's not worth repeating all the possible options you have for building tables here because they are all very well documented above the template_preprocess_table() preprocessor function. So, do check there for more information. Instead, we'll focus on a simple use case of rendering a table, and we'll do so via an example:

$header = ['Column 1', 'Column 2'];

$rows = [

  ['Row 1, Column 1', 'Row 1, Column 2'],

  ['Row 2, Column 1', 'Row 2, Column 2']

];

return [

  '#theme' => 'table',

  '#header' => $header,

  '#rows' => $rows,

];

So, as you can see, we have the two critical variables. We have the list of header items and the rows (whose cells are in the array in the same order as the header). Of course, you have many more options, including attributes at all levels of the table, handy sorting capability that makes it easy to integrate with a database query, and more. I strongly encourage you to explore these options in the documentation.