The theme() function

Understanding theme()

The Theme Registry

The theme() function relies on a large body of information which is the theme registry which contains entries for every conceivable element that can be presented. There are entries for :

• - large items of presentation like "node_list" which will present a list of drupal nodes,
• - units of presentation like "search_block_form" which presents the search text field and button,
• - right down to individual elements of presentation like "breadcrumbs" and even "text_textarea"

Each element in the theme registry contains the following information:

• default argument values for the arguments required for the element
• the path to the currently selected theme (since template files reside here)
• the name of the function or template to be used for rendering
• the list of pre-process functions - more on these later

This information is used to make the call to the function that will render the element.

Recursion

Drupal has organized its structure recursively, so that a call to the larger presentation element results in calls to theme() for smaller presentation elements which results in calls to theme() for even smaller presentation elements.

Functions

Depending on the information in the theme registry entry for the element being processed by them(), either the specified function is called or a template rendering function is called. If it is a function that is called, there is no further processing - the information from the theme registry and the passed arguments are passed onto the function.

or Templates

If it is a template that is invoked, then a set of variables are constructed which will be used by the template. Preprocess functions populate these variables. The preprocess_template() function is called for all templates and it populates variables like is_admin, is_front, is_logged_in and the user object.

If a template require additional variables, then there are special preprocess functions that populate additional variables. For example, the special preprocess function for the "page" element populates over twenty variables.

The Whole Picture

Having understood the pieces, here is the "whole picture" view.

Drupal wants to separate the presentation from the drupal core. So it says - let me create data for whatever can be overridden - and puts it in the theme registry. So, node-lists, search-blocks and breadcrumbs along with a few hundred other elements get into the theme registry.

So what does this do? It allows the elements to be changed. And, in what ways can an element be changed? Since you can change the function that is called for generating the output, this means that you can generate whatever output you want.

And, the beauty of the system is that it allows the change to be made on an element-by-element basis, thus allowing customization over the entire range - from the smallest to the largest elements.