Drupal专业开发指南 第10章 Drupal表单API（form API）--表单API属性

表单API属性

 

 

译者：老葛    ESKALATE科技公司

 

当在你的表单构建函数中构建一个表单的定义时，数组中的键用来声明表单的信息。下面部分列出了常用的键。一些键将被表单构建器自动添加进来。

表单的属性

下面部分中的属性特定于表单。换句话说，你可以设置$form['#programmed'] = TRUE，但是如果你设置$form['myfieldset']['mytextfield'] [#programmed'] = TRUE那么表单构建器将不知道你要它做什么了。

 

#parameters

该属性是一个数组，包含了传递给drupal_get_form()的原始参数。通过drupal_retrieve_form()可添加该属性。

 

#programmed

这是一个布尔值属性，用来指示一个表单被以程序的方式比如通过drupal_execute()来提交的。如果在表单处理前设置了属性#post,那么可以使用drupal_prepare_form()来设置该属性。

 

#build_id

该属性是一个字符串（用MD5哈希）。在多步表单中，#build_id用来标识一个特定的表单实例。它作为一个隐藏域放在表单中，通过使用drupal_prepare_form()来设置该表单元素，如下所示：

$form['form_build_id'] = array(

'#type' => 'hidden',

'#value' => $form['#build_id'],

'#id' => $form['#build_id'],

'#name' => 'form_build_id',

);

 

#base

这是一个可选的字符串属性，当Drupal决定要调用哪个验证、提交、和主题函数时使用。将$form['#base']设置为你想让Drupal使用的前缀。例如，如果你将$form['#base'] 设置为'foo'，并调用drupal_get_form('bar')，在bar_validate() 和 bar_submit()不存在的情况下，Drupal将使用foo_validate() 和foo_submit()作为处理器。该属性也用于映射主题函数。参看drupal_render_form() (http://api.drupal.org/api/5/function/drupal_render_form)。

 

#token

该字符串（用MD5哈希）是一个唯一的令牌，每个表单中都带有它，通过该令牌Drupal能够决定一个表单是一个真的Drupal表单而不是一个恶意用户修改后的。

 

#id

该属性是一个由form_clean_id($form_id)生成的字符串，并且它是一个HTML ID属性。$form_id中的任何翻转的括号对“][”，下划线“_”，或者空格’’都将被连字符替换以生成一致的CSS ID。

 

#action

该字符串属性是表单标签的动作属性。默认情况，它是request_uri()的返回值。

 

#method

该字符串属性指的是表单的提交方式---通常为post。表单API是基于post方法构建的，它将不会处理使用GET方法提交的表单。参看HTML规范中的关于GET 和POST的区分部分。如果你需要使用GET方法时，你可能需要使用Drupal的菜单API，而不是表单API。

 

#redirect

该属性可以是一个字符串或者一个数组。如果是字符串时，那么它是在表单提交以后用户想要重定向的Drupal路径。如果将其设为一个数组，该数组将被传递给drupal_goto()，其中数组中的第一个元素应该是目标路径（这将允许向drupal_goto()传递额外的参数）。

 

#pre_render

该属性是一个数组，它包含了在表单呈现以前所要调用的函数。每个要调用的函数都包含参数$form_id 和 $form。例如，设置#pre_render =array('foo', 'bar')将促使Drupal先调用函数foo($form_id, $form)，然后接着调用bar($form_id, $form)。当你想在表单验证完以后，显示以前，使用钩子修改表单结构时非常有用。如果想在验证以前修改表单，使用hook_form_alter()。

 

 

添加到所有表单元素上的属性

当表单构建器使用表单定义构建表单时，它需要保证每一个表单元素都要有一些默认设置。这些默认值在includes/form.inc的函数_element_info()中设置，但是可以被hook_elements()中的表单元素定义所覆盖。

 

#description

将为所有表单元素添加该字符串属性，它默认为NULL。通过表单元素的主题函数来呈现它。例如，textfield的描述出现在textfield输入框的下面，如图10-2所示。

 

#required

将为所有表单元素添加该布尔值属性，它默认为FALSE。将它设为TRUE，如果表单被提交以后而该字段为空时，Drupal内置的表单验证将抛出一个错误消息。还有，如果将它设为TRUE，那么就会为该表单元素设置一个CSS类（参看includes/form.inc中的theme_form_element()）

 

#tree

将为所有表单元素添加该布尔值属性，它默认为FALSE。如果将它设为TRUE，表单提交后的$form_values数组将会是嵌套的（而不是平坦的）。这将影响你访问提交数据的格式。（参看本章中的“字段集（Fieldsets）“部分）。

 

#post

该数组属性是原始$_POST数据的一个拷贝，它将被表单构建器添加到所有的表单元素上。这样，在#process 和 #after_build中定义的函数就可以基于#post的内容做出智能的决定。

 

#parents

将为所有表单元素添加该数组属性，它默认为一个空数组。它在表单构建器的内部使用，以标识表单树中的父表单元素节点。更多信息，参看http://drupal.org/node/48643。

 

#attributes

将为所有表单元素添加该数组属性，它默认为一个空数组，但是主题函数将逐步的填充该数组。该数组中的成员将被作为HTML属性。例如$form['#attributes'] = array('enctype' => 'multipart/form-data')。

通用表单元素属性

本部分解释的属性在所有表单元素中都可以使用。

#type

该字符串声明了一个表单元素的类型。例如，#type = 'textfield'。表单根部必须包含声明#type = 'form'。

 

#access

该布尔值属性决定表单元素对于用户是否可见。如果表单元素有子表单元素的话，如果父表单元素的#access属性为FALSE的话，那么子表单元素将不被显示出来。例如，如果表单元素是一个字段集的话，如果它的#access为FALSE的话，那么字段集里面的所有的字段都不被显示。

 

#process

该属性是一个关联数组。在数组的每个项目中，一个函数名作为键，传递给函数的任何参数作为值。当构建表单元素时将调用这些函数，从而允许在构建表单元素时添加额外的操作。例如，在system.module定义了checkboxes类型，在构建表单期间，将调用设置的includes/form.inc里面的函数expand_checkboxes()：

 

$type['checkboxes'] = array(

'#input' => TRUE,

'#process' => array('expand_checkboxes' => array()),

'#tree' => TRUE);

参看本章中“收集所有可能的表单元素定义“部分的另一个例子。当#process数组中的所有的函数都被调用之后，将为每个表单元素添加一个#processed属性。

 

#after_build

该属性是一个数组。数组中保存了在表单元素构建完以后要立即调用的函数。每个要被调用的函数都有两个参数：$form 和 $form_values。例如，如果$form['#after_build'] = array('foo', 'bar')，那么Drupal在表单元素构建完以后，分别调用foo($form, $form_values)和bar($form, $form_values)。一旦这些函数都被调用之后，Drupal在内部将为每个表单元素添加一个#after_build_done属性。

 

#theme

该可选属性定义了一个字符串，当Drupal为该表单元素寻找主题函数的时候使用它。例如，设置#theme = 'foo'，将使得Drupal调用theme_get_function('foo', $element)，该函数将按照顺序查找函数themename_foo(), themeengine_foo(), 和 theme_foo()。参看本章前面的“为表单寻找主题函数“部分。

 

#prefix

该属性是一个字符串，在表单元素呈现时它将被添加到表单元素的前面。

 

#suffix

该属性是一个字符串，在表单元素呈现时它将被添加到表单元素的后面。

 

#title

该字符串是表单元素的标题。

 

#weight

该属性可以是一个整数或者分数。当呈现表单元素时，将根据它们的重量进行排序。重量小的元素将被放到前面，重量大的元素将被放到页面的下面位置。

 

#default_value

该属性的类型根据表单元素的类型而定。对于输入表单元素，如果表单还没有被提交，那么它就是该字段所使用的值。不要将它于表单元素#value相混淆。表单元素#value定义了一个内部表单值，用户看不到该值，但是它却定义在表单中并出现在$form_values中。