/**
* Adds a new field to this group. A field must have a unique name within
* the group. Otherwise the existing field is overwritten.
*
* If you add a nested group, this group should also be represented in the
* object hierarchy. If you want to add a group that operates on the same
* hierarchy level, use merge().
*
* <code>
* class Entity
* {
* public $location;
* }
*
* class Location
* {
* public $longitude;
* public $latitude;
* }
*
* $entity = new Entity();
* $entity->location = new Location();
*
* $form = new Form('entity', $entity, $validator);
*
* $locationGroup = new FieldGroup('location');
* $locationGroup->add(new TextField('longitude'));
* $locationGroup->add(new TextField('latitude'));
*
* $form->add($locationGroup);
* </code>
*
* @param FieldInterface $field
*/
public function add(FieldInterface $field)
{
if ($this->isBound()) {
throw new AlreadyBoundException('You cannot add fields after binding a form');
}
$this->fields[$field->getKey()] = $field;
$field->setParent($this);
$data = $this->getTransformedData();
// if the property "data" is NULL, getTransformedData() returns an empty
// string
if (!empty($data)) {
$field->updateFromProperty($data);
}
return $field;
}