Fieldset_Field Class

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.

Static No
Parameters
Param Default Description
$fieldset 
required
 Instance of Fieldset you want to assign this Field object to.
Returns Fieldset_Field Object, for chaining
Example 
$fieldset = \Fieldset::forge('myfieldset');
$field = new \Fieldset_Field('client', 'Name of the client');
$field->set_fieldset($fieldset);

set_name($name, $update = true)

Change the name of a field.

Static No
Parameters
Param Default Description
$name 
required
 Name of the field when generating the HTML for this field.
$update 
true
 When set to false, the associated fieldset is not updated. This is for internal use only!
Returns Fieldset_Field Object, for chaining
Example 
$fieldset->field('fieldname')->set_name('newfieldname');

If the fieldset field is part of a field, the field will be renamed in the fieldset too. Field order in the fieldset will be maintained.

set_label($label)

Set or change the label of a field.

Static No
Parameters
Param Default Description
$label 
required
 Label to be displayed for the field when generating the HTML for this field.
Returns Fieldset_Field Object, for chaining
Example 
$fieldset->field('fieldname')->set_label('New Label');

set_type($type)

Set or change the HTML form field type.

Static No
Parameters
Param Default Description
$type 
required
 Input field type used when generating the HTML for this field.
Returns Fieldset_Field Object, for chaining
Example 
// 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.

Static No
Parameters
Param Default Description
$type 
required
 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).
Returns Fieldset_Field Object, for chaining
Example 
$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.

Static No
Parameters
Param Default Description
$description 
required
 Field description.
Returns Fieldset_Field Object, for chaining
Example 
$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.

Static No
Parameters
Param Default Description
$template 
null
 The template to be used to render the HTML for this field.
Returns Fieldset_Field Object, for chaining
Example 
$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.

Static No
Parameters
Param Default Description
$rule 
required
 Validation rule for which you want to override the default error message.
$msg 
required
 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.
Returns Fieldset_Field Object, for chaining
Example 
// 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.

Static No
Parameters
Param Default Description
$rule 
required
 The name of the validation rule who's message should be fetched.
Returns Mixed, string if there is a custom message, or null if not
Example 
// 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.

Static No
Parameters
Param Default Description
$callback 
required
 Either a string with a valid validation rule name, or full callback.
Returns Fieldset_Field Object, for chaining
Example 
// 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.

Static No
Parameters
Param Default Description
$callback 
required
 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.
Returns Fieldset_Field Object, for chaining
Example 
// 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.

Static No
Parameters
Param Default Description
$attr 
required
 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.
Returns Fieldset_Field Object, for chaining
Example 
// 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.

Static No
Parameters
Param Default Description
$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.
Returns Mixed, a single attribute value, or multiple values in an array if $key was an array of attributes
Example 
// 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.

Static No
Parameters
Param Default Description
$value 
required
 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).
Returns Fieldset_Field Object, for chaining
Example 
// if the field is a select: <option value="1">Label</option>
// if the field is a checkbox: <label>Label</label><input type="checkbox" ... />
$style = $fieldset->field('fieldname')->set_options('1', 'Label');

fieldset()

Get the Fieldset object this Field is associated with.

Static No
Parameters None
Returns Fieldset instance
Example 
// returns true
$same = ($fieldset === $fieldset->field('fieldname')->fieldset());

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

Alias for the Fieldset add() method.

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

Alias for the Fieldset add_before() method.

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

Alias for the Fieldset add_after() method.

build()

Generates the form HTML for the field.

Static No
Parameters None
Returns string, the generated HTML
Example 
// if the field is a select: <option value="1">Label</option>
// if the field is a checkbox: <label>Label</label><input type="checkbox" ... />
$style = $fieldset->field('fieldname')->set_options('1', 'Label');

input()

Alias for the Validation input() method, and returning the input value for the current field. Returns null if no input value is present.

validated()

Alias for the Validation validated() method, and returning the validated input value for the current field. Returns null if no validated input value is present.

error()

Alias for the Validation error() method, and any error messages present after the validation of this field has run. Returns false if no errors were detected.