lib/form/autocomplete.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * autocomplete type form element
  20  *
  21  * Contains HTML class for a autocomplete type element
  22  *
  23  * @package   core_form
  24  * @copyright 2015 Damyon Wiese <damyon@moodle.com>
  25  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26  */
  27
  28 global $CFG;
  29
  30 require_once($CFG->libdir . '/form/select.php');
  31
  32 /**
  33  * Autocomplete as you type form element
  34  *
  35  * HTML class for a autocomplete type element
  36  *
  37  * @package   core_form
  38  * @copyright 2015 Damyon Wiese <damyon@moodle.com>
  39  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40  */
  41 class MoodleQuickForm_autocomplete extends MoodleQuickForm_select {
  42
  43     /** @var boolean $tags Should we allow typing new entries to the field? */
  44     protected $tags = false;
  45     /** @var string $ajax Name of an AMD module to send/process ajax requests. */
  46     protected $ajax = '';
  47     /** @var string $placeholder Placeholder text for an empty list. */
  48     protected $placeholder = '';
  49     /** @var bool $casesensitive Whether the search has to be case-sensitive. */
  50     protected $casesensitive = false;
  51     /** @var bool $showsuggestions Show suggestions by default - but this can be turned off. */
  52     protected $showsuggestions = true;
  53     /** @var string $noselectionstring String that is shown when there are no selections. */
  54     protected $noselectionstring = '';
  55
  56     /**
  57      * constructor
  58      *
  59      * @param string $elementName Select name attribute
  60      * @param mixed $elementLabel Label(s) for the select
  61      * @param mixed $options Data to be used to populate options
  62      * @param mixed $attributes Either a typical HTML attribute string or an associative array. Special options
  63      *                          "tags", "placeholder", "ajax", "multiple", "casesensitive" are supported.
  64      */
  65     public function __construct($elementName=null, $elementLabel=null, $options=null, $attributes=null) {
  66         // Even if the constructor gets called twice we do not really want 2x options (crazy forms!).
  67         $this->_options = array();
  68         if ($attributes === null) {
  69             $attributes = array();
  70         }
  71         if (isset($attributes['tags'])) {
  72             $this->tags = $attributes['tags'];
  73             unset($attributes['tags']);
  74         }
  75         if (isset($attributes['showsuggestions'])) {
  76             $this->showsuggestions = $attributes['showsuggestions'];
  77             unset($attributes['showsuggestions']);
  78         }
  79         $this->placeholder = get_string('search');
  80         if (isset($attributes['placeholder'])) {
  81             $this->placeholder = $attributes['placeholder'];
  82             unset($attributes['placeholder']);
  83         }
  84         $this->noselectionstring = get_string('noselection', 'form');
  85         if (isset($attributes['noselectionstring'])) {
  86             $this->noselectionstring = $attributes['noselectionstring'];
  87             unset($attributes['noselectionstring']);
  88         }
  89
  90         if (isset($attributes['ajax'])) {
  91             $this->ajax = $attributes['ajax'];
  92             unset($attributes['ajax']);
  93         }
  94         if (isset($attributes['casesensitive'])) {
  95             $this->casesensitive = $attributes['casesensitive'] ? true : false;
  96             unset($attributes['casesensitive']);
  97         }
  98         parent::__construct($elementName, $elementLabel, $options, $attributes);
  99
 100         $this->_type = 'autocomplete';
 101     }
 102
 103     /**
 104      * Old syntax of class constructor. Deprecated in PHP7.
 105      *
 106      * @deprecated since Moodle 3.1
 107      */
 108     public function MoodleQuickForm_autocomplete($elementName=null, $elementLabel=null, $options=null, $attributes=null) {
 109         debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER);
 110         self::__construct($elementName, $elementLabel, $options, $attributes);
 111     }
 112
 113     /**
 114      * Returns HTML for select form element.
 115      *
 116      * @return string
 117      */
 118     function toHtml(){
 119         global $PAGE;
 120
 121         // Enhance the select with javascript.
 122         $this->_generateId();
 123         $id = $this->getAttribute('id');
 124
 125         if (!$this->isFrozen()) {
 126             $PAGE->requires->js_call_amd('core/form-autocomplete', 'enhance', $params = array('#' . $id, $this->tags, $this->ajax,
 127                 $this->placeholder, $this->casesensitive, $this->showsuggestions, $this->noselectionstring));
 128         }
 129
 130         return parent::toHTML();
 131     }
 132
 133     /**
 134      * Search the current list of options to see if there are any options with this value.
 135      * @param  string $value to search
 136      * @return boolean
 137      */
 138     function optionExists($value) {
 139         foreach ($this->_options as $option) {
 140             if (isset($option['attr']['value']) && ($option['attr']['value'] == $value)) {
 141                 return true;
 142             }
 143         }
 144         return false;
 145     }
 146
 147     /**
 148      * Set the value of this element. If values can be added or are unknown, we will
 149      * make sure they exist in the options array.
 150      * @param  mixed string|array $value The value to set.
 151      * @return boolean
 152      */
 153     function setValue($value) {
 154         $values = (array) $value;
 155         foreach ($values as $onevalue) {
 156             if (($this->tags || $this->ajax) &&
 157                     (!$this->optionExists($onevalue)) &&
 158                     ($onevalue !== '_qf__force_multiselect_submission')) {
 159                 $this->addOption($onevalue, $onevalue);
 160             }
 161         }
 162         return parent::setValue($value);
 163     }
 164
 165     /**
 166      * Returns a 'safe' element's value
 167      *
 168      * @param  array   array of submitted values to search
 169      * @param  bool    whether to return the value as associative array
 170      * @access public
 171      * @return mixed
 172      */
 173     function exportValue(&$submitValues, $assoc = false) {
 174         if ($this->ajax || $this->tags) {
 175             // When this was an ajax request, we do not know the allowed list of values.
 176             $value = $this->_findValue($submitValues);
 177             if (null === $value) {
 178                 $value = $this->getValue();
 179             }
 180             // Quickforms inserts a duplicate element in the form with
 181             // this value so that a value is always submitted for this form element.
 182             // Normally this is cleaned as a side effect of it not being a valid option,
 183             // but in this case we need to detect and skip it manually.
 184             if ($value === '_qf__force_multiselect_submission' || $value === null) {
 185                 $value = '';
 186             }
 187             return $this->_prepareValue($value, $assoc);
 188         } else {
 189             return parent::exportValue($submitValues, $assoc);
 190         }
 191     }
 192
 193     /**
 194      * Called by HTML_QuickForm whenever form event is made on this element
 195      *
 196      * @param string $event Name of event
 197      * @param mixed $arg event arguments
 198      * @param object $caller calling object
 199      * @return bool
 200      */
 201     function onQuickFormEvent($event, $arg, &$caller)
 202     {
 203         switch ($event) {
 204             case 'createElement':
 205                 $caller->setType($arg[0], PARAM_TAGLIST);
 206                 break;
 207         }
 208         return parent::onQuickFormEvent($event, $arg, $caller);
 209     }
 210
 211     public function export_for_template(renderer_base $output) {
 212         global $PAGE;
 213
 214         $this->_generateId();
 215         $context = parent::export_for_template($output);
 216         $context['tags'] = !empty($this->tags);
 217         $context['ajax'] = $this->ajax;
 218         $context['placeholder'] = $this->placeholder;
 219         $context['casesensitive'] = !empty($this->casesensitive);
 220         $context['showsuggestions'] = !empty($this->showsuggestions);
 221         $context['noselectionstring'] = $this->noselectionstring;
 222
 223         return $context;
 224     }
 225 }