2010-06-24 09:40:05 +01:00
|
|
|
<?php
|
|
|
|
|
2010-10-02 11:38:11 +01:00
|
|
|
/*
|
2011-01-15 13:29:43 +00:00
|
|
|
* This file is part of the Symfony package.
|
2010-10-02 11:38:11 +01:00
|
|
|
*
|
2011-03-06 11:40:06 +00:00
|
|
|
* (c) Fabien Potencier <fabien@symfony.com>
|
2010-10-02 11:38:11 +01:00
|
|
|
*
|
2011-01-15 13:29:43 +00:00
|
|
|
* For the full copyright and license information, please view the LICENSE
|
|
|
|
* file that was distributed with this source code.
|
2010-10-02 11:38:11 +01:00
|
|
|
*/
|
|
|
|
|
2011-01-15 13:29:43 +00:00
|
|
|
namespace Symfony\Component\Form;
|
|
|
|
|
2010-06-24 09:40:05 +01:00
|
|
|
/**
|
2012-08-26 07:28:19 +01:00
|
|
|
* A form group bundling multiple forms in a hierarchical structure.
|
2010-06-24 09:40:05 +01:00
|
|
|
*
|
2012-05-26 08:48:33 +01:00
|
|
|
* @author Bernhard Schussek <bschussek@gmail.com>
|
2010-06-24 09:40:05 +01:00
|
|
|
*/
|
2011-03-20 12:35:19 +00:00
|
|
|
interface FormInterface extends \ArrayAccess, \Traversable, \Countable
|
2010-06-24 09:40:05 +01:00
|
|
|
{
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
|
|
|
* Sets the parent form.
|
|
|
|
*
|
2012-08-26 20:13:38 +01:00
|
|
|
* @param FormInterface|null $parent The parent form or null if it's the root.
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
|
|
|
* @return FormInterface The form instance
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
|
|
|
* @throws Exception\AlreadyBoundException If the form has already been bound.
|
|
|
|
* @throws Exception\FormException When trying to set a parent for a form with
|
|
|
|
* an empty name.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function setParent(FormInterface $parent = null);
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the parent form.
|
|
|
|
*
|
2012-08-26 20:13:38 +01:00
|
|
|
* @return FormInterface|null The parent form or null if there is none.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getParent();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Adds a child to the form.
|
|
|
|
*
|
2012-12-14 18:27:28 +00:00
|
|
|
* @param FormInterface|string|integer $child The FormInterface instance or the name of the child.
|
|
|
|
* @param string|null $type The child's type, if a name was passed.
|
|
|
|
* @param array $options The child's options, if a name was passed.
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
|
|
|
* @return FormInterface The form instance
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2012-12-14 15:05:05 +00:00
|
|
|
* @throws Exception\AlreadyBoundException If the form has already been bound.
|
|
|
|
* @throws Exception\FormException When trying to add a child to a non-compound form.
|
|
|
|
* @throws Exception\UnexpectedTypeException If $child or $type has an unexpected type.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-12-14 15:05:05 +00:00
|
|
|
public function add($child, $type = null, array $options = array());
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2012-01-18 06:05:44 +00:00
|
|
|
/**
|
|
|
|
* Returns the child with the given name.
|
2012-01-26 15:54:42 +00:00
|
|
|
*
|
2012-01-18 06:05:44 +00:00
|
|
|
* @param string $name The name of the child
|
2012-01-26 15:54:42 +00:00
|
|
|
*
|
2012-01-18 06:05:44 +00:00
|
|
|
* @return FormInterface The child form
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
2012-08-26 08:47:56 +01:00
|
|
|
* @throws \OutOfBoundsException If the named child does not exist.
|
2012-01-18 06:05:44 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function get($name);
|
2012-01-18 06:05:44 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether a child with the given name exists.
|
|
|
|
*
|
2012-01-18 06:05:44 +00:00
|
|
|
* @param string $name The name of the child
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function has($name);
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Removes a child from the form.
|
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @param string $name The name of the child to remove
|
|
|
|
*
|
|
|
|
* @return FormInterface The form instance
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
|
|
|
* @throws Exception\AlreadyBoundException If the form has already been bound.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function remove($name);
|
2011-04-15 10:06:51 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns all children in this group.
|
|
|
|
*
|
2012-11-01 15:08:59 +00:00
|
|
|
* @return FormInterface[] An array of FormInterface instances
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function all();
|
2011-03-22 00:40:02 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns all errors.
|
|
|
|
*
|
2012-11-01 15:08:59 +00:00
|
|
|
* @return FormError[] An array of FormError instances that occurred during binding
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getErrors();
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2012-08-26 07:28:19 +01:00
|
|
|
* Updates the form with default data.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-11-06 21:40:27 +00:00
|
|
|
* @param mixed $modelData The data formatted as expected for the underlying object
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @return FormInterface The form instance
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
|
|
|
* @throws Exception\AlreadyBoundException If the form has already been bound.
|
|
|
|
* @throws Exception\FormException If listeners try to call setData in a cycle. Or if
|
|
|
|
* the view data does not match the expected type
|
|
|
|
* according to {@link FormConfigInterface::getDataClass}.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function setData($modelData);
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the data in the format needed for the underlying object.
|
|
|
|
*
|
|
|
|
* @return mixed
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getData();
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the normalized data of the field.
|
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @return mixed When the field is not bound, the default data is returned.
|
2012-08-26 07:28:19 +01:00
|
|
|
* When the field is bound, the normalized bound data is
|
|
|
|
* returned if the field is valid, null otherwise.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getNormData();
|
2011-05-04 15:58:39 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the data transformed by the value transformer.
|
|
|
|
*
|
2012-08-26 07:28:19 +01:00
|
|
|
* @return mixed
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getViewData();
|
2011-03-22 22:20:14 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the extra data.
|
|
|
|
*
|
|
|
|
* @return array The bound data which do not belong to a child
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getExtraData();
|
2011-05-10 14:32:14 +01:00
|
|
|
|
|
|
|
/**
|
2012-05-17 15:09:13 +01:00
|
|
|
* Returns the form's configuration.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-05-17 15:09:13 +01:00
|
|
|
* @return FormConfigInterface The configuration.
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getConfig();
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
2012-12-31 14:29:36 +00:00
|
|
|
* Returns whether the form is submitted.
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-12-31 14:29:36 +00:00
|
|
|
* @return Boolean true if the form is submitted, false otherwise
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isBound();
|
2011-03-24 21:20:54 +00:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
|
|
|
* Returns the name by which the form is identified in forms.
|
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @return string The name of the form.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getName();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2012-05-17 15:09:13 +01:00
|
|
|
/**
|
|
|
|
* Returns the property path that the form is mapped to.
|
|
|
|
*
|
2013-01-07 08:19:31 +00:00
|
|
|
* @return \Symfony\Component\PropertyAccess\PropertyPathInterface The property path.
|
2012-05-17 15:09:13 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getPropertyPath();
|
2012-05-17 15:09:13 +01:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
2011-05-10 14:32:14 +01:00
|
|
|
* Adds an error to this form.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @param FormError $error
|
|
|
|
*
|
|
|
|
* @return FormInterface The form instance
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function addError(FormError $error);
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2012-08-26 20:36:01 +01:00
|
|
|
* Returns whether the form and all children are valid.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isValid();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns whether the form is required to be filled out.
|
|
|
|
*
|
|
|
|
* If the form has a parent and the parent is not required, this method
|
|
|
|
* will always return false. Otherwise the value set with setRequired()
|
|
|
|
* is returned.
|
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isRequired();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2012-01-26 15:54:42 +00:00
|
|
|
* Returns whether this form is disabled.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-01-26 15:54:42 +00:00
|
|
|
* The content of a disabled form is displayed, but not allowed to be
|
|
|
|
* modified. The validation of modified disabled forms should fail.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-04-13 15:06:32 +01:00
|
|
|
* Forms whose parents are disabled are considered disabled regardless of
|
2011-03-20 12:35:19 +00:00
|
|
|
* their own state.
|
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isDisabled();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
|
|
|
/**
|
2011-05-10 14:32:14 +01:00
|
|
|
* Returns whether the form is empty.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2011-04-27 06:25:26 +01:00
|
|
|
* @return Boolean
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isEmpty();
|
2011-03-20 12:35:19 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the data in the different formats is synchronized.
|
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isSynchronized();
|
2011-03-25 09:54:04 +00:00
|
|
|
|
2011-03-20 12:35:19 +00:00
|
|
|
/**
|
2012-08-26 07:28:19 +01:00
|
|
|
* Binds data to the form, transforms and validates it.
|
2011-03-20 12:35:19 +00:00
|
|
|
*
|
2012-08-26 07:28:19 +01:00
|
|
|
* @param null|string|array $submittedData The data
|
2012-05-20 10:18:31 +01:00
|
|
|
*
|
|
|
|
* @return FormInterface The form instance
|
2012-08-26 07:28:19 +01:00
|
|
|
*
|
|
|
|
* @throws Exception\AlreadyBoundException If the form has already been bound.
|
2011-03-20 12:35:19 +00:00
|
|
|
*/
|
2012-08-26 07:28:19 +01:00
|
|
|
public function bind($submittedData);
|
2011-03-22 00:40:02 +00:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns the root of the form tree.
|
|
|
|
*
|
2012-05-20 10:18:31 +01:00
|
|
|
* @return FormInterface The root of the tree
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function getRoot();
|
2011-03-31 14:23:33 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is the root of the form tree.
|
|
|
|
*
|
|
|
|
* @return Boolean
|
|
|
|
*/
|
2012-07-09 13:50:58 +01:00
|
|
|
public function isRoot();
|
2011-04-13 08:31:11 +01:00
|
|
|
|
2011-05-10 14:32:14 +01:00
|
|
|
/**
|
|
|
|
* Creates a view.
|
|
|
|
*
|
2012-07-16 13:57:09 +01:00
|
|
|
* @param FormView $parent The parent view
|
2011-05-10 14:32:14 +01:00
|
|
|
*
|
2012-07-16 13:57:09 +01:00
|
|
|
* @return FormView The view
|
2011-05-10 14:32:14 +01:00
|
|
|
*/
|
2012-07-16 13:57:09 +01:00
|
|
|
public function createView(FormView $parent = null);
|
2011-03-24 21:20:54 +00:00
|
|
|
}
|