表单辅助函数

表单辅助函数为创建表单提供辅助方法。它不会对数据做验证或过滤。如果你想为表单进行验证或过滤，你可以配合使用 Forge 库（译者住：这个官方应该没有修改，Forge 库已经从 Kohana 2.2 版本移除，大家可以使用系统默认的 校验库（Validation Library））。

如果只需要插入下面的一行代码就可以开始创建表单：

print form::open(string $submit, array $attr, array $hidden );

变量 $submit 是一个像 '/class/method' 这样的相对的 URL。$attr 是一个数组形式的表单属性，比如 ('id' ⇒ 'forumid', 'class'⇒'login_form')。$hidden 是一个隐藏表单字段的数组。这三个参数都可以为空。如果你不设置第一个参数，提交的 URL 则会是当前控制器方法的相对页面。

您可以使用 HTML 语句添加表单字段，也可以使用 Kohana 预置的语句添加，下面是一些例子：

print form::dropdown($data, $options, $selected)
print form::textarea($data)
print form::input($data)

创建一个表单，你只需要使用默认值，用 POST 提交表达当当前页面。

print form::open()

要添加属性：

// 设置提交页面： domain.tld/products/search.html
// 附加 CSS 类 'search_form'
print form::open('products/search', array('class'=>'search_form'));
 
// 提交当前页面，并添加一个隐藏类型的名为  'type' 值为 'product' 输入框
print form::open(NULL, array(), array('type'=>'product'));
 
// 使用 GET 的方法提交到当前页面
print form::open(NULL, array('method'=>'get'));

通过 POST 打开一个提交二进制数据的表单。你可以使用 'multipart/form-data' 指定编码类型。

实例:

// 提交多部分的表单数据到当前页面
print form::open(NULL, array('enctype' => 'multipart/form-data'));

返回结果（HTML）

<form action="http://localhost/index.php/welcome" enctype="multipart/form-data" method="post">

创建 HTML 的输入类型的标签。默认为文本类型，参数：

• [string]/[array] 输入数据的名称和 id 或者以数组的形式输入
• [string] 当使用名称时赋予的 input 的值
• [string] 额外的字符串附加到属性的末尾
• [bool] 编码存在的 html 实体 （默认为 TRUE）

实例:

print form::input('field_name', 'field_value', ' style="text-align: right;"');

返回结果（HTML）

<input type="text" id="field_name" name="field_name" value="field_value" style="text-align: right;" />

不需要使用所有的参数。

实例：

print form::input(); // 没有使用参数
print form::input('field_name'); // 仅使用了一个参数 - 名称和 id
print form::input('field_name', 'field_value'); // 仅使用了两个参数 - 名称和 id 以及值

返回结果（HTML）

<input type="text" id="" name="" value="" />
<input type="text" id="field_name" name="field_name" value="" />
<input type="text" id="field_name" name="field_name" value="field_value" />

'hidden' 创建一个隐藏类型的字段，参数：

• [string]/[array] 键属性的数据
• [string] 字段的值 - 默认 = ””

实例:

// 注意，print() 方法只是为了调试显示结果
print Kohana::debug(form::hidden("fieldName","fieldValue"));
$array=array('field1'=>'value1','field2'=>'value2');
print Kohana::debug(form::hidden($array));

返回结果（HTML）

<input type="hidden" id="fieldName" name="fieldName" value="fieldValue" />
 
<input type="hidden" id="field1" name="field1" value="value1" />
<input type="hidden" id="field2" name="field2" value="value2" />

'password' 创建一个密码类型的字段，参数：

• [string]/[array] 键属性的数据
• [string] 字段的值 - 默认 = ””
• [string] 附加额外的字符串到属性的末尾 – 默认 = ””

实例:

// 注意，print() 方法只是为了调试显示结果
print Kohana::debug(form::password("fieldName","fieldValue"));
print Kohana::debug(form::password("fieldName","fieldValue",' id="fieldId"'));
$array=array('name'=>'fieldName','value'=>'fieldValue','id'=>'fieldId','class'=>'formField');
print Kohana::debug(form::password($array));

返回结果（HTML）

<input type="password" id="fieldName" name="fieldName" value="fieldValue" />
 
<input type="password" id="fieldName" name="fieldName" value="fieldValue"id="fieldId" />
 
<input type="password" id="fieldId" name="fieldName" value="fieldValue" class="formField" />

创建一个上传文件类型的输入标签。参数：

• [string]/[array] - 属性名或数组性的属性
• [string] - 属性值[可选]
• [string] - 额外附加[可选]

实例

$attributes = array('name' => 'file_1', 'class' => 'your-class');
echo form::upload($attributes, 'path/to/local/file')

返回结果（HTML）

<input type="file" name="file_1" value="path/to/local/file" class="your-class" />

创建文本区便签：

print form::textarea(string/array $data, string $value)

参数：

• [string]/[array] 文本区的名称或以数组形式
• [string] 当使用名称是文本区的值
• [string] 附加额外的字符串到属性的末尾
• [bool] 编码存在的 html 实体 （默认为 TRUE）

实例

print form::textarea('field_name', 'field_value');

返回结果（HTML）

<textarea id="field_name" name="field_name">field_value</textarea>

也尅使用数组的形式写第一个参数：

print form::textarea(array('name' => 'field_name', 'value' => 'field_value', 'class' => 'our_class'));

返回结果（HTML）

<textarea id="field_name" name="field_name" class="our_class">field_value</textarea>

创建下拉框标签，参数：

• [string|array] input name or array of HTML attributes
• [array] the select options, when using input name
• [string|array] the option or an array of options to be selected by default
• [string] extra string to be added to the end of the attributes – default = ””

实例:

$selection = array('basic' =>'Basic', 'standard' => 'Standard', 'custom' => 'Custom');
// The 'standard' option will be the default selection
print form::dropdown('input_dropdown',$selection,'standard');
 
$selection = array('basic' =>'Basic', 'standard' => 'Standard', 'custom' => 'Custom', 'something' => 'Something');
print form::dropdown(array('name' => 'input_dropdown', 'multiple' => 'multiple', 'size' => 4), $selection, array('standard', 'basic'));
 
$selection = array('basic' =>array('basic1' => 'Basic1', 'basic2' => 'Basic2'), 'standard' => 'Standard', 'custom' => 'Custom', 'something' => 'Something');
print form::dropdown(array('name' => 'input_dropdown', 'multiple' => 'multiple', 'size' => 6), $selection, array('standard', 'basic1'));

浏览器输出

<select id="input_dropdown" name="input_dropdown">
<option value="basic">Basic</option>
<option selected="selected" value="standard">Standard</option>
<option value="custom">Custom</option>
</select>
 
<select id="input_dropdown" multiple="multiple" size="4" name="input_dropdown"> 
<option selected="selected" value="basic">Basic</option> 
<option selected="selected" value="standard">Standard</option> 
<option value="custom">Custom</option> 
<option value="something">Something</option> 
</select> 
 
<select id="input_dropdown" multiple="multiple" size="6" name="input_dropdown"> 
<optgroup label="basic"> 
<option selected="selected" value="basic1">Basic1</option> 
<option value="basic2">Basic2</option> 
</optgroup> 
<option selected="selected" value="standard">Standard</option> 
<option value="custom">Custom</option> 
<option value="something">Something</option> 
</select>

Creates a 'tick box' type selection box.

The parameters are:

• [string/array] input name or an array of HTML attributes
• [string] input value, when using a name
• [boolean] make the checkbox checked by default
• [string] a string to be attached to the end of the attributes

Example:

print form::label('check_spam_box', 'Always send me Spam (Opt in): ');
print form::checkbox('check_spam_box', 'send_spam');
print form::label('check_money_box', 'Never send me Money (Opt out): ');
print form::checkbox('check_money_box', 'send_no_money', TRUE);

返回结果（HTML）

<label for="check_spam_box">Always send me Spam (Opt in): </label>
<input type="checkbox" id="check_spam_box" name="check_spam_box" value="send_spam" />
<label for="check_money_box">Never send me Money (Opt out): </label>
<input type="checkbox" id="check_money_box" name="check_money_box" value="send_no_money" checked="checked" />

浏览器输出：

Always send me Spam (Opt in): Never send me Money (Opt out):

Generates a 'radio' type selection box, similar to checkbox, but allows for easier multiple selections.

The parameters are:

• [string/array] input name or an array of HTML attributes
• [string] input value, when using a name
• [boolean] make the radio selected by default
• [string] a string to be attached to the end of the attributes

Example:

print form::label('radio_cute_box', 'I am cute: ');
print form::radio('radio_cute_box', 'is_cute').'<br />';
print form::label('radio_single_box', 'I am single: ');
print form::radio('radio_single_box', 'is_single', TRUE).'<br />';
print form::label('radio_rich_box', 'I am rich: ');
print form::radio('radio_rich_box', 'is_rich').'<br />';

Results in HTML

<label for="radio_cute_box">I am cute: </label>
<input type="radio" name="radio_cute_box" value="is_cute" /><br />
<label for="radio_single_box">I am single: </label>
<input type="radio" name="radio_single_box" value="is_single" checked="checked" /><br />
<label for="radio_rich_box">I am rich: </label>
<input type="radio" name="radio_rich_box" value="is_rich" /><br />

Browser output

I am cute: （）
I am single: （*）
I am rich: （）

Creates a 'submit' type button for the form.

The parameters are:

• [string/array] input name or an array of HTML attributes
• [string] input value, when using a name
• [string] a string to be attached to the end of the attributes

Example:

print form::submit('submit', 'Send');

Results in HTML

<input type="submit" id="submit" name="submit" value="Send" />

Creates a button for the form. Note this is not the same as the button associated with input type 'submit' or 'reset'.

The parameters are:

• [string/array] input name or an array of HTML attributes
• [string] input value, when using a name
• [string] a string to be attached to the end of the attributes

Example:

print form::button('button', 'Does not do Much');

Results in HTML

<button type="button" id="button" name="button">Does not do Much</button>

Creates a label for a form entry field.

The parameters are:

• [string/array] label “for” name or an array of HTML attributes
• [string] label text or HTML
• [string] a string to be attached to the end of the attributes

Example:

print form::label('imageup', 'Image Uploads');

Results in HTML

<label for="imageup">Image Uploads</label>

Returns an attribute string, from an array of HTML attributes in key/value format, sorted by form attributes first.

The parameters are:

• [array] HTML attributes array

Example:

print form::attributes(array('id' => 'input_name', 'class' => 'submission'));

Outputs

id="input_name" class="submission"

Creates a fieldset opening tag. The fieldset HTML element is used to logically group together elements in a form, and draw a box around them.

The parameters are:

• [array] an array of HTML attributes
• [string] a string to be attached to the end of the attributes

Example:

print form::open_fieldset(array('class' => 'important'));

Results in HTML

<fieldset class="important">

Generates a fieldset closing tag

Example:

print form::close_fieldset();

Results in HTML

</fieldset>

Creates a legend for describing a fieldset.

The parameters are:

• [string] legend text or HTML
• [array] an array of HTML attributes
• [string] a string to be attached to the end of the attributes

Example:

print form::legend('More about you', array('id' => 'more_infos'));

Results in HTML

<legend id="more_infos">More about you</legend>

In order to close the form, you simply need to:

print form::close()

Or you can set parameter:

print form::close('</div>')

Result in HTML:

</form></div>