FuelPHP，PHP 5.3 框架 简体中文手册

forge($name = 'default', $config = array())

forge 方法回傳一个新的 Fieldset 實例。注意：每个 $name 只能有一个實例。

'default'

$article_form = Fieldset::forge('article');

當建構一个 Fieldset 物件時，你可以傳遞一个允許你用自訂配置來設置物件的配置陣列。 支援以下項目：

null

null

除了这些欄位，你可以傳遞自訂表单配置來修改 Fieldset 產生表单的方式。 對於有效的配置值，看看 form.php 配置档案。

instance($instance = null)

回傳一个指定的實例，或預設實例（如果必要時建立）。

null

$article_form = Fieldset::instance('article');

validation()

取得 Validation 實例給目前的 Fieldset。建立該 Validation 實例如果它還不存在。

$validation = $article_form->validation();

form()

取得 Form 實例給目前的 Fieldset。建立該 Form 實例如果它還不存在。

$form = $article_form->form();

add($name, $label = '', array $attributes = array(), array $rules = array())

建立一个 Fieldset_Field 實例并添加到目前的 Fieldset。

''

array()

array()

$title_field = $article_form->add('article_title', 'Title', array('class' => 'pretty_input'));

// Radio 範例
$ops = array('male', 'female');
$form->add(
	'gender', '',
	array('options' => $ops, 'type' => 'radio', 'value' => 'true')
);

// Checkbox 範例
$ops = array('male', 'female');
$form->add(
	'gender', '',
	array('options' => $ops, 'type' => 'checkbox', 'value' => 'true')
);

// Email input 範例，使用驗證規則
$form->add(
	'email', 'E-mail',
	array('type' => 'email', 'class' => 'pretty_input'),
	array('required', 'valid_email')
);

// text input 範例，使用陣列表示的驗證規則
$form->add(
	'name', 'Full name',
	array('type' => 'name', 'class' => 'pretty_input'),
	array(array('required'), array('valid_string', array('alpha-numeric', 'dots', 'spaces')))
);

delete($name)

從 Fieldset 移除一个具名的 Fieldset_Field 實例。

$fieldset->delete('article_title');

add_before($name, $label = '', array $attributes = array(), array $rules = array(), $fieldname = null)

建立一个 Fieldset_Field 實例并添加它到目前的 Fieldset，就在已定義的透過 $fieldname 識別的欄位之前。

''

array()

array()

null

// Radio 按鈕欄位，被添加在 'location' 欄位之前。
$ops = array('male', 'female');
$form->add_before('gender', '', array('options' => $ops, 'type' => 'radio', 'value' => 'true'), array(), 'location');

add_after($name, $label = '', array $attributes = array(), array $rules = array(), $fieldname = null)

建立一个 Fieldset_Field 實例并添加它到目前的 Fieldset，就在已定義的透過 $fieldname 識別的欄位之後。

''

array()

array()

null

// Radio 按鈕欄位，被添加在 'location' 欄位之後。
$ops = array('male', 'female');
$form->add_after('gender', '', array('options' => $ops, 'type' => 'radio', 'value' => 'true'), array(), 'location');

field($name = null)

Gets one or all Fieldset_Field instances for the current Fieldset.

null

$fields = $article_form->field();
$title_field = $article_form->field('article_title');

add_model($class, $instance = null, $method = 'set_form_fields')

Add a model's fields. The model must have a method set_form_fields() that takes this Fieldset instance and adds fields to it.
Orm\Model have support this build in.

null

'set_form_fields'

$article_form = Fieldset::forge('article');
$article_form->add_model('Model_Article');

set_config($config, $value = null)

在 Fieldset 設定一个配置值。

null

$article_form->set_config($config);

// 或

$article_form->set_config('key', 'value');

get_config($key = null, $default = null)

透過鍵取得配置陣列的一个或更多配置值。

null

null

$config = $article_form->get_config();

get_name()

取得 Fieldset 實例識別。

$article_form = Fieldset::forge('article');
$name = $article_form->get_name();  // 'article'

populate($input, $repopulate = false)

Set initial field values to the given input, optionally set it to repopulate after that as well.

$article_form->populate($model);

repopulate()

Set all field values to the input send by a form submission (uses the form method attribute to decide whether to check POST or GET).

$article_form->repopulate();

build($action = null)

Alias for $this->form()->build() for this fieldset. Generates the HTML form markup. See Form.

null

$this->template->form = $article_form->build(Uri::create('article/submit'));

disable($field)

The disable method allows you to disable a field from being build. You can use this if you want to alter the sequence of fields on the form, or to create more complex layouts without having to build individual fields.

$fieldset->disable('name');

The field is not removed from the fieldset, so it will still be validated.

enable($field)

enable 方法能让你重新啟用之前已经被停用的欄位。

$fieldset->enable('name');

input($field = null)

$this->validation()->input() 的別名。取得一个驗證過的來自 POST 或所給輸入的輸入值陣列。詳見 Validation。

null

$input_values = $article_form->input();

validated($field = null)

$this->validation()->validated() 的別名。取得一个通過驗證的輸入值陣列。詳見 Validation。

null

$validated_values = $article_form->validated();

error($field = null)

$this->validation()->error() 的別名。取得一个沒通過驗證的輸入值陣列。詳見 Validation。

null

$errors = $article_form->error();

show_errors(Array $config = array())

$this->validation()->show_errors() 的別名。回傳列表中的所有错误，或帶來自 $config 參数的設定标記。詳見 Validation。

array()

$all_errors = $article_form->show_errors();

set_tabular_form($model, $relation, $parent, $blanks = 1)

Define an embedded fieldset on a related ORM model to create a One-to-Many form.

1

The tabular form is displayed in a table, controlled by template definitions in the config/form.php configuration file. You are free to modify these templates, but you should leave the table structure, as the fieldset class will add the table headers based on the fields present in each row. This will generate invalid HTML if you remove the table and row definition from the template.

get_tabular_form()

回傳定義的表格式表单的名稱。

if ($name = $form->get_tabular_form())
{
	echo '$form is a tabular fieldset named', $name;
}

使用 ORM 模型建立表单

The Fieldset class can be used to create forms from ORM models. The following example will build a form based on the fields specified in $_properties of your model. In the example, $article is an instance of Model_Article.

echo Fieldset::forge('article')->add_model($article)->populate($article, true)->build();

If you do not wish every property of the model to be on your form, you can set the form type of those to false and they will not be generated.
This actually uses the Observer_Validation behind the scenes, but you do not need to add it as an observer for this to work.

Creating One-to-Many forms with ORM Models

The Fieldset class can also be used to create forms for an ORM model object and a Many relation. This is done by embedding a tabular form fieldset into the main form fieldset, specifying the related model and the name of the relation.

By default, the One-to-Many fieldset is displayed in tabular form, controlled by the template in the config/form.php file.

// We're going to create a one-to-many form of an article, identified by $id, and it's comments

// get the article and it's related comments
$article = Model_Article::find($id, array('related' => array('comments')));

// create the form fieldset for this article using the ORM model's form definition
$form = Fieldset::forge('article')->add_model($article);

/*
 * add the tabular form to it to create the one-to-many table.
 *
 * the data is provided by the relation 'comments' of the $article object, which
 * are objects of the class 'Model_Comment'.
 *
 * you can disable the fieldset tag to avoid embedded fieldsets in your form
 */
$form->add(\Fieldset::forge('tabular')->set_tabular_form('Model_Comment', 'comments', $article)->set_fieldset_tag(false));
				

这只適用於沒有複合鍵的關聯模型！

A tabular form generates HTML input tags that use an array with the name of the relation specified, and the primary key value of the record as it's index value. Any blank rows that are added at the bottom of the table will use the relation name, with a '_new' suffix. This will allow you to update the parent record, and all related records, in one go, and process the new lines separately.

In this example, you'll see input tag names like comments[12][fieldA] for existing rows (in this case a row with id = 12, and comments_new[0][fieldA] for a field in the first blank line.

// Process the posted one-to-many form
if (\Input::post())
{
	// validate the input
	$form->validation()->run();

	// if validated, save the updates
	if ( ! $form->validation()->error())
	{
		// update the article record, and any comment record changes
		$article->from_array($data);

		// do we need to delete tabular form records?
		foreach ($data['comments'] as $id => $row)
		{
			if ($id and ! empty($row['_delete']))
			{
				unset($article->comments[$id]);
			}
		}

		// do we have a new tabular form record data (assuming we've added only one blank line)?
		$data = array_filter($data['comments_new'][0]);

		$new_errors = false;
		if ( ! empty($data))
		{
			// check for required fields
			if (empty($data['fieldA']) or empty($data['fieldB']))
			{
				$new_errors = true;
				// display an error message about missing required fields here...
			}
			else
			{
				// create a new related record
				$article->comments[] = Model_Comment::forge(array('article_id' => $article->id, 'fieldA' => $data['fieldA'], 'fieldB' => $data['fieldB']));
			}
		}

		// save the updates
		if ( ! $new_errors)
		{
			if ($article->save())
			{
				// display a save-succesful message here and redirect away
			}
			else
			{
				// display an error message, save was not succesful
			}
		}
	}
	else
	{
		// inform the user validation failed
	}
}

表单屬性

The layout of the forms generated by the fieldset is controlled by the form.php configuration file.

以下配置值可以被定義：

true

true

'form_'

'post'

'\n\t\t{open}
\n\t\t<table>\n{fields}\n\t\t</table>
\n\t\t{close}\n'

'\t\t<tr>
\n\t\t\t<td class=\"{error_class}\">
{label}{required}</td>
\n\t\t\t<td class=\"{error_class}\">{field}
<span>{description}</span> {error_msg}
</td>\n\t\t</tr>\n'

'\t\t<tr>
\n\t\t\t<td class=\"{error_class}\">
{group_label}{required}</td>
\n\t\t\t<td class=\"{error_class}\">{fields}
\n\t\t\t\t{field} {label}
\n{fields}<span>{description}</span>
\t\t\t{error_msg}\n\t\t\t</td>\n\t\t</tr>\n'

'<span>{error_msg}</span>'

'<span>{label}</span>'

'*'

false

null

null

'<table>{fields}</table>\n'

'{field}'

'<tr>{fields}</tr>\n'

'\t\t\t<td>{label}{required} {field} {error_msg}</td>\n'

'Delete?'

表单屬性巨集

以下巨集可被用在表单樣板。

修改表单屬性

變更在 Fieldset 中 form() 實例的屬性可用兩種方式辦到。你可以在 forge() 方法的屬性陣列中提供你的選項，或直接修改 Form 實例。

// 在 Fieldset 物件的屬性中使用 form_attributes 選項
$fieldset = Fieldset::forge('article', array(
	'form_attributes' => array(
		'id' => 'edit_article_form',
		'name' => 'edit_article'
		)
	)
);

// 直接修改表单實例
$fieldset->form()->set_attribute('id', 'edit_article_form');