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

 * @subpackage Decorator

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

require_once 'Zend/Form/Decorator/Abstract.php';

/**

 * Zend_Form_Decorator_Description

 *

 * Accepts the options:

 * - separator: separator to use between label and content (defaults to PHP_EOL)

 * - placement: whether to append or prepend label to content (defaults to prepend)

 * - tag: if set, used to wrap the label in an additional HTML tag

 * - class: if set, override default class used with HTML tag

 * - escape: whether or not to escape description (true by default)

 *

 * Any other options passed will be used as HTML attributes of the HTML tag used.

 *

 * @category   Zend

 * @package    Zend_Form

 * @subpackage Decorator

 * @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: Description.php 20096 2010-01-06 02:05:09Z bkarwin $

 */

class Zend_Form_Decorator_Description extends Zend_Form_Decorator_Abstract

{

    /**

     * Whether or not to escape the description

     * @var bool

     */

    protected $_escape;

    /**

     * Default placement: append

     * @var string

     */

    protected $_placement = 'APPEND';

    /**

     * HTML tag with which to surround description

     * @var string

     */

    protected $_tag;

    /**

     * Set HTML tag with which to surround description

     *

     * @param  string $tag

     * @return Zend_Form_Decorator_Description

     */

    public function setTag($tag)

    {

        $this->_tag = (string) $tag;

        return $this;

    }

    /**

     * Get HTML tag, if any, with which to surround description

     *

     * @return string

     */

    public function getTag()

    {

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

            $tag = $this->getOption('tag');

            if (null !== $tag) {

                $this->removeOption('tag');

            } else {

                $tag = 'p';

            }

            $this->setTag($tag);

            return $tag;

        }

        return $this->_tag;

    }

    /**

     * Get class with which to define description

     *

     * Defaults to 'hint'

     *

     * @return string

     */

    public function getClass()

    {

        $class = $this->getOption('class');

        if (null === $class) {

            $class = 'hint';

            $this->setOption('class', $class);

        }

        return $class;

    }

    /**

     * Set whether or not to escape description

     *

     * @param  bool $flag

     * @return Zend_Form_Decorator_Description

     */

    public function setEscape($flag)

    {

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

        return $this;

    }

    /**

     * Get escape flag

     *

     * @return true

     */

    public function getEscape()

    {

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

            if (null !== ($escape = $this->getOption('escape'))) {

                $this->setEscape($escape);

                $this->removeOption('escape');

            } else {

                $this->setEscape(true);

            }

        }

        return $this->_escape;

    }

    /**

     * Render a description

     *

     * @param  string $content

     * @return string

     */

    public function render($content)

    {

        $element = $this->getElement();

        $view    = $element->getView();

        if (null === $view) {

            return $content;

        }

        $description = $element->getDescription();

        $description = trim($description);

        if (!empty($description) && (null !== ($translator = $element->getTranslator()))) {

            $description = $translator->translate($description);

        }

        if (empty($description)) {

            return $content;

        }

        $separator = $this->getSeparator();

        $placement = $this->getPlacement();

        $tag       = $this->getTag();

        $class     = $this->getClass();

        $escape    = $this->getEscape();

        $options   = $this->getOptions();

        if ($escape) {

            $description = $view->escape($description);

        }

        if (!empty($tag)) {

            require_once 'Zend/Form/Decorator/HtmlTag.php';

            $options['tag'] = $tag;

            $decorator = new Zend_Form_Decorator_HtmlTag($options);

            $description = $decorator->render($description);

        }

        switch ($placement) {

            case self::PREPEND:

                return $description . $separator . $content;

            case self::APPEND:

            default:

                return $content . $separator . $description;

        }

    }

}