Fieldset_Field - 类別

优质

小牛编辑

139浏览

2023-12-01

The Fieldset_Field class defines a single field inside a fieldset. It defines the type of field, how the field should be rendered, and which validation rules should be used when validating field input.

Although it is technically possible to create stand-alone Fieldset_Field instances, normally they will be created as part of a Fieldset, using the Fieldsets add_field() method.

set_fieldset(Fieldset $fieldset)

If you have created a standalone Fieldset_Field object (i.e. not via the Fieldset class), you can use the set_fieldset method to assign the field object to a fieldset object.

静态否

参数

参数	预设	描述
`$fieldset`	必要	Instance of Fieldset you want to assign this Field object to.

回传 Fieldset_Field 物件，鍊结用

範例

$fieldset = \Fieldset::forge('myfieldset');
$field = new \Fieldset_Field('client', 'Name of the client');
$field->set_fieldset($fieldset);

set_label($label)

Set or change the label of a field.

静态否

参数

参数	预设	描述
`$label`	必要	Label to be displayed for the field when generating the HTML for this field.

回传 Fieldset_Field 物件，鍊结用

範例

$fieldset->field('fieldname')->set_label('New Label');

set_type($type)

Set or change the HTML form field type.

静态否

参数

参数	预设	描述
`$type`	必要	Input field type used when generating the HTML for this field.

回传 Fieldset_Field 物件，鍊结用

範例

// will generate <input type="hidden"... >
$fieldset->field('fieldname')->set_type('hidden');

set_value($value, $repopulate = false)

Set or changes the value of the field. For radio buttons and checkboxes, you can choose to repopulate, which will recalculate the "checked" value of the field based on the current and the passed value.

静态否

参数

参数	预设	描述
`$type`	必要	Input field type used when generating the HTML for this field.
`$repopulate`	`false`	If true, the field will be repopulated based on the value (only for radio buttons and checkboxes).

回传 Fieldset_Field 物件，鍊结用

範例

$fieldset->field('fieldname')->set_value('this is the new value');

set_description($description)

Set or changes the fields description. The description is mapped to the {description} ta in the form field template, and can for example be used to display a help text.

静态否

参数

参数	预设	描述
`$description`	必要	栏位描述。

回传 Fieldset_Field 物件，鍊结用

範例

$fieldset
	->field('fieldname')
	->set_description('We would like you to enter something here');

set_template($template = null)

Sets or resets a custom form field template for this field.

静态否

参数

参数	预设	描述
`$template`	`null`	The template to be used to render the HTML for this field.

回传 Fieldset_Field 物件，鍊结用

範例

$fieldset
	->field('fieldname')
	->set_template('<div class=\"{error_class}\">{label}{required}</div><div class="field-fieldname">{field} {description} {error_msg}</div>');

If you don't pass anything, or pass null, the default field template as defined in the form.php config file will be used.

set_error_message($rule, $msg)

Set a custom error message for a specific validation rule.

静态否

参数

参数	预设	描述
`$rule`	必要	Validation rule for which you want to override the default error message.
`$msg`	必要	The message to display. You can use :label as a placeholder for the field label, and :param:<number> for the parameters passed to the rule.

回传 Fieldset_Field 物件，鍊结用

範例

// set a custom error message for the "valid_string" validation rule
$fieldset
	->field('fieldname')
	->set_error_message('valid_string', ':label must contain both upper and lowercase characters!');

// set a custom error message for "exact_length"

$fieldset
	->field('fieldname')
	->set_error_message('exact_length', ':label is not exactly :param:1 long!');

get_error_message($rule)

Checks if a custom message for a validation rule is defined, and if so, the message is returned.

静态否

参数

参数	预设	描述
`$rule`	必要	The name of the validation rule who's message should be fetched.

回传 Mixed, string if there is a custom message, or null if not

範例

// set a custom error message for the "valid_string" validation rule
$fieldset
	->field('fieldname')
	->set_error_message('valid_string', ':label must contain both upper and lowercase characters!');

// returns: :label must contain both upper and lowercase characters!
$message = $fieldset->field('fieldname')->get_error_message('valid_string');

add_rule($callback)

Add a validation rule to a field, either an internal validation rule identified by name, or a valid callback that validates the field.

静态否

参数

参数	预设	描述
`$callback`	必要	Either a string with a valid validation rule name, or full callback.

回传 Fieldset_Field 物件，鍊结用

範例

// set a valid_string rule on the field
$fieldset->field('fieldname')->add_rule('valid_string', array('alpha-numeric', 'dots', 'spaces'));

// and make the field required
$message = $fieldset->field('fieldname')->add_rule('required');

When you set the required rule, the "required" attribute of the form input tag will be set.

delete_rule($callback, $set_attr = true)

Removes a validation rule to a field, identified by either an internal validation rule identified by name, or a valid callback that validates the field.

静态否

参数

参数	预设	描述
`$callback`	必要	Either a string with a valid validation rule name, or full callback.
`$set_attr`	`true`	If true, attributes related to the rule are updated too.

回传 Fieldset_Field 物件，鍊结用

範例

// remove the valid_string rule from the field
$fieldset->field('fieldname')->delete_rule('valid_string');

// and make the field no longer required
$message = $fieldset->field('fieldname')->delete_rule('required', true);

When you remove the required rule, the "required" attribute of the form input tag will be removed if $set_attr is set to true.

set_attribute($attr, $value = null)

Set one or more HTML field attributes for the field.

静态否

参数

参数	预设	描述
`$attr`	必要	Either a string with the name of the attribute, or an assoc array of attributes and values.
`$value`	`null`	The attributes value. Ignored if $attr is an array.

回传 Fieldset_Field 物件，鍊结用

範例

// add a custom CSS style
$fieldset->field('fieldname')
	->set_attribute('style', 'font-weight:bold;color:yellow;');

// or multiple attributes at once
$fieldset->field('fieldname')->set_attribute(array(
	'style' => 'font-weight:bold;color:yellow;',
	'disabled' => 'disabled'
));

If you pass null as a value, the attribute will be removed from the field attribute list.

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

Get one or all HTML field attributes of the field.

静态否

参数

参数	预设	描述
`$key`	`null`	Name or array of names of attribute(s) to get. If null, all attributes set are returned.
`$default`	`null`	Value to return if the requested attribute has not been set.

回传 Mixed, a single attribute value, or multiple values in an array if $key was an array of attributes

範例

// get any custom style defined, or false if no style is set
$style = $fieldset->field('fieldname')
	->get_attribute('style', false);

set_options($value, $label = null, $replace_options = false)

Set one or more options. Only valid for radio buttons, checkboxes and selects.

静态否

参数

参数	预设	描述
`$value`	必要	Value of the option, or an assoc array of values and labels.
`$label`	`null`	Label to be set on the value. Only used if $value is not an array.
`$replace_options`	`false`	If true, existing options will be deleted before setting the new one(s).

回传 Fieldset_Field 物件，鍊结用

範例

// 如果该栏位是一个 select： <option value="1">Label</option>
// 如果该栏位是一个 checkbox： <label>Label</label><input type="checkbox" ... />
$style = $fieldset->field('fieldname')->set_options('1', 'Label');

fieldset()

取得此 Field 关联的 Fieldset 物件。

静态	否
参数	无
回传	Fieldset 实例
範例	`// 回传 true $same = ($fieldset === $fieldset->field('fieldname')->fieldset());`

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

Fieldset add() 方法的别名。

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

Fieldset add_before() 方法的别名。

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

Fieldset add_after() 方法的别名。

build()

为该栏位产生表单 HTML。

静态	否
参数	无
回传	字串，产生的 HTML
範例	`// 如果该栏位是一个 select：<option value="1">Label</option> // 如果该栏位是一个 checkbox：<label>Label</label><input type="checkbox" ... /> $style = $fieldset->field('fieldname')->set_options('1', 'Label');`

input()

Validation input() 方法的别名，并为目前栏位回传输入值。回传 null 如果没有输入值存在。

validated()

Validation validated() 方法的别名，并为目前栏位回传验证的输入值。回传 null 如果没有输入值存在。

error()

Validation error() 方法的别名，并在此栏位执行验证之后回传任何存在的错误讯息。回传 false 如果没有侦测到错误。