How Drupal Finds Themable Function Overrides

When a Drupal programmer wants to generate output by calling a themable function, he uses a special invocation that follows the pattern theme($function_name, [$params, ...]) (see the theme() function in includes/theme.inc) to call the function dynamically instead of calling it directly. For example, to call the appropriate themable function theme_foo, you would use theme('foo', $params...).

Tip The theme() function is used to call all theme_foo functions in Drupal. For example, to call theme_foo($param1, $param2), use the syntax theme('foo', $param1, $param2).

Drupal then looks in several places to see if a matching function is implemented and calls the first one that is found. It checks three areas, or namespaces, to find overrides to themable functions:

Theme's namespace: The first place Drupal checks is the active theme's namespace. If Bluemarine is the active theme, the namespace is bluemarine. Drupal will look for a function called bluemarine_foo() and call it with whatever extra parameters were passed to theme(). If theme('foo', $bar) is the original call, and a function named bluemarine_foo is found, the call will be bluemarine_foo($bar).

Theme engine's namespace: If the bluemarine namespace doesn't provide a function to theme foo, then Drupal looks to the theme engine namespace next. Assuming that Bluemarine is the active theme, the engine's namespace is phptemplate, as Bluemarine is a PHPTemplate theme. The function that Drupal will look for is therefore called phptemplate_foo($bar).

Default namespace: Finally, if the function is not found in the engine's namespace, Drupal will use the default namespace, which is theme. A function named theme_foo($bar) will be called, and this is the function provided by the core include file or module. Thus, you can see that the default implementation of any themable function must begin with the prefix theme_.

The active theme's own namespace is rarely used to override functions. You will not find many examples of bluemarine_foo, bluemarine_breadcrumb, and so on. Rather, you will see functions in the engine's namespace being written in the theme files. Anyone overriding a themable function is encouraged to take the engine's namespace to name the override functions. A strong and simple case can be made for this practice: if you want to move the function to a different theme or reuse it in some other way, you won't need to rename the function. Sticking with this policy will also allow you to copy whole theme directories and rename the directory, perhaps as the first step in creating a new theme. For the rest of the chapter, I will choose the option of naming themable functions after the theme engine and will not use the active theme's namespace.

■ Note Pure themes (Chameleon)—the themes that don't rely on an external theme engine—are the exception to the advice of not using the active theme's namespace. If you need to override a theme function and you are using the Chameleon theme, you must use the Chameleon namespace.

Table 5-3 shows some examples of common themable functions, what they would be named if overridden in the Bluemarine theme, and how they are evoked (parameters omitted).

Table 5-3. Examples of Overriding Themable Functions in the Bluemarine Theme

Default Version

Bluemarine Version

Invocation

theme links()

phptemplate links()

theme('links')

theme submenu()

phptemplate submenu()

theme('submenu')

theme xml icon()

phptemplate xml icon()

theme('xml icon')

Exercise 5-1 demonstrates how to override a themable function.

Exercise 5-1 demonstrates how to override a themable function.

0 0

Post a comment