Posted on February 14, 2008 | Tags:
Just a little to the left please. Flip it around. Put that on top of this. Call it by a different name. It is the little changes, that seem trivial and small, that often end up being real headaches to make and support our clients in making. Do we really want to try to build capacity with clients by teaching them to adjust #weight in hook_form_alter?
The Drupal Theming System is pretty powerful and, when done right, can offer a good avenue for our clients and their staff to edit, modify, and change their own website content. Its a lot easier to modify HTML files than Drupal module files.
A good example of where this kind of process is needed is on the user registration page. There are a lot of little bits of language and ordering to change and add, but to do so in Drupal module code can get a little hairy. Observe our technique to abstract the user/register form into a flat template file (while maintaing most of the other good Drupal goodness).
Step One: Create a theme override in your module code for the user/register form that executes a _phptemplate_callback to use a separate template file.
<?php
function theme_user_register($form) {
$vars = array();
$output = _phptemplate_callback('user_registration_form', $vars);
$output .= drupal_render($form);
return $output;
}
?>
Step Two: Expand the theme override function made in step one to remove the titles and descriptions Drupal provides for the form elements. We do this in the theme function (instead of in a hook_form_alter) to preserve the original field titles so they can be used as part of any error messages coming out of form validation.
<?php
foreach($form as $key => $value) { // loop through top level
if (is_array($form[$key])) {
$form[$key]['#title'] = '';
$form[$key]['#description'] = '';
foreach($form[$key] as $key2 => $value2) { // loop through second level
if (is_array($form[$key][$key2])) {
$form[$key][$key2]['#title'] = '';
$form[$key][$key2]['#description'] = '';
}
}
}
}
?>
Step Three: Create "rendered" versions of each of the form elements and set them as variables that can be passed to the template file.
Note: This can also be done with a generic foreach loop (similar to the one in step two) that renders each form element automatically.
<?php
// Set up the Vars Array
$vars = array();
// Render Specific Fields You Want on Your Registration Form
// note - the specific location of the element in the form array varies
$vars['name_element'] = drupal_render($form['account']['name']);
$vars['mail_element'] = drupal_render($form['account']['mail']);
// continue for each field you want...
// Don't Forget the Submit Button
$vars['submit_button'] = drupal_render($form['submit']);
?>
Step Four: Create a template file in your site's theme directory to build the user/register form with the customized variables we defined in step three.
Note: This file needs to be the same name as specified in the _phptemplate_callback (example: user_registration_form.tpl.php).
<div class="user-register-element">
<label>Enter a screen name:</label>
<div class="user-register-element-input">
<?php print $name_element; ?>
</div>
<div class="user-register-element-description">
Screen names can be up to 13 characters in length.
</div>
</div>
<div class="user-register-element">
<label>Enter an Email:</label>
<div class="user-register-element-input">
<?php print $mail_element; ?>
</div>
<div class="user-register-element-description">
Emails must be valid.
</div>
</div>
<?php // continue on for each rendered form element ?>
The drupal magic here is that the user registration form is now uniquely customizable by anyone who can edit the theme template. This allows for customized "prompts" for each profile field element, without changing the site-wide field name in admin/user/profile, and it allows for customization of the username and email titles and descriptions.
This technique will need to be modified to support external modules that modify the user/register form like LoginToboggan. It also needs to take into account things like "required" fieldstates.
The magic of 
A few services fill this role, such as the excellent 
