lib/form/selectgroups.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3 // +----------------------------------------------------------------------+
   4 // | PHP version 4.0                                                      |
   5 // +----------------------------------------------------------------------+
   6 // | Copyright (c) 1997-2003 The PHP Group                                |
   7 // +----------------------------------------------------------------------+
   8 // | This source file is subject to version 2.0 of the PHP license,       |
   9 // | that is bundled with this package in the file LICENSE, and is        |
  10 // | available at through the world-wide-web at                           |
  11 // | http://www.php.net/license/2_02.txt.                                 |
  12 // | If you did not receive a copy of the PHP license and are unable to   |
  13 // | obtain it through the world-wide-web, please send a note to          |
  14 // | license@php.net so we can mail you a copy immediately.               |
  15 // +----------------------------------------------------------------------+
  16 // | Authors: Adam Daniel <adaniel1@eesus.jnj.com>                        |
  17 // |          Bertrand Mansion <bmansion@mamasam.com>                     |
  18 // +----------------------------------------------------------------------+
  19 //
  20 // $Id$
  21
  22 require_once('HTML/QuickForm/element.php');
  23
  24 /**
  25  * Class to dynamically create an HTML SELECT with all options grouped in optgroups
  26  *
  27  * @author       Adam Daniel <adaniel1@eesus.jnj.com>
  28  * @author       Bertrand Mansion <bmansion@mamasam.com>
  29  * @version      1.0
  30  * @since        PHP4.04pl1
  31  * @access       public
  32  */
  33 class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
  34
  35     // {{{ properties
  36
  37     /** add choose option */
  38     var $showchoose = false;
  39
  40     /**
  41      * Contains the select optgroups
  42      *
  43      * @var       array
  44      * @since     1.0
  45      * @access    private
  46      */
  47     var $_optGroups = array();
  48
  49     /**
  50      * Default values of the SELECT
  51      *
  52      * @var       string
  53      * @since     1.0
  54      * @access    private
  55      */
  56     var $_values = null;
  57
  58     /**
  59      * html for help button, if empty then no help
  60      *
  61      * @var string
  62      */
  63     var $_helpbutton='';
  64     var $_hiddenLabel=false;
  65
  66     /**
  67      * Class constructor
  68      *
  69      * @param     string    Select name attribute
  70      * @param     mixed     Label(s) for the select
  71      * @param     mixed     Data to be used to populate options
  72      * @param     mixed     An array whose keys are labels for optgroups and whose values are arrays similar to those passed
  73      *                          to the select element with keys that are values for options and values are strings for display.
  74      * @param     mixed     Either a typical HTML attribute string or an associative array
  75      * @param     bool      add standard moodle "Choose..." option as first item
  76      * @since     1.0
  77      * @access    public
  78      * @return    void
  79      */
  80     function MoodleQuickForm_selectgroups($elementName=null, $elementLabel=null, $optgrps=null, $attributes=null, $showchoose=false)
  81     {
  82         $this->showchoose = $showchoose;
  83         HTML_QuickForm_element::HTML_QuickForm_element($elementName, $elementLabel, $attributes);
  84         $this->_persistantFreeze = true;
  85         $this->_type = 'selectgroups';
  86         if (isset($optgrps)) {
  87             $this->loadArrayOptGroups($optgrps);
  88         }
  89     } //end constructor
  90
  91     // }}}
  92     // {{{ apiVersion()
  93
  94
  95     /**
  96      * Sets the default values of the select box
  97      *
  98      * @param     mixed    $values  Array or comma delimited string of selected values
  99      * @since     1.0
 100      * @access    public
 101      * @return    void
 102      */
 103     function setSelected($values)
 104     {
 105         if (is_string($values) && $this->getMultiple()) {
 106             $values = split("[ ]?,[ ]?", $values);
 107         }
 108         if (is_array($values)) {
 109             $this->_values = array_values($values);
 110         } else {
 111             $this->_values = array($values);
 112         }
 113     } //end func setSelected
 114
 115     // }}}
 116     // {{{ getSelected()
 117
 118     /**
 119      * Returns an array of the selected values
 120      *
 121      * @since     1.0
 122      * @access    public
 123      * @return    array of selected values
 124      */
 125     function getSelected()
 126     {
 127         return $this->_values;
 128     } // end func getSelected
 129
 130     // }}}
 131     // {{{ setName()
 132
 133     /**
 134      * Sets the input field name
 135      *
 136      * @param     string    $name   Input field name attribute
 137      * @since     1.0
 138      * @access    public
 139      * @return    void
 140      */
 141     function setName($name)
 142     {
 143         $this->updateAttributes(array('name' => $name));
 144     } //end func setName
 145
 146     // }}}
 147     // {{{ getName()
 148
 149     /**
 150      * Returns the element name
 151      *
 152      * @since     1.0
 153      * @access    public
 154      * @return    string
 155      */
 156     function getName()
 157     {
 158         return $this->getAttribute('name');
 159     } //end func getName
 160
 161     // }}}
 162     // {{{ getPrivateName()
 163
 164     /**
 165      * Returns the element name (possibly with brackets appended)
 166      *
 167      * @since     1.0
 168      * @access    public
 169      * @return    string
 170      */
 171     function getPrivateName()
 172     {
 173         if ($this->getAttribute('multiple')) {
 174             return $this->getName() . '[]';
 175         } else {
 176             return $this->getName();
 177         }
 178     } //end func getPrivateName
 179
 180     // }}}
 181     // {{{ setValue()
 182
 183     /**
 184      * Sets the value of the form element
 185      *
 186      * @param     mixed    $values  Array or comma delimited string of selected values
 187      * @since     1.0
 188      * @access    public
 189      * @return    void
 190      */
 191     function setValue($value)
 192     {
 193         $this->setSelected($value);
 194     } // end func setValue
 195
 196     // }}}
 197     // {{{ getValue()
 198
 199     /**
 200      * Returns an array of the selected values
 201      *
 202      * @since     1.0
 203      * @access    public
 204      * @return    array of selected values
 205      */
 206     function getValue()
 207     {
 208         return $this->_values;
 209     } // end func getValue
 210
 211     // }}}
 212     // {{{ setSize()
 213
 214     /**
 215      * Sets the select field size, only applies to 'multiple' selects
 216      *
 217      * @param     int    $size  Size of select  field
 218      * @since     1.0
 219      * @access    public
 220      * @return    void
 221      */
 222     function setSize($size)
 223     {
 224         $this->updateAttributes(array('size' => $size));
 225     } //end func setSize
 226
 227     // }}}
 228     // {{{ getSize()
 229
 230     /**
 231      * Returns the select field size
 232      *
 233      * @since     1.0
 234      * @access    public
 235      * @return    int
 236      */
 237     function getSize()
 238     {
 239         return $this->getAttribute('size');
 240     } //end func getSize
 241
 242     // }}}
 243     // {{{ setMultiple()
 244
 245     /**
 246      * Sets the select mutiple attribute
 247      *
 248      * @param     bool    $multiple  Whether the select supports multi-selections
 249      * @since     1.2
 250      * @access    public
 251      * @return    void
 252      */
 253     function setMultiple($multiple)
 254     {
 255         if ($multiple) {
 256             $this->updateAttributes(array('multiple' => 'multiple'));
 257         } else {
 258             $this->removeAttribute('multiple');
 259         }
 260     } //end func setMultiple
 261
 262     // }}}
 263     // {{{ getMultiple()
 264
 265     /**
 266      * Returns the select mutiple attribute
 267      *
 268      * @since     1.2
 269      * @access    public
 270      * @return    bool    true if multiple select, false otherwise
 271      */
 272     function getMultiple()
 273     {
 274         return (bool)$this->getAttribute('multiple');
 275     } //end func getMultiple
 276
 277     /**
 278      * Loads the options from an associative array
 279      *
 280      * @param     array    $arr     Associative array of options
 281      * @param     mixed    $values  (optional) Array or comma delimited string of selected values
 282      * @since     1.0
 283      * @access    public
 284      * @return    PEAR_Error on error or true
 285      * @throws    PEAR_Error
 286      */
 287     function loadArrayOptGroups($arr, $values=null)
 288     {
 289         if (!is_array($arr)) {
 290             return PEAR::raiseError('Argument 1 of HTML_Select::loadArrayOptGroups is not a valid array');
 291         }
 292         if (isset($values)) {
 293             $this->setSelected($values);
 294         }
 295         foreach ($arr as $key => $val) {
 296             // Warning: new API since release 2.3
 297             $this->addOptGroup($key, $val);
 298         }
 299         return true;
 300     }
 301     /**
 302      * Adds a new OPTION to the SELECT
 303      *
 304      * @param     string    $text       Display text for the OPTION
 305      * @param     string    $value      Value for the OPTION
 306      * @param     mixed     $attributes Either a typical HTML attribute string
 307      *                                  or an associative array
 308      * @since     1.0
 309      * @access    public
 310      * @return    void
 311      */
 312     function addOptGroup($text, $value, $attributes=null)
 313     {
 314         if (null === $attributes) {
 315             $attributes = array('label' => $text);
 316         } else {
 317             $attributes = $this->_parseAttributes($attributes);
 318             $this->_updateAttrArray($attributes, array('label' => $text));
 319         }
 320         $index = count($this->_optGroups);
 321         $this->_optGroups[$index] = array('attr' => $attributes);
 322         $this->loadArrayOptions($index, $value);
 323     }
 324
 325     /**
 326      * Loads the options from an associative array
 327      *
 328      * @param     array    $arr     Associative array of options
 329      * @param     mixed    $values  (optional) Array or comma delimited string of selected values
 330      * @since     1.0
 331      * @access    public
 332      * @return    PEAR_Error on error or true
 333      * @throws    PEAR_Error
 334      */
 335     function loadArrayOptions($optgroup, $arr, $values=null)
 336     {
 337         if (!is_array($arr)) {
 338             return PEAR::raiseError('Argument 1 of HTML_Select::loadArray is not a valid array');
 339         }
 340         if (isset($values)) {
 341             $this->setSelected($values);
 342         }
 343         foreach ($arr as $key => $val) {
 344             // Warning: new API since release 2.3
 345             $this->addOption($optgroup, $val, $key);
 346         }
 347         return true;
 348     }
 349
 350     /**
 351      * Adds a new OPTION to an optgroup
 352      *
 353      * @param     string    $text       Display text for the OPTION
 354      * @param     string    $value      Value for the OPTION
 355      * @param     mixed     $attributes Either a typical HTML attribute string
 356      *                                  or an associative array
 357      * @since     1.0
 358      * @access    public
 359      * @return    void
 360      */
 361     function addOption($optgroup, $text, $value, $attributes=null)
 362     {
 363         if (null === $attributes) {
 364             $attributes = array('value' => $value);
 365         } else {
 366             $attributes = $this->_parseAttributes($attributes);
 367             if (isset($attributes['selected'])) {
 368                 // the 'selected' attribute will be set in toHtml()
 369                 $this->_removeAttr('selected', $attributes);
 370                 if (is_null($this->_values)) {
 371                     $this->_values = array($value);
 372                 } elseif (!in_array($value, $this->_values)) {
 373                     $this->_values[] = $value;
 374                 }
 375             }
 376             $this->_updateAttrArray($attributes, array('value' => $value));
 377         }
 378         $this->_optGroups[$optgroup]['options'][] = array('text' => $text, 'attr' => $attributes);
 379     }
 380
 381     /**
 382      * Returns the SELECT in HTML
 383      *
 384      * @since     1.0
 385      * @access    public
 386      * @return    string
 387      */
 388     function toHtml()
 389     {
 390         if ($this->_flagFrozen) {
 391             return $this->getFrozenHtml();
 392         } else {
 393             $tabs    = $this->_getTabs();
 394             $strHtml = '';
 395
 396             if ($this->getComment() != '') {
 397                 $strHtml .= $tabs . '<!-- ' . $this->getComment() . " //-->\n";
 398             }
 399
 400             if (!$this->getMultiple()) {
 401                 $attrString = $this->_getAttrString($this->_attributes);
 402             } else {
 403                 $myName = $this->getName();
 404                 $this->setName($myName . '[]');
 405                 $attrString = $this->_getAttrString($this->_attributes);
 406                 $this->setName($myName);
 407             }
 408             $strHtml .= $tabs;
 409             if ($this->_hiddenLabel){
 410                 $this->_generateId();
 411                 $strHtml .= '<label class="accesshide" for="'.$this->getAttribute('id').'" >'.
 412                             $this->getLabel().'</label>';
 413             }
 414             $strHtml .=  '<select' . $attrString . ">\n";
 415             if ($this->showchoose) {
 416                 $strHtml .= $tabs . "\t\t<option value=\"\">" . get_string('choose') . "...</option>\n";
 417             }
 418             foreach ($this->_optGroups as $optGroup) {
 419                 if (empty($optGroup['options'])) {
 420                     //xhtml strict
 421                     continue;
 422                 }
 423                 $strHtml .= $tabs . "\t<optgroup" . ($this->_getAttrString($optGroup['attr'])) . '>';
 424                 foreach ($optGroup['options'] as $option){
 425                     if (is_array($this->_values) && in_array((string)$option['attr']['value'], $this->_values)) {
 426                         $this->_updateAttrArray($option['attr'], array('selected' => 'selected'));
 427                     }
 428                     $strHtml .= $tabs . "\t\t<option" . $this->_getAttrString($option['attr']) . '>' .
 429                                 $option['text'] . "</option>\n";
 430                 }
 431                 $strHtml .= $tabs . "\t</optgroup>\n";
 432             }
 433             return $strHtml . $tabs . '</select>';
 434         }
 435     } //end func toHtml
 436
 437     // }}}
 438     // {{{ getFrozenHtml()
 439
 440     /**
 441      * Returns the value of field without HTML tags
 442      *
 443      * @since     1.0
 444      * @access    public
 445      * @return    string
 446      */
 447     function getFrozenHtml()
 448     {
 449         $value = array();
 450         if (is_array($this->_values)) {
 451             foreach ($this->_values as $key => $val) {
 452                 foreach ($this->_optGroups as $optGroup) {
 453                     for ($i = 0, $optCount = count($optGroup['options']); $i < $optCount; $i++) {
 454                         if ((string)$val == (string)$optGroup['options'][$i]['attr']['value']) {
 455                             $value[$key] = $optGroup['options'][$i]['text'];
 456                             break;
 457                         }
 458                     }
 459                 }
 460             }
 461         }
 462         $html = empty($value)? '&nbsp;': join('<br />', $value);
 463         if ($this->_persistantFreeze) {
 464             $name = $this->getPrivateName();
 465             // Only use id attribute if doing single hidden input
 466             if (1 == count($value)) {
 467                 $id     = $this->getAttribute('id');
 468                 $idAttr = isset($id)? array('id' => $id): array();
 469             } else {
 470                 $idAttr = array();
 471             }
 472             foreach ($value as $key => $item) {
 473                 $html .= '<input' . $this->_getAttrString(array(
 474                              'type'  => 'hidden',
 475                              'name'  => $name,
 476                              'value' => $this->_values[$key]
 477                          ) + $idAttr) . ' />';
 478             }
 479         }
 480         return $html;
 481     } //end func getFrozenHtml
 482
 483     // }}}
 484     // {{{ exportValue()
 485
 486    /**
 487     * We check the options and return only the values that _could_ have been
 488     * selected. We also return a scalar value if select is not "multiple"
 489     */
 490     function exportValue(&$submitValues, $assoc = false)
 491     {
 492         $value = $this->_findValue($submitValues);
 493         if (is_null($value)) {
 494             $value = $this->getValue();
 495         } elseif(!is_array($value)) {
 496             $value = array($value);
 497         }
 498         if (is_array($value) && !empty($this->_optGroups)) {
 499             $cleanValue = null;
 500             foreach ($value as $v) {
 501                 foreach ($this->_optGroups as $optGroup){
 502                     if (empty($optGroup['options'])) {
 503                         continue;
 504                     }
 505                     for ($i = 0, $optCount = count($optGroup['options']); $i < $optCount; $i++) {
 506                         if ($v == $optGroup['options'][$i]['attr']['value']) {
 507                             $cleanValue[] = $v;
 508                             break;
 509                         }
 510                     }
 511                 }
 512             }
 513         } else {
 514             $cleanValue = $value;
 515         }
 516         if (is_array($cleanValue) && !$this->getMultiple()) {
 517             return $this->_prepareValue($cleanValue[0], $assoc);
 518         } else {
 519             return $this->_prepareValue($cleanValue, $assoc);
 520         }
 521     }
 522
 523     // }}}
 524     // {{{ onQuickFormEvent()
 525
 526     function onQuickFormEvent($event, $arg, &$caller)
 527     {
 528         if ('updateValue' == $event) {
 529             $value = $this->_findValue($caller->_constantValues);
 530             if (null === $value) {
 531                 $value = $this->_findValue($caller->_submitValues);
 532                 // Fix for bug #4465 & #5269
 533                 // XXX: should we push this to element::onQuickFormEvent()?
 534                 if (null === $value && (!$caller->isSubmitted() || !$this->getMultiple())) {
 535                     $value = $this->_findValue($caller->_defaultValues);
 536                 }
 537             }
 538             if (null !== $value) {
 539                 $this->setValue($value);
 540             }
 541             return true;
 542         } else {
 543             return parent::onQuickFormEvent($event, $arg, $caller);
 544         }
 545     }
 546     function setHiddenLabel($hiddenLabel){
 547         $this->_hiddenLabel = $hiddenLabel;
 548     }
 549    /**
 550     * Automatically generates and assigns an 'id' attribute for the element.
 551     *
 552     * Currently used to ensure that labels work on radio buttons and
 553     * checkboxes. Per idea of Alexander Radivanovich.
 554     * Overriden in moodleforms to remove qf_ prefix.
 555     *
 556     * @access private
 557     * @return void
 558     */
 559     function _generateId()
 560     {
 561         static $idx = 1;
 562
 563         if (!$this->getAttribute('id')) {
 564             $this->updateAttributes(array('id' => 'id_'. substr(md5(microtime() . $idx++), 0, 6)));
 565         }
 566     } // end func _generateId
 567     /**
 568      * set html for help button
 569      *
 570      * @access   public
 571      * @param array $help array of arguments to make a help button
 572      * @param string $function function name to call to get html
 573      */
 574     function setHelpButton($helpbuttonargs, $function='helpbutton'){
 575         if (!is_array($helpbuttonargs)){
 576             $helpbuttonargs=array($helpbuttonargs);
 577         }else{
 578             $helpbuttonargs=$helpbuttonargs;
 579         }
 580         //we do this to to return html instead of printing it
 581         //without having to specify it in every call to make a button.
 582         if ('helpbutton' == $function){
 583             $defaultargs=array('', '', 'moodle', true, false, '', true);
 584             $helpbuttonargs=$helpbuttonargs + $defaultargs ;
 585         }
 586         $this->_helpbutton=call_user_func_array($function, $helpbuttonargs);
 587     }
 588     /**
 589      * get html for help button
 590      *
 591      * @access   public
 592      * @return  string html for help button
 593      */
 594     function getHelpButton(){
 595         return $this->_helpbutton;
 596     }
 597
 598     /**
 599      * Slightly different container template when frozen. Don't want to use a label tag
 600      * with a for attribute in that case for the element label but instead use a div.
 601      * Templates are defined in renderer constructor.
 602      *
 603      * @return string
 604      */
 605     function getElementTemplateType(){
 606         if ($this->_flagFrozen){
 607             return 'static';
 608         } else {
 609             return 'default';
 610         }
 611     }
 612 }
 613 ?>