Skip to main content
deleted 38 characters in body
Source Link
Clive
  • 167.9k
  • 19
  • 303
  • 337

Where my confusion comes in is when I go to specify parameters or document the function. What parameters does the function take? What hook does it implement?

Preprocess hooks are only provided a single parameter: $variables. The hook that you're implementing is literally hook_preprocess_HOOK. The HOOK part of it is the identifier for the theme entry, as defined in a hook_theme() implementation somewhere.

So if you have this:

function MODULE_theme() {
  return [
    'foo' => [
      'variables' => [],
    ],
  ];
}

Then, by convention, you can implement hook_preprocess_hook like so:

/**
 * Implements hook_preprocess_HOOK() for foo templates
 */
function MODULE_preprocess_foo(&$variables) {
  // ...
}

Note the docblock; the convention is to use for THEMEXXX templates, where THEMEXXX is a description of the aforementioned identifieritem being preprocessed. If you search for implements hook_preprocess in the theme entrycore folder, you'll find a lot of these as examples.

So, once I have written a hook implementation (i.e. my_theme_preprocess_block or my_theme_preprocess_page__user__edit), how can I definitively know what hook I have just implemented?

By definition, you already know :) You created the function with a certain name, and that name defines the for THEME part of the phrase in the docblock aboveso you know which theme entry you're preprocessing variables for.

like for the block - hook_preprocess_HOOK is very generic, how can I be sure I'm not implementing something more specific that I just missed in my Googling?

Because there can only ever be one theme entry for a given nameidentifier, you won't run into this problem.

In the case of the hook above, I'm able to find documentation for a template_preprocess_page function, and no such hook_preprocess_page function

something I should know about the difference between template_preprocess_whatever and hook_preprocess_whatever functions that if I knew that thing I wouldn't be confused

Hopefully, along with the above, this will clear things up:

  • template_process_HOOKtemplate_preprocess_HOOK is, again by convention, used by the module implementing the theme entry, to provide the base variables. It's always run first, before hook_preprocess_HOOK is invoked, so it helps those defining theme entries to ensure important variables and processing are done up front before the rest of the system gets involved.
  • hook_preprocess_HOOK is essentially for other modules to preprocess the variables, rather than for the module implementing the theme. There's nothing to stop that module from implementing hook_preprocess_HOOK as well (it's just a naming convention and no special checking is made), but it could be undesirable to do that if some initial processing needs to be done, a la template_preprocess_HOOK.

Where my confusion comes in is when I go to specify parameters or document the function. What parameters does the function take? What hook does it implement?

Preprocess hooks are only provided a single parameter: $variables. The hook that you're implementing is literally hook_preprocess_HOOK. The HOOK part of it is the identifier for the theme entry, as defined in a hook_theme() implementation somewhere.

So if you have this:

function MODULE_theme() {
  return [
    'foo' => [
      'variables' => [],
    ],
  ];
}

Then, by convention, you can implement hook_preprocess_hook like so:

/**
 * Implements hook_preprocess_HOOK() for foo
 */
function MODULE_preprocess_foo(&$variables) {
  // ...
}

Note the docblock; the convention is to use for THEME, where THEME is the aforementioned identifier for the theme entry.

So, once I have written a hook implementation (i.e. my_theme_preprocess_block or my_theme_preprocess_page__user__edit), how can I definitively know what hook I have just implemented?

By definition, you already know :) You created the function with a certain name, and that name defines the for THEME part of the phrase in the docblock above.

like for the block - hook_preprocess_HOOK is very generic, how can I be sure I'm not implementing something more specific that I just missed in my Googling?

Because there can only ever be one theme entry for a given name, you won't run into this problem.

In the case of the hook above, I'm able to find documentation for a template_preprocess_page function, and no such hook_preprocess_page function

something I should know about the difference between template_preprocess_whatever and hook_preprocess_whatever functions that if I knew that thing I wouldn't be confused

Hopefully, along with the above, this will clear things up:

  • template_process_HOOK is, again by convention, used by the module implementing the theme entry, to provide the base variables. It's always run first, before hook_preprocess_HOOK is invoked, so it helps those defining theme entries to ensure important variables and processing are done up front before the rest of the system gets involved.
  • hook_preprocess_HOOK is essentially for other modules to preprocess the variables, rather than for the module implementing the theme. There's nothing to stop that module from implementing hook_preprocess_HOOK as well (it's just a naming convention and no special checking is made), but it could be undesirable to do that if some initial processing needs to be done, a la template_preprocess_HOOK.

Where my confusion comes in is when I go to specify parameters or document the function. What parameters does the function take? What hook does it implement?

Preprocess hooks are only provided a single parameter: $variables. The hook that you're implementing is literally hook_preprocess_HOOK. The HOOK part of it is the identifier for the theme entry, as defined in a hook_theme() implementation somewhere.

So if you have this:

function MODULE_theme() {
  return [
    'foo' => [
      'variables' => [],
    ],
  ];
}

Then, by convention, you can implement hook_preprocess_hook like so:

/**
 * Implements hook_preprocess_HOOK() for foo templates
 */
function MODULE_preprocess_foo(&$variables) {
  // ...
}

Note the docblock; the convention is to use for XXX templates, where XXX is a description of the item being preprocessed. If you search for implements hook_preprocess in the core folder, you'll find a lot of these as examples.

So, once I have written a hook implementation (i.e. my_theme_preprocess_block or my_theme_preprocess_page__user__edit), how can I definitively know what hook I have just implemented?

By definition, you already know :) You created the function with a certain name, so you know which theme entry you're preprocessing variables for.

like for the block - hook_preprocess_HOOK is very generic, how can I be sure I'm not implementing something more specific that I just missed in my Googling?

Because there can only ever be one theme entry for a given identifier, you won't run into this problem.

something I should know about the difference between template_preprocess_whatever and hook_preprocess_whatever functions that if I knew that thing I wouldn't be confused

Hopefully, along with the above, this will clear things up:

  • template_preprocess_HOOK is, again by convention, used by the module implementing the theme entry, to provide the base variables. It's always run first, before hook_preprocess_HOOK is invoked, so it helps those defining theme entries to ensure important variables and processing are done up front before the rest of the system gets involved.
  • hook_preprocess_HOOK is essentially for other modules to preprocess the variables, rather than for the module implementing the theme. There's nothing to stop that module from implementing hook_preprocess_HOOK as well (it's just a naming convention and no special checking is made), but it could be undesirable to do that if some initial processing needs to be done, a la template_preprocess_HOOK.
Source Link
Clive
  • 167.9k
  • 19
  • 303
  • 337

Where my confusion comes in is when I go to specify parameters or document the function. What parameters does the function take? What hook does it implement?

Preprocess hooks are only provided a single parameter: $variables. The hook that you're implementing is literally hook_preprocess_HOOK. The HOOK part of it is the identifier for the theme entry, as defined in a hook_theme() implementation somewhere.

So if you have this:

function MODULE_theme() {
  return [
    'foo' => [
      'variables' => [],
    ],
  ];
}

Then, by convention, you can implement hook_preprocess_hook like so:

/**
 * Implements hook_preprocess_HOOK() for foo
 */
function MODULE_preprocess_foo(&$variables) {
  // ...
}

Note the docblock; the convention is to use for THEME, where THEME is the aforementioned identifier for the theme entry.

So, once I have written a hook implementation (i.e. my_theme_preprocess_block or my_theme_preprocess_page__user__edit), how can I definitively know what hook I have just implemented?

By definition, you already know :) You created the function with a certain name, and that name defines the for THEME part of the phrase in the docblock above.

like for the block - hook_preprocess_HOOK is very generic, how can I be sure I'm not implementing something more specific that I just missed in my Googling?

Because there can only ever be one theme entry for a given name, you won't run into this problem.

In the case of the hook above, I'm able to find documentation for a template_preprocess_page function, and no such hook_preprocess_page function

something I should know about the difference between template_preprocess_whatever and hook_preprocess_whatever functions that if I knew that thing I wouldn't be confused

Hopefully, along with the above, this will clear things up:

  • template_process_HOOK is, again by convention, used by the module implementing the theme entry, to provide the base variables. It's always run first, before hook_preprocess_HOOK is invoked, so it helps those defining theme entries to ensure important variables and processing are done up front before the rest of the system gets involved.
  • hook_preprocess_HOOK is essentially for other modules to preprocess the variables, rather than for the module implementing the theme. There's nothing to stop that module from implementing hook_preprocess_HOOK as well (it's just a naming convention and no special checking is made), but it could be undesirable to do that if some initial processing needs to be done, a la template_preprocess_HOOK.