Theming Inside a Module

Once the philquotes_block() function has obtained the content of a quote, it must add some formatting and styling to the data. This is handled with functions that make use of the theme system. And the first stage is handled with the theme() function.

We took a look at the theme() function in the last chapter. But there we were primarily interested in creating themes. Here, we are working on a module. In the module, we want to provide some default theming, but in a way that makes use of the theme system. This provides more flexibility: theme developers can change the layout of our module without having to change any of our code.

Default Themes "

Often, a module adds content that existing themes do not already provide layout information for. In such cases, the module developer should provide a default theme. A default theme should provide layout information for the new content that the module makes available.

The theme() function is called in philquotes_block() with three parameters:

$content = theme('philquotes_quote', check_plain($item->body), check_plain($item->title));

The first, philquotes_quote, tells the theme() function which theme hook should be executed. The theme() function will query the theme system to find an implementation of a function called theme_philquotes_quote() or a template called philquotes_quote.

Neither a matching function nor a matching theme exists in the default installation of Drupal. But in a moment, we will solve this problem by creating a default theme function that will be part of our module.

The next two parameters are the body and title of the quote we want to display. (Recall that $item is the object that contains the content of our random quote node.)

The theme() function itself does not do anything special with parameters after the first. Instead, they are passed on to the special theme hook (in this case, theme_philquotes_quote() ).

Check the Content

In the last chapter, we looked at check_plain() and other content checking functions. Why do we use check_plain() here? The ^ content of a quote may contain HTML content, and some of the HTML may not be safe. So before passing this data on to the theme system, it ought to be escaped. In this case, we want HTML-escaped text, so we use check_plain(). Failure to properly escape content can lead to security vulnerabilities.

Where will the theme() function, which now must find theme_philquotes_ quote(), look for themes? One place it will look is inside the currently enabled theme. In our case, this is the Descartes theme we created in the last chapter. But there is no philquotes_quote function or template in that theme.

Drupal's theme system will also look among other registered themes. Modules can register their own theme functions, making these themes available to the theme system. If no theming is provided by the default theme, the module's theme will be used. Since our module is providing new content that needs some theming, we will need to register a theming function to provide default theming.

In Chapter 2, we created the Goodreads module. The output generated by H that module was hard-coded HTML. To improve that module, we could make use of the theme system in much the same way that we are about to do for this module.

0 0

Post a comment