We have the choice of changing the output of various aspects of Webform within the pertinent template files directly or by means of theme preprocessing functions.
The rule of thumb is that we should make changes within the template file if our coding contains more HTML than PHP logic, otherwise the coding should go into a preprocessing function. In this exercise, we're going to do a little of each to demonstrate the underlying principles.
Let's move on now and have a brief look at how we may interact with the internals of the Drupal theme layer.
- We need to make a copy of the
webform-confirmation.tpl.phpfile from ourspeakers/templatesfolder and place it in oursites/all/themes/speakersdirectory. - Let's rename it as
webform-confirmation-NID.tpl.php(substitutingNIDwith our node identifier as before). - Let's now open the file with our text editor and edit the last bit of code to read as follows:
<div class="links"> <a href="<?php print $link_url ?>" title="<?php print $link_tip ?>"><?php print $link_title ?></a> </div>
- Next we add the following code into a new file called
template.phpand save the file in oursites/all/themes/speakersfolder:<?php function speakers_preprocess_webform_confirmation (&$variables, $hook) { // Override empty confirmation message variable. if (!isset($variables['confirmation_message']) || $variables['confirmation_message'] == '') { $variables['confirmation_message'] = t('Thank you! We have received your speaker registration.'), } // Additional variables to change "Go back to the form." link message. $variables['link_url'] = url('node/'. $variables['node']->nid); $variables['link_title'] = t('Register another speaker'), $variables['link_tip'] = t('Click here to register another speaker'), } - Since we created a new template file, we need to navigate to Configuration in our menu toolbar, click on the Performance link and then click on the Clear all caches button as we did before.
- To see how these changes affect our form's confirmation page, we refresh our theme registry by clicking on the Save configuration button on the Appearance administration page.
- Next we navigate to our Speaker Registration form and complete a new submission.
- The link at the end of the confirmation message has changed from Go back to the form to Register another speaker.
- Additionally, most browsers will display a tooltip showing the link tip text entered above while our mouse pointer hovers over the link.
In this example, we have modified the HTML output of the confirmation page by editing webform-confirmation-NID.tpl.php (where NID needs to be replaced by the node identifier). The only Webform on our site that will be affected is our Speaker Registration node, because we included the node identifier in the filename. We changed the links division to utilize variables for the link target address ($link_url) as well as the link text ($link_title). We also added a title attribute to the link.
To populate the new variables ($link_url and $link_title) we introduced to our template file we need to create a template preprocess function. The Drupal theming system permits this flexibility via placement of a file called template.php in our theme folder. This file allows us to override any theme functions and template preprocess functions. Functions in this file are where we specify any PHP logic that will affect our template variables.
Functions contained within template.php need to follow a naming scheme in order to be called prior to the respective template being processed. The function names are made up of three components separated by the underscore character: the theme name, the word preprocess, and finally, the name of the template or theme function we wish to override (hyphens in the template/function name are replaced by underscore characters). That is how we arrived at our override function being named speakers_preprocess_webform_confirmation.
Our function contains two distinct sections. In the first part, we ensure that the confirmation message will never be empty when our Webform confirmation template is called, meaning that the default message (Thank you, your submission has been received) specified in webform-confirmation.tpl.php will never be displayed.
In the second section, we add our new template variables to the $variables array for use in processing the confirmation page template.
The principles we have covered in this exercise pertain equally to all of the other Webform templates we copied into our theme folder. Changes to these templates may be applied to a specific Webform only by specifying the node identifier within a template filename or to all Webforms across our website by leaving the filename as is.
We have had a brief toe-in-the-water look at theme overrides as they pertain to Webform. For a more detailed introduction to the subject we may navigate to http://drupal.org/node/341628.
In our sites/all/modules/webform folder, we find some handy theming tips in a file named THEMING.txt.
Depending on the setup of our site and which themes are active, it can be quite a job to determine exactly which templates or theme functions require overriding to achieve the effects we want. We can install the Devel module (http://drupal.org/project/devel) and the Theme developer module (http://drupal.org/project/devel_themer) to assist with our theming requirements.