Drupal7 forms_api_reference翻译 + Demo

（元素）Elements

属性名通常需要创建这个表单元素时定义。默认值是属性名称旁边的括号中表示，如果它们存在。

actions

描述:一个包装元素，去组合一个或多个button按钮在表单中。使用的“action”的元素作为数组的关键，有助于确保在主题适当的造型，使其他模块，以适当的改变表单的action

属性: #access,#after_build,#attributes#children,#id,#parents,#post_render,#pre_render,#prefix,#process,#states,#suffix,#theme,#theme_wrappers,#tree,#type,#weight

使用例子:

<?php
  $form['actions'] = array('#type' => 'actions');
  $form['actions']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );
  $form['actions']['delete'] = array(
    '#type' => 'button',
    '#value' => t('Delete'),
  );
  $form['actions']['cancel'] = array(
    '#markup' => l(t('Cancel'), 'foo/bar'),
  );
?>

效果:

#markup为链接

button

 

描述: 格式化操作按钮。当按下按钮时，表单将被提交到Drupal，它是验证和重建。提交处理程序是不会被调用。

属性: #access, #after_build, #ajax, #attributes, #button_type(default: submit), #disabled, #element_validate, #executes_submit_callback(default: FALSE), #limit_validation_errors, #name(default: op), #parents, #post_render, #prefix, #pre_render, #process, #submit, #states, #suffix, #theme, #theme_wrappers, #tree, #type, #validate, #value, #weight

使用例子:

<?php
$form['preview'] = array(
  '#type' => 'button',
  '#value' => t('Preview'),
  '#weight' => 19,
);
?>

checkbox

描述: 格式化一个复选框。

属性: #access,#after_build,#ajax,#attributes,#default_value,#description,#disabled,#element_validate,#field_prefix,#field_suffix,#parents,#post_render,#prefix,#pre_render,#process,#required,#return_value(default: 1), #states,#suffix,#theme,#theme_wrappers,#title,#title_display(default: after), #tree,#type,#weight

使用例子:

<?php
$form['copy'] = array(
  '#type' => 'checkbox',
  '#title' => t('Sendme a copy.'),
);
?>

效果:

checkboxes

描述: 格式设置一个复选框。 ＃options是一个关联数组，其中的关键key是＃return_value复选框，值是被显示。 ＃options数组不能有0的关键key，因为它不可能辨别checked和unchecked的状态。

属性: #access,#after_build,#ajax,#attributes,#default_value,#description,#disabled,#element_validate,#options,#parents,#post_render,#prefix,#pre_render,#process,#required,#states,#suffix,#theme,#theme_wrappers,#title,#title_display,#tree(default: TRUE), #type,#weight

使用例子:

<?php
$form['node_options'] = array(

 '#type' => 'checkboxes',

  '#title' => t('Default options'),

 '#default_value' => array('status','moderate'),//默认值

 '#options' => array(

   'status' => t('Published'),

   'moderate' => t('In moderation queue'),

   'promote' => t('Promoted to front page'),

   'sticky' => t('Sticky at top of lists'),

   'revision' => t('Create new revision'),

 ),

 '#description' => t('Users with the <em>administernodes</em> permission will be able to override these options.'),

);?>

效果:

通过$form_state['values'][‘node_options’]能取得提交的值，对应的数组为选中的字符串

Drupal专业开发指南中示例:

复选框元素的示例如下。该元素的呈现版本如图10-13所示。

$options = array(

'poison' => t('Sprays deadly poison'),

'metal' => t('Can bite/claw through metal'),

'deadly' => t('Killed previous owner') );

$form['danger'] = array(

'#title' => t('Special conditions'),

'#type' => 'checkboxes',

'#description' => (t('Please note if any ofthese conditions apply to your

pet.')),

'#options' => $options,

'#weight' => 25,

);

在验证和提交函数中，通常使用array_filter()函数来获取复选框的键。例如，假如在图10-13中前两个复选框被选中了，那么$form_state['values']['danger']将包含以下内容：

array(

'poison' => 'poison',

'metal' => 'metal',

deadly' => 0,

)

运行array_filter($form_state['values']['danger'])将生成只包含复选框的键的数组：array('poison', 'metal')。

复选框元素的常用属性如下：#attributes, #default_value, #description, #options, #prefix,#required, #suffix, #title, #tree (默认为TRUE), 和#weight.注意#process属性默认设为expand_checkboxes() (参看 includes/form.inc)。

Value（值）

值元素是用来在drupal内部将数值从$form传递到$form_state['values']的，而不需要将其发送到浏览器端，例如：

$form['pid']= array(

'#type'=> 'value',

'#value'=> 123,

);

当表单提交后$form_state['values']['pid']将为123。

不要混淆了type = '#value' 和 #value = 123。前者声明了正被描述的元素的类型，而后者声明了该元素的值。值元素只有属性#type和#value可用

container

描述: 返回HTML包装在一个容器中的子元素。围绕子元素增加<div>，像类或一个HTML ID属性。

属性: #access,#after_build,#attributes#children,#id,#parents,#post_render,#pre_render,#prefix,#process,#states,#suffix,#theme,#theme_wrappers,#tree,#type,#weight

使用例子:

<?php
  if ($elements) {
    // Also aid intheming of field widgets by rendering a classified
    // container.
    $addition[$field_name] = array(
      '#type'=> 'container',
      '#attributes'=> array(
        'class' =>array(
          'field-type-' . drupal_html_class($field['type']),
          'field-name-' . drupal_html_class($field_name),
          'field-widget-' . drupal_html_class($instance['widget']['type']),
        ),
      ),
      '#weight'=> $instance['widget']['weight'],
    );
  }
?>

   // Also aid in theming of field widgets by rendering a classified

   // container.

   $form['container'] = array(

     '#type' => 'container',

     '#attributes' => array(

       'class' => array(

         'field-type-' ,

         'field-name-' ,

         'field-widget-' ,

       ),

     ),

   );

效果:

包装div和class

date

描述: 格式化日期的选择框。 ＃default_value将今天的日期，如果没有提供值。 ＃default_value和＃return_value格式是三个键元素的数组：“年”，月“，和”天“。例如，数组（“今年'=> 2007年，”月“=> 2，'天'=> 15）

属性: #access,#after_build,#attributes,#default_value,#description,#disabled,#element_validate,#parents,#post_render,#prefix,#pre_render,#process,#required,#states,#suffix,#theme,#theme_wrappers,#title,#title_display,#tree,#type,#weight

使用例子:

 <?php
$fields[$category][$field->name] = array(
  '#type' => 'date',
  '#title' => check_plain($field->title),
  '#default_value' => $edit[$field->name],
  '#description' => _profile_form_explanation($field),
  '#required' => $field->required
);
?>

Drupal专业开发指南中示例:

   $form['deadline'] = array(

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

                     '#type'=> 'date',

                     '#description'=> t('Set the deadline.'),

                     '#default_value'=> array(

                     'month'=> format_date(time(), 'custom', 'n'),

                     'day'=> format_date(time(), 'custom', 'j'),

                     'year'=> format_date(time(), 'custom', 'Y'),

                     ),

              );

日期元素的常用属性如下：#attributes, #default_value, #description, #prefix, #required,#suffix, #title, 和#weight.属性#process默认设为expand_date()，在该方法中年选择器被硬编码为从1900到2050。属性#element_validate默认设为date_validate()（两个函数都位于includes/form.inc中）。当你在表单中定义日期元素时，通过定义这些属性,就使用你自己的代码来替代默认的了。

fieldset

描述: 字段集。

属性: #access,#after_build,#attributes,#collapsed(default: FALSE), #collapsible(default: FALSE), #description,#element_validate,#parents,#post_render,#prefix,#pre_render,#process,#states,#suffix,#theme,#theme_wrappers,#title,#title_display,#tree,#type,#weight

使用例子:

 <?php
$form['contact'] = array(
  '#type' => 'fieldset',
  '#title' => t('Contact settings'),
  '#weight' => 5,
  '#collapsible' => TRUE,
  '#collapsed' => FALSE,
);
?>

效果:

Drupal专业开发指南中示例:

字段集元素是用来对其它表单元素进行归类分组的。可将其声明为可伸缩的，这样当用户查看表单并点击字段集标题时，由Drupal自动提供的JavaScript能够动态的打开和关闭字段集。注意，在这个例子中，属性#access用来允许或拒绝访问字段集中的所有字段：

// Node author information for administrators.

$form['author'] = array(

'#type' => 'fieldset',

'#access' => user_access('administer nodes'),

'#title' => t('Authoring information'),

'#collapsible' => TRUE,

'#collapsed' => TRUE,

'#weight' => 20,

);

访问字段集中的所字段集元素的常用属性如下：#attributes, #collapsed (默认为 FALSE), #collapsible (默认为 FALSE), #description, #prefix, #suffix, #title, #process(默认为form_expand_ahah)，和 #weight

file

描述: 格式的文件上传字段。

注意，如果你使用了文件元素，那么你需要在你表单的根部设置属性enctype：$form['#attributes']['enctype']= 'multipart/form-data';

属性: #access,#after_build,#array_parents,#attached,#attributes,#description,#disabled,#element_validate,#parents,#post_render,#prefix,#pre_render,#process,#required,#size(default: 60), #states,#suffix,#theme,#theme_wrappers,#title,#title_display,#tree,#type,#weight

使用例子:

 <?php
$element['upload'] = array(
    '#name' => 'files[' . implode('_', $element['#parents']) . ']',
    '#type' => 'file',
    '#title' => t('Choose a file'),
    '#title_display'=> 'invisible',
    '#size' => 22,
    '#theme_wrappers'=> array(),
    '#weight' => -10,
  );
?>

Drupal专业开发指南中示例:

$form['picture']['picture_upload']= array(

'#type' => 'file',

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

'#size' => 48,

'#description' => t('Yourvirtual face or picture.')

);

效果:

(未完待续。。。)