Functions and templates for the user interface that themes can override.

Drupal's theme system allows a theme to have nearly complete control over
the appearance of the site, which includes both the markup and the CSS used
to style the markup. For this system to work, modules, instead of writing
HTML markup directly, need to return "render arrays", which are structured
hierarchical arrays that include the data to be rendered into HTML (or XML or
another output format), and options that affect the markup. Render arrays
are ultimately rendered into HTML or other output formats by recursive calls
to drupal_render(), traversing the depth of the render array hierarchy. At
each level, the theme system is invoked to do the actual rendering. See the
documentation of drupal_render() and the
Theme system and Render API topic for more
information about render arrays and rendering.

Theme Hooks

The theme system is invoked in \Drupal\Core\Render\Renderer::doRender() by
calling the \Drupal\Core\Theme\ThemeManagerInterface::render() function,
which operates on the concept of "theme hooks". Theme hooks define how a
particular type of data should be rendered. They are registered by modules by
implementing hook_theme(), which specifies the name of the hook, the input
"variables" used to provide data and options, and other information. Modules
implementing hook_theme() also need to provide a default implementation for
each of their theme hooks, normally in a Twig file, and they may also provide
preprocessing functions. For example, the core Search module defines a theme
hook for a search result item in search_theme():

Given this definition, the template file with the default implementation is
search-result.html.twig, which can be found in the
core/modules/search/templates directory, and the variables for rendering are
the search result and the plugin ID. In addition, there is a function
template_preprocess_search_result(), located in file search.pages.inc, which
preprocesses the information from the input variables so that it can be
rendered by the Twig template; the processed variables that the Twig template
receives are documented in the header of the default Twig template file.

hook_theme() implementations can also specify that a theme hook
implementation is a theme function, but that is uncommon and not recommended.
Note that while Twig templates will auto-escape variables, theme functions
must explicitly escape any variables by using theme_render_and_autoescape().
Failure to do so is likely to result in security vulnerabilities. Theme
functions are deprecated in Drupal 8.0.x and will be removed before
Drupal 9.0.x. Use Twig templates instead.

Overriding Theme Hooks

Themes may register new theme hooks within a hook_theme() implementation, but
it is more common for themes to override default implementations provided by
modules than to register entirely new theme hooks. Themes can override a
default implementation by creating a template file with the same name as the
default implementation; for example, to override the display of search
results, a theme would add a file called search-result.html.twig to its
templates directory. A good starting point for doing this is normally to
copy the default implementation template, and then modifying it as desired.

In the uncommon case that a theme hook uses a theme function instead of a
template file, a module would provide a default implementation function
called theme_HOOK, where HOOK is the name of the theme hook (for example,
theme_search_result() would be the name of the function for search result
theming). In this case, a theme can override the default implementation by
defining a function called THEME_HOOK() in its THEME.theme file, where THEME
is the machine name of the theme (for example, 'bartik' is the machine name
of the core Bartik theme, and it would define a function called
bartik_search_result() in the bartik.theme file, if the search_result hook
implementation was a function instead of a template). Normally, copying the
default function is again a good starting point for overriding its behavior.
Again, note that theme functions (unlike templates) must explicitly escape
variables using theme_render_and_autoescape() or risk security
vulnerabilities. Theme functions are deprecated in Drupal 8.0.x and will be
removed before Drupal 9.0.x. Use Twig templates instead.

Preprocessing for Template Files

If the theme implementation is a template file, several functions are called
before the template file is invoked to modify the variables that are passed
to the template. These make up the "preprocessing" phase, and are executed
(if they exist), in the following order (note that in the following list,
HOOK indicates the hook being called or a less specific hook. For example, if
'#theme' => 'node__article' is called, hook is node__article and node. MODULE
indicates a module name, THEME indicates a theme name, and ENGINE indicates a
theme engine name). Modules, themes, and theme engines can provide these
functions to modify how the data is preprocessed, before it is passed to the
theme template:

template_preprocess(&$variables, $hook): Creates a default set of variables
for all theme hooks with template implementations. Provided by Drupal Core.

template_preprocess_HOOK(&$variables): Should be implemented by the module
that registers the theme hook, to set up default variables.

MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all
implementing modules.

MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on
all implementing modules, so that modules that didn't define the theme hook
can alter the variables.

ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to
set necessary variables for all theme hooks with template implementations.

ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set
necessary variables for the particular theme hook.

THEME_preprocess(&$variables, $hook): Allows the theme to set necessary
variables for all theme hooks with template implementations.

THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary
variables specific to the particular theme hook.

Preprocessing for Theme Functions

If the theming implementation is a function, only the theme-hook-specific
preprocess functions (the ones ending in _HOOK) are called from the list
above. This is because theme hooks with function implementations need to be
fast, and calling the non-theme-hook-specific preprocess functions for them
would incur a noticeable performance penalty.

Theme hook suggestions

In some cases, instead of calling the base theme hook implementation (either
the default provided by the module that defined the hook, or the override
provided by the theme), the theme system will instead look for "suggestions"
of other hook names to look for. Suggestions can be specified in several
ways:

In a render array, the '#theme' property (which gives the name of the hook
to use) can be an array of theme hook names instead of a single hook name.
In this case, the render system will look first for the highest-priority
hook name, and if no implementation is found, look for the second, and so
on. Note that the highest-priority suggestion is at the end of the array.

In a render array, the '#theme' property can be set to the name of a hook
with a '__SUGGESTION' suffix. For example, in search results theming, the
hook 'item_list__search_results' is given. In this case, the render system
will look for theme templates called item-list--search-results.html.twig,
which would only be used for rendering item lists containing search
results, and if this template is not found, it will fall back to using the
base item-list.html.twig template. This type of suggestion can also be
combined with providing an array of theme hook names as described above.

A module can implement hook_theme_suggestions_HOOK(). This allows the
module that defines the theme template to dynamically return an array
containing specific theme hook names (presumably with '__' suffixes as
defined above) to use as suggestions. For example, the Search module
does this in search_theme_suggestions_search_result() to suggest
search_result__PLUGIN as the theme hook for search result items, where
PLUGIN is the machine name of the particular search plugin type that was
used for the search (such as node_search or user_search).

Altering theme hook suggestions

Modules can also alter the theme suggestions provided using the mechanisms
of the previous section. There are two hooks for this: the
theme-hook-specific hook_theme_suggestions_HOOK_alter() and the generic
hook_theme_suggestions_alter(). These hooks get the current list of
suggestions as input, and can change this array (adding suggestions and
removing them).

Assets

We can distinguish between three types of assets:

Unconditional page-level assets (loaded on all pages where the theme is in
use): these are defined in the theme's *.info.yml file.

Conditional page-level assets (loaded on all pages where the theme is in
use and a certain condition is met): these are attached in
hook_page_attachments_alter(), e.g.: