Chapter 5: Output Themeable Content from a Module

One of the features of any content management system's architecture is the separation of presentation and data. In Drupal, modules are responsible for figuring out what should be on the page, and themes are responsible for the final look and feel of anything shown in the browser. It's vital for a module to return themeable output, so that the active theme can determine how it's presented.

In this tutorial, we'll:

• Define themeable output.
• Show how modules can avoid embedding presentation data in their output.
• Explain why Drupal favors structured arrays over HTML strings for data presentation.

By the end of this tutorial, you will be able to articulate the role modules play in enabling themes to customize a Drupal site's appearance.

Drupal's Render API plays a crucial role in how content is presented on a site. The Render API manages how content is rendered through render arrays and render elements.

In this tutorial, we'll:

• Define render arrays, highlighting properties and elements.
• Explain how render elements are used as shorthand for complex structures.
• Describe the primary types of data we can use in a render array.
• Touch on the role of renderers and special methods for rendering entities.

By the end of this tutorial, you'll better understand how Drupal constructs a page's output through render arrays and streamlines rendering with render elements.

Controllers in Drupal should return renderable arrays that contain the content to display for the page. Doing so makes it easier for the theme layer to override the output and customize it for a specific site.

In this tutorial, we'll:

• Convert the WeatherPage controller to use a renderable array instead of hard-coded HTML for displaying the weather forecast.
• Verify our updates.

By the end of this tutorial, you should understand how to structure content as a render array within a controller.

Template files in Drupal modules provide the default HTML markup for the visual presentation of a module's data. Be aware that themes are likely to override the template with site-specific customizations. This template should contain only minimal markup to ensure functionality, and document the variables fed into the template.

In this tutorial, we'll:

• Explain the role of Twig template files in modules.
• Show how modules declare and use template files.
• Recognize how a render array can specify a template.

By the end of this tutorial, you should be able to articulate how and when a module should define a new template file.

Template files are used by modules when they need to add custom HTML to the content they output. The most common example is wrapping your output in one or more <div> tags to give it additional structure and context. Using custom template files in a Drupal module requires defining a new theme hook, creating the template file, an associating the appropriate data with the template file via a render array.

In this tutorial, we'll:

• Learn how to add a custom Twig template file to a module.
• Update the WeatherPage controller to use the new template file.

By the end of this tutorial you should be able to create and use custom template files in a module.

Asset libraries in Drupal associate CSS and JavaScript files with components, which enhances performance because the assets will only be loaded when they're needed.

In this tutorial, we'll:

• Define asset libraries and their purpose.
• Learn how to define an asset library in a module.
• Examine how asset libraries attach to components.

By the end of this tutorial, you should understand how asset libraries optimize resource loading and facilitate component-based development in Drupal.

Modules can define new asset libraries that include CSS and JavaScript files, and then attach them to the content they output. This process involves defining a new asset library, authoring the related CSS and JavaScript, and using the #attached render array property to associate the library with the applicable content.

In this tutorial, we'll:

• Define a new asset library in the anytown module.
• Include CSS and JavaScript in the library.
• Attach the new library to the /weather page.

By the end of this tutorial, you should be able to define an asset library and add CSS and JavaScript to a page from a Drupal module.

Drupal modules need to ensure that any strings of text they add in code can be localized by Drupal's translation system. When our code creates a new <button> element with the text "Toggle forecast" it needs to be done in a way that would allow changing that text to another string, like "Alternar pronóstico", depending on the user's preferred language.

In this tutorial, we'll:

• Define the difference between internationalization and localization and how they allow a Drupal site to be translated.
• Explore the utilities available to module developers to ensure that the user interface strings in their code are translatable.

By the end of this tutorial, you should be able to explain how and why to internationalize the code in your Drupal modules.

It's a Drupal best practice to always use Drupal's internationalization utilities for any user interface strings in your code. This includes the PHP t() function and StringTranslationTrait trait, the Twig t filter, and the JavaScript Drupal.t() function. This makes it possible for our module's interface to be localized.

In this tutorial, we'll:

• Edit the WeatherPage controller and use the t() method from the StringTranslationTrait trait for all UI strings.
• Update the weather-page.html.twig template file to use the Twig t filter.
• Modify the JavaScript in our forecast.js code to use the Drupal.t() function for UI strings.

By the end of this tutorial you should be able to update the PHP, Twig, and JavaScript code in your module to ensure that any user interface strings they output are translatable.