Problem/Motivation

We need to figure out how best to document the variables for theme templates. There are two main users of this documentation:

a) Themers -- they need to know what variables are available for theming, in the template itself.

b) Module/core developers -- they need to know what variables to put into their render arrays. For templates with preprocessing functions, this list of variables is not the same as the variables in the theme template itself.

Proposed resolution

Probably the templates (either .html.twig or .tpl.php files, for Drupal 8 or 7) should have the variables that are available in the template itself, for themers.

What needs to be determined is where to document the variables that a module developer would need to put in their render array, and how a module developer would discover them.

Remaining tasks

Figure this out, write a standard, update Core to comply with it.

Original report....

It seems to me that the removal of theme functions in D8 has left a gap in our documentation, because there's no equivalent place to document how to use a theme hook.

For example, consider item_list.

On D7, the main documentation for this is https://api.drupal.org/api/drupal/includes!theme.inc/function/theme_item..., which tells you exactly what to pass in to a call to theme('item_list') or to a render array that uses #theme => item_list.

On D8, I don't think there is an equivalent.

There is https://api.drupal.org/api/drupal/core!modules!system!templates!item-lis..., but the documentation there tells you about the variables available to the template. In many cases, these will have been changed by the preprocess functions, so that's not always a correct guide on how to use the theme hook in a render array.

There's also https://api.drupal.org/api/drupal/core!includes!theme.inc/function/templ..., but that doesn't seem like an intuitive place to put the docs. Also, not every theme hook in core will have a preprocessor, so I wouldn't expect to find docs on how to use a theme hook here.

Comments

joachim created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Active » Closed (works as designed)

The variables available to the module developer should be documented on the template if preprocessing is minimal, or on the (hopefully linked) preprocess function if not. This was also true in D7, when most of the theme functions were converted to tpl.php files.

In 8, most of these are elements and not #theme anyway... the few remaining places where you should actually use #theme and not #type should be documented on the templates.

If there are individual theme templates that need better docs, let's open individual issues to get them fixed.

joachim’s picture

joachim CreditAttribution: joachim as a volunteer commented

> documented on the template if preprocessing is minimal, or on the (hopefully linked) preprocess function if not.

But that means that the place where you find how to use them is inconsistent.

And when the preprocessor function doesn't touch a particular variable at all, that tends to not get documented there.

joachim’s picture

joachim CreditAttribution: joachim as a volunteer commented
Status: Closed (works as designed) » Active

It's not just me who has this concern -- from #2620854: links.html.twig docs are out of date:

We have a case here where there is a preprocessing function that expects certain input from the render array, and then the Twig template expects the processed output of that as its input.

My question is whether in the Twig template we are supposed to document what comes in after preprocessing? In which case, where are we documenting what goes into the render array? This is kind of a generic question, not just for this issue:
- Module developers passing stuff from their module through a given theme hook -- where do they look for docs and what do they expect?
- Theme developers overriding a theme template -- where do they look for docs and what do they expect?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Active » Postponed

OK, well if it's a real problem, it seems like what we need to do is file an issue in Coding Standards and agree to a standard. Then we can fix Core to comply with it. Postponing this issue until that process is done.

joachim’s picture

joachim CreditAttribution: joachim as a volunteer commented
Project: Drupal core » Coding Standards
Version: 8.2.x-dev »
Component: documentation » Documentation
Category: Bug report » Task
Status: Postponed » Active

Let's make this issue the coding standards issue, as my intention in filing it was to discuss how we deal with this.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: gap in documentation for theme hooks » Decide how to document theme variables
Issue summary: View changes

Updating title and summary

joachim’s picture

joachim CreditAttribution: joachim as a volunteer commented

I could have sworn I also filed an issue about how there's a problem with how to refer to theme elements now that theme_foo() functions don't exist.

But in the absence of that, here will do.

    // By default, render the form using theme_confirm_form().
    if (!isset($form['#theme'])) {
      $form['#theme'] = 'confirm_form';
    }

Even core doesn't know how to do this!