FuelPHP, a PHP 5.3 Framework Documentation

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

The forge method returns a new Fieldset instance. Note: there can only be one instance per $name.

'default'

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

instance($instance = null)

Returns a specific instance, or the default instance (is created if necessary).

null

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

validation()

Gets the Validation instance for the current Fieldset. Creates the Validation instance if it doesn't already exist.

$validation = $article_form->validation();

form()

Gets the Form instance for the current Fieldset. Creates the Form instance if it doesn't already exist.

$form = $article_form->form();

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

Creates a Fieldset_Field instance and adds it to the current Fieldset.

''

array()

array()

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

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

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

// Example of an Email input, with validation rules
$form->add(
	'email', 'E-mail',
	array('type' => 'email', 'class' => 'pretty_input'),
	array('required', 'valid_email')
);

// Example of an text input, with array notation for the validation rules
$form->add(
	'name', 'Full name',
	array('type' => 'name', 'class' => 'pretty_input'),
	array(array('required'), array('valid_string', array('alpha-numeric', 'dots', 'spaces')))
);

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

Creates a Fieldset_Field instance and adds it to the current Fieldset, just before an already defined field identified by $fieldname.

''

array()

array()

null

// Radio button field, to be added before the 'location' field.
$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)

Creates a Fieldset_Field instance and adds it to the current Fieldset, just after an already defined field identified by $fieldname.

''

array()

array()

null

// Radio button field, to be added after the 'location' field.
$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)

Sets a config value on the fieldset.

null

$article_form->set_config($config);

// or

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

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

Get the configuration array or one or more config values by key.

null

null

$config = $article_form->get_config();

get_name()

Get the identifier of the fieldset instance.

$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 wether 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)

The enable method allows you to re-enable a field that has been disabled before.

$fieldset->enable('name');

input($field = null)

Alias for $this->validation()->input(). Gets an array of validated input value(s) from either POST data or given input. See Validation.

null

$input_values = $article_form->input();

validated($field = null)

Alias for $this->validation()->validated(). Gets an array of input value(s) that passed validation. See Validation.

null

$validated_values = $article_form->validated();

error($field = null)

Alias for $this->validation()->error(). Gets an array of input value(s) that did not pass validation. See Validation.

null

$errors = $article_form->error();

show_errors(Array $config = array())

Alias for $this->validation()->show_errors(). Returns all errors in a list or with set markup from the $config parameter. See 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()

Return the name of the defined tabular form.

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

Creating Forms with ORM Models

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_Comments'.
 *
 * you can disable the fieldset tag to avoid embedded fieldsets in your form
 */
$form->add(\Fieldset::forge('tabular')->set_tabular_form('Model_Comments', 'comments', $article)->set_fieldset_tag(false));
				

This only works for related models that DO NOT have a compound key!

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_Comments::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
	}
}

Form Attributes

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

The following configuration values can be defined:

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?'

Form Attribute macro's

The following macro's can be used in a form template.

Modify Form Attributes

Changing the attributes of the form() instance in the fieldset can be done in two ways. You can either provide your options in the forge() method's attributes array, or modify the form instance directly.

// Use the form_attributes option in the attributes of the Fieldset object
$fieldset = Fieldset::forge('article', array(
	'form_attributes' => array(
		'id' => 'edit_article_form',
		'name' => 'edit_article'
		)
	)
);

// Modify the form instance directly
$fieldset->form()->set_attribute('id', 'edit_article_form');