2010-06-24 09:40:05 +01:00
|
|
|
<?php
|
|
|
|
|
2010-08-20 22:09:55 +01:00
|
|
|
namespace Symfony\Component\Form;
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-10-02 11:38:11 +01:00
|
|
|
/*
|
|
|
|
* This file is part of the Symfony framework.
|
|
|
|
*
|
|
|
|
* (c) Fabien Potencier <fabien.potencier@symfony-project.com>
|
|
|
|
*
|
|
|
|
* This source file is subject to the MIT license that is bundled
|
|
|
|
* with this source code in the file LICENSE.
|
|
|
|
*/
|
|
|
|
|
2010-08-20 22:09:55 +01:00
|
|
|
use Symfony\Component\I18N\TranslatorInterface;
|
2010-06-24 09:40:05 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* A form field that can be embedded in a form.
|
|
|
|
*
|
|
|
|
* @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
|
|
|
|
*/
|
2010-09-09 11:14:06 +01:00
|
|
|
interface FieldInterface extends Localizable
|
2010-06-24 09:40:05 +01:00
|
|
|
{
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Marks a constraint violation in a form field
|
|
|
|
* @var integer
|
|
|
|
*/
|
|
|
|
const FIELD_ERROR = 0;
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Marks a constraint violation in the data of a form field
|
|
|
|
* @var integer
|
|
|
|
*/
|
|
|
|
const DATA_ERROR = 1;
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Clones this field.
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function __clone();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Sets the parent field.
|
|
|
|
*
|
|
|
|
* @param FieldInterface $parent The parent field
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function setParent(FieldInterface $parent = null);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-09-03 08:56:52 +01:00
|
|
|
/**
|
|
|
|
* Returns the parent field.
|
|
|
|
*
|
|
|
|
* @return FieldInterface The parent field
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getParent();
|
2010-09-03 08:56:52 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Sets the key by which the field is identified in field groups.
|
|
|
|
*
|
|
|
|
* Once this field is nested in a field group, i.e. after setParent() was
|
|
|
|
* called for the first time, this method should throw an exception.
|
|
|
|
*
|
|
|
|
* @param string $key The key of the field
|
|
|
|
* @throws BadMethodCallException When the field already has a parent
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function setKey($key);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the key by which the field is identified in field groups.
|
|
|
|
*
|
|
|
|
* @return string The key of the field.
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getKey();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the name of the field.
|
|
|
|
*
|
|
|
|
* @return string When the field has no parent, the name is equal to its
|
|
|
|
* key. If the field has a parent, the name is composed of
|
|
|
|
* the parent's name and the field's key, where the field's
|
|
|
|
* key is wrapped in squared brackets
|
|
|
|
* (e.g. "parent_name[field_key]")
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getName();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the ID of the field.
|
|
|
|
*
|
|
|
|
* @return string The ID of a field is equal to its name, where all
|
|
|
|
* sequences of squared brackets are replaced by a single
|
|
|
|
* underscore (e.g. if the name is "parent_name[field_key]",
|
|
|
|
* the ID is "parent_name_field_key").
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getId();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Sets the property path
|
|
|
|
*
|
|
|
|
* The property path determines the property or a sequence of properties
|
|
|
|
* that a field updates in the data of the field group.
|
|
|
|
*
|
|
|
|
* @param string $propertyPath
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function setPropertyPath($propertyPath);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the property path of the field
|
|
|
|
*
|
|
|
|
* @return PropertyPath
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getPropertyPath();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Writes a property value of the object into the field
|
|
|
|
*
|
|
|
|
* The chosen property is determined by the field's property path.
|
|
|
|
*
|
|
|
|
* @param array|object $objectOrArray
|
|
|
|
*/
|
2010-12-10 09:19:51 +00:00
|
|
|
function updateFromProperty(&$objectOrArray);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Writes a the field value into a property of the object
|
|
|
|
*
|
|
|
|
* The chosen property is determined by the field's property path.
|
|
|
|
*
|
|
|
|
* @param array|object $objectOrArray
|
|
|
|
*/
|
2010-12-10 09:19:51 +00:00
|
|
|
function updateProperty(&$objectOrArray);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the normalized data of the field.
|
|
|
|
*
|
|
|
|
* @return mixed When the field is not bound, the default data is returned.
|
|
|
|
* When the field is bound, the normalized bound data is
|
|
|
|
* returned if the field is valid, null otherwise.
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getData();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns the data of the field as it is displayed to the user.
|
|
|
|
*
|
|
|
|
* @return string|array When the field is not bound, the transformed
|
|
|
|
* default data is returned. When the field is bound,
|
|
|
|
* the bound data is returned.
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function getDisplayedData();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Sets the default data
|
|
|
|
*
|
|
|
|
* @param mixed $default The default data
|
|
|
|
* @throws UnexpectedTypeException If the default data is invalid
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function setData($default);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Binds POST data to the field, transforms and validates it.
|
|
|
|
*
|
|
|
|
* @param string|array $taintedData The POST data
|
|
|
|
* @return boolean Whether the form is valid
|
|
|
|
* @throws InvalidConfigurationException when the field is not configured
|
|
|
|
* correctly
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function bind($taintedData);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Recursively adds constraint violations to the fields
|
|
|
|
*
|
|
|
|
* Violations in the form fields usually have property paths like:
|
|
|
|
*
|
|
|
|
* <code>
|
|
|
|
* iterator[firstName].data
|
|
|
|
* iterator[firstName].displayedData
|
|
|
|
* iterator[Address].iterator[street].displayedData
|
|
|
|
* ...
|
|
|
|
* </code>
|
|
|
|
*
|
|
|
|
* Violations in the form data usually have property paths like:
|
|
|
|
*
|
|
|
|
* <code>
|
|
|
|
* data.firstName
|
|
|
|
* data.Address.street
|
|
|
|
* ...
|
|
|
|
* </code>
|
|
|
|
*
|
2010-11-18 22:33:44 +00:00
|
|
|
* @param FieldError $error
|
2010-10-10 22:15:28 +01:00
|
|
|
* @param PropertyPathIterator $pathIterator
|
2010-06-24 10:24:08 +01:00
|
|
|
* @param ConstraintViolation$violation
|
|
|
|
*/
|
2010-11-18 22:33:44 +00:00
|
|
|
function addError(FieldError $error, PropertyPathIterator $pathIterator = null, $type = null);
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is bound.
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isBound();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is valid.
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isValid();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field requires a multipart form.
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isMultipart();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is required to be filled out.
|
|
|
|
*
|
|
|
|
* If the field 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
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isRequired();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether this field is disabled
|
|
|
|
*
|
|
|
|
* The content of a disabled field is displayed, but not allowed to be
|
|
|
|
* modified. The validation of modified, disabled fields should fail.
|
|
|
|
*
|
|
|
|
* Fields whose parents are disabled are considered disabled regardless of
|
|
|
|
* their own state.
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isDisabled();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Returns whether the field is hidden
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function isHidden();
|
2010-06-24 09:40:05 +01:00
|
|
|
|
2010-06-24 10:24:08 +01:00
|
|
|
/**
|
|
|
|
* Sets whether this field is required to be filled out when submitted.
|
|
|
|
*
|
|
|
|
* @param boolean $required
|
|
|
|
*/
|
2010-10-17 12:39:51 +01:00
|
|
|
function setRequired($required);
|
2010-10-02 11:38:11 +01:00
|
|
|
}
|