Theming forms with Template Files
Creating template files for forms is surprisingly easy given what you’ve already learned. As mentioned in the “First Steps for Theming Forms” section, you’ll need to open
template.php and implement a
hook_theme() function. Instead of just defining the render element, you’ll need to add two more things, as shown in Listing 16–30:
- A path key (optional) that contains the path to where the template file is located in your theme.
- A template key that contains the name of the template file, without the
After creating the
hook_theme() function shown in Listing 16–30, you’ll need to create the template file. In this case, it’s located in the
templates directory within your theme:
Once that’s complete, simply clear the cache and Drupal will begin using your template file.
If there’s nothing in your file to begin with, you’ll get a blank page where the form used to be. The first thing you should do is add this line back to the template file:
<?php print drupal_render_children($form); ?>. This will get the entire form back, and even though you may not want to keep everything in the form, you need to print the contents of this at the bottom of the form to ensure everything works properly as we detailed in the “Using drupal_render_children() is a Must!” section.
Manipulating Form Elements in Template Files
For the sake of covering this topic in detail, let’s use the example from the Manipulating Form Elements in Theme Functions section. The code in Listing 16–31 represents the result of completing the following tasks:
- Changing the labels for the name and mail elements.
- Rendering the name and mail elements individually.
- Arranging your markup and individually rendered elements as you want them.
- Finally, printing
drupal_render_children($form)at the bottom of the template.
While there are slight differences, it’s mostly the same (with less PHP). All of the possibilities that apply in theme functions apply just as well in template files. The variables themselves are slightly different. In theme functions and preprocess functions, the name element would be located in
$variables['form']['name']. In template files, that same variable would be
$form['name']. This is done specifically to make Drupal’s monster arrays easier on template authors.
Keep Your Template Cleaner with Preprocess Functions
In our example of theming a form with a template file, the template is quite messy. The definition of a clean template file is one that contains hardly any logic and that simply prints variables and maybe an occasional IF statement. If you are dissatisfied with the appearance of the template file, this is a perfect opportunity to use preprocess functions. To make this really clean, you’d do the following in a preprocess function:
- Perform all modifications to the form array.
- Create any new variables.
- Render each field individually and provide easy variables for templates.
Of course, this is not something you’d want to do on every form on your site. However, it’s very useful and convenient for highly styled user-facing forms that you want to take extra care to get right, such as the login, registration, and contact forms. The process of doing this is very easy, as demonstrated in Listing 16–32 with the contact form.
Because you’ve done all the work in the preprocess function, the template file in Listing 16–33 is crispy clean. Adding markup and classes and moving elements around is a piece of cake, and it’s very easy to see what this template file does at first glance.