gistfile1.md

Example for terminology:

• hook = hook
• themeID = node
• suggestionID = article

1) Definition

hook_theme()

This is "as is"

2) Suggestions

hook_theme_suggestions_alter()
hook_theme_suggestions_themeID_alter()

The only way to add or remove suggestions. Replaces $variables['#theme_suggestions']. Also allows altering the default found suggestion, similar to the display_id in views_preprocess_view.

3) Prepare

hook_theme_prepare()
hook_theme_prepare_themeID()

Prepares variables for output in a theme (like a link moving from path, text to url, check_plain()ed text), replaces template_preprocess_*

4) Alter

hook_theme_prepare_alter()
hook_theme_prepare_themeID_alter()
hook_theme_prepare_themeID_suggestionID_alter()

Allows altering the variables, like form_formID alter for the suggestionID.

5) Render/Output

• theme function -> HTML
• template -> HTML
• special render = TRUE / FALSE flag as third parameter to return variables as is -> array().

Clean, extensible, no magic, and works exactly like form API and _alter() is fast by definition and the right thing to do here.