<?php

/**

 * Zend Framework

 *

 * LICENSE

 *

 * This source file is subject to the new BSD license that is bundled

 * with this package in the file LICENSE.txt.

 * It is also available through the world-wide-web at this URL:

 * http://framework.zend.com/license/new-bsd

 * If you did not receive a copy of the license and are unable to

 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Form

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 */

/** @see Zend_Filter */

require_once 'Zend/Filter.php';

/** @see Zend_Form */

require_once 'Zend/Form.php';

/** @see Zend_Validate_Interface */

require_once 'Zend/Validate/Interface.php';

/** @see Zend_Validate_Abstract */

require_once 'Zend/Validate/Abstract.php';

/**

 * Zend_Form_Element

 *

 * @category   Zend

 * @package    Zend_Form

 * @subpackage Element

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: Element.php 22464 2010-06-19 17:31:21Z alab $

 */

class Zend_Form_Element implements Zend_Validate_Interface

{

    /**

     * Element Constants

     */

    const DECORATOR = 'DECORATOR';

    const FILTER    = 'FILTER';

    const VALIDATE  = 'VALIDATE';

    /**

     * Default view helper to use

     * @var string

     */

    public $helper = 'formText';

    /**

     * 'Allow empty' flag

     * @var bool

     */

    protected $_allowEmpty = true;

    /**

     * Flag indicating whether or not to insert NotEmpty validator when element is required

     * @var bool

     */

    protected $_autoInsertNotEmptyValidator = true;

    /**

     * Array to which element belongs

     * @var string

     */

    protected $_belongsTo;

    /**

     * Element decorators

     * @var array

     */

    protected $_decorators = array();

    /**

     * Element description

     * @var string

     */

    protected $_description;

    /**

     * Should we disable loading the default decorators?

     * @var bool

     */

    protected $_disableLoadDefaultDecorators = false;

    /**

     * Custom error messages

     * @var array

     */

    protected $_errorMessages = array();

    /**

     * Validation errors

     * @var array

     */

    protected $_errors = array();

    /**

     * Separator to use when concatenating aggregate error messages (for

     * elements having array values)

     * @var string

     */

    protected $_errorMessageSeparator = '; ';

    /**

     * Element filters

     * @var array

     */

    protected $_filters = array();

    /**

     * Ignore flag (used when retrieving values at form level)

     * @var bool

     */

    protected $_ignore = false;

    /**

     * Does the element represent an array?

     * @var bool

     */

    protected $_isArray = false;

    /**

     * Is the error marked as in an invalid state?

     * @var bool

     */

    protected $_isError = false;

    /**

     * Has the element been manually marked as invalid?

     * @var bool

     */

    protected $_isErrorForced = false;

    /**

     * Element label

     * @var string

     */

    protected $_label;

    /**

     * Plugin loaders for filter and validator chains

     * @var array

     */

    protected $_loaders = array();

    /**

     * Formatted validation error messages

     * @var array

     */

    protected $_messages = array();

    /**

     * Element name

     * @var string

     */

    protected $_name;

    /**

     * Order of element

     * @var int

     */

    protected $_order;

    /**

     * Required flag

     * @var bool

     */

    protected $_required = false;

    /**

     * @var Zend_Translate

     */

    protected $_translator;

    /**

     * Is translation disabled?

     * @var bool

     */

    protected $_translatorDisabled = false;

    /**

     * Element type

     * @var string

     */

    protected $_type;

    /**

     * Array of initialized validators

     * @var array Validators

     */

    protected $_validators = array();

    /**

     * Array of un-initialized validators

     * @var array

     */

    protected $_validatorRules = array();

    /**

     * Element value

     * @var mixed

     */

    protected $_value;

    /**

     * @var Zend_View_Interface

     */

    protected $_view;

    /**

     * Is a specific decorator being rendered via the magic renderDecorator()?

     *

     * This is to allow execution of logic inside the render() methods of child

     * elements during the magic call while skipping the parent render() method.

     *

     * @var bool

     */

    protected $_isPartialRendering = false;

    /**

     * Constructor

     *

     * $spec may be:

     * - string: name of element

     * - array: options with which to configure element

     * - Zend_Config: Zend_Config with options for configuring element

     *

     * @param  string|array|Zend_Config $spec

     * @param  array|Zend_Config $options

     * @return void

     * @throws Zend_Form_Exception if no element name after initialization

     */

    public function __construct($spec, $options = null)

    {

        if (is_string($spec)) {

            $this->setName($spec);

        } elseif (is_array($spec)) {

            $this->setOptions($spec);

        } elseif ($spec instanceof Zend_Config) {

            $this->setConfig($spec);

        }

        if (is_string($spec) && is_array($options)) {

            $this->setOptions($options);

        } elseif (is_string($spec) && ($options instanceof Zend_Config)) {

            $this->setConfig($options);

        }

        if (null === $this->getName()) {

            require_once 'Zend/Form/Exception.php';

            throw new Zend_Form_Exception('Zend_Form_Element requires each element to have a name');

        }

        /**

         * Extensions

         */

        $this->init();

        /**

         * Register ViewHelper decorator by default

         */

        $this->loadDefaultDecorators();

    }

    /**

     * Initialize object; used by extending classes

     *

     * @return void

     */

    public function init()

    {

    }

    /**

     * Set flag to disable loading default decorators

     *

     * @param  bool $flag

     * @return Zend_Form_Element

     */

    public function setDisableLoadDefaultDecorators($flag)

    {

        $this->_disableLoadDefaultDecorators = (bool) $flag;

        return $this;

    }

    /**

     * Should we load the default decorators?

     *

     * @return bool

     */

    public function loadDefaultDecoratorsIsDisabled()

    {

        return $this->_disableLoadDefaultDecorators;

    }

    /**

     * Load default decorators

     *

     * @return Zend_Form_Element

     */

    public function loadDefaultDecorators()

    {

        if ($this->loadDefaultDecoratorsIsDisabled()) {

            return $this;

        }

        $decorators = $this->getDecorators();

        if (empty($decorators)) {

            $getId = create_function('$decorator',

                                     'return $decorator->getElement()->getId()

                                             . "-element";');

            $this->addDecorator('ViewHelper')

                 ->addDecorator('Errors')

                 ->addDecorator('Description', array('tag' => 'p', 'class' => 'description'))

                 ->addDecorator('HtmlTag', array('tag' => 'dd',

                                                 'id'  => array('callback' => $getId)))

                 ->addDecorator('Label', array('tag' => 'dt'));

        }

        return $this;

    }

    /**

     * Set object state from options array

     *

     * @param  array $options

     * @return Zend_Form_Element

     */

    public function setOptions(array $options)

    {

        if (isset($options['prefixPath'])) {

            $this->addPrefixPaths($options['prefixPath']);

            unset($options['prefixPath']);

        }

        if (isset($options['disableTranslator'])) {

            $this->setDisableTranslator($options['disableTranslator']);

            unset($options['disableTranslator']);

        }

        unset($options['options']);

        unset($options['config']);

        foreach ($options as $key => $value) {

            $method = 'set' . ucfirst($key);

            if (in_array($method, array('setTranslator', 'setPluginLoader', 'setView'))) {

                if (!is_object($value)) {

                    continue;

                }

            }

            if (method_exists($this, $method)) {

                // Setter exists; use it

                $this->$method($value);

            } else {

                // Assume it's metadata

                $this->setAttrib($key, $value);

            }

        }

        return $this;

    }

    /**

     * Set object state from Zend_Config object

     *

     * @param  Zend_Config $config

     * @return Zend_Form_Element

     */

    public function setConfig(Zend_Config $config)

    {

        return $this->setOptions($config->toArray());

    }

    // Localization:

    /**

     * Set translator object for localization

     *

     * @param  Zend_Translate|null $translator

     * @return Zend_Form_Element

     */

    public function setTranslator($translator = null)

    {

        if (null === $translator) {

            $this->_translator = null;

        } elseif ($translator instanceof Zend_Translate_Adapter) {

            $this->_translator = $translator;

        } elseif ($translator instanceof Zend_Translate) {

            $this->_translator = $translator->getAdapter();

        } else {

            require_once 'Zend/Form/Exception.php';

            throw new Zend_Form_Exception('Invalid translator specified');

        }

        return $this;

    }

    /**

     * Retrieve localization translator object

     *

     * @return Zend_Translate_Adapter|null

     */

    public function getTranslator()

    {

        if ($this->translatorIsDisabled()) {

            return null;

        }

        if (null === $this->_translator) {

            return Zend_Form::getDefaultTranslator();

        }

        return $this->_translator;

    }

    /**

     * Does this element have its own specific translator?

     *

     * @return bool

     */

    public function hasTranslator()

    {

        return (bool)$this->_translator;

    }

    /**

     * Indicate whether or not translation should be disabled

     *

     * @param  bool $flag

     * @return Zend_Form_Element

     */

    public function setDisableTranslator($flag)

    {

        $this->_translatorDisabled = (bool) $flag;

        return $this;

    }

    /**

     * Is translation disabled?

     *

     * @return bool

     */

    public function translatorIsDisabled()

    {

        return $this->_translatorDisabled;

    }

    // Metadata

    /**

     * Filter a name to only allow valid variable characters

     *

     * @param  string $value

     * @param  bool $allowBrackets

     * @return string

     */