Theming the register form in Drupal 6

The following exercise consists in adding Terms of Use to the register form in Drupal 6. Provided that your website visitors aren't logged in, they can view the register form on the page myWebSite.com/user/register.

This exercise will show you how to:

• recognize when a module has not registered a specific theming function for a form it generates,
• register a theming function for a Drupal form in your theme, using HOOK_theme,
• use the Devel module function dsm() to inspect complex variables, such as Drupal forms,
• use the Theme Developer 'Themer info' widget to inspect those forms that only 'anonymous users' can see, for instance... the register form.

Storing the Terms of Use in a node

Context: You're having a bad fuel day, and you're developing a Drupal site for Randy.com. You were lucky enough to find ready-made Terms of Use, while googling +"Terms of Use", Terms of Use you'll shamelessly 'use' on Randy.com — yes, you will use these copyrighted Terms of Use, to protect Randy's website content.

The Terms of Use are terse just as they ought to be:

You want to show these Terms of Use in the register form, and you want to add a required checkbox below these Terms with something like this written next to it: I agree with these Terms.

Randy agrees to use these Terms of Use, but not "as is". He would like to insert, here and there, words to elicit a WTF-reaction. But he's not a programmer. So you've created a node to store the Terms, and given the node alias to Randy (that is, terms-of-use), so that Randy may change the Terms whenever he wants to whatever he wants (click on the edit tab, Randy).

You've taken mental note of the node hi-dee.

You'll need that number later. Randy only needs to know the path alias. You remind Randy that he probably should not promote the 'page'. (Leave the publishing options alone, Randy.)

What theming function to override...?

So, now, you want to theme the register form. That's your goal. The first question you ask yourself is What theming function must I intercept and override?

To find answers to these types of questions, 11heavens.com recommends using the module Theme Developer.

Download the Devel set of modules from Drupal.org, extract it to sites/all/modules, and enable the Devel module on your admin/build/modules page.

Make sure to move the Development block to some active region on your page.

You would like to use the Themer info widget on the register page, but, alas, when you try and access the register page you get an Access denied message: You are not authorized to access this page.. You're the admin, what the hell is that? The explaination: you can view the register form — on the page myWebSite.com/user/register — only if you aren't logged in. However, when you log out, you can no longer use the Themer info widget. What to do?

If you're working locally, and not on some site that sits on a server somewhere, you can give access to the Themer info widget to anonymous users. Head over to the admin/user/permissions page and select the appropriate radio button. Then, log out.

You might also want to change the Devel module 'permissions' to make the Switch user block available to all logged-in users, that is, 'authenticated users'. When you're working on your local machine (in your bunker), and you're tesing who can see and do what, it's efficient to be able to switch from being logged-in as yourself, to being logged-in as some Dude with role X, to being logged-in as Dudesse with role Y, to being logged-in as yourself again, etc. and in a snap. Having to log out and login is tedious.

End of sidenote. Back to business.

Once you've finally landed on the register page as an anonymous user, click on the 'Enable Theme developer' link in your Development block.

Now, enable the Themer info widget. The Themer info toggle checkbox sits on the bottom-left of your viewport. (Thought I should throw the fancy word "viewport" in there.)

You want to click on the form, but you end up selecting one field or another within the form. Argh. Solution: click somewhere to the right of the form button(s). So, you click somewhere on the right of the Create a new account button.

There's no specific theming function that's been registered to theme the register form. How do you know that? Answer: the function theme_form() is used to theme the form. How do you know that theme_form() is used to theme the register form? The Themer info widget tells you that.

You're not interested in overriding the theme_form() function. You want to theme the register form. You do not want to theme all forms. You want to theme only that form. What will you do ?

First, eat something.

You will register a theming function for the register form.

Modules and themes can both register theming functions. Modules and themes can both implement the function hook_theme.

Registering a theming function

To register a theming function for a form, you must know its Form ID.

There are at least two ways to find the Form ID.

• Look at the <form> CSS id. That id is the hyphenated version of the Form ID: <form action="/user/register" accept-charset="UTF-8" method="post" id="user-register">. Hence, the Form ID, here, is user_register.
• Look at some hidden input in the form markup with name "form_id". The value of that input is the Form ID: <input name="form_id" id="edit-user-register" value="user_register" type="hidden">

You take mental note of the Form ID. (You and I both have amazing storage capacities in our brains.)

Just for fun (and to learn a few things), you take a peek inside the user module to make sure that it provides no theming function for the register form. You're looking for the module's implementation of hook_theme(). In the modules/user folder, you search for the string function user_theme.

Search results guide you to the file user.module.

The module is registering quite a lot of theming functions, but nah, none for 'user_register'.

You make these fine observations:

• When the module provides a theming function per se, a 'file' is specified, the file in which the function is defined — but the module does so only when the function is stored in a separate file, that is, not in user.module.
• Whenever the module provides a *.tpl.php file, a 'template' is specified. The template name, as the convention goes for a form, is the hyphenated version of the Form ID. You take mental note of this.

So that you understand, in the hook_theme() function, the key to each sub-array is the internal name of the hook. And we mean hook in "themespeak", not "modulespeak". For a form, the name of the hook is the Form ID. Each sub-array contains info about said hook, and that info is an associative array. Among the info, there's only one required item, and that is the 'arguments'. Plural form.

So, now, you'll register a theming function for the user_register form. The user module hasn't done so. So, you will.

Registering a theming function for a form

You open your theme's template.php file. Randy.com uses the Garland theme. (For the money he's paying you, he better not fuss.) Here's the code to register a theming function for the 'user_register' form:

You take good note of the following:

• The hook_theme function always returns an array. It returns an array even when it registers only one single theming function.
• The hook_theme function returns an associative array. In that array, the key(s) is(are) the hooks (in "theme speak") that need to be themed — and for a form, the hook is the Form ID.
• The 'arguments' element (plural form, please!) is also an associative array, and it is an array even when it contains only one element. The key/value pair for that one element, in our case, is 'form' and NULL.
• You could provide an 'arguments' element, and stop there. You could then use a function like garland_user_register($form) to theme the form. But if you prefer to use a *.tpl.php file to theme the form, you need to provide a 'template' name. (And you prefer that. But why?) The value of 'template' is the name of the file you intend on using — without the tpl.php extension. Note that the template name can be ANYTHING AT ALL, that is, 'anything-at-all', provided you create a file that's called anything-at-all.tpl.php. But to follow Drupal's coding conventions, you, my Drupal-worker friend, use the hyphenated version of the Form ID.

Providing a template file and its preprocess function

When we want to override a template provided by a module, the process is the same. Always. We locate the template file and copy it to our theme folder. When we want to pass additional variables to the template, we define a preprocess function for the template in our theme. The second step is optional. It's usually not needed.

In our case, the module has provided no default template. Heck, it has not even provided a theming function! We had to register one! So we must go through these two steps:

• Create the template file out of thin air.
• Define a preprocess function to pass along to the template file any variable that it needs; all of the variables that have not been passed along already through the 'arguments' defined above; all of the variables it requires except the ones passed along already, and excluding those variables that are automatically made available to all template files, like $user and $logged_in. (For a list of what's available in any *.tpl.php file, head over here).

By the way, are you still using global $user; in your template files? Just use $user, it's a default baseline variable available in all *.tpl.php files. It's part of your free meal.

For each template file used to theme content in Drupal 6, there must exist a function to pass to it whatever variables are needed to output content. For each template file used to theme content in Drupal 6, there exists somewhere a preprocess function.

Let's move on.

Create a file called user-register.tpl.php in your theme folder. In it, place this markup:

Then, create the skeleton for the template preprocess function in your template.php file like so:

The function garland_preprocess_user_register(), as defined above, creates a new variable and passes it to the template file. That new variable is $form_markup, and it contains the markup for the form 'user_register'.

You know this already about $vars:

• The $vars includes the key $vars['form'] as well as the default baseline variables available to all templates.
• $vars['form'] is a complex nested array that contains our 'register_form'.
• $vars is passed to the preprocess function 'by reference'. This means we can add to it, edit it, do whatever we want to it, and our changes will 'keep'. The preprocess function is usually used to pass additional variables to the template file — by adding to $vars — but it can also be used to alter stuff that's passed already. You'll use it that way.

You know this already about drupal_render():

• The drupal_render() function is what's used by themes to whip a $form array into XHTML markup.
• The drupal_render() function can render any part of a form, or the whole thing.
• When used to render the entire form, drupal_render() will only render these parts of the form that have not been rendered yet. It can keep track of what has been rendered thus far, in other words.

Clear your Drupal cache. That will clear the Theme registry.

Does Drupal use my template?

After you've refreshed your page in your browser, you should see a 'Hello world' greeting between the title of the page and the register form.

Satisfied and relieved, you remove the Hello World heading from your template file.

A little planning

You're thinking about how it is you want to include your Terms of Use. You want to create a new fieldset with title "Terms of Use". In that fieldset you want to print the text that's in node... what's the number? 402. Below the text you want to put some checkbox with text "I agree with these terms" next to it. It must be required for the "user" (also referred to as the "visitor") to check that box, otherwise the register form won't be submitted.

Checking out the form

To troubleshoot any problems we may encounter while editing the form, we need to inspect it. The devel module provides a kit of 5 functions to inspect the content of variables:

Function	To inspect content of	Content shown	Using a recursive function
dsm()	Any variable	In a message	Yes, perfect for all.
dvm()	A complex variable, such as an object or array	In a message	No. Ugly print.
dpr()	A complex variable, such as an object or array	At the top of the page.	Yes. Perfect for complex, ie: nested, objects and arrays.
dpm()	A complex variable, such as an object or array	In a message.	Yes. Perfect for complex, ie: nested, objects and arrays.
dvr()	Any variable	At the top of a page.	No. Ugly print.

To inspect complex nested arrays such as forms, you can use either dpr() or dpm()/dsm(). These functions pretty-print forms either at the top of the page, or in the 'message' area. dpm() and dsm() have the same behavior.

Creating a fieldset

You want to create a fieldset for the Terms of Use, titled 'Terms of Use'.

Without the '#weight' attribute, the fieldset rises to the top. You want it to sink to the bottom of the form.

Adding the content of a node to a fieldset

To place text or HTML in a form is not exactly adding a field to it. But still, markup that just sits there is a field in its own right and it is the default type for a field in the Drupal form API. Hence, we need not specify a '#type' of 'markup' for it.

We use node_prepare() to apply the filters that would normally be applied to the node's content if it were shown at Randy.com/terms-of-use. Likewise, using '#prefix' and '#suffix', we wrap the Terms of Use in a <div> with the same class names used for any node when shown on any other page.

Adding a checkbox to a fieldset

The checkbox will appear below the Terms following the order in which the form fields have been added to the fieldset.

Two unresolved issues

You ask yourself: Why in the hell did I create a template file when all it does is print a variable ? It doesn't even contain HTML markup! All it contains is this:

So, you've changed your mind about this. You delete the template file user-register.tpl.php. (You heard that using a template is 5x slower than using a theming function.)

Then, you open your template.php file. You remove from the garland_theme() function any mention of the template file. The function becomes:

Then, you go ahead and comment out the whole preprocess function. Preprocess functions are for template files only.

Next, you write your theming function. This consists in moving the code from the commented-out preprocess function to a new function you call garland_user_register ($form). In that new function, you replace all mention of $vars['form'] with $form. What the theming function must return is themed content. Hence, you delete the line of code which consisted in adding a variable to $vars, and place the following 'return' instruction in its place:

Here's the code for the entire function:

Don't forget to clear the cache.

Randy is happy. He sends you two-thirds of the money he promised you, along with this photo of him. He says he's on the left.

But I mentioned there were two problems. The second problem is that you cannot make that damn checkbox a requirement. It just doesn't work. I will leave this outstanding bug for you to fix. What's wrong here? Read the comments for the solution.

This tutorial was helpful to you? Post a comment and/or donate. Thank you.