How Forms Work in Drupal

With Drupal 5, the approach to form handling continues to evolve. Drupal forms are tightly integrated into the core, and as a result, theming them can be a bit of a chore. Unlike other areas of the system, most forms are not the subject of a variety of pre-existing themeable functions. Instead, if you wish to theme a form you are typically left with the choice of either working directly with the form functions in the Drupal core or with following the well-trodden path of intercepting and overriding the form output using the power of the PHPTemplate template engine.

While themeable functions are pretty easy to deal with—being essentially concerned with the formatting of output — the Drupal form functions tend to be rather complicated. Finding the proper bit to modify and then accomplishing that without unintended side effects requires either a solid knowledge of PHP or a willingness to experiment, combined with a great deal of patience.

While you will note that a number of functions are mentioned in this chapter, most of them specific to a particular form, the global function drupal_render is worthy of particular mention. This function produces form output throughout the system and is one of the keys to theming your forms.

At first glance, the function doesn't volunteer much information. Look at this example of the function in action, in this case providing the output of the user login block:

function phptemplate_user_login_block($form) { $output = drupal_render($form);

return $output; }

In this example, we have created an override to the form function. This override would be placed inside the template. php file. As written, the override does nothing other than produce the output of the form. The important points to note here are:

1. You can place the form output with this simple statement and then add HTML around it easily.

2. As you can see above, there are no visible options for controlling individual form elements in this basic formulation; to style individual form elements you must do more.

3. If you are using PHPTemplate, you also have the option to set up a dedicated template (.tpl. php) to hold this function and any modifications.

To achieve a greater degree of control over the styling, we need to go behind the scenes a bit, to look at what goes on when the system invokes this function.

[r'STX drupal_render supersedes the old function form_render, which was I used in earlier Drupal systems. I

For the sake of discussion, let's take a look at an example of an unaltered Drupal form function and examine it in more detail.

Here's the function that produces the user Login Form that appears in a Block. The form ID for this form is user login block and the original code can be found in modules/user/user.module:

function user_login_block() { $form = array(

'#action' => url($_GET['q'], drupal_get_destination()), '#id' => 'user-login-form', '#base' => 'user_login',

$form['name'] = array('#type' => 'textfield', '#title' => t('Username'), '#maxlength' => USERNAME_MAX_LENGTH, '#size' => 15, '#required' => TRUE,

$form['pass'] = array('#type' => 'password', '#title' => t('Password'), '#maxlength' => 60, '#size' => 15, '#required' => TRUE,

$form['submit'] = array('#type' => 'submit', '#value' => t('Log in'),

$items[] = l(t('Create new aeeount'), 'user/register', array('title' => t('Create a new user aeeount.')));

$items[] = l(t('Request new password'), 'user/password', array('title' => t('Request new password via e-mail.')));

$form['links'] = array('#value' => theme('item_list', $items));

Note how this function sets the attributes for the various fields, including field lengths and data labels. The snippet below, for example, produces the password field and its related attributes:

$form['pass'] = array('#type' => 'password', '#title' => t('Password'), '#maxlength' => 60, '#size' => 15, '#required' => TRUE,

Here is the code for the production of the submit button:

$form['submit'] = array('#type' => 'submit', '#value' => t('Log in'),

This snippet sets the text for the links at the bottom of the form:

$items[] = l(t('Request new password'), 'user/password', array('title' => t('Request new password via e-mail.')));

All of these items can be modified by intercepting and overriding this function, as discussed below. The trick is locating the form ID of the original item you wish to change and then identifying the elements (e.g., the password field or the submit button, etc.) that you wish to override.

[_If you really want to get into the nuts and bolts of Drupal forms, check out the forms section of the Drupal API: http : / /api . drupal. org/ ' ?q=api/file/developer/topics/forms_api.html/5.

Was this article helpful?

0 0

Post a comment