This is a proposal for the new Drupal 8 theme system. It consists of 5 Phases.
Example for terminology: For the following explanation and all examples, let's say we are working with a node of type Article.
- hook = the name of the module or theme that is inplementing the hook (examples at bottom)
- THEME_ID = name of the theme hook. for the node template his will be
node
. - SUGGESTION_ID = name of the template suggestion. for the node template, this will be
article
.
hook_theme()
This phase remains unchanged. This is where a new theme function is defined, the variables that will be passed in, and the template file that will be used to generate the output.
hook_theme_suggestions_alter()
hook_theme_suggestions_THEME_ID_alter()
This is a new phase. It will be the only way to add, change, or remove suggestions. Replaces $variables['#theme_suggestions']
in preprocess. This phase also allows altering the default 'found suggestion', so for a node of type article, article
could be changed back to page
, for example.
hook_theme_prepare()
hook_theme_prepare_THEME_ID()
This phase is where the arguments passed into theme() are converted into variables to be printed in the template.
- Things that will happen here include loading a node from a nid, or creating a url from a path.
- Things that will NOT happen here are things like calls to check_plain (since all sanitization will happen when the variables are printed in the template, by Twig)
hook_theme_prepare_alter()
hook_theme_prepare_THEME_ID_alter()
hook_theme_prepare_THEME_ID_SUGGESTION_ID_alter()
This is a replacement for the current preprocess. It allows for altering the variables that were prepared in Phase 3, similar to hook_form_FORM_ID_alter
. The big difference here (and the reason for renaming this function) is that we don't want modules that defined their own theme hook to use this phase to alter those variables into a printable state. Modules should use the prepare phase for that instead.
The final phase may have three possible outcomes:
- the variables are inserted into a template (sanitized) | template -> HTML
- the variables are concatinated into a string (sanitized) | theme function -> HTML
- or the variables may be returned (unsanitized)*
(*)This special case may not end up being necessary, but it would be possible by adding a TRUE/FALSE flag as a third parameter to return these variables as an array.
node module:
- Node module would call
node_theme()
to define the node template and variables. - Node module would then call
node_theme_prepare_node()
to prepare them for insertion to the template. - Node modue would also provide a
core/modules/node/templates/node.html.twig
file for use.
rdf module:
- RDF module could (optionally) call
rdf_theme_suggestions_alter()
if it wanted to provide new RDF-specific suggestions, perhaps node--rdf.html.twig (see below). - RDF module could (optionally) call
rdf_theme_prepare_node_alter()
if it wanted to alter the variables prepared for insertion into that template, to include new RDF attributes. - RDF module could (optionally) provide a
core/modules/rdf/templates/node--rdf.html.twig
to replace the node template with one that contained more span tags for adding additional attributes more easily.
bartik theme:
- Bartik theme could (optionally) call
bartik_theme_suggestions_alter()
if it wanted node 26 to usenode--awesome.html.twig
instead ofnode.html.twig
. - Bartik theme could (optionally) call
bartik_theme_prepare_node_alter()
if it wanted to add or change the variables used in its template. - Bartik theme could (optionally) provide a
core/themes/bartik/templates/node.html.twig
file that would replace the one provided by node module, or anode--awesome.html.twig
file that would be used when conditions defined inbartik_theme_suggestions_alter()
are met.
Clean. +1