# 表单辅助函数

表单辅助函数包含了一些函数用于帮助你处理表单。

- 加载辅助函数
- 对域值转义
- 可用函数

## 加载辅助函数

使用下面的代码来加载表单辅助函数:

    $this->load->helper('form');

## 对域值转义

你可能会需要在表单元素中使用 HTML 或者诸如引号这样的字符，为了安全性， 你需要使用 通用函数 `html_escape()` 。

考虑下面这个例子:

    $string = 'Here is a string containing "quoted" text.';

    <input type="text" name="myfield" value="<?php echo $string; ?>" />

因为上面的字符串中包含了一对引号，它会破坏表单，使用 `html_escape()` 函数可以对 HTML 的特殊字符进行转义，从而可以安全的在域值中使用字符串:

    <input type="text" name="myfield" value="<?php echo html_escape($string); ?>" />

注解

如果你使用了这个页面上介绍的任何一个函数，表单的域值会被自动转义， 所以你无需再调用这个函数。只有在你创建自己的表单元素时需要使用它。

## 可用函数

该辅助函数有下列可用函数：

`form_open`([$action = ''[, $attributes = ''[, $hidden = array()]]])

  参数: | $action (string) -- Form action/target URI string $attributes (array) -- HTML attributes $hidden (array) -- An array of hidden fields' definitions
  返回: | An HTML form opening tag
  返回类型: | string

  生成一个 form 起始标签，并且它的 action URL 会根据你的配置文件自动生成。 你还可以给表单添加属性和隐藏域，另外，它还会根据你配置文件中的字符集参数 自动生成 accept-charset 属性。

  使用该函数来生成标签比你自己写 HTML 代码最大的好处是：当你的 URL 变动时， 它可以提供更好的可移植性。

  这里是个简单的例子:

      echo form_open('email/send');

  上面的代码会创建一个表单，它的 action 为根 URL 加上 "email/send"，向下面这样:

      <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send">

  添加属性

  > 可以通过第二个参数传递一个关联数组来添加属性，例如:

  >     $attributes = array('class' => 'email', 'id' => 'myform');
  >     echo form_open('email/send', $attributes);

  > 另外，第二个参数你也可以直接使用字符串:

  >     echo form_open('email/send', 'class="email" id="myform"');

  > 上面的代码会创建一个类似于下面的表单:

  >     <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform">

  添加隐藏域

  > 可以通过第三个参数传递一个关联数组来添加隐藏域，例如:

  >     $hidden = array('username' => 'Joe', 'member_id' => '234');
  >     echo form_open('email/send', '', $hidden);

  > 你可以使用一个空值跳过第二个参数。

  > 上面的代码会创建一个类似于下面的表单:

  >     <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send">
  >         <input type="hidden" name="username" value="Joe" />
  >         <input type="hidden" name="member_id" value="234" />

`form_open_multipart`([$action = ''[, $attributes = array()[, $hidden = array()]]])

  参数: | $action (string) -- Form action/target URI string $attributes (array) -- HTML attributes $hidden (array) -- An array of hidden fields' definitions
  返回: | An HTML multipart form opening tag
  返回类型: | string

  这个函数和上面的 `form_open()` 函数完全一样， 只是它会给表单添加一个 multipart 属性，在你使用表单上传文件时必须使用它。

`form_hidden`($name[, $value = ''])

  参数: | $name (string) -- Field name $value (string) -- Field value
  返回: | An HTML hidden input field tag
  返回类型: | string

  生成隐藏域。你可以使用名称和值两个参数来创建一个隐藏域:

      form_hidden('username', 'johndoe');
      // Would produce: <input type="hidden" name="username" value="johndoe" />

  ... 或者你可以使用一个关联数组，来生成多个隐藏域:

      $data = array(
          'name'  => 'John Doe',
          'email' => 'john@example.com',
          'url'   => 'http://example.com'
      );

      echo form_hidden($data);

      /*
          Would produce:
          <input type="hidden" name="name" value="John Doe" />
          <input type="hidden" name="email" value="john@example.com" />
          <input type="hidden" name="url" value="http://example.com" />
      */

  你还可以向第二个参数传递一个关联数组:

      $data = array(
          'name'  => 'John Doe',
          'email' => 'john@example.com',
          'url'   => 'http://example.com'
      );

      echo form_hidden('my_array', $data);

      /*
          Would produce:

          <input type="hidden" name="my_array[name]" value="John Doe" />
          <input type="hidden" name="my_array[email]" value="john@example.com" />
          <input type="hidden" name="my_array[url]" value="http://example.com" />
      */

  如果你想创建带有其他属性的隐藏域，可以这样:

      $data = array(
          'type'  => 'hidden',
          'name'  => 'email',
          'id'    => 'hiddenemail',
          'value' => 'john@example.com',
          'class' => 'hiddenemail'
      );

      echo form_input($data);

      /*
          Would produce:

          <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" />
      */

`form_input`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML text input field tag
  返回类型: | string

  用于生成标准的文本输入框，你可以简单的使用文本域的名称和值:

      echo form_input('username', 'johndoe');

  或者使用一个关联数组，来包含任何你想要的数据:

      $data = array(
          'name'      => 'username',
          'id'        => 'username',
          'value'     => 'johndoe',
          'maxlength' => '100',
          'size'      => '50',
          'style'     => 'width:50%'
      );

      echo form_input($data);

      /*
          Would produce:

          <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%"  />
      */

  如果你还希望能包含一些额外的数据，例如 JavaScript ，你可以通过第三个参数传一个字符串:

      $js = 'onClick="some_function()"';
      echo form_input('username', 'johndoe', $js);

  Or you can pass it as an array:

      $js = array('onClick' => 'some_function();');
      echo form_input('username', 'johndoe', $js);

`form_password`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML password input field tag
  返回类型: | string

  该函数和上面的 `form_input()` 函数一样，只是生成的输入框为 "password" 类型。

`form_upload`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML file upload input field tag
  返回类型: | string

  该函数和上面的 `form_input()` 函数一样，只是生成的输入框为 "file" 类型， 可以用来上传文件。

`form_textarea`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML textarea tag
  返回类型: | string

  该函数和上面的 `form_input()` 函数一样，只是生成的输入框为 "textarea" 类型。

  注解

  对于 textarea 类型的输入框，你可以使用 rows 和 cols 属性， 来代替上面例子中的 maxlength 和 size 属性。

`form_dropdown`([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]])

  参数: | $name (string) -- Field name $options (array) -- An associative array of options to be listed $selected (array) -- List of fields to mark with the selected attribute $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML dropdown select field tag
  返回类型: | string

  用于生成一个标准的下拉框域。第一个参数为域的名称，第二个参数为一个关联数组， 包含所有的选项，第三个参数为你希望默认选中的值。你也可以把第三个参数设置成 一个包含多个值的数组，CodeIgniter 将会为你生成多选下拉框。

  例如:

      $options = array(
          'small'     => 'Small Shirt',
          'med'       => 'Medium Shirt',
          'large'     => 'Large Shirt',
          'xlarge'    => 'Extra Large Shirt',
      );

      $shirts_on_sale = array('small', 'large');
      echo form_dropdown('shirts', $options, 'large');

      /*
          Would produce:

          <select name="shirts">
              <option value="small">Small Shirt</option>
              <option value="med">Medium  Shirt</option>
              <option value="large" selected="selected">Large Shirt</option>
              <option value="xlarge">Extra Large Shirt</option>
          </select>
      */

      echo form_dropdown('shirts', $options, $shirts_on_sale);

      /*
          Would produce:

          <select name="shirts" multiple="multiple">
              <option value="small" selected="selected">Small Shirt</option>
              <option value="med">Medium  Shirt</option>
              <option value="large" selected="selected">Large Shirt</option>
              <option value="xlarge">Extra Large Shirt</option>
          </select>
      */

  如果你希望为起始标签 <select> 添加一些额外的数据，例如 id 属性或 JavaScript ， 你可以通过第四个参数传一个字符串:

      $js = 'id="shirts" onChange="some_function();"';
      echo form_dropdown('shirts', $options, 'large', $js);

  Or you can pass it as an array:

      $js = array(
          'id'       => 'shirts',
          'onChange' => 'some_function();'
      );
      echo form_dropdown('shirts', $options, 'large', $js);

  如果你传递的 `$options` 数组是个多维数组，`form_dropdown()` 函数将会生成带 <optgroup> 的下拉框，并使用数组的键作为 label 。

`form_multiselect`([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]])

  参数: | $name (string) -- Field name $options (array) -- An associative array of options to be listed $selected (array) -- List of fields to mark with the selected attribute $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML dropdown multiselect field tag
  返回类型: | string

  用于生成一个标准的多选下拉框。第一个参数为域的名称，第二个参数为一个关联数组， 包含所有的选项，第三个参数为你希望默认选中的一个或多个值。

  参数的用法和上面的 `form_dropdown()` 函数一样，只是域的名称需要使用 数组语法，例如：foo[]

`form_fieldset`([$legend_text = ''[, $attributes = array()]])

  参数: | $legend_text (string) -- Text to put in the <legend> tag $attributes (array) -- Attributes to be set on the <fieldset> tag
  返回: | An HTML fieldset opening tag
  返回类型: | string

  用于生成 fieldset 和 legend 域。

  例如:

      echo form_fieldset('Address Information');
      echo "<p>fieldset content here</p>\n";
      echo form_fieldset_close();

      /*
          Produces:

              <fieldset>
                  <legend>Address Information</legend>
                      <p>form content here</p>
              </fieldset>
      */

  和其他的函数类似，你也可以通过给第二个参数传一个关联数组来添加额外的属性:

      $attributes = array(
          'id'    => 'address_info',
          'class' => 'address_info'
      );

      echo form_fieldset('Address Information', $attributes);
      echo "<p>fieldset content here</p>\n";
      echo form_fieldset_close();

      /*
          Produces:

          <fieldset id="address_info" class="address_info">
              <legend>Address Information</legend>
              <p>form content here</p>
          </fieldset>
      */

`form_fieldset_close`([$extra = ''])

  参数: | $extra (string) -- Anything to append after the closing tag, as is
  返回: | An HTML fieldset closing tag
  返回类型: | string

  用于生成结束标签 </fieldset> ，使用这个函数唯一的一个好处是， 它可以在结束标签的后面加上一些其他的数据。例如：

      $string = '</div></div>';
      echo form_fieldset_close($string);
      // Would produce: </fieldset></div></div>

`form_checkbox`([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $checked (bool) -- Whether to mark the checkbox as being checked $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML checkbox input tag
  返回类型: | string

  用于生成一个复选框，例如:

      echo form_checkbox('newsletter', 'accept', TRUE);
      // Would produce:  <input type="checkbox" name="newsletter" value="accept" checked="checked" />

  第三个参数为布尔值 TRUE 或 FALSE ，用于指定复选框默认是否为选定状态。

  和其他函数一样，你可以传一个属性的数组给它:

      $data = array(
          'name'      => 'newsletter',
          'id'        => 'newsletter',
          'value'     => 'accept',
          'checked'   => TRUE,
          'style'     => 'margin:10px'
      );

      echo form_checkbox($data);
      // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" />

  另外，如果你希望向标签中添加额外的数据如 JavaScript ，也可以传一个字符串给第四个参数:

      $js = 'onClick="some_function()"';
      echo form_checkbox('newsletter', 'accept', TRUE, $js);

  Or you can pass it as an array:

      $js = array('onClick' => 'some_function();');
      echo form_checkbox('newsletter', 'accept', TRUE, $js);

`form_radio`([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]])

  参数: | $data (array) -- Field attributes data $value (string) -- Field value $checked (bool) -- Whether to mark the radio button as being checked $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML radio input tag
  返回类型: | string

  该函数和 `form_checkbox()` 函数完全一样，只是它生成的是单选框。

`form_label`([$label_text = ''[, $id = ''[, $attributes = array()]]])

  参数: | $label_text (string) -- Text to put in the <label> tag $id (string) -- ID of the form element that we're making a label for $attributes (string) -- HTML attributes
  返回: | An HTML field label tag
  返回类型: | string

  生成 <label> 标签，例如:

      echo form_label('What is your Name', 'username');
      // Would produce:  <label for="username">What is your Name</label>

  和其他的函数一样，如果你想添加额外的属性的话，可以传一个关联数组给第三个参数。

  例如:

      $attributes = array(
          'class' => 'mycustomclass',
          'style' => 'color: #000;'
      );

      echo form_label('What is your Name', 'username', $attributes);
      // Would produce:  <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label>

`form_submit`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (string) -- Button name $value (string) -- Button value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML input submit tag
  返回类型: | string

  用于生成一个标准的提交按钮。例如:

      echo form_submit('mysubmit', 'Submit Post!');
      // Would produce:  <input type="submit" name="mysubmit" value="Submit Post!" />

  和其他的函数一样，如果你想添加额外的属性的话，可以传一个关联数组给第一个参数， 第三个参数可以向表单添加额外的数据，例如 JavaScript 。

`form_reset`([$data = ''[, $value = ''[, $extra = '']]])

  参数: | $data (string) -- Button name $value (string) -- Button value $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML input reset button tag
  返回类型: | string

  用于生成一个标准的重置按钮。用法和 `form_submit()` 函数一样。

`form_button`([$data = ''[, $content = ''[, $extra = '']]])

  参数: | $data (string) -- Button name $content (string) -- Button label $extra (mixed) -- Extra attributes to be added to the tag either as an array or a literal string
  返回: | An HTML button tag
  返回类型: | string

  用于生成一个标准的按钮，你可以简单的使用名称和内容来生成按钮:

      echo form_button('name','content');
      // Would produce: <button name="name" type="button">Content</button>

  或者使用一个关联数组，来包含任何你想要的数据:

      $data = array(
          'name'      => 'button',
          'id'        => 'button',
          'value'     => 'true',
          'type'      => 'reset',
          'content'   => 'Reset'
      );

      echo form_button($data);
      // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button>

  如果你还希望能包含一些额外的数据，例如 JavaScript ，你可以通过第三个参数传一个字符串:

      $js = 'onClick="some_function()"';
      echo form_button('mybutton', 'Click Me', $js);

`form_close`([$extra = ''])

  参数: | $extra (string) -- Anything to append after the closing tag, as is
  返回: | An HTML form closing tag
  返回类型: | string

  用于生成结束标签 </form> ，使用这个函数唯一的一个好处是， 它可以在结束标签的后面加上一些其他的数据。例如：

  > $string = '</div></div>'; echo form_close($string); // Would produce: </form> </div></div>

`set_value`($field[, $default = ''[, $html_escape = TRUE]])

  参数: | $field (string) -- Field name $default (string) -- Default value $html_escape (bool) -- Whether to turn off HTML escaping of the value
  返回: | Field value
  返回类型: | string

  用于你显示 input 或者 textarea 类型的输入框的值。你必须在第一个参数中指定名称， 第二个参数是可选的，允许你设置一个默认值，第三个参数也是可选，可以禁用对值的转义， 当你在和 `form_input()` 函数一起使用时，可以避免重复转义。

  例如:

      <input type="text" name="quantity" value="<?php echo set_value('quantity', '0'); ?>" size="50" />

  当上面的表单元素第一次加载时将会显示“0”。

  注解

  If you've loaded the 表单验证类 and have set a validation rule for the field name in use with this helper, then it will forward the call to the 表单验证类's own `set_value()` method. Otherwise, this function looks in `$_POST` for the field value.

`set_select`($field[, $value = ''[, $default = FALSE]])

  参数: | $field (string) -- Field name $value (string) -- Value to check for $default (string) -- Whether the value is also a default one
  返回: | 'selected' attribute or an empty string
  返回类型: | string

  如果你使用 <select> 下拉菜单，此函数允许你显示选中的菜单项。

  第一个参数为下拉菜单的名称，第二个参数必须包含每个菜单项的值。 第三个参数是可选的，用于设置菜单项是否为默认选中状态（TRUE / FALSE）。

  例如:

      <select name="myselect">
          <option value="one" <?php echo  set_select('myselect', 'one', TRUE); ?> >One</option>
          <option value="two" <?php echo  set_select('myselect', 'two'); ?> >Two</option>
          <option value="three" <?php echo  set_select('myselect', 'three'); ?> >Three</option>
      </select>

`set_checkbox`($field[, $value = ''[, $default = FALSE]])

  参数: | $field (string) -- Field name $value (string) -- Value to check for $default (string) -- Whether the value is also a default one
  返回: | 'checked' attribute or an empty string
  返回类型: | string

  允许你显示一个处于提交状态的复选框。

  第一个参数必须包含此复选框的名称，第二个参数必须包含它的值， 第三个参数是可选的，用于设置复选框是否为默认选中状态（TRUE / FALSE）。

  例如:

      <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> />
      <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> />

`set_radio`($field[, $value = ''[, $default = FALSE]])

  参数: | $field (string) -- Field name $value (string) -- Value to check for $default (string) -- Whether the value is also a default one
  返回: | 'checked' attribute or an empty string
  返回类型: | string

  允许你显示那些处于提交状态的单选框。 该函数和上面的 `set_checkbox()` 函数一样。

  例如:

      <input type="radio" name="myradio" value="1" <?php echo  set_radio('myradio', '1', TRUE); ?> />
      <input type="radio" name="myradio" value="2" <?php echo  set_radio('myradio', '2'); ?> />

  注解

  如果你正在使用表单验证类，你必须为你的每一个表单域指定一个规则， 即使是空的，这样可以确保 `set_*()` 函数能正常运行。 这是因为如果定义了一个表单验证对象，`set_*()` 函数的控制权将移交到表单验证类， 而不是辅助函数函数。

`form_error`([$field = ''[, $prefix = ''[, $suffix = '']]])

  参数: | $field (string) -- Field name $prefix (string) -- Error opening tag $suffix (string) -- Error closing tag
  返回: | HTML-formatted form validation error message(s)
  返回类型: | string

  从 表单验证类 返回验证错误消息， 并附上验证出错的域的名称，你可以设置错误消息的起始和结束标签。

  例如:

      // Assuming that the 'username' field value was incorrect:
      echo form_error('myfield', '<div class="error">', '</div>');

      // Would produce: <div class="error">Error message associated with the "username" field.</div>

`validation_errors`([$prefix = ''[, $suffix = '']])

  参数: | $prefix (string) -- Error opening tag $suffix (string) -- Error closing tag
  返回: | HTML-formatted form validation error message(s)
  返回类型: | string

  和 `form_error()` 函数类似，返回所有 表单验证类 生成的错误信息，你可以为为每个错误消息设置起始和结束标签。

  例如:

      echo validation_errors('<span class="error">', '</span>');

      /*
          Would produce, e.g.:

          <span class="error">The "email" field doesn't contain a valid e-mail address!</span>
          <span class="error">The "password" field doesn't match the "repeat_password" field!</span>

       */

`form_prep`($str)

  参数: | $str (string) -- Value to escape
  返回: | Escaped value
  返回类型: | string

  允许你在表单元素中安全的使用 HTML 和例如引号这样的字符，而不用担心对表单造成破坏。

  注解

  如果你使用了这个页面上介绍的任何一个函数，表单的域值会被自动转义， 所以你无需再调用这个函数。只有在你创建自己的表单元素时需要使用它。

  注解

  该函数已经废弃，现在只是 通用函数 `html_escape()` 的一个别名，请使用 `html_escape()` 代替它。