Drupal 7

49

Supporting "right to left" (RTL) languages  

Drupal version: Drupal 6.x Last modified: January 29, 2011

Adding support for RTL (Right to Left) languages involves overriding the lateral styles through cascades and naming the file based on the style sheet it is paired to. The inclusion of the RTL style sheet is automated. The inclusion of the file depends on the language settings set for the site. For example, in the core theme Garland, "style.css" is the main style sheet. It also includes "style-rtl.css" for right to left languages like Arabic or Hebrew. The inclusion of the two styles always loads with the main style first and the RTL style second. This allows cascading of all the rulesets within the two files without having to worry about specificity in the selectors used in the RTL style. There is a coding standard to keep the rules organized. Rules that are dependent on the lateral positioning or dimensions should be commented with /* LTR */ indicating that the property is specific to a left to right layout. This includes floats, margins, padding, etc. Inline text should flow automatically as long as the theme sets the language direction of the document through the "page.tpl.php" template. Example base style: ul.primary-links { margin-top: 1em; padding: 0 1em 0 0; /* LTR */ float: left; /* LTR */ position: relative; }

Corresponding RTL style: ul.primary-links { padding: 0 0 0 1em; float: right; }

While working with the main CSS file, this makes it easier to spot where changes may be needed in the RTL style. Note that if your theme overrides a module style, the associated RTL style will be omitted unless it is present in your theme.

50

Advanced theming  

Drupal version: Drupal 6.x, Drupal 7.x Last modified: May 6, 2011

This section goes beyond basic theming concepts, and discusses more ways you can extend your theme. These topics are good ones to be familiar with to master the art of theming.      

Creating advanced theme settings Custom theme for custom form 6.x Theming Custom Entities Theming forms in your theme Targeting different devices JavaScript and jQuery

51

Creating advanced theme settings Drupal 6 In the Drupal administration section, each theme has its own settings page at admin/build/themes/settings/themeName. And this page has a form with standard settings like “Logo image settings” and “Shortcut icon settings.” Drupal 7 Drupal 7 uses admin/appearance/settings/themeName. In Drupal 6 and beyond, theme authors can now customize this page by adding additional settings to the form. In Drupal 5, theme authors and theme users will have to install the Theme Settings API module (5.x-2.1 or later) before being able to use the method described below.

Adding form widgets for your custom theme settings First, create a theme-settings.php file in your theme directory and add a themeName_settings() or themeEngineName_settings() function. The themeEngineName_settings() form is discouraged since it can lead to fatal errors when two functions with the same name are defined in your Drupal installation. The function should use the Forms API to create the additional form widgets. For example: to add settings to the Garland theme, a garland_settings() or phptemplate_settings() function would be placed in the theme’s theme-settings.php file. Directly modifying Garland or Minnelli is strongly discouraged, since they are used for the install and upgrade process. If a user has previously saved the theme settings form, the saved values will be passed to this function in the $saved_settings parameter. The widgets to add to the form should be returned as a Forms API array. The comments in the following example explain the details:
52

$defaults = array( 'garland_happy' => 1, 'garland_shoes' => 0, ); // Merge the saved variables and their default values $settings = array_merge($defaults, $saved_settings); // Create the form widgets using Forms API $form['garland_happy'] = array( '#type' => 'checkbox', '#title' => t('Get happy'), '#default_value' => $settings['garland_happy'], ); $form['garland_shoes'] = array( '#type' => 'checkbox', '#title' => t('Use ruby red slippers'), '#default_value' => $settings['garland_shoes'], ); // Return the additional form widgets return $form; } ?>

Note that theme authors can create complex, dynamic forms using advanced Forms API (auto-completion, collapsible fieldsets) and the JavaScript library, jQuery.

Getting the settings’ values in your theme files In order to retrieve the settings in the theme’s template.php or .tpl.php files, simply use theme_get_setting('varname'). See the Drupal API for details: http://api.drupal.org/api/6/function/theme_get_setting For example:

or in Drupal 7:

Initializing the default values Since we can’t guarantee that a user will ever go to the admin/build/themes/settings/themeName page, we have to ensure that the default values for our custom settings get initialized. The theme settings variables aren’t set until we submit the admin/build/themes/settings/themeName form for the first time, so in our template.php file we need to check whether the variables are set or not. If they aren’t set, we need to set them to the default values. We accomplish that by retrieving one of the variables and seeing if

53

it is null. If it is null, we save the defaults using variable_set() and then force the refresh of the settings in Drupal’s internals using theme_get_setting('', TRUE). Add the following code near the top of your template.php file:
// <-- change this line

/* * The default values for the theme variables. Make sure $defaults exactly * matches the $defaults in the theme-settings.php file. */ $defaults = array( // <-- change this array 'garland_happy' => 1, 'garland_shoes' => 0, ); // Get default theme settings. $settings = theme_get_settings($theme_key); // Don't save the toggle_node_info_ variables. if (module_exists('node')) { // NOTE: node_get_types() is renamed to node_type_get_types() in Drupal 7 foreach (node_type_get_types() as $type => $name) { unset($settings['toggle_node_info_' . $type]); } } // Save default theme settings. variable_set( str_replace('/', '_', 'theme_'. $theme_key .'_settings'), array_merge($defaults, $settings) ); // Force refresh of Drupal internals. theme_get_setting('', TRUE); } ?>

Note that the variable name “garland_happy” in the first line of the above code would be replaced with a variable name from your custom theme settings and the $defaults array would need to be copied from your theme-settings.php file.

Adding additional settings to a new version of your theme After you have released a 1.0 version of your theme, you will eventually want to add some additional custom settings to the 2.0 version. The process is mostly straight-forward. But pay close attention to the initialization code in the third step: 1. In your theme-settings.php file, add the new settings to the $defaults and $form variables. 2. In your template.php file, add the settings to the $defaults variable in the Initialize theme settings code.

54

3. In your template.php file, update the initialization code to check for the existence of one of your new settings. For example, if you added several settings, including a garland_slippers setting, you would change the first line of the Initialize theme settings code to read: if (is_null(theme_get_setting('garland_slippers'))) {

This will ensure that the defaults for your newly-added custom settings get added to the saved values of the old custom settings.

Drupal 7 In Drupal 7, themes can more flexibly modify the entire theme settings form. In a theme’s theme-settings.php, themes should now use a THEMENAME_form_system_theme_settings_alter(&$form, $form_state) function. This gives the same power to themes that modules have if they use hook_form_system_theme_settings_alter(). See the “Forms API Quickstart Guide” and “Forms API Reference” on http://api.drupal.org/api/7, as well as the hook_form_FORM_ID_alter() docs to learn the full flexibility of Forms API. Note that themes can no longer use the phptemplate_ prefix to the function; you’ll need to use the actual name of your theme as the prefix. Here’s an example if you had a “foo” theme and wanted to add a textfield whose default value was “blue bikeshed”: 'textfield', '#title' => t('Widget'), '#default_value' => theme_get_setting('foo_example'), '#description' => t("Place this text in the widget spot on your site."), ); } ?>

In order to set the default value for any form element you add, you’ll need to add a simple line to your .info file: settings[SETTING_NAME] = DEFAULT_VALUE. For our foo theme, you’d need to edit the foo.info file and add this line: settings[foo_example] = blue bikeshed

In any of your theme’s PHP files, you can retrieve the value the user set by calling:

55

Custom theme for custom form 6.x This page is about how to create custom layout for your custom form. Assumptions:   

Experience with PHP Experience with module writing Experience with theme writing

This document has following structure: 



Module o mymodule.module: function mymodule_menu() o mymodule.module: function myformgene() Theme o template.php: mytheme_theme() o template.php: mytheme_preprocess_myformname() o mytemplate.tpl.php

Some strings, functions, etc are prefixed by 'my' to clearly show what you have to define yourself. During development remember to clear Drupal cache so that it would reread your hooks and theme.

Module Assume you have created module mymodule. Here you create structure of your form and method of displaying it.

mymodule.module: mymodule_menu() By default you create menu entry for the form, which further makes structure builder function callback. function mymodule_menu() { return array( 'mypath' => array( 'title' => 'My title', 'page callback' => 'drupal_get_form', 'page arguments' => array('myformgene'), 'access callback' => true, 'type' => MENU_CALLBACK, ), ); }

This module lets you see the form at http://myhost/mypath

56

See also: hook_menu()

mymodule.module: myformgene() Then you create function which actually defines the structure of your form. It will be called by drupal_get_form(). function myformgene( &$form_state, &$obj ) { return array( 'mysecret' => array( '#type' => 'hidden', ... ), 'myitem1' => array( ... ), 'myitem2' => array( ... ), '#theme' => 'myformname', ); }

This form will be themed by identifier myformname. See also: drupal_get_form(), Forms API reference

Theme template.php: mytheme_theme() Announce that your theme handles theming of myformname object. function mytheme_theme( $existing, $type, $theme, $path ) { return array( 'myformname' => array( 'arguments' => array( 'form' => NULL ), 'template' => 'mytemplate', ), ); }

By convention myformname and mytemplate are identical, except usage of _underscores_ in former and -dashes- in latter. For example: my_cool_form becomes my-cool-form. See also: hook_theme()

template.php: mytheme_preprocess_myformname() Next you have to do some preprocessing for that form. Specifically you specify which elements you render yourself. function mytheme_preprocess_myformname( &$vars ) { foreach( $vars['form'] as $k => $v ) {

57

if( preg_match( '/^[a-z]/', $k ) ) { $vars[$k] = $vars['form'][$k]; unset( $vars['form'][$k] ); } } }

Usually you want to place visible elements yourself in your theme. If you need only some elements to render yourself, then you have to adjust this function and "manually" unset these. See also: preprocessing

mytemplate.tpl.php Lastly, finally, we reach to theming

Remember:   

If your template file is empty (zero length file), then your template will be ignored. If your template contains only print drupal_render( $form ); then all elements will be rendered. If you do render some of the fields yourself, then this addition does nothing.

Note that hidden fields and form tags will be added around your form outside of your template, its automatic. Note that print drupal_render( $form ); DOES NOT print out form tags.

... your-rendered-template ...

During development remember to clear Drupal cache so that it would reread your hooks and theme.

58

Theming Custom Entities There are three pieces, or more specifically functions, that are required to theme the output of a custom entity: hook_menu(), Page Callback, and the MODULE_theme() Hook.

hook_menu() In order to access our entities, Menu paths must be created for tasks such as adding, editing, viewing and deleting entities. Adding, Editing and Deleting entities are related to Drupal's Forms API and beyond the scope of this tutorial. While these other menu definitions are required, we will focus solely on the menu definition for the 'view' task. The menu hook allows us to define the path necessary to view a particular entity, the callback function that handles the request, the page title and the access requirements (among others). See also: hook_menu() In the code below, pay particular attention to the page callback key/value pair. This entry in the array tells Drupal that requests for http://mysite.com/my_entity/$id should be handled by the function entity_page_view. Drupal will simply hand the request off to this function along with the variables we specify. http://mysite.com/entity/1), this callback will * be executed. */ function entity_menu() { $items['entity/%entity'] = array( 'title callback' => 'entity_page_title', 'title arguments' => array(1), 'page callback' => 'entity_page_view', 'page arguments' => array(1), 'access arguments' => array('view entitys'), 'type' => MENU_CALLBACK, ); return $items; } ?>

Page Callback In the entity_menu() hook above, we indicated that requests to view an individual entity will be handled by a callback named entity_page_view. Now we need to define that callback. The code below is pretty simple and most of what you see is comments that explain what each section of the code does. 59

The code takes the entity identified by $id as the first argument and the view mode (full or teaser) as the second. Drupal will pass the view mode arguement and you can use its value to make decisions about what to display and how to display it but for now we will ignore it for the sake of simplicity. What we really want to understand is how to tell Drupal to use a custom template file to theme the output of the entity. The first section of the code sets the $entity->content property to an empty array to clear out any previously rendered content. This property is where the what gets rendered in the template will be stored. In other words, this is the Render Array that Drupal will use to build the output of the entity. In the middle section of the code, we use Drupal's hooks to add any custom fields to the entity. When you add fields to an entity through the Admin GUI, this is the code that retrieves the field definitions and their values and attaches them to the entity for display. During this step, the output for the fields is rendered and stored in the #markup property of the field. It is possible to create custom templates for the output of each field but an explanation of how to do so is beyond the scope of this article. And finally, in the last section of the code, we tell Drupal which themplate file to use to render the output of the entity. By default, Drupal will use the BLOCK template to theme the output. We need to over-ride the default and point drupal to the name of our custom template. It is not necessary to indicate the full path or full name of the file. Drupal can figure that out on its own. We simply point to the theme in the Theme Registry we wish to use. It is important to note that the order in which these tasks are performed appears to be important. The fields must be rendered and attached to the entity before the theme is specified. http://mysite.com/entity/1 (1 is just an example ID, * it could be anything). This function will set up the data and * prepare the render array(s). You will specify the template to * use in this callback. The critical thing to note below is the * order in which field_attach_prepare_view, entity_prepare_view * and field_attach_view are called. These functions must be called * in this order and they must be called before you specify which * theme to use. */ function entity_page_view($entity, $view_mode='full') { /* * Remove previously built content, if exists */ $entity->content = array(); $title = filter_xss($entity->title); /* * Build the fields content */

60

field_attach_prepare_view('entity', array($entity->aid => $entity), $view_mode); entity_prepare_view('entity', array($entity->aid => $entity)); $entity->content += field_attach_view('entity', $entity, $view_mode); /* * Specify the theme to use and set the #element. Note that the key * you use to pass the entity object must match the key you set in the * variables in entity_theme(). So in the case below, we use the key * named #element because in entity_theme() we set the following code: * * array( * 'entity' => array( * 'variables' => array('element' => null), * 'template' => 'entity' * ), * ); */ $entity->content += array( '#theme' => 'entity', '#element' => $entity, '#view_mode' => 'full', '#language' => NULL, ); return $entity->content; } ?>

MODULE_theme() Hook So far we have defined the menu item path and callback for our entity. The only two pieces remaining are to create an entry in the Theme Registry which points to our template, then to create the template file. The function below implements the MODULE_theme() hook to create this module's Theme Registry entries. The array that is returned has as its keys, the name of the Theme Registry entry, which must match the value specified in: content += array( '#theme' => 'entity' ); ?> array( 'variables' => array('element' => null), 'template' => 'entity' ), ); } ?>

61

So the #theme key in $entity->content points to the Theme Registry entry. The template key in the Theme Registry entry points to the name of the actual template file. The value of this key should be set to the {name}.tpl.php portion of the template file. It is simply the name of the file minus the .tpl.php extension. After adding the code above, be sure to empty all caches and rebuild the Theme Registry. I use Devel to do this very easily from a sidebar link.

The Template File Now all that remains is creating the template file. Just create a new file in /sites/all/themes/your_theme/{entity_type}.tpl.php. When someone requests http://yoursite.com/entity/$id, Drupal will use your template to render the output. The code below is some sample code from the entity theme but it can be whatever you want it to be. content; $aid = isset($element->aid) ? $aid = $element->aid : "" ; ?>

/edit">Edit

62

Theming forms in your theme An example about how to theme Drupal Commerce Check Out form:

template.php 'form', 'path' => drupal_get_path('theme', 'yourtheme') . '/templates/forms', ); return array( 'commerce_checkout_form_checkout' => $base + array( 'template' => 'commerce-checkout-form-checkout', ), ); } /** * Preprocessor for commerce_checkout_form_checkout theme. */ function yourtheme_preprocess_commerce_checkout_form_checkout(&$variables) { /* Add or modify your variables */ } ?>

[yourtheme]/templates/forms/commerce-checkout-form-checkout.tpl.php

Don't forget clearing the theme registry cache.

63

Targeting different devices This section provides information on targeting different devices with your theme.

Adding browser-specific style sheets You can add a browser-specific style sheet.

Drupal 6 Below is a Drupal 6 theme example for including IE6< targeted CSS files. (Examples are taken from the Garland theme found in the Drupal core installation.) page.tpl.php: ... ?> template.php: '; if ($language->direction == LANGUAGE_RTL) { $iecss .= ''; } return $iecss; } ... ?>

Drupal 7 Drupal 7 adds the ability to specify a 'browsers' key when calling drupal_add_css(). template.php:

64

CSS_THEME, 'browsers' => array('IE' => 'lt IE 7', '!IE' => FALSE), 'preprocess' => FALSE)); } ... ?>

See the API documentation for drupal_pre_render_conditional_comments() for details on the 'IE' and '!IE' keys. It is recommended for themes to always use drupal_add_css() for adding a CSS file, so that Drupal code knows the exact total number of CSS files being added. This is information that might be needed for working around Internet Explorer's limitation of only being able to load the first 31 LINK/STYLE tags.

65

JavaScript and jQuery Using JavaScript adds dynamic presentation effects to a theme. In addition to custom Javascript files many Drupal developers find jQuery useful. jQuery is a lightweight JavaScript library which is built into Drupal. jQuery contains all the common DOM, event, effects, and Ajax functions. Drupal 7 includes jQuery 1.4.4 and jQuery UI 1.8.7. Drupal 6.0 to 6.2 included jQuery 1.2.3 while Drupal 6.3 includes an update to jQuery 1.2.6. For use in module development which requires a later version of jQuery, apply the jQuery update module. When JavaScript is added to a page through Drupal, jQuery is automatically added to the page. For more information jQuery visit the jQuery API and Documentation site.

Adding JavaScript There are two ways for Themes to easily add JavaScript to a page.

In .info File In the .info file for a theme scripts can be added using the script tag. For example, to add the script foo.js to every page on a Drupal site add the following to the themes .info file. scripts[] = foo.js

Scripts added in a themes .info file are added at the theme level of ordering and will come after core/library JavaScript and module JavaScript. This ordering is important because it allows the theme JavaScript an opportunity to act on the page after the JavaScript providing the functionality within the page. In Drupal 6 there is a default script file, named script.js that can be added to a theme without specifying it in the .info file. If that script is included in the theme it will be automatically added to all pages. In Drupal 7 all script files need to be specified.

In template.php Alternately scripts can be added in the template.php file using drupal_add_js() or, in Drupal 7, drupal_add_library(). For example, adding a script in the root directory of a theme named foo.js would like like: In Drupal 6:

66

In Drupal 7: JS_THEME, ); drupal_add_js(drupal_get_path('theme', 'example'). '/foo.js', $options); } ?>

Note, in Drupal 7 the $scripts variable does not need to be rebuilt. $scripts is built in template_process_html which happens after this function. Drupal 7 includes library management. Libraries are collections of JavaScript, CSS, and dependent libraries. For example, Drupal 7 includes jQuery UI. jQuery UI is a component library with internal dependencies. When ui.autocomplete is included it needs ui.core and ui.position to be included as well. Drupal libraries takes care of this for us. Adding ui.autocomplete with all of it's CSS, JS, and dependencies can be accomplished with the following code:

This one command includes jquery.ui.autocomplete.js, jquery.ui.autocomplete.css, and the dependencies of jquery.ui.position.js, jquery.ui.widget.js, jquery.ui.core.js, jquery.ui.core.css, and jquery.ui.theme.css. For more information on drupal_add_library see the API documentation.

JavaScript closures It's best practice to wrap your code in a closure. A closure is nothing more than a function that helps limit the scope of variables so you don't accidentally overwrite global variables. // Define a new function. (function () { // Variables defined in here will not affect the global scope. var window = "Whoops, at least I only broke my code."; console.log(window); // The extra set of parenthesis here says run the function we just defined. }()); // Our wacky code inside the closure doesn't affect everyone else. console.log(window);

A closure can have one other benefit, if we pass jQuery in as a parameter we can map it to the $ shortcut allowing us to use use $() without worrying if jQuery.noConflict() has been called. // We define a function that takes one parameter named $. (function ($) { // Use jQuery with the shortcut: console.log($.browser); // Here we immediately call the function with jQuery as the parameter. }(jQuery));

67

In Drupal 7 jQuery.noConflict() is called to make it easier to use other JS libraries, so you'll either have to type out jQuery() or have the closure rename it for you.

JavaScript behaviors Drupal uses a "behaviors" system to provide a single mechanism for attaching JavaScript functionality to elements on a page. The benefit of having a single place for the behaviors is that they can be applied consistently when the page is first loaded and then when new content is added during AHAH/AJAX requests. In Drupal 7 behaviors have two functions, one called when content is added to the page and the other called when it is removed. Behaviors are registered by setting them as properties of Drupal.behaviors. Drupal will call each and pass in a DOM element as the first parameter (in Drupal 7 a settings object will be passed as the second parameter). For the sake of efficiency the behavior function should do two things: 

Limit the scope of searches to the context element and its children. This is done by passing context parameter along to jQuery: jQuery('.foo', context);



Avoid processing the same element multiple times. In Drupal 6 assign a marker class to the element and use that class to restrict selectors: jQuery('.foo:not(.foo-processed)', context).addClass('fooprocessed').css('color', 'red');

In Drupal 7 use the jQuery Once plugin that's bundled with core: jQuery('.foo', context).once('foo').css('color', 'red');

As a simple example lets look at how you'd go about finding all the https links on a page and adding some additional text marking them as secure, turning Example into Example (Secure!). This should make the importance of only running the code once apparent, if our code ran twice the link would end up reading "Example (Secure!) (Secure!)". In Drupal 6 it would be done like this: // Using the closure to map jQuery to $. (function ($) { // Store our function as a property of Drupal.behaviors. Drupal.behaviors.myModuleSecureLink = function (context) { // Find all the secure links inside context that do not have our processed // class. $('a[href^="https://"]:not(.secureLink-processed)', context) // Add the class to any matched elements so we avoid them in the future. .addClass('secureLink-processed') // Then stick some text into the link denoting it as secure. .append(' (Secure!)'); }; // You could add additional behaviors here.

68

Drupal.behaviors.myModuleMagic = function(context) {}; }(jQuery));

In Drupal 7 it's a little different because behaviors can be attached when content is added to the page and detached when it is removed: // Using the closure to map jQuery to $. (function ($) { // Store our function as a property of Drupal.behaviors. Drupal.behaviors.myModuleSecureLink = { attach: function (context, settings) { // Find all the secure links inside context that do not have our processed // class. $('a[href^="https://"]', context) // Only process elements once. .once('secureLink') // Then stick some text into the link denoting it as secure. .append(' (Secure!)'); } } // You could add additional behaviors here. Drupal.behaviors.myModuleMagic = { attach: function (context, settings) { }, detach: function (context, settings) { } }; }(jQuery));

JavaScript theming Drupal provides a theming mechanism for JavaScript code in a similar manner to the way theming works within the rest of Drupal. This enables themes to customize the markup generated by JavaScript. Modules provide theme functions for their markup. For example, the following code uses the theme function powered (This displays a "powered by Drupal" icon): Drupal.theme.prototype.powered = function(color, height, width) { return '"; }

When a module wants to insert the markup it would do so in a matter like: $('.footer').append(Drupal.theme('powered', 'black', 135, 42));

This will place an image in any elements with the class footer with the following markup:

When a theme wants to provide a different markup it can do so by providing an alternate theme function. Following our example the following function provides an a theme function for the theme.

69

Drupal.theme.powered = function(color, height, width) { return ''; }

While the modules theme function is at Drupal.theme.prototype.powered the themes is at Drupal.theme.powered. Including this function in the themes JavaScript will will cause the markup generated by the snippet: $('.footer').append(Drupal.theme('powered', 'black', 135, 42));

to be

JavaScript theme functions are entirely free in their return value. They can vary from simple strings to complex data types like objects, arrays, and jQuery elements. Refer to the original (default) theme function to see what your custom theme function should return. For more information on using JavaScript and jQuery in Drupal, see the JavaScript section of the developer guide. Also, join the Javascript group on Groups.Drupal.org to get advice on Javascript and jQuery: http://groups.drupal.org/javascript

70

Using Newer Versions of jQuery with Drupal 6 There are a lot of forum posts and issue queues revolving around the need to use a newer version of jQuery on a Drupal 6.x site. There are several ways to achieve this, such as using the jQuery Update module, but I'm going to focus on the recommended method of running 2 versions of jQuery side-by-side - the jQuery noConflict() function. The Problem Your custom theme, dropdown menu, slideshow, or other jQuery dependant scripts require jQuery 1.4, jQuery UI 1.8, or some other jQuery version or component. Drupal 6 ships with jQuery 1.2.6. You could just replace the jquery.js file in example.com/misc with a newer version, but you'd run into some issues, such as:   

Useful UI features like draggable tables and ajax search will stop working Contributed modules that use jQuery assume you are using 1.2.6 After updating Drupal to a newer version, your custom jquery.js file would be overwritten with 1.2.6

The Solution jQuery already has the functionality to run along side a different version of jQuery (or, really, along side any other JavaScript library that uses the $ symbol as a function or variable). This is the noConflict() function. You can view the API page here: http://api.jquery.com/jQuery.noConflict/ To use this functionality within your project, simply tell the browser about your new jQuery library and that you'll be referencing it via your custom noConflict identifier: <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"> <script type="text/javascript"> var $jq = jQuery.noConflict();

Example: my-theme/page.tpl.php <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"> <script type="text/javascript"> var $jq = jQuery.noConflict();

With this method jQuery 1.2.6 is loading with every page, and can be used by Views, Draggable.js, any contributed Ajax calls, etc. Also, jQuery 1.4.4 (as in this example) is also

71

loading and the 2 are not interfering with each other. Another point worth adding is that 1.4.4 is being loaded from the Google CDN - one less file for your audience to download from your server.

Using noConflict in your scripts To execute scripts with the new version of jQuery you simply need to use $jq instead of $ in your scripts, for example: $jq(document).ready(function(){ $jq('#my-div').function(); });

Using noConflict in contributed scripts You can easily modify an external script to use your custom noConflict identifier. For example, the Qtip library depends on jQuery 1.5. You could include it via the above methods and then alter jquery.qtip.js, replacing the first line (function($, window, undefined) {

with (function($jq, window, undefined) {

72

Core templates and suggestions Core comes with a number of default template files. In order to override these templates, all you need to do is copy them into your theme folder and clear the theme registry. You can also override these templates in a more targeted way. This section lists the default templates in Drupal core and explains how to create more targeted template files. In Drupal 6, some template files could be overridden in a targeted way. For example, the theme could contain a "node-article.tpl.php" file which would be used for nodes of the article type only. In Drupal 7, these need to be renamed to use a double-hyphen. For example, "node-article.tpl.php". A single hyphen is still used to separate words: for example, "userpicture.tpl.php" or "node--long-content-type-name.tpl.php", so the double hyphen always indicates a more targeted override of what comes before the "--". See Converting 6.x themes to 7.x for more info.

73

Core templates Default templates: These are the default template (.tpl.php) files provided by core in Drupal 7. Documentation on the variables and purpose of these templates are located inside the templates. There is a default set of variables available to all templates. In order to override these templates, all you need to do is copy them into your theme folder and clear the theme registry. To override templates in a more targeted way, see Drupal 7 Template Suggestions or Drupal 6 Template Suggestions. Aggregator "modules/aggregator/..."     

aggregator-feed-source.tpl.php aggregator-item.tpl.php aggregator-summary-item.tpl.php aggregator-summary-items.tpl.php aggregator-wrapper.tpl.php

Block "modules/block/..."  

block-admin-display-form.tpl.php block.tpl.php

Note: the Drupal 6 version of block.tpl.php used to be part of "modules/system/...". Book "modules/book/..."    

book-all-books-block.tpl.php book-export-html.tpl.php book-navigation.tpl.php book-node-export-html.tpl.php

Comment "modules/comment/..."  

comment-wrapper.tpl.php comment.tpl.php

Note: comment-folded.tpl.php has been deprecated in Drupal 7. Field "modules/field/theme/..."

74



field.tpl.php

Note: field.tpl.php is a new template in Drupal 7. Forum "modules/forum/..."     

forum-icon.tpl.php forum-list.tpl.php forum-submitted.tpl.php forum-topic-list.tpl.php forums.tpl.php

Note: forum-topic-navigation.tpl.php has been deprecated in Drupal 7. Node "modules/node/..." 

node.tpl.php

Overlay "modules/overlay/..." 

overlay.tpl.php

Note: overlay.tpl.php is a new template in Drupal 7. Poll "modules/poll/..."     

poll-bar--block.tpl.php poll-bar.tpl.php poll-results--block.tpl.php poll-results.tpl.php poll-vote.tpl.php

Note: Former templates poll-results-block.tpl.php and poll-bar-block.tpl.php have been renamed with a double dash in Drupal 7. Profile "modules/profile/..."   

profile-block.tpl.php profile-listing.tpl.php profile-wrapper.tpl.php

Search "modules/search/..." 

search-block-form.tpl.php

75

 

search-result.tpl.php search-results.tpl.php

Note: search-theme-form.tpl.php has been deprecated in Drupal 7. System "modules/system/..."    

page.tpl.php maintenance-page.tpl.php region.tpl.php html.tpl.php

Note: box.tpl.php has been deprecated in Drupal 7. html.tpl.php and region.tpl.php have been added. Taxonomy "modules/taxonomy/..." 

taxonomy-term.tpl.php

Note: taxonomy-term.tpl.php is a new template in Drupal 7. Toolbar "modules/toolbar/..." 

toolbar.tpl.php

Note: toolbar.tpl.php is a new template in Drupal 7. User "modules/user/..."    

user-picture.tpl.php user-profile-category.tpl.php user-profile-item.tpl.php user-profile.tpl.php

76

Drupal 7 Template Suggestions Template suggestions: What's a template suggestion? It's an alternate template (.tpl.php) file that you have created to override the base or original template file. Suggestions only work when they are placed in the same directory as the base templates.

Custom Template Suggestions Custom suggestions beyond the ones listed below can be created. See the page Working with template suggestions.

Default Template Suggestions in Core block--[region|[module|--delta]].tpl.php base template: block.tpl.php Template suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds: 1. block--module--delta.tpl.php 2. block--module.tpl.php 3. block--region.tpl.php "module" being the name of the module and "delta", the internal id assigned to the block by the module. For example, "block--block--1.tpl.php" would be used for the first user-submitted block added from the block administration screen since it was created by the block module with the id of 1. "region" will take effect for specific regions. An example of a region-specific template would be block-sidebar_first.tpl.php. If you had a block created by a custom module called "custom" and a delta of "my-block", the template suggestion would be called "block--custom-my-block.tpl.php." comment--[node-type].tpl.php base template: comment.tpl.php Support was added to create comment--type.tpl.php files, to format comments of a certain node type differently than other comments in the site. For example, a comment made on an article-type node would be "comment--node-article.tpl.php". comment-wrapper--[node-type].tpl.php base template: comment-wrapper.tpl.php Similar to the above but for the wrapper template. field--[type|name[--content-type]|content-type].tpl.php base template: field.tpl.php

77

Template suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds: 1. 2. 3. 4.

field--field-name--content-type.tpl.php field--content-type.tpl.php field--field-name.tpl.php field--field-type.tpl.php

Remember to include "field-" in custom field names, e.g: field--field-phone.tpl.php forums--[[container|topic]--forumID].tpl.php base template: forums.tpl.php Template suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds: For forum containers: 1. forums--containers--forumID.tpl.php 2. forums--forumID.tpl.php 3. forums--containers.tpl.php For forum topics: 1. forums--topics--forumID.tpl.php 2. forums--forumID.tpl.php 3. forums--topics.tpl.php maintenance-page--[offline].tpl.php base template: maintenance-page.tpl.php This applies when the database fails. Useful for presenting a friendlier page without error messages. Theming the maintenance page must be properly setup first. node--[type|nodeid].tpl.php base template: node.tpl.php Template suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds: 1. node--nodeid.tpl.php 2. node--type.tpl.php 3. node.tpl.php See node.tpl.php in the Drupal API documentation for more information. page--[front|internal/path].tpl.php base template: page.tpl.php

78

The suggestions are numerous. The one that takes precedence is for the front page. The rest are based on the internal path of the current page. Do not confuse the internal path to path aliases which are not accounted for. Keep in mind that the commonly used Path auto module works its magic through path aliases. The front page can be set at "Administration > Configuration > System > Site information." In Drupal 6, at "Administrator > Site configuration > Site information." Anything set there will trigger the suggestion of "page--front.tpl.php" for it. The list of suggested template files is in order of specificity based on internal paths. One suggestion is made for every element of the current path, though numeric elements are not carried to subsequent suggestions. For example, "http://www.example.com/node/1/edit" would result in the following suggestions: 1. 2. 3. 4.

page--node--edit.tpl.php page--node--1.tpl.php page--node.tpl.php page.tpl.php

Also see page.tpl.php in the Drupal API documentation for more information.

How Drupal determines page template suggestions based on path Here is another explanation based on the theme_get_suggestions() function: The list of possible templates for a given page is generated by Drupal through the theme_get_suggestions() function, which is called by the template_preprocess_page() function. The Drupal path of the page is first broken up into its components. As mentioned above, the Drupal path is not any of its aliases: there is one and only one Drupal path for a page. For the examples "http://www.example.com/node/1/edit" and "http://www.example.com/mysitename?q=node/1/edit", the Drupal path is node/1/edit, and its components are "node", 1, and "edit". Next, the prefix is set to "page". Then, for every component, the following logic is followed: 1. If the component is a number, add the prefix plus "__%" to the list of suggestions. 2. Regardless of whether the component is a number or not, add the prefix plus "__" plus the component to the list of suggestions. 3. If the component is not a number, append "__" plus the component to the prefix. After the list of components is iterated through, if the page is the front page (as set through "Administration > Configuration > System > Site information."), then "page__front" is added to the list of suggestions.

79

Note that eventually, to turn a suggestion into an actual file name, "__" gets turned into "--", and ".tpl.php" gets appended to the suggestion. Thus, for node/1/edit, we get the following list of suggestions: 1. 2. 3. 4.

page.tpl.php (this is always a suggestion) page--node.tpl.php (and prefix is set to page__node) page--node--%.tpl.php page--node--1.tpl.php (prefix is not changed because the component is a number) 5. page--node--edit.tpl.php (and prefix is set to page__node__edit) 6. page--front.tpl.php (but only if node/1/edit is the front page) When the page is actually rendered, the last suggestion is checked. If it exists, that suggestion is used. Otherwise the next suggestion up is checked, and so on. Of course, if none of the overriding suggestions exist, page.tpl.php is the final suggestion. This also explains why page--front.tpl.php, if it exists, overrides any other suggestion for the front page: it is always the last suggestion for the page designated as the front page. poll-results--[block].tpl.php base template: poll-results.tpl.php The theme function that generates poll results are shared for nodes and blocks. The default is to use it for nodes but a suggestion is made for rendering them inside block regions. This suggestion is used by default and the template file is located at "modules/poll/poll-results--block.tpl.php". poll-vote--[block].tpl.php base template: poll-vote.tpl.php Similar to poll-results--[block].tpl.php but for generating the voting form. You must provide your own template for it to take effect. poll-bar--[block].tpl.php base template: poll-bar.tpl.php Same as poll-vote--[block].tpl.php but for generating individual bars. profile-wrapper--[field].tpl.php base template: profile-wrapper.tpl.php The profile wrapper template is used when browsing the member listings page. When browsing specific fields, a suggestion is made with the field name. For example, http://drupal.org/profile/country/Belgium would suggest "profile-wrapper-country.tpl.php". region--[region].tpl.php base template: region.tpl.php

80

The region template is used when a page region has content, either from the Block system or a function like hook_page_build(). Possible region names are determined by the theme's .info file. search-results--[searchType].tpl.php base template: search-results.tpl.php search-results.tpl.php is the default wrapper for search results. Depending on type of search different suggestions are made. For example, "example.com/search/node/Search+Term" would result in "search-results-node.tpl.php" being used. Compare that with "example.com/search/user/bob" resulting in "search-results--user.tpl.php". Modules can extend search types adding more suggestions of their type. search-result--[searchType].tpl.php base template: search-result.tpl.php The same as above but for individual search results.

Cache issue When working with template suggestion, there is a possibility that Drupal use its cache rather than the new templates as suggested. Remove the cache if you experience this problem. To clear the cache, choose one of the methods described in Clearing Drupal's cache.

81

Drupal 6 Template Suggestions Template suggestions: What's a template suggestion? It's an alternate template (.tpl.php) file that you have created to override the base or original template file. Suggestions only work when they are placed in the same directory as the base templates. In other words, if you want comment-blog.tpl.php to display in your browser, comment.tpl.php also needs to exist inside your theme and the two files must be in the same directory. Custom suggestions beyond the ones listed below can be created. See the page Working with template suggestions. Note: There is a bug which prevents derivative template files from being detected if the base template file is not also present. See #279573: Themes can't use nodestory.tpl.php without node.tpl.php for more information. block-[region|[module|-delta]].tpl.php base template: block.tpl.php Suggestions made based on these factors in this order: 1. block-module-delta.tpl.php 2. block-module.tpl.php 3. block-region.tpl.php "module" being the name of the module and "delta", the internal id assigned to the block by the module. For example, "block-user-1.tpl.php" would be used for the default user navigation block since it was created by the user module with the id of 1. "region" will take effect for specific regions. comment-[type].tpl.php base template: comment.tpl.php Support was added to create comment-type.tpl.php files, to format comments of a certain node type differently than other comments in the site. Similar to node[type].tpl.php but for comments. comment-wrapper-[type].tpl.php base template: comment-wrapper.tpl.php Similar to the above but for the wrapper template. forums-[[container|topic]-forumID].tpl.php base template: forums.tpl.php Template suggestions added based on these factors, in this order. For forum containers:

82

1. forums-containers-forumID.tpl.php 2. forums-forumID.tpl.php 3. forums-containers.tpl.php For forum topics: 1. forums-topics-forumID.tpl.php 2. forums-forumID.tpl.php 3. forums-topics.tpl.php maintenance-page-[offline].tpl.php base template: maintenance-page.tpl.php This applies when the database fails. Useful for presenting a friendlier page without error messages. Theming the maintenance page must be properly setup first. node-[type].tpl.php base template: node.tpl.php In Drupal 7, templates for specific content types are created slightly different than in Drupal 6.  

Drupal 6: node-mytype.tpl.php Drupal 7: node--mytype.tpl.php

See node.tpl.php in the Drupal API documentation for more information. Note that in order to override the template for a specific node type, the theme must also implement the base node.tpl.php file. If this file is omitted, the theme will not detect the presence of node-[type].tpl.php files. page-[front|internal/path].tpl.php base template: page.tpl.php The suggestions are numerous. The one that takes precedence is for the front page. The rest are based on the internal path of the current page. Do not confuse the internal path to path aliases which are not accounted for. Keep in mind that the commonly used Path auto module works its magic through path aliases. The front page can be set at "Administration > Configuration > System > Site information." In Drupal 6, at "Administrator > Site configuration > Site information." Anything set there will trigger the suggestion of "page-front.tpl.php" for it. The list of suggested template files is in order of specificity based on internal paths. One suggestion is made for every element of the current path, though numeric elements are not carried to subsequent suggestions. For example, "http://www.example.com/node/1/edit" would result in the following suggestions: 1. page-node-edit.tpl.php 2. page-node-1.tpl.php

83

3. page-node.tpl.php 4. page.tpl.php poll-results-[block].tpl.php base template: poll-results.tpl.php The theme function that generates poll results are shared for nodes and blocks. The default is to use it for nodes but a suggestion is made for rendering them inside block regions. This suggestion is used by default and the template file is located at "modules/poll/poll-results-block.tpl.php". poll-vote-[block].tpl.php base template: poll-vote.tpl.php Similar to poll-results-[block].tpl.php but for generating the voting form. You must provide your own template for it to take effect. poll-bar-[block].tpl.php base template: poll-bar.tpl.php Same as poll-vote-[block].tpl.php but for generating individual bars. profile-wrapper-[field].tpl.php base template: profile-wrapper.tpl.php The profile wrapper template is used when browsing the member listings page. When browsing specific fields, a suggestion is made with the field name. For example, http://drupal.org/profile/country/Belgium would "suggest profile-wrappercountry.tpl.php". search-results-[searchType].tpl.php base template: search-results.tpl.php search-results.tpl.php is the default wrapper for search results. Depending on type of search different suggestions are made. For example, "example.com/search/node/Search+Term" would result in "search-resultsnode.tpl.php" being used. Compare that with "example.com/search/user/bob" resulting in "search-results-user.tpl.php". Modules can extend search types adding more suggestions of their type. search-result-[searchType].tpl.php base template: search-result.tpl.php The same as above but for individual search results.

84

Overriding themable output Depending on how your site is configured, the HTML code that makes up each page in your site is compiled from the output of various Drupal modules.

About modifying HTML markup If the default HTML markup supplied by any module does not suit the requirements of your theme, you can override some or all of it, so that the resulting page is exactly what you need for your design. For example, you might decide that for your site, the default search box should have an image of a magnifying glass and that the label on the search button should read "Discover great stuff!" rather than the default label of "Search". You can completely override the default markup, so that the markup calls for your image file and that the button is labeled the way you want.

Don't hack core It's very important to understand the concept of "overriding". While it is technically possible to just find the module responsible for the search field and edit the code directly, this is definitely NOT recommended. In the short term, it will seem to solve your problem, but it will soon make it difficult to keep your site up to date. Whenever you update the module, perhaps for a general security release, you would need to remember to redo any of your customizations.

How to change HTML the Drupal way The "Drupal Way" is to do an override. This involves four basic steps: 1. Locate the module responsible for the markup 2. Do one of the following:  

If the module provides a template (tpl.php file), copy the template to your theme directory. See Core Templates and Suggestions for a list of core templates. OR... In the module code, identify the theme or preprocess function that is generating the markup you want to change and copy the function to your theme's template.php file. You will need to change the "theme_" or "template_" prefix to match the name of your theme. For example, "theme_breadcrumb" would become "mythemename_breadcrumb"; "template_preprocess_page" would become "mythemename_preprocess_page".

 Within the copied function or template, change the HTML code to suit your needs.  Refresh the theme cache. These steps are explained in greater detail in the following pages.

85

Using PHP for theming If you are not already familiar with PHP, the process might seem somewhat intimidating, but it generally does not require that you understand anything about actually writing PHP. As long as you know what HTML you want to be displayed, it's simply a matter of modifying that part of the code. As with any theming work, you should not make changes to a live or production site until you have thoroughly tested the changes on a development site.

Overriding CSS Many modules also provide style sheets (.css files) which specify the default look and feel of the markup. These style sheets can also be overridden. For more information, see Overriding style sheets from modules and base themes.

Popular Contributed Modules that override the default HTML output Some contributed modules have their own theming guides. Also see overriding style sheets from modules and base themes. Modules for which theming-specific documentation exists are listed below by Drupal version.

Drupal 7–compatible modules     

Panels Date and Calendar Views 3 Slideshow Print Menu Block

Drupal 6-compatible modules          

CCK Views 2 Views 2 Slideshow Panels Flag Print Nice Menus Menu Block Simplenews Browser Theme Settings

     

Beginners guide to overriding themable output Introduction to PHP for theming About overriding themable output Setting up variables for use in a template (preprocess and process functions) Default baseline variables Customizing and Overriding User Login page, Register, and Password Reset in Drupal 6

86

     

Example: Themable output Identifying Core Components Menu theming The theme registry for special cases Working with template suggestions Architectural view of theming

87

Beginners guide to overriding themable output Drupal theming is based on the concept of overriding the output from Drupal core and modules. Instead of having to modify the module to change the output (which you don't want to do, because it will make upgrades difficult later), you can modify it by adding functions or files to your theme. The functions or files will take precedence over the module's choice for how to produce the HTML. Overriding is done one of two ways: overriding theme functions, or overriding theme files, depending on how the output from Drupal is being created.

Avoiding having to override at all Before you decide that you need to modify the output coming from Drupal or one of the modules on your site, check the following possibilities -- you may be able to avoid the whole process: 



Can you just change a setting? For instance, you can click on a "Configure" link for any block, and it will allow you to change the text of the block title, or even remove the title completely (you can also move any block to a different region of the page on the blocks configuration screen). Other modules will let you change aspects of their output through settings too (labels for text fields, order of output, etc.). To find settings pages, click on Administer, and then By module, and check out all the settings pages offered by your module. Some settings are also on your theme's configuration page, and some are in various tabs of your content types' settings pages (under Content management >> Content types). Can you accomplish your goal through CSS? Nearly all output in Drupal is enclosed in DIV elements with specific classes or IDs, so you can easily customize a particular piece of output. CSS will let you change fonts, sizes, placement, background images, etc. To override the CSS provided by Drupal or a module, just add to one of your theme's CSS files.

If neither of these options lets you change what you want to customize, then you do actually need to customize the HTML output of Drupal or one of your modules -- read on.

Overriding theme functions A theme function is a PHP function in Drupal whose name begins with 'theme_', such as 'theme_username'. To override a theme function: 1. Open your theme's template.php file in a plain text editor. 2. Copy the theme or template function you found into your template.php file. (One way of finding the function is searching for the function name at http://api.drupal.org. There is also a Function reference in the menu provided by the Devel module.) 3. Rename the function you copied in (see note below). If your theme's base prefix is "wonderful", and the theme function you are trying to override is called "theme_xyz", then you need to rename the function "wonderful_xyz". If you are overriding 88

"template_preprocess_xyz", then the new name should be "wonderful_preprocess_xyz". To change a function name, e.g. from "theme_xyz" to "wonderful_xyz", find a line that looks something like this: function theme_xyz( $a, $b, $c) {

and change it to: function wonderful_xyz( $a, $b, $c) {

Make sure you leave the part inside the parentheses unchanged! 4. Modify the function so that it does what you want it to do. 5. Upload the template.php file to your web site, in your theme directory. 6. Refresh the theme cache (see http://drupal.org/node/173880#theme-registry).

Overriding a theme file If the HTML output you want to override is in a theme file, here are the steps to follow to override it: 1. Copy the theme file to your theme directory, if your theme directory does not already have a file by that name. 2. If you are implementing a suggestion, rename the file to the suggestion name it should have. Note that some suggestion files will not be recognized unless their base file is also present -- for instance, if you want to make a node content type suggestion file for your content type, you need to have node.tpl.php present in your theme directory order for your node-my_content_type.tpl.php file to be recognized. However, suggestions for Views do not require that the base Views template file be present in your template directory. 3. Modify the file so it does what you want it to do. 4. Upload the file to your web site, including the new base theme file if necessary, into your theme's directory. 5. Refresh the theme cache (see http://drupal.org/node/173880#theme-registry)

Finding where the themable output is coming from The first step in overriding Drupal's HTML output is to figure out where the HTML output you want to modify is coming from. What you are looking for is either a theme function (a PHP function called "theme_xyz", such as "theme_search" or "theme_aggregator_block_item"), a template preprocess function (a PHP function called "template_preprocess_xyz"), or a theme file (a PHP file whose name ends in .tpl.php, such as "views-more.tpl.php"). To find the right file or function, start by finding the module directory for the module that is producing the output (under "modules", "sites/all/modules", or "sites/your_sub_dir/modules").

89

Theme files will generally be in either the top-level module directory, a sub-module directory underneath, or a directory called "theme" underneath. Theme and template preprocess functions will generally be in either a module file (ending in .module) or an include file (usually ending in .inc); the file will be located in the module directory or a sub-directory. A good way to find the right function or file is to search for a specific CSS ID or class on the HTML element you are trying to modify, or some other unique text that the module is producing. Another method of finding the appropriate override function is using the Theme developer module, which is an add-on to the popular Devel project. When enabled, Theme Developer allows the site builder to hover over the elements of the page and click the ones where more theme information is required. Some modules also will honor theme file suggestions. For instance, in Views 2, you can get theme information when you are editing a View -- it tells you which theme files will be used to produce the view, and the first one in each list is a theme file that is located in the "themes" sub-directory of your views module; this is the theme file you will want to override. The other names in the list are possibilities for what you will want to name the file when you put it into your theme, depending on how specific you want your override to be (e.g., do you want to override how all views are displayed, or just your specific view?). You can also use suggestions to override core Drupal module theming. For instance, if you want to override how a particular node content type is displayed, you can use the node.tpl.php file from your theme (or Drupal core) as the overrideable file, and rename the copy nodecontent_type_name.tpl.php. There is more information about the core module files and suggestion file names you can use on the Core templates and suggestions page. Once you have found the right function or file to override, follow the directions in one of the next two sections to override it. However, if you find what is producing the HTML output you want to override, and it is not inside a theme function, template preprocess function, or theme file, then you will probably not be able to modify the output with theme functions alone. You may need to check the support forums or contact the module developer to find out how to modify the output.

90

Introduction to PHP for theming Teaching PHP is beyond the scope of the Drupal documentation, but this page will introduce you to some of the most basic techniques which are important to working with themes.

Discovering your data Use the Theme Developer module The easiest way to see the variables that a template file has to work with is to use the Theme Developer module. Not only will this give you access to a live, interactive display of the variables that were used to create any part of a page, but it also includes numerous functions for outputting debugging data while you are working.

Do it the hard way If for some reason you can't (or won't) use the Theme Developer module, it is possible to use a PHP function to see all of the variables that have been passed to your template file. To do so, you can add the following code to the top of any template (.tpl.php) file in your theme.

Both of the techniques described above use a lot of resources and can expose internal information to the public. Therefore, you should never use either technique on a production site.

Using the information you get Once you have used one of the techniques above, you will be able to see numerous variables and arrays(). If you wish, you can refer directly to any of these in your template. For example, to display the title, you would add the following code to your .tpl.php file:

To display the node title along with a link to the node and some heading formatting, add the following code:

" title="">

Arrays The output from the print_r technique shown above will probably contain a number of arrays. For example, if you are using a taxonomy you might see something like this:

91

[taxonomy] => Array

An array allows a group of related data to be stored in an organized way. If you only want one item from an array to be displayed you can specify that item using its related "key". For example, suppose the print_r technique showed you the following array: [location] => Array ( [lid] => 3 [name] => My Place [street] => 235 King Edward Avenue [additional] => [city] => Ottawa [province] => ON [postal_code] => K1N 7L8 [country] => ca [latitude] => 45.431993 [longitude] => -75.688390 [source] => 3 [is_primary] => 0 [province_name] => Ontario [country_name] => Canada )

If you just wanted to display the city, you could add the following code to your .tpl.php file:

There are many other ways to manipulate your content using PHP. For more information, consult one of the PHP references on the web.

92

About overriding themable output The following only applies when the default markup needs changes. This section can be skipped if the presentation is handled only through style sheets. There are three aspects to overriding the themed output. The first is knowing where the source originates, the second is providing the override, and third is understanding its type. Note that Drupal maintains cached theming data through the theme registry. It must be cleared when setting up overrides. 1. Finding the source: Finding the source can be difficult to track down due to the hierarchy of theming calls whose source can be spread throughout the whole system.

Links to 520KB PDF. Provided for illustration only. Most of the page elements are typically pulled with theme('page') and placed inside the page.tpl.php template after rendering navigation bits, the bits within the navigation bits, block regions, the blocks within the block regions, etc. Each chunk of themed data is often referred to as a theming "hook".

93

Note: Theming functions and templates will now be referred to as theming hooks. There are many hooks unrelated to theming throughout the system. Any mention of it here only relates to theming. Getting to the source of any specific chunk of markup can now be tracked with the theme developer module. It includes a theming tool to easily visualize the source of any output, its type and tons of other theming data. See the screencast for a demonstration. This is not available for Drupal versions less than 6 due to technical limitations. 2. System of overrides: The system of overrides has a specific cascading order with few exceptions. Drupal core and modules provide a reasonable default for its markup handled by the theming hook. If it does not suit the requirements of the theme, then an alternate can be provided preventing the defaults from being used. This way, the defaults are left alone and all the theme specific changes are localized to the theme. You should never change code outside your theme to alter default output. (Here are some reasons why you should not "hack core.")

94

If you need more control beyond this convention of overrides, the theme registry can be manipulated for more control. Note: Although it is still possible, PHPTemplate.engine in Drupal 6 no longer overrides theme functions. In 5, that is what allowed templates to be used for a handful of the theming hooks. It is no longer necessary. 3. Functions vs. templates: There are two ways of implementing a theming hook, either a function or a template. The type that is used should depend on what you're trying to achieve. Drupal core and modules can use either type to construct the output, and themes can use the same type or change it.

Links to PDF. Flow map for 5 also available for comparison. Functions are marginally faster than templates, but they can be difficult for designers who may be only familiar with XHTML. The speed depends on the nature of the hook multiplied by the number of times it is called on a page. For example, using templates for the theming hook "links" could cause a noticeable performance hit for complex and busy sites due to its repeated use. Here are two examples on overriding with the help of devel themer. Overriding functions:

95

The theme function theme_menu_local_tasks is a simple function for outputting both primary and secondary tabs. The theming hook in this case is "menu_local_tasks". To override, the "theme" prefix in the function name needs to be changed to the name of your theme. (In Drupal 6 you could also use the name of the theme engine the theme is running under, but this was not a recommended practice. That option has been removed in Drupal 7.)

The example is from Drupal 6 and shows Garland is using the name of the theme engine for the override. Again, in Drupal 6 it si recommended to use the theme name and in Drupal 7 it is mandatory to use the theme name. Placing the following inside the theme's template.php file will override the default after clearing the theme registry. Change "mytheme" in the function name to the name of your theme. \n". $primary ."\n"; } if ($secondary = menu_secondary_local_tasks()) { $output .= "

\n". $secondary ."

\n"; } return $output; } ?>

The only change here is the markup from an unordered list to an ordered list. A listing of all the theme functions can be found on api.drupal.org. Overriding templates: If the default implementation is done as a template then simply copying the source template file into the theme will automatically override it after clearing the theme registry. Here is an example for search-theme-form.tpl.php. Note that the theming hook in this case is "search_theme_form" with the template using hyphens instead of underscores.

96

That is all you need to do. Open the copied template in your editor to make your alterations. All the core .tpl.php files are documented. It should give a good indication on what can be done with the output. Note: templates can be placed in any directory within the theme. This allows for better management and less clutter in the base level of the theme directory. Related pages:  

To customize the variables inside templates, see the sub-page on Preprocess functions. A listing of all the theme templates can be found on the sub-page, Core templates and suggestions.

Converting from functions to templates Converting a theme function into a template takes some initial work but once it is done, it's easier to work with. If you are collaborating with a designer, the conversion will enable them to focus on designing, not coding. There are many templates already available in core and many more will be converted in future versions. Contributed modules that follow best practices should also have templates available. These instructions are provided for the theming hooks not already made available as templates. Getting Drupal to recognize the theming hook as a template is automated. These are the only requirements to trigger this change:   

Name of the template must match the theming hook. The underscores in the hook must be changed to hyphens. The template name must have an extension of ".tpl.php". (It can vary based on the theme engine.)

Consider the theming function theme_user_signature. The theme hook here is "user_signature". Creating a file named "user-signature.tpl.php" will tell Drupal that the hook is now a template after clearing the registry. Any content in this file will now take the place of the function. The part that takes more work is setting up the variables to be used in this file and that is done through preprocess functions.

97

A few notes: 



  

While it is possible to code directly inside the template, it is not considered good practice. All the complex logic should be separated from the .tpl.php file and placed within preprocess functions. This keeps it clean and easy to manage. There is also the issue of security. The separation can minimize the chance of cross-site scripting attacks by cleaning out potentially malicious user generated content. When handing over template files to your designer, all the output should be clean so they do not have to concern themselves with security issues. If your theme implements both a theme function and a template for a given hook, the theme function will always be used. The auto discovery of theme overrides are done by PHPTemplate engine so make sure your theme has set the engine from the .info file. Compare the theming functions in 5 to the template conversions in 6 for forums. You can use that as an example on converting between the two types.

The theme registry: Drupal's theme registry maintains cached data on the available theming hooks and how to handle them. For most theme developers, the registry does not have to be dealt with directly. Just remember to clear it when adding or removing theme functions and templates. Editing existing functions and templates does not require a registry rebuild. To clear the theme registry, do one of the following things:   

On the "Administer > Site configuration > Performance" page, click on the "Clear cached data" button. With devel block enabled (comes with devel module), click the "Empty cache" link. The API function drupal_rebuild_theme_registry (D6) or drupal_theme_rebuild (D7).

The theme registry is cached data instructing Drupal on the available theming hooks and how to handle it by indicating its type. In previous versions all theming calls were handled on the fly. Since a lot more work is being done under the hood, the cached instructions speeds up the process especially for templates. The theme engine your theme is running under should automatically register all the theming hooks for you. There are special cases where you may need to work with the registry directly. When your theme requires a new hook to be registered that was not already implemented on the layers below it (core, modules, engine). This includes some forms when they are not explicitly themed by core or modules but instead rely on the default form presentation. 

More details can be found in the sub-page, The theme registry for special cases.

98

 

Do not confuse the theme registry with the theme's .info file which is also cached. Points 1 and 2 on clearing the registry will clear both. Your theme must be using phptemplate engine for its templates and functions to be discovered. Other engines should behave the same way. For engineless themes, it must be done manually. See phptemplate_theme to see how it is done.

99

Setting up variables for use in a template (preprocess and process functions) (Since 7 they apply to templates and functions). The main role of the preprocessor is to set up variables to be placed within the template (.tpl.php) files. Plain theme functions do not interact with preprocessors. Notes:   

Preprocessors are also used for providing template suggestions. In versions 5 and below, the function _phptemplate_variables served the same purpose. It has been deprecated in 6. Prior to Drupal 6.7, for your theme to have its preprocessors recognized, the template associated with the hook had to exist inside the theme. When a default template exists, copy it to your theme and clear the registry (or you should really be upgrading to a later version of Drupal anyway for security reasons, at which point you don't have to worry about this).

There can be numerous preprocessors for each theming hook. Every layer from core, modules, engines and themes can have one, each progressively building upon the variables before being rendered through template files. This keeps the markup clean and easy to work with inside templates by placing most of the logic inside these preprocessors. Here are the expected preprocessors. They are run in this order when they exist: 1. template_preprocess - This is supplied by core and always added. The variables generated here are used for every templated hook. 2. template_preprocess_hook - The module or core file that implements the theming hook supplies this. The initial generation of all the variables specific to the hook is usually done here. 3. moduleName_preprocess - Do not confuse this with the preprocessor before it. This allows modules that did not originally implement the hook to influence the variables. Applies to all hooks. 4. moduleName_preprocess_hook - Same idea as the previous preprocessor but for specific hooks. 5. engineName_engine_preprocess - The preprocessor for theming engines. Applies to all hooks. 6. engineName_engine_preprocess_hook - Another preprocessor for theming engines but specific to a single hook. 7. engineName_preprocess - NOT RECOMMENDED. This is the first preprocessor that can be used inside the theme. It can be named after the theme engine the theme is running under. Applies to all hooks. 8. engineName_preprocess_hook - NOT RECOMMENDED. Another preprocessor named after the engine but specific to a single hook.

100

9. themeName_preprocess - This one is named after the theme itself. Applies to all hooks. 10. themeName_preprocess_hook - Same as the previous preprocessor but for a specific hook. There are many possibilities here for modifying the variables. In most cases, it is only the first two preprocessors that exist. The first adds the default baseline variables and the second adds a set specific to the theming hook. Contributed modules taking advantage of the preprocessor slots (3 & 4) should document their behavior. It will not be covered extensively here. While it is possible, the default PHPTemplate does not inject itself to this list. (5 & 6) Themes can start adding their preprocessors seventh in the list. The preprocess function should be added to the theme's template.php file. However, due to the problems listed below, it is recommended that themes use their own names as the prefix (9 & 10). It is possible to grow this list beyond the ten shown above by having sub-themes add preprocessors strictly through their theme name as it is shown in the last two examples. A few notes: 



There is an unfortunate design flaw/bug in the theme system when a theme is part of a base theme/sub-theme hierarchy. Any preprocess functions prefixed with engineName_preprocess will be run multiple times (once for each theme in the hierarchy) instead of just once. Not only is this wasting resources, it can also cause difficult-to-debug errors. The theme name (9 & 10) should always be used for themes. This minimizes any chance of a sub-theme redeclaring a function with an engineName_preprocess prefix and causing fatal PHP errors due to duplicate functions.

Note that nothing should be returned from these functions and the variables have to be passed by reference indicated by the ampersand before variables, e.g., &$variables. Since the variables set early on are run through all the latter preprocessors due to references, be careful that you do not inadvertently reset any added before your theme. It is fine to reset them, but doing so accidentally can keep you guessing on what went wrong. Example set from a module implementing the hook of "foo":

And the preprocessor created from the theme to add to the variable set above:
101

// Do not do this unless you mean to: $variables['foo_list'] = array('list item 4'); // Instead do this: $variables['foo_list'][] = 'list item 4'; } ?>

The variables that end up in the template file are the keys set within $variables. So, with the above example, the variable in the template would result in $foo_list. When using a preprocessor not specific to a theming hook, a second parameter can be used which always passes the current hook. Using a more specialized preprocess function like the one shown above is easier to maintain but if there will be shared code for multiple theming hooks, you may want to opt for this instead.

In Drupal 7, there are two sets of variable process functions. The first is the existing "preprocess" functions. The second is "process" functions which are run after preprocessors. All the various prefixes and suffixes apply to this second phase in the exact same way. This is useful when certain variables need to be worked on in two phases. For example, adding classes into an array for the "preprocess" phase then flattening them into a string in the "process" phase, so it's ready to print within a template.

102

Default baseline variables The following are the baseline variables available to all template files. They are generated through the preprocessor function, template_preprocess. Variables specific to the template are documented inside the file.

New Variables available in D7 $attributes_array $title_attributes_array $content_attributes_array $classes_array

Array of html class attribute values. It is flattened into a string within the variable $classes. $title_prefix

An array containing additional output populated by modules, intended to be displayed in front of the main title tag that appears in the template. $title_suffix

An array containing additional output populated by modules, intended to be displayed after the main title tag that appears in the template.

Variables available in both D6 and D7 $id

The placement of the template. Each time the template is used, it is incremented by one. $zebra

Either "odd" or "even". Alternate each time the template is used. $directory

The theme path relative to the base install. example: "sites/all/themes/myTheme" $is_admin

Boolean returns TRUE when the visitor is a site administrator. $is_front

Boolean returns TRUE when viewing the front page of the site. $logged_in

Boolean returns TRUE when the visitor is a member of the site, logged in and authenticated. $db_is_active

Boolean returns TRUE when the database is active and running. This is only useful for theming in maintenance mode where the site may run into database problems. $user

The user object containing data for the current visitor. Some of the data contained here may not be safe. Be sure to pass potentially dangerous strings through check_plain.

103

Customizing and Overriding User Login page, Register, and Password Reset in Drupal 6 Customizing the user login, register, and password reset pages is fairly simple, and uses the following concepts:   

preprocessing to set variables registration of functions in the theme registry creation of one or more theme templates.

Step 1. In the site theme directory, create or edit your template.php file. Step 2. Look for a function named yourtheme_theme() and either modify it to add these return values or if it doesn't exist add the following: array( 'template' => 'user-login', 'arguments' => array('form' => NULL), ), 'user_register' => array( 'template' => 'user-register', 'arguments' => array('form' => NULL), ), 'user_pass' => array( 'template' => 'user-pass', 'arguments' => array('form' => NULL), ), ); } ?>

Notes about that code:    

Change the function name by replacing "yourtheme" with the name of your theme The template can be the same for all three. The example above uses a different template for each case: user-login, user-register, and user-pass The template names must use a dash, not an underscore Note: It's user_pass not user_password

104

Step 3. Now you implement three preprocess functions. There may be more concise ways to code this, but this works very well and is easy to read, so here we go!

Notes about that code:   

Change the function name by replacing "yourtheme" with the name of your theme The line $variables['intro_text'] adds the text that follows to the $variables array, which gets passed to the template as $intro_text The second line renders the form and adds that code to the $variables array, which gets passed to the template as $rendered

Step 4. Create template files to match the 'template' values defined above. In this case, we only need two: user-login.tpl.php and user-register.tpl.php (make sure to use a dash, not an underscore) Step 5. Paste the following into user-login.tpl.php. Modify as necessary for user-login.tpl.php and user-register.tpl.php:

Step 6. Save this file to the theme's main directory Step 7. Rebuild the cache. Go to Administration > Performance and click on "Rebuild Cache" on the bottom of the page. Now, the user login page will contain the new text from the preprocess function, and the tpl.php file(s) can be modified to suit the site's needs. 105

Example: Themable output  

Audience: Developers and coders Last modified: March 1, 2011

How to customize HTML for the search block This example explains how to customize the HTML for the default search block. The default search block is created by the search module. Using the .tpl.php file method: 1. From your site root, go into the modules/search folder 2. Copy modules/search/search-block-form.tpl.php to sites/all/themes/yourtheme/searchblock-form.tpl.php You can now edit the version of the file that is in your theme folder. search-block-form.tpl.php has this code:

This example removes the simple form print statement there, and creates new HTML output, following the documentation at the top of the file: '; print $search['search_block_form']; print $search['submit']; print $search['hidden']; ?>