jenlampton/gist:5654283

## gistfile1.md

      
    Raw
  

              gistfile1.md
            
          
    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.

1) Definition

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.
2) Alter Suggestions

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.
3) Prepare Variables

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)

4) Alter Variables

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.
5) Render/Output

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.
Example for usage

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 use node--awesome.html.twig instead of node.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 a node--awesome.html.twig file that would be used when conditions defined in bartik_theme_suggestions_alter() are met.