interface/modules/zend_modules/library/Zend/Form/Element.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Form;
  11
  12 use Traversable;
  13 use Zend\Stdlib\ArrayUtils;
  14 use Zend\Stdlib\InitializableInterface;
  15
  16 class Element implements
  17     ElementAttributeRemovalInterface,
  18     ElementInterface,
  19     InitializableInterface
  20 {
  21     /**
  22      * @var array
  23      */
  24     protected $attributes = array();
  25
  26     /**
  27      * @var string
  28      */
  29     protected $label;
  30
  31     /**
  32      * @var array
  33      */
  34     protected $labelAttributes;
  35
  36     /**
  37      * @var array Validation error messages
  38      */
  39     protected $messages = array();
  40
  41     /**
  42      * @var array custom options
  43      */
  44     protected $options = array();
  45
  46     /**
  47      * @var mixed
  48      */
  49     protected $value;
  50
  51     /**
  52      * @param  null|int|string  $name    Optional name for the element
  53      * @param  array            $options Optional options for the element
  54      * @throws Exception\InvalidArgumentException
  55      */
  56     public function __construct($name = null, $options = array())
  57     {
  58         if (null !== $name) {
  59             $this->setName($name);
  60         }
  61
  62         if (!empty($options)) {
  63             $this->setOptions($options);
  64         }
  65     }
  66
  67     /**
  68      * This function is automatically called when creating element with factory. It
  69      * allows to perform various operations (add elements...)
  70      *
  71      * @return void
  72      */
  73     public function init()
  74     {
  75     }
  76
  77     /**
  78      * Set value for name
  79      *
  80      * @param  string $name
  81      * @return Element|ElementInterface
  82      */
  83     public function setName($name)
  84     {
  85         $this->setAttribute('name', $name);
  86         return $this;
  87     }
  88
  89     /**
  90      * Get value for name
  91      *
  92      * @return string|int
  93      */
  94     public function getName()
  95     {
  96         return $this->getAttribute('name');
  97     }
  98
  99     /**
 100      * Set options for an element. Accepted options are:
 101      * - label: label to associate with the element
 102      * - label_attributes: attributes to use when the label is rendered
 103      *
 104      * @param  array|Traversable $options
 105      * @return Element|ElementInterface
 106      * @throws Exception\InvalidArgumentException
 107      */
 108     public function setOptions($options)
 109     {
 110         if ($options instanceof Traversable) {
 111             $options = ArrayUtils::iteratorToArray($options);
 112         } elseif (!is_array($options)) {
 113             throw new Exception\InvalidArgumentException(
 114                 'The options parameter must be an array or a Traversable'
 115             );
 116         }
 117
 118         if (isset($options['label'])) {
 119             $this->setLabel($options['label']);
 120         }
 121
 122         if (isset($options['label_attributes'])) {
 123             $this->setLabelAttributes($options['label_attributes']);
 124         }
 125
 126         $this->options = $options;
 127
 128         return $this;
 129     }
 130
 131     /**
 132      * Get defined options
 133      *
 134      * @return array
 135      */
 136     public function getOptions()
 137     {
 138         return $this->options;
 139     }
 140
 141     /**
 142      * Return the specified option
 143      *
 144      * @param string $option
 145      * @return NULL|mixed
 146      */
 147     public function getOption($option)
 148     {
 149         if (!isset($this->options[$option])) {
 150             return null;
 151         }
 152
 153         return $this->options[$option];
 154     }
 155
 156     /**
 157      * Set a single element attribute
 158      *
 159      * @param  string $key
 160      * @param  mixed  $value
 161      * @return Element|ElementInterface
 162      */
 163     public function setAttribute($key, $value)
 164     {
 165         // Do not include the value in the list of attributes
 166         if ($key === 'value') {
 167             $this->setValue($value);
 168             return $this;
 169         }
 170         $this->attributes[$key] = $value;
 171         return $this;
 172     }
 173
 174     /**
 175      * Retrieve a single element attribute
 176      *
 177      * @param  $key
 178      * @return mixed|null
 179      */
 180     public function getAttribute($key)
 181     {
 182         if (!array_key_exists($key, $this->attributes)) {
 183             return null;
 184         }
 185         return $this->attributes[$key];
 186     }
 187
 188     /**
 189      * Remove a single attribute
 190      *
 191      * @param string $key
 192      * @return ElementInterface
 193      */
 194     public function removeAttribute($key)
 195     {
 196         unset($this->attributes[$key]);
 197         return $this;
 198     }
 199
 200     /**
 201      * Does the element has a specific attribute ?
 202      *
 203      * @param  string $key
 204      * @return bool
 205      */
 206     public function hasAttribute($key)
 207     {
 208         return array_key_exists($key, $this->attributes);
 209     }
 210
 211     /**
 212      * Set many attributes at once
 213      *
 214      * Implementation will decide if this will overwrite or merge.
 215      *
 216      * @param  array|Traversable $arrayOrTraversable
 217      * @return Element|ElementInterface
 218      * @throws Exception\InvalidArgumentException
 219      */
 220     public function setAttributes($arrayOrTraversable)
 221     {
 222         if (!is_array($arrayOrTraversable) && !$arrayOrTraversable instanceof Traversable) {
 223             throw new Exception\InvalidArgumentException(sprintf(
 224                 '%s expects an array or Traversable argument; received "%s"',
 225                 __METHOD__,
 226                 (is_object($arrayOrTraversable) ? get_class($arrayOrTraversable) : gettype($arrayOrTraversable))
 227             ));
 228         }
 229         foreach ($arrayOrTraversable as $key => $value) {
 230             $this->setAttribute($key, $value);
 231         }
 232         return $this;
 233     }
 234
 235     /**
 236      * Retrieve all attributes at once
 237      *
 238      * @return array|Traversable
 239      */
 240     public function getAttributes()
 241     {
 242         return $this->attributes;
 243     }
 244
 245     /**
 246      * Remove many attributes at once
 247      *
 248      * @param array $keys
 249      * @return ElementInterface
 250      */
 251     public function removeAttributes(array $keys)
 252     {
 253         foreach ($keys as $key) {
 254             unset($this->attributes[$key]);
 255         }
 256
 257         return $this;
 258     }
 259
 260     /**
 261      * Clear all attributes
 262      *
 263      * @return Element|ElementInterface
 264      */
 265     public function clearAttributes()
 266     {
 267         $this->attributes = array();
 268         return $this;
 269     }
 270
 271     /**
 272      * Set the element value
 273      *
 274      * @param  mixed $value
 275      * @return Element
 276      */
 277     public function setValue($value)
 278     {
 279         $this->value = $value;
 280         return $this;
 281     }
 282
 283     /**
 284      * Retrieve the element value
 285      *
 286      * @return mixed
 287      */
 288     public function getValue()
 289     {
 290         return $this->value;
 291     }
 292
 293     /**
 294      * Set the label used for this element
 295      *
 296      * @param $label
 297      * @return Element|ElementInterface
 298      */
 299     public function setLabel($label)
 300     {
 301         if (is_string($label)) {
 302             $this->label = $label;
 303         }
 304
 305         return $this;
 306     }
 307
 308     /**
 309      * Retrieve the label used for this element
 310      *
 311      * @return string
 312      */
 313     public function getLabel()
 314     {
 315         return $this->label;
 316     }
 317
 318     /**
 319      * Set the attributes to use with the label
 320      *
 321      * @param array $labelAttributes
 322      * @return Element|ElementInterface
 323      */
 324     public function setLabelAttributes(array $labelAttributes)
 325     {
 326         $this->labelAttributes = $labelAttributes;
 327         return $this;
 328     }
 329
 330     /**
 331      * Get the attributes to use with the label
 332      *
 333      * @return array
 334      */
 335     public function getLabelAttributes()
 336     {
 337         return $this->labelAttributes;
 338     }
 339
 340     /**
 341      * Set a list of messages to report when validation fails
 342      *
 343      * @param  array|Traversable $messages
 344      * @return Element|ElementInterface
 345      * @throws Exception\InvalidArgumentException
 346      */
 347     public function setMessages($messages)
 348     {
 349         if (!is_array($messages) && !$messages instanceof Traversable) {
 350             throw new Exception\InvalidArgumentException(sprintf(
 351                 '%s expects an array or Traversable object of validation error messages; received "%s"',
 352                 __METHOD__,
 353                 (is_object($messages) ? get_class($messages) : gettype($messages))
 354             ));
 355         }
 356
 357         $this->messages = $messages;
 358         return $this;
 359     }
 360
 361     /**
 362      * Get validation error messages, if any.
 363      *
 364      * Returns a list of validation failure messages, if any.
 365      *
 366      * @return array|Traversable
 367      */
 368     public function getMessages()
 369     {
 370         return $this->messages;
 371     }
 372 }