Drupal专业开发指南 第10章 Drupal表单API（form API）--创建基本的表单

创建基本的表单

译者：老葛 ESKALATE

       如果你拥有直接通过HTML创建自己表单的经验，那么，刚开始，你可能会觉得Drupal的方式让人感到困惑。本节通过例子使你能够快速的创建自己的表单。在开始，我们将创建一个简单的模块，用来让你输入自己的名字并将其打印出来。我们把它放在一个独立的模块里面，这样我们就不需要修改任何已存在的代码了。我们的表单仅包含两个元素：文本输入框和提交按钮。我们首先在 简历一个.info文件，输入以下内容：

; $Id$

name = Form example

description = Shows how to build a Drupal form.

version = "$Name$"

 

接下来，我们把真实的模块放在sites/all/modules/custom/formexample/formexample.module:

 

<?php

// $Id$

/**

* Implementation of hook_menu().

*/

function formexample_menu($may_cache) {

$items = array();

if ($may_cache) {

$items[] = array(

'path' => 'formexample',

'title' => t('View the form'),

'callback' => 'formexample_page',

'access' => TRUE

);

}

return $items;

}

/**

* Called when user goes to example.com/?q=formexample

*/

function formexample_page() {

$output = t('This page contains our example form.');

// Return the HTML generated from the $form data structure.

$output .= drupal_get_form('formexample_nameform');

return $output;

}

/**

* Defines a form.

*/

function formexample_nameform() {

$form['user_name'] = array(

'#title' => t('Your Name'),

'#type' => 'textfield',

'#description' => t('Please enter your name.'),

);

$form['submit'] = array(

'#type' => 'submit',

'#value' => t('Submit')

);

return $form;

}

/**

* Validate the form.

*/

function formexample_nameform_validate($form_id, $form_values) {

if ($form_values['user_name'] == 'King Kong') {

// We notify the form API that this field has failed validation.

form_set_error('user_name',

t('King Kong is not allowed to use this form.'));

}

}

/**

* Handle post-validation form submission.

*/

function formexample_nameform_submit($form_id, $form_values) {

$name = $form_values['user_name'];

drupal_set_message(t('Thanks for filling out the form, %name',

array('%name' => $name)));

}

 

我们在这里实现了处理表单的基本函数：一个函数用户定义表单，一个用于验证，一个用于提交。另外，我们实现了一个菜单钩子和它对应的函数，这样就将一个URL和我们的函数联系在了一起。如果你现在正在计算机上实践并且已安装了这一模块，那么就可以访问http://example.com/?q=formexample以查看表单了。我们的简单表单如图10-2所示:

图10-2一个包含了一个文本输入框和一个提交按钮的基本表单

 

工作的重点就是向表单的数据结构中填充数据，或句话说，就是向Drupal表述表单。这一信息包含在一个嵌套的数组中，该数组描述了表单的元素和属性，它一般包含在一个名为$form的变量中。

 

    在前面的例子中，定义表单的重点在于方法formexample_nameform()，在这里我们提供了Drupal展示表单所需要的最小信息。

 

注意： 属性和元素有哪些区别呢？最基本的区别就是，属性没有属性，而元素可以有属性。一个元素的例子就是提交按钮，属性的例子就是提交按钮的属性#type。你一眼便可以认出属性，因为属性拥有前缀”#”。我们有时把属性称为键，因为它们拥有一个值，为了得到该值，你必须知道相应的键。一个初学者常遇到的错误是忘记了前缀“#”，此时，无论是Drupal还是你自己，都会感到非常困惑。

 

表单属性

 

有些属性是通用的，而有些则特定于一个元素，比如一个按钮。对于属性的完整列表，参看本章的最后部分。下面这个表单是比上例中表单复杂一点的版本：

$form['#method'] = 'post';

$form['#action'] = 'http://example.com/?q=foo/bar';

$form['#attributes'] = array(

'enctype' => 'multipart/form-data',

'target' => 'name_of_target_frame'

);

$form['#prefix'] = '<div class="my-form-class">';

$form['#suffix'] = '</div>';

 

#method属性的默认值为post，因此可以被忽略。表单API不支持get方法，它在Drupal中也不常用，这是因为通过Drupal的菜单分发机制可以很容易的解析路径中的参数。#action属性在system_elements中定义，默认值为函数request_uri()的结果，一般与显示表单的URL相同。

 

表单IDs

 

Drupal需要有一些方式来唯一的标识表单，这样当一个页面有多个表单时，它就可以决定提交的是哪一个表单，并且可以将表单与处理该表单的函数联系在一起。为了唯一的标识表单，我们为每个表单分配了一个表单ID。通过调用方法drupal_get_form()来定义ID，如下所示：

drupal_get_form('mymodulename_identifier');

对于大多数表单，其ID的命名规则为模块名称加上一个表述该表单做什么的标识。例如，由用户模块创建的用户登录表单，它的ID为user_login。

Drupal使用表单ID来决定表单的验证、提交、主体函数的名称.另外，Drupal使用表单ID作为基础来为该表单生成一个CSS ID，这样在Drupal中所有的表单都有一个为一个的CSS ID。通过设置#id属性，你可以覆盖CSS ID。

$form['#id'] = 'my-special-css-identifier';

    表单ID作为名为form_id的隐藏于也嵌套在表单之中。在我们的例子中，我们选择formexample_nameform作为我们的表单名，这一因为它很好的描述了我们的表单，从名称就可以看出了，我们表单的目的是让用户输入他们的名称。我们也可以将它命名为formexample_form，但是它的描述性不好，而且在接下来我们可能向再为我们的模块添加一个表单。

 

字段集

很多时候，你想将你的表单化分成不同的字段集---使用表单API可以很容易的做到这一点。每一个字段集都定义在表单的数据结构中，而它所包含的字段都定义为它的孩子。让我们向我们的例子中添加一个字段---喜欢的颜色：

function formexample_nameform() {

$form = array();

$form['name'] = array(

'#title' => t('Your Name'),

'#type' => 'fieldset',

'#description' => t('What people call you.')

);

$form['name']['user_name'] = array(

'#title' => t('Your Name'),

'#type' => 'textfield',

'#description' => t('Please enter your name.')

);

$form['color'] = array(

'#title' => t('Color'),

'#type' => 'fieldset',

'#collapsible' => TRUE,

'#collapsed' => FALSE

);

$form['color_options'] = array(

'#type' => 'value',

'#value' => array(t('red'), t('green'), t('blue'))

);

$form['color']['favorite_color'] = array(

'#title' => t('Favorite Color'),

'#type' => 'select',

'#description' => t('Please select your favorite color.'),

'#options' => $form['color_options']['#value']

);

$form['submit'] = array(

'#type' => 'submit',

'#value' => t('Submit')

);

return $form;

}

表单的显示结果如图10-3所示：

图10-3 带有字段集的简单表单

 

我们使用可选的属性#collapsible和#collapsed来告诉Drupal使用Javascript，在点击第2个字段集标题使它可以伸缩。

  这里有个问题值得思考：当$form_values传递到验证和提交函数是，字段color应该是$form_values['color']['favorite_color'] 还是$form_values['favorite_color']？换句话说，值需不需要嵌套在字段集里面。默认时，在表单处理器中，表单值不用嵌套，所以下面的代码是正确的：

function formexample_nameform_submit($form_id, $form_values) {

$name = $form_values['user_name'];

$color_key = $form_values['favorite_color'];

$color = $form_values['color_options'][$color_key];

drupal_set_message(t('%name loves the color %color!',

array('%name' => $name, '%color' => $color)));

}

在提交函数中设置的消息可以在图10-4中看到。

 

    然而，如果将属性#tree设为TRUE，那么表单值数组的结构就是嵌套的格式。所以，如果我们在定义表单时声明了：

$form['#tree'] = TRUE;

    那么我们就可以使用下面的方式访问数据了：

function formexample_nameform_submit($form_id, $form_values) {

$name = $form_values['name']['user_name'];

$color_key = $form_values['color']['favorite_color'];

$color = $form_values['color_options'][$color_key];

drupal_set_message(t('%name loves the color %color!',

array('%name' => $name, '%color' => $color)));

}

图10-4 表单提交函数中设置的消息

 

提示：将属性#tree设为TRUE，你将得到一个嵌套的表单值数组。当将属性#tree设为FALSE（默认情况），你将得到一个未嵌套的表单值数组。