The current documentation could be improved. On the API page: https://api.drupal.org/api/drupal/core%21modules%21system%21system.api.p... the documentation says only:
base hook: A string declaring the base theme hook if this theme implementation is actually implementing a suggestion for another theme hook.
I was attempting to implement exactly that - a hook suggestion for
theme_image() - and the single sentence above left many questions unanswered; for instance, did I need to fully copy the base hook's
'variables' => array(...) in my hook's info? The answer in this case is "yes." But the documentation is entirely unclear.
When theme($hook, $variables) is called,
base hook can greatly change the outcome of
These are the determining steps (for the following, assume
base hook = 'image' and
hook = 'image__example'):
hook_theme_suggestions_HOOK()is invoked where HOOK is the base hook (
'image'in our example).
- The original hook (
'image__example'in our example) is added to the end of
hook_theme_suggestions_HOOK_alter()is invoked where HOOK is the base hook ("image").
- At this point, the original hook
'image__example'may or may not remain as the best (last) item in
- If the base hook ("image") has any
$info['includes']files, they are included.
- If the base hook has any
$info['preprocess functions'], they clobber the original hook ("image__example")'s preprocess functions - the original hook's processors will not be called.
- The base hook's
$info['preprocess functions']are called against
$info, where the original hook may still be overridden and prevented from rendering output.
As a result, the original hook's preprocess functions are possibly not called (if the base hook has preprocess functions), and the original hook's theme function/template may not be used (clobbered by something implementing the base hook). Developers should be aware of these possibilities, so that they may use base hook effectively to invoke the base hook's preprocessing and include files, and so that they are not surprised if/when their theme hook suggestion isn't called due to vagaries in the base hook's preprocessors or hook_theme_suggestions_HOOK_alter().
The procedure described above is the same in D7, with a few minor changes (D7 checks the base hook's process functions as well as preprocess functions, and D7 uses "theme_hook_suggestion" to store the original hook instead of appending it to the "theme_hook_suggestions" array n.k.a.
This is a quick issue built from a comment originally in .
PASSED: [[SimpleTest]]: [MySQL] 59,476 pass(es).
PASSED: [[SimpleTest]]: [MySQL] 59,420 pass(es).
PASSED: [[SimpleTest]]: [MySQL] 59,434 pass(es).
FAILED: [[SimpleTest]]: [MySQL] 59,366 pass(es), 0 fail(s), and 2 exception(s).