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

 */

/**

 * Zend_Form_DisplayGroup

 *

 * @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

 * @version    $Id: DisplayGroup.php 22930 2010-09-09 18:45:18Z matthew $

 */

class Zend_Form_DisplayGroup implements Iterator,Countable

{

    /**

     * Group attributes

     * @var array

     */

    protected $_attribs = array();

    /**

     * Display group decorators

     * @var array

     */

    protected $_decorators = array();

    /**

     * Description

     * @var string

     */

    protected $_description;

    /**

     * Should we disable loading the default decorators?

     * @var bool

     */

    protected $_disableLoadDefaultDecorators = false;

    /**

     * Element order

     * @var array

     */

    protected $_elementOrder = array();

    /**

     * Elements

     * @var array

     */

    protected $_elements = array();

    /**

     * Form object to which the display group is currently registered

     * 

     * @var Zend_Form

     */

    protected $_form;

    /**

     * Whether or not a new element has been added to the group

     * @var bool

     */

    protected $_groupUpdated = false;

    /**

     * Plugin loader for decorators

     * @var Zend_Loader_PluginLoader

     */

    protected $_loader;

    /**

     * Group name

     * @var string

     */

    protected $_name;

    /**

     * Group order

     * @var int

     */

    protected $_order;

    /**

     * @var Zend_Translate

     */

    protected $_translator;

    /**

     * Is translation disabled?

     * @var bool

     */

    protected $_translatorDisabled = false;

    /**

     * @var Zend_View_Interface

     */

    protected $_view;

    /**

     * Constructor

     *

     * @param  string $name

     * @param  Zend_Loader_PluginLoader $loader

     * @param  array|Zend_Config $options

     * @return void

     */

    public function __construct($name, Zend_Loader_PluginLoader $loader, $options = null)

    {

        $this->setName($name);

        $this->setPluginLoader($loader);

        if (is_array($options)) {

            $this->setOptions($options);

        } elseif ($options instanceof Zend_Config) {

            $this->setConfig($options);

        }

        // Extensions...

        $this->init();

        $this->loadDefaultDecorators();

    }

    /**

     * Initialize object; used by extending classes

     *

     * @return void

     */

    public function init()

    {

    }

    /**

     * Set options

     *

     * @param  array $options

     * @return Zend_Form_DisplayGroup

     */

    public function setOptions(array $options)

    {

        $forbidden = array(

            'Options', 'Config', 'PluginLoader', 'View',

            'Translator', 'Attrib'

        );

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

            $normalized = ucfirst($key);

            if (in_array($normalized, $forbidden)) {

                continue;

            }

            $method = 'set' . $normalized;

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

                $this->$method($value);

            } else {

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

            }

        }

        return $this;

    }

    /**

     * Set options from config object

     *

     * @param  Zend_Config $config

     * @return Zend_Form_DisplayGroup

     */

    public function setConfig(Zend_Config $config)

    {

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

    }

    /**

     * Set group attribute

     *

     * @param  string $key

     * @param  mixed $value

     * @return Zend_Form_DisplayGroup

     */

    public function setAttrib($key, $value)

    {

        $key = (string) $key;

        $this->_attribs[$key] = $value;

        return $this;

    }

    /**

     * Add multiple form attributes at once

     *

     * @param  array $attribs

     * @return Zend_Form_DisplayGroup

     */

    public function addAttribs(array $attribs)

    {

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

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

        }

        return $this;

    }

    /**

     * Set multiple form attributes at once

     *

     * Overwrites any previously set attributes.

     *

     * @param  array $attribs

     * @return Zend_Form_DisplayGroup

     */

    public function setAttribs(array $attribs)

    {

        $this->clearAttribs();

        return $this->addAttribs($attribs);

    }

    /**

     * Retrieve a single form attribute

     *

     * @param  string $key

     * @return mixed

     */

    public function getAttrib($key)

    {

        $key = (string) $key;

        if (!isset($this->_attribs[$key])) {

            return null;

        }

        return $this->_attribs[$key];

    }

    /**

     * Retrieve all form attributes/metadata

     *

     * @return array

     */

    public function getAttribs()

    {

        return $this->_attribs;

    }

    /**

     * Remove attribute

     *

     * @param  string $key

     * @return bool

     */

    public function removeAttrib($key)

    {

        if (array_key_exists($key, $this->_attribs)) {

            unset($this->_attribs[$key]);

            return true;

        }

        return false;

    }

    /**

     * Clear all form attributes

     *

     * @return Zend_Form

     */

    public function clearAttribs()

    {

        $this->_attribs = array();

        return $this;

    }

    /**

     * Set form object to which the display group is attached

     * 

     * @param  Zend_Form $form 

     * @return Zend_Form_DisplayGroup

     */

    public function setForm(Zend_Form $form)

    {

        $this->_form = $form;

        // Ensure any elements attached prior to setting the form are now 

        // removed from iteration by the form

        foreach ($this->getElements() as $element) {

            $form->removeFromIteration($element->getName());

        }

        return $this;

    }

    /**

     * Get form object to which the group is attached

     * 

     * @return Zend_Form|null

     */

    public function getForm()

    {

        return $this->_form;

    }

    /**

     * Filter a name to only allow valid variable characters

     *

     * @param  string $value

     * @return string

     */

    public function filterName($value)

    {

        return preg_replace('/[^a-zA-Z0-9_\x7f-\xff]/', '', (string) $value);

    }

    /**

     * Set group name

     *

     * @param  string $name

     * @return Zend_Form_DisplayGroup

     */

    public function setName($name)

    {

        $name = $this->filtername($name);

        if (('0' !== $name) && empty($name)) {

            require_once 'Zend/Form/Exception.php';

            throw new Zend_Form_Exception('Invalid name provided; must contain only valid variable characters and be non-empty');

        }

        $this->_name = $name;

        return $this;

    }

    /**

     * Retrieve group name

     *

     * @return string

     */

    public function getName()

    {

        return $this->_name;

    }

    /**

     * Get fully qualified name

     *

     * Places name as subitem of array and/or appends brackets.

     *

     * @return string

     */

    public function getFullyQualifiedName()

    {

        return $this->getName();

    }

    /**

     * Get element id

     *

     * @return string

     */

    public function getId()

    {

        if (isset($this->id)) {

            return $this->id;

        }

        $id = $this->getFullyQualifiedName();

        // Bail early if no array notation detected

        if (!strstr($id, '[')) {

            return $id;

        }

        // Strip array notation

        if ('[]' == substr($id, -2)) {

            $id = substr($id, 0, strlen($id) - 2);

        }

        $id = str_replace('][', '-', $id);

        $id = str_replace(array(']', '['), '-', $id);

        $id = trim($id, '-');

        return $id;

    }

    /**

     * Set group legend

     *

     * @param  string $legend

     * @return Zend_Form_DisplayGroup

     */

    public function setLegend($legend)

    {

        return $this->setAttrib('legend', (string) $legend);

    }

    /**

     * Retrieve group legend

     *

     * @return string

     */

    public function getLegend()

    {

        return $this->getAttrib('legend');

    }

    /**

     * Set description

     *

     * @param  string $value

     * @return Zend_Form_DisplayGroup

     */

    public function setDescription($value)

    {

        $this->_description = (string) $value;

        return $this;

    }

    /**

     * Get description

     *

     * @return string

     */

    public function getDescription()

    {

        return $this->_description;

    }

    /**

     * Set group order

     *

     * @param  int $order

     * @return Zend_Form_Element

     */

    public function setOrder($order)

    {

        $this->_order = (int) $order;

        return $this;

    }

    /**

     * Retrieve group order

     *

     * @return int

     */

    public function getOrder()

    {

        return $this->_order;

    }

    // Elements

    /**

     * Add element to stack

     *