/library/Zend/Form/Decorator/Label.php

  1<?php
  2/**
  3 * Zend Framework
  4 *
  5 * LICENSE
  6 *
  7 * This source file is subject to the new BSD license that is bundled
  8 * with this package in the file LICENSE.txt.
  9 * It is also available through the world-wide-web at this URL:
 10 * http://framework.zend.com/license/new-bsd
 11 * If you did not receive a copy of the license and are unable to
 12 * obtain it through the world-wide-web, please send an email
 13 * to license@zend.com so we can send you a copy immediately.
 14 *
 15 * @category   Zend
 16 * @package    Zend_Form
 17 * @subpackage Decorator
 18 * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
 19 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 20 */
 21
 22/** Zend_Form_Decorator_Abstract */
 23require_once 'Zend/Form/Decorator/Abstract.php';
 24
 25/**
 26 * Zend_Form_Decorator_Label
 27 *
 28 * Accepts the options:
 29 * - separator: separator to use between label and content (defaults to PHP_EOL)
 30 * - placement: whether to append or prepend label to content (defaults to prepend)
 31 * - tag: if set, used to wrap the label in an additional HTML tag
 32 * - opt(ional)Prefix: a prefix to the label to use when the element is optional
 33 * - opt(iona)lSuffix: a suffix to the label to use when the element is optional
 34 * - req(uired)Prefix: a prefix to the label to use when the element is required
 35 * - req(uired)Suffix: a suffix to the label to use when the element is required
 36 *
 37 * Any other options passed will be used as HTML attributes of the label tag.
 38 *
 39 * @category   Zend
 40 * @package    Zend_Form
 41 * @subpackage Decorator
 42 * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
 43 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 44 * @version    $Id: Label.php 24594 2012-01-05 21:27:01Z matthew $
 45 */
 46class Zend_Form_Decorator_Label extends Zend_Form_Decorator_Abstract
 47{
 48    /**
 49     * Default placement: prepend
 50     * @var string
 51     */
 52    protected $_placement = 'PREPEND';
 53
 54    /**
 55     * HTML tag with which to surround label
 56     * @var string
 57     */
 58    protected $_tag;
 59
 60    /**
 61     * Class for the HTML tag with which to surround label
 62     * @var string
 63     */
 64    protected $_tagClass;
 65
 66    /**
 67     * Set element ID
 68     *
 69     * @param  string $id
 70     * @return Zend_Form_Decorator_Label
 71     */
 72    public function setId($id)
 73    {
 74        $this->setOption('id', $id);
 75        return $this;
 76    }
 77
 78    /**
 79     * Retrieve element ID (used in 'for' attribute)
 80     *
 81     * If none set in decorator, looks first for element 'id' attribute, and
 82     * defaults to element name.
 83     *
 84     * @return string
 85     */
 86    public function getId()
 87    {
 88        $id = $this->getOption('id');
 89        if (null === $id) {
 90            if (null !== ($element = $this->getElement())) {
 91                $id = $element->getId();
 92                $this->setId($id);
 93            }
 94        }
 95
 96        return $id;
 97    }
 98
 99    /**
100     * Set HTML tag with which to surround label
101     *
102     * @param  string $tag
103     * @return Zend_Form_Decorator_Label
104     */
105    public function setTag($tag)
106    {
107        if (empty($tag)) {
108            $this->_tag = null;
109        } else {
110            $this->_tag = (string) $tag;
111        }
112
113        $this->removeOption('tag');
114
115        return $this;
116    }
117
118    /**
119     * Get HTML tag, if any, with which to surround label
120     *
121     * @return void
122     */
123    public function getTag()
124    {
125        if (null === $this->_tag) {
126            $tag = $this->getOption('tag');
127            if (null !== $tag) {
128                $this->removeOption('tag');
129                $this->setTag($tag);
130            }
131            return $tag;
132        }
133
134        return $this->_tag;
135    }
136
137    /**
138     * Set the class to apply to the HTML tag with which to surround label
139     *
140     * @param  string $tagClass
141     * @return Zend_Form_Decorator_Label
142     */
143    public function setTagClass($tagClass)
144    {
145        if (empty($tagClass)) {
146            $this->_tagClass = null;
147        } else {
148            $this->_tagClass = (string) $tagClass;
149        }
150
151        $this->removeOption('tagClass');
152
153        return $this;
154    }
155
156    /**
157     * Get the class to apply to the HTML tag, if any, with which to surround label
158     *
159     * @return void
160     */
161    public function getTagClass()
162    {
163        if (null === $this->_tagClass) {
164            $tagClass = $this->getOption('tagClass');
165            if (null !== $tagClass) {
166                $this->removeOption('tagClass');
167                $this->setTagClass($tagClass);
168            }
169        }
170
171        return $this->_tagClass;
172    }
173
174    /**
175     * Get class with which to define label
176     *
177     * Appends either 'optional' or 'required' to class, depending on whether
178     * or not the element is required.
179     *
180     * @return string
181     */
182    public function getClass()
183    {
184        $class   = '';
185        $element = $this->getElement();
186
187        $decoratorClass = $this->getOption('class');
188        if (!empty($decoratorClass)) {
189            $class .= ' ' . $decoratorClass;
190        }
191
192        $type  = $element->isRequired() ? 'required' : 'optional';
193
194        if (!strstr($class, $type)) {
195            $class .= ' ' . $type;
196            $class = trim($class);
197        }
198
199        return $class;
200    }
201
202    /**
203     * Load an optional/required suffix/prefix key
204     *
205     * @param  string $key
206     * @return void
207     */
208    protected function _loadOptReqKey($key)
209    {
210        if (!isset($this->$key)) {
211            $value = $this->getOption($key);
212            $this->$key = (string) $value;
213            if (null !== $value) {
214                $this->removeOption($key);
215            }
216        }
217    }
218
219    /**
220     * Overloading
221     *
222     * Currently overloads:
223     *
224     * - getOpt(ional)Prefix()
225     * - getOpt(ional)Suffix()
226     * - getReq(uired)Prefix()
227     * - getReq(uired)Suffix()
228     * - setOpt(ional)Prefix()
229     * - setOpt(ional)Suffix()
230     * - setReq(uired)Prefix()
231     * - setReq(uired)Suffix()
232     *
233     * @param  string $method
234     * @param  array $args
235     * @return mixed
236     * @throws Zend_Form_Exception for unsupported methods
237     */
238    public function __call($method, $args)
239    {
240        $tail = substr($method, -6);
241        $head = substr($method, 0, 3);
242        if (in_array($head, array('get', 'set'))
243            && (('Prefix' == $tail) || ('Suffix' == $tail))
244        ) {
245            $position = substr($method, -6);
246            $type     = strtolower(substr($method, 3, 3));
247            switch ($type) {
248                case 'req':
249                    $key = 'required' . $position;
250                    break;
251                case 'opt':
252                    $key = 'optional' . $position;
253                    break;
254                default:
255                    require_once 'Zend/Form/Exception.php';
256                    throw new Zend_Form_Exception(sprintf('Invalid method "%s" called in Label decorator, and detected as type %s', $method, $type));
257            }
258
259            switch ($head) {
260                case 'set':
261                    if (0 === count($args)) {
262                        require_once 'Zend/Form/Exception.php';
263                        throw new Zend_Form_Exception(sprintf('Method "%s" requires at least one argument; none provided', $method));
264                    }
265                    $value = array_shift($args);
266                    $this->$key = $value;
267                    return $this;
268                case 'get':
269                default:
270                    if (null === ($element = $this->getElement())) {
271                        $this->_loadOptReqKey($key);
272                    } elseif (isset($element->$key)) {
273                        $this->$key = (string) $element->$key;
274                    } else {
275                        $this->_loadOptReqKey($key);
276                    }
277                    return $this->$key;
278            }
279        }
280
281        require_once 'Zend/Form/Exception.php';
282        throw new Zend_Form_Exception(sprintf('Invalid method "%s" called in Label decorator', $method));
283    }
284
285    /**
286     * Get label to render
287     *
288     * @return string
289     */
290    public function getLabel()
291    {
292        if (null === ($element = $this->getElement())) {
293            return '';
294        }
295
296        $label = $element->getLabel();
297        $label = trim($label);
298
299        if (empty($label)) {
300            return '';
301        }
302
303        if (null !== ($translator = $element->getTranslator())) {
304            $label = $translator->translate($label);
305        }
306
307        $optPrefix = $this->getOptPrefix();
308        $optSuffix = $this->getOptSuffix();
309        $reqPrefix = $this->getReqPrefix();
310        $reqSuffix = $this->getReqSuffix();
311        $separator = $this->getSeparator();
312
313        if (!empty($label)) {
314            if ($element->isRequired()) {
315                $label = $reqPrefix . $label . $reqSuffix;
316            } else {
317                $label = $optPrefix . $label . $optSuffix;
318            }
319        }
320
321        return $label;
322    }
323
324
325    /**
326     * Render a label
327     *
328     * @param  string $content
329     * @return string
330     */
331    public function render($content)
332    {
333        $element = $this->getElement();
334        $view    = $element->getView();
335        if (null === $view) {
336            return $content;
337        }
338
339        $label     = $this->getLabel();
340        $separator = $this->getSeparator();
341        $placement = $this->getPlacement();
342        $tag       = $this->getTag();
343        $tagClass  = $this->getTagClass();
344        $id        = $this->getId();
345        $class     = $this->getClass();
346        $options   = $this->getOptions();
347
348
349        if (empty($label) && empty($tag)) {
350            return $content;
351        }
352
353        if (!empty($label)) {
354            $options['class'] = $class;
355            $label = $view->formLabel($element->getFullyQualifiedName(), trim($label), $options);
356        } else {
357            $label = '&#160;';
358        }
359
360        if (null !== $tag) {
361            require_once 'Zend/Form/Decorator/HtmlTag.php';
362            $decorator = new Zend_Form_Decorator_HtmlTag();
363            if (null !== $this->_tagClass) {
364                $decorator->setOptions(array('tag'   => $tag,
365                                             'id'    => $id . '-label',
366                                             'class' => $tagClass));
367            } else {
368                $decorator->setOptions(array('tag'   => $tag,
369                                             'id'    => $id . '-label'));
370            }
371
372            $label = $decorator->render($label);
373        }
374
375        switch ($placement) {
376            case self::APPEND:
377                return $content . $separator . $label;
378            case self::PREPEND:
379                return $label . $separator . $content;
380        }
381    }
382}