lib/form/duration.php

   1 <?php
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.org                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 global $CFG;
  27 require_once($CFG->libdir . '/form/group.php');
  28 require_once($CFG->libdir . '/formslib.php');
  29 require_once($CFG->libdir . '/form/text.php');
  30
  31 /**
  32  * HTML class for a length of time. For example, 30 minutes of 4 days. The
  33  * values returned to PHP is the duration in seconds.
  34  *
  35  * @package formslib
  36  */
  37 class MoodleQuickForm_duration extends MoodleQuickForm_group {
  38    /**
  39     * Control the fieldnames for form elements
  40     * optional => if true, show a checkbox beside the element to turn it on (or off)
  41     */
  42    protected $_options = array('optional' => false, 'defaultunit' => 60);
  43
  44    private $_units = null;
  45
  46    /**
  47     * Class constructor
  48     *
  49     * @access public
  50     * @param  string $elementName Element's name
  51     * @param  mixed  $elementLabel Label(s) for an element
  52     * @param  array  $options Options to control the element's display. Recognised values are
  53     *       'optional' => true/false - whether to display an 'enabled' checkbox next to the element.
  54     *       'defaultunit' => 1|60|3600|86400 - the default unit to display when the time is blank. If not specified, minutes is used.
  55     * @param  mixed  $attributes Either a typical HTML attribute string or an associative array
  56     */
  57     function MoodleQuickForm_duration($elementName = null, $elementLabel = null, $options = array(), $attributes = null) {
  58         $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes);
  59         $this->_persistantFreeze = true;
  60         $this->_appendName = true;
  61         $this->_type = 'duration';
  62
  63         // Set the options, do not bother setting bogus ones
  64         if (!is_array($options)) {
  65             $options = array();
  66         }
  67         $this->_options['optional'] = !empty($options['optional']);
  68         if (isset($options['defaultunit'])) {
  69             if (!array_key_exists($options['defaultunit'], $this->get_units())) {
  70                 throw new coding_exception($options['defaultunit'] .
  71                         ' is not a recognised unit in MoodleQuickForm_duration.');
  72             }
  73             $this->_options['defaultunit'] = $options['defaultunit'];
  74         }
  75     }
  76
  77     /**
  78      * @return array unit length in seconds => string unit name.
  79      */
  80     public function get_units() {
  81         if (is_null($this->_units)) {
  82             $this->_units = array(
  83                 86400 => get_string('days'),
  84                 3600 => get_string('hours'),
  85                 60 => get_string('minutes'),
  86                 1 => get_string('seconds'),
  87             );
  88         }
  89         return $this->_units;
  90     }
  91
  92     /**
  93      * @param $seconds an amout of time in seconds.
  94      * @return array($number, $unit) Conver an interval to the best possible unit.
  95      *      for example 1800 -> array(30, 60) = 30 minutes.
  96      */
  97     public function seconds_to_unit($seconds) {
  98         if ($seconds == 0) {
  99             return array(0, $this->_options['defaultunit']);
 100         }
 101         foreach ($this->get_units() as $unit => $notused) {
 102             if (fmod($seconds, $unit) == 0) {
 103                 return array($seconds / $unit, $unit);
 104             }
 105         }
 106         return array($seconds, 1);
 107     }
 108
 109     // Override of standard quickforms method.
 110     function _createElements() {
 111         $attributes = $this->getAttributes();
 112         if (is_null($attributes)) {
 113             $attributes = array();
 114         }
 115         if (!isset($attributes['size'])) {
 116             $attributes['size'] = 3;
 117         }
 118         $this->_elements = array();
 119         $this->_elements[] = MoodleQuickForm::createElement('text', 'number', get_string('time', 'form'), $attributes, true);
 120         unset($attributes['size']);
 121         $this->_elements[] = MoodleQuickForm::createElement('select', 'timeunit', get_string('timeunit', 'form'), $this->get_units(), $attributes, true);
 122         // If optional we add a checkbox which the user can use to turn if on
 123         if($this->_options['optional']) {
 124             $this->_elements[] = MoodleQuickForm::createElement('checkbox', 'enabled', null, get_string('enable'), $this->getAttributes(), true);
 125         }
 126         foreach ($this->_elements as $element){
 127             if (method_exists($element, 'setHiddenLabel')){
 128                 $element->setHiddenLabel(true);
 129             }
 130         }
 131     }
 132
 133     // Override of standard quickforms method.
 134     function onQuickFormEvent($event, $arg, $caller) {
 135         switch ($event) {
 136             case 'updateValue':
 137                 // constant values override both default and submitted ones
 138                 // default values are overriden by submitted
 139                 $value = $this->_findValue($caller->_constantValues);
 140                 if (null === $value) {
 141                     // if no boxes were checked, then there is no value in the array
 142                     // yet we don't want to display default value in this case
 143                     if ($caller->isSubmitted()) {
 144                         $value = $this->_findValue($caller->_submitValues);
 145                     } else {
 146                         $value = $this->_findValue($caller->_defaultValues);
 147                     }
 148                 }
 149                 if (!is_array($value)) {
 150                     list($number, $unit) = $this->seconds_to_unit($value);
 151                     $value = array('number' => $number, 'timeunit' => $unit);
 152                     // If optional, default to off, unless a date was provided
 153                     if ($this->_options['optional']) {
 154                         $value['enabled'] = $number != 0;
 155                     }
 156                 } else {
 157                     $value['enabled'] = isset($value['enabled']);
 158                 }
 159                 if (null !== $value){
 160                     $this->setValue($value);
 161                 }
 162                 break;
 163
 164             case 'createElement':
 165                 if ($arg[2]['optional']) {
 166                     $caller->disabledIf($arg[0], $arg[0] . '[enabled]');
 167                 }
 168                 $caller->setType($arg[0] . '[number]', PARAM_NUMBER);
 169                 return parent::onQuickFormEvent($event, $arg, $caller);
 170                 break;
 171
 172             default:
 173                 return parent::onQuickFormEvent($event, $arg, $caller);
 174         }
 175     }
 176
 177     // Override of standard quickforms method.
 178     function toHtml() {
 179         include_once('HTML/QuickForm/Renderer/Default.php');
 180         $renderer = new HTML_QuickForm_Renderer_Default();
 181         $renderer->setElementTemplate('{element}');
 182         parent::accept($renderer);
 183         return $renderer->toHtml();
 184     }
 185
 186     // Override of standard quickforms method.
 187     function accept($renderer, $required = false, $error = null) {
 188         $renderer->renderElement($this, $required, $error);
 189     }
 190
 191     /**
 192      * Output a timestamp. Give it the name of the group.
 193      * Override of standard quickforms method.
 194      *
 195      * @param array $submitValues
 196      * @param bool $notused Not used.
 197      * @return array field name => value. The value is the time interval in seconds.
 198      */
 199     function exportValue($submitValues, $notused = false) {
 200         // Get the values from all the child elements.
 201         $valuearray = array();
 202         foreach ($this->_elements as $element) {
 203             $thisexport = $element->exportValue($submitValues[$this->getName()], true);
 204             if (!is_null($thisexport)) {
 205                 $valuearray += $thisexport;
 206             }
 207         }
 208
 209         // Convert the value to an integer number of seconds.
 210         if (empty($valuearray)) {
 211             return null;
 212         }
 213         if ($this->_options['optional'] && empty($valuearray['enabled'])) {
 214             return array($this->getName() => 0);
 215         }
 216         return array($this->getName() => $valuearray['number'] * $valuearray['timeunit']);
 217     }
 218 }