system/helpers/form.php

   1 <?php defined('SYSPATH') OR die('No direct access allowed.');
   2 /**
   3  * Form helper class.
   4  *
   5  * $Id: form.php 3917 2009-01-21 03:06:22Z zombor $
   6  *
   7  * @package    Core
   8  * @author     Kohana Team
   9  * @copyright  (c) 2007-2008 Kohana Team
  10  * @license    http://kohanaphp.com/license.html
  11  */
  12 class form {
  13
  14         /**
  15          * Generates an opening HTML form tag.
  16          *
  17          * @param   string  form action attribute
  18          * @param   array   extra attributes
  19          * @param   array   hidden fields to be created immediately after the form tag
  20          * @return  string
  21          */
  22         public static function open($action = NULL, $attr = array(), $hidden = NULL)
  23         {
  24                 // Make sure that the method is always set
  25                 empty($attr['method']) and $attr['method'] = 'post';
  26
  27                 if ($attr['method'] !== 'post' AND $attr['method'] !== 'get')
  28                 {
  29                         // If the method is invalid, use post
  30                         $attr['method'] = 'post';
  31                 }
  32
  33                 if ($action === NULL)
  34                 {
  35                         // Use the current URL as the default action
  36                         $action = url::site(Router::$complete_uri);
  37                 }
  38                 elseif (strpos($action, '://') === FALSE)
  39                 {
  40                         // Make the action URI into a URL
  41                         $action = url::site($action);
  42                 }
  43
  44                 // Set action
  45                 $attr['action'] = $action;
  46
  47                 // Form opening tag
  48                 $form = '<form'.form::attributes($attr).'>'."\n";
  49
  50                 // Add hidden fields immediate after opening tag
  51                 empty($hidden) or $form .= form::hidden($hidden);
  52
  53                 return $form;
  54         }
  55
  56         /**
  57          * Generates an opening HTML form tag that can be used for uploading files.
  58          *
  59          * @param   string  form action attribute
  60          * @param   array   extra attributes
  61          * @param   array   hidden fields to be created immediately after the form tag
  62          * @return  string
  63          */
  64         public static function open_multipart($action = NULL, $attr = array(), $hidden = array())
  65         {
  66                 // Set multi-part form type
  67                 $attr['enctype'] = 'multipart/form-data';
  68
  69                 return form::open($action, $attr, $hidden);
  70         }
  71
  72         /**
  73          * Generates a fieldset opening tag.
  74          *
  75          * @param   array   html attributes
  76          * @param   string  a string to be attached to the end of the attributes
  77          * @return  string
  78          */
  79         public static function open_fieldset($data = NULL, $extra = '')
  80         {
  81                 return '<fieldset'.html::attributes((array) $data).' '.$extra.'>'."\n";
  82         }
  83
  84         /**
  85          * Generates a fieldset closing tag.
  86          *
  87          * @return  string
  88          */
  89         public static function close_fieldset()
  90         {
  91                 return '</fieldset>'."\n";
  92         }
  93
  94         /**
  95          * Generates a legend tag for use with a fieldset.
  96          *
  97          * @param   string  legend text
  98          * @param   array   HTML attributes
  99          * @param   string  a string to be attached to the end of the attributes
 100          * @return  string
 101          */
 102         public static function legend($text = '', $data = NULL, $extra = '')
 103         {
 104                 return '<legend'.form::attributes((array) $data).' '.$extra.'>'.$text.'</legend>'."\n";
 105         }
 106
 107         /**
 108          * Generates hidden form fields.
 109          * You can pass a simple key/value string or an associative array with multiple values.
 110          *
 111          * @param   string|array  input name (string) or key/value pairs (array)
 112          * @param   string        input value, if using an input name
 113          * @return  string
 114          */
 115         public static function hidden($data, $value = '')
 116         {
 117                 if ( ! is_array($data))
 118                 {
 119                         $data = array
 120                         (
 121                                 $data => $value
 122                         );
 123                 }
 124
 125                 $input = '';
 126                 foreach ($data as $name => $value)
 127                 {
 128                         $attr = array
 129                         (
 130                                 'type'  => 'hidden',
 131                                 'name'  => $name,
 132                                 'value' => $value
 133                         );
 134
 135                         $input .= form::input($attr)."\n";
 136                 }
 137
 138                 return $input;
 139         }
 140
 141         /**
 142          * Creates an HTML form input tag. Defaults to a text type.
 143          *
 144          * @param   string|array  input name or an array of HTML attributes
 145          * @param   string        input value, when using a name
 146          * @param   string        a string to be attached to the end of the attributes
 147          * @param   boolean       encode existing entities
 148          * @return  string
 149          */
 150         public static function input($data, $value = '', $extra = '', $double_encode = TRUE )
 151         {
 152                 if ( ! is_array($data))
 153                 {
 154                         $data = array('name' => $data);
 155                 }
 156
 157                 // Type and value are required attributes
 158                 $data += array
 159                 (
 160                         'type'  => 'text',
 161                         'value' => $value
 162                 );
 163
 164                 return '<input'.form::attributes($data).' '.$extra.' />';
 165         }
 166
 167         /**
 168          * Creates a HTML form password input tag.
 169          *
 170          * @param   string|array  input name or an array of HTML attributes
 171          * @param   string        input value, when using a name
 172          * @param   string        a string to be attached to the end of the attributes
 173          * @return  string
 174          */
 175         public static function password($data, $value = '', $extra = '')
 176         {
 177                 if ( ! is_array($data))
 178                 {
 179                         $data = array('name' => $data);
 180                 }
 181
 182                 $data['type'] = 'password';
 183
 184                 return form::input($data, $value, $extra);
 185         }
 186
 187         /**
 188          * Creates an HTML form upload input tag.
 189          *
 190          * @param   string|array  input name or an array of HTML attributes
 191          * @param   string        input value, when using a name
 192          * @param   string        a string to be attached to the end of the attributes
 193          * @return  string
 194          */
 195         public static function upload($data, $value = '', $extra = '')
 196         {
 197                 if ( ! is_array($data))
 198                 {
 199                         $data = array('name' => $data);
 200                 }
 201
 202                 $data['type'] = 'file';
 203
 204                 return form::input($data, $value, $extra);
 205         }
 206
 207         /**
 208          * Creates an HTML form textarea tag.
 209          *
 210          * @param   string|array  input name or an array of HTML attributes
 211          * @param   string        input value, when using a name
 212          * @param   string        a string to be attached to the end of the attributes
 213          * @param   boolean       encode existing entities
 214          * @return  string
 215          */
 216         public static function textarea($data, $value = '', $extra = '', $double_encode = TRUE )
 217         {
 218                 if ( ! is_array($data))
 219                 {
 220                         $data = array('name' => $data);
 221                 }
 222
 223                 // Use the value from $data if possible, or use $value
 224                 $value = isset($data['value']) ? $data['value'] : $value;
 225
 226                 // Value is not part of the attributes
 227                 unset($data['value']);
 228
 229                 return '<textarea'.form::attributes($data, 'textarea').' '.$extra.'>'.html::specialchars($value, $double_encode).'</textarea>';
 230         }
 231
 232         /**
 233          * Creates an HTML form select tag, or "dropdown menu".
 234          *
 235          * @param   string|array  input name or an array of HTML attributes
 236          * @param   array         select options, when using a name
 237          * @param   string        option key that should be selected by default
 238          * @param   string        a string to be attached to the end of the attributes
 239          * @return  string
 240          */
 241         public static function dropdown($data, $options = NULL, $selected = NULL, $extra = '')
 242         {
 243
 244                 if ( ! is_array($data))
 245                 {
 246                         $data = array('name' => $data);
 247                 }
 248                 else
 249                 {
 250                         if (isset($data['options']))
 251                         {
 252                                 // Use data options
 253                                 $options = $data['options'];
 254                                 unset($data['options']);
 255                         }
 256
 257                         if (isset($data['selected']))
 258                         {
 259                                 // Use data selected
 260                                 $selected = $data['selected'];
 261                                 unset($data['selected']);
 262                         }
 263                 }
 264
 265                 $input = '<select'.form::attributes($data, 'select').' '.$extra.'>'."\n";
 266                 foreach ((array) $options as $key => $val)
 267                 {
 268                         // Key should always be a string
 269                         $key = (string) $key;
 270
 271                         // Selected must always be a string
 272                         $selected = (string) $selected;
 273
 274                         if (is_array($val))
 275                         {
 276                                 $input .= '<optgroup label="'.$key.'">'."\n";
 277                                 foreach ($val as $inner_key => $inner_val)
 278                                 {
 279                                         // Inner key should always be a string
 280                                         $inner_key = (string) $inner_key;
 281
 282                                         if (is_array($selected))
 283                                         {
 284                                                 $sel = in_array($inner_key, $selected, TRUE);
 285                                         }
 286                                         else
 287                                         {
 288                                                 $sel = ($selected === $inner_key);
 289                                         }
 290
 291                                         $sel = ($sel === TRUE) ? ' selected="selected"' : '';
 292                                         $input .= '<option value="'.$inner_key.'"'.$sel.'>'.$inner_val.'</option>'."\n";
 293                                 }
 294                                 $input .= '</optgroup>'."\n";
 295                         }
 296                         else
 297                         {
 298                                 $sel = ($selected === $key) ? ' selected="selected"' : '';
 299                                 $input .= '<option value="'.$key.'"'.$sel.'>'.$val.'</option>'."\n";
 300                         }
 301                 }
 302                 $input .= '</select>';
 303
 304                 return $input;
 305         }
 306
 307         /**
 308          * Creates an HTML form checkbox input tag.
 309          *
 310          * @param   string|array  input name or an array of HTML attributes
 311          * @param   string        input value, when using a name
 312          * @param   boolean       make the checkbox checked by default
 313          * @param   string        a string to be attached to the end of the attributes
 314          * @return  string
 315          */
 316         public static function checkbox($data, $value = '', $checked = FALSE, $extra = '')
 317         {
 318                 if ( ! is_array($data))
 319                 {
 320                         $data = array('name' => $data);
 321                 }
 322
 323                 $data['type'] = 'checkbox';
 324
 325                 if ($checked == TRUE OR (isset($data['checked']) AND $data['checked'] == TRUE))
 326                 {
 327                         $data['checked'] = 'checked';
 328                 }
 329                 else
 330                 {
 331                         unset($data['checked']);
 332                 }
 333
 334                 return form::input($data, $value, $extra);
 335         }
 336
 337         /**
 338          * Creates an HTML form radio input tag.
 339          *
 340          * @param   string|array  input name or an array of HTML attributes
 341          * @param   string        input value, when using a name
 342          * @param   boolean       make the radio selected by default
 343          * @param   string        a string to be attached to the end of the attributes
 344          * @return  string
 345          */
 346         public static function radio($data = '', $value = '', $checked = FALSE, $extra = '')
 347         {
 348                 if ( ! is_array($data))
 349                 {
 350                         $data = array('name' => $data);
 351                 }
 352
 353                 $data['type'] = 'radio';
 354
 355                 if ($checked == TRUE OR (isset($data['checked']) AND $data['checked'] == TRUE))
 356                 {
 357                         $data['checked'] = 'checked';
 358                 }
 359                 else
 360                 {
 361                         unset($data['checked']);
 362                 }
 363
 364                 return form::input($data, $value, $extra);
 365         }
 366
 367         /**
 368          * Creates an HTML form submit input tag.
 369          *
 370          * @param   string|array  input name or an array of HTML attributes
 371          * @param   string        input value, when using a name
 372          * @param   string        a string to be attached to the end of the attributes
 373          * @return  string
 374          */
 375         public static function submit($data = '', $value = '', $extra = '')
 376         {
 377                 if ( ! is_array($data))
 378                 {
 379                         $data = array('name' => $data);
 380                 }
 381
 382                 if (empty($data['name']))
 383                 {
 384                         // Remove the name if it is empty
 385                         unset($data['name']);
 386                 }
 387
 388                 $data['type'] = 'submit';
 389
 390                 return form::input($data, $value, $extra);
 391         }
 392
 393         /**
 394          * Creates an HTML form button input tag.
 395          *
 396          * @param   string|array  input name or an array of HTML attributes
 397          * @param   string        input value, when using a name
 398          * @param   string        a string to be attached to the end of the attributes
 399          * @return  string
 400          */
 401         public static function button($data = '', $value = '', $extra = '')
 402         {
 403                 if ( ! is_array($data))
 404                 {
 405                         $data = array('name' => $data);
 406                 }
 407
 408                 if (empty($data['name']))
 409                 {
 410                         // Remove the name if it is empty
 411                         unset($data['name']);
 412                 }
 413
 414                 if (isset($data['value']) AND empty($value))
 415                 {
 416                         $value = arr::remove('value', $data);
 417                 }
 418
 419                 return '<button'.form::attributes($data, 'button').' '.$extra.'>'.$value.'</button>';
 420         }
 421
 422         /**
 423          * Closes an open form tag.
 424          *
 425          * @param   string  string to be attached after the closing tag
 426          * @return  string
 427          */
 428         public static function close($extra = '')
 429         {
 430                 return '</form>'."\n".$extra;
 431         }
 432
 433         /**
 434          * Creates an HTML form label tag.
 435          *
 436          * @param   string|array  label "for" name or an array of HTML attributes
 437          * @param   string        label text or HTML
 438          * @param   string        a string to be attached to the end of the attributes
 439          * @return  string
 440          */
 441         public static function label($data = '', $text = NULL, $extra = '')
 442         {
 443                 if ( ! is_array($data))
 444                 {
 445                         if (is_string($data))
 446                         {
 447                                 // Specify the input this label is for
 448                                 $data = array('for' => $data);
 449                         }
 450                         else
 451                         {
 452                                 // No input specified
 453                                 $data = array();
 454                         }
 455                 }
 456
 457                 if ($text === NULL AND isset($data['for']))
 458                 {
 459                         // Make the text the human-readable input name
 460                         $text = ucwords(inflector::humanize($data['for']));
 461                 }
 462
 463                 return '<label'.form::attributes($data).' '.$extra.'>'.$text.'</label>';
 464         }
 465
 466         /**
 467          * Sorts, possibly shuffles, but most likely keeps the order of a
 468          * key/value array of HTML attributes, and returns an attribute string.
 469          *
 470          * Beacause this is Kohana, this also does some magical stuff... In this
 471          * case, it sets id attribute to the name attribute, if id doesn't exist.
 472          *
 473          * @param   array   HTML attributes array
 474          * @return  string
 475          */
 476         public static function attributes($attr, $type = NULL)
 477         {
 478                 if (empty($attr))
 479                         return '';
 480
 481                 if (isset($attr['name']) AND empty($attr['id']) AND strpos($attr['name'], '[') === FALSE)
 482                 {
 483                         if ($type === NULL AND ! empty($attr['type']))
 484                         {
 485                                 // Set the type by the attributes
 486                                 $type = $attr['type'];
 487                         }
 488
 489                         switch ($type)
 490                         {
 491                                 case 'text':
 492                                 case 'textarea':
 493                                 case 'password':
 494                                 case 'select':
 495                                 case 'checkbox':
 496                                 case 'file':
 497                                 case 'image':
 498                                 case 'button':
 499                                 case 'submit':
 500                                         // Only specific types of inputs use name to id matching
 501                                         $attr['id'] = $attr['name'];
 502                                 break;
 503                         }
 504                 }
 505
 506                 // Combine the sorted and unsorted attributes and create an HTML string
 507                 return html::attributes($attr);
 508         }
 509
 510 } // End form