MDL-21198 improved parameter types specification in renderer api
[moodle.git] / lib / outputcomponents.php
CommitLineData
d9c8f425 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * Classes representing HTML elements, used by $OUTPUT methods
20 *
21 * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
22 * for an overview.
23 *
24 * @package moodlecore
25 * @copyright 2009 Tim Hunt
26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 */
28
29/**
7b1f2c82 30 * Base class for classes representing HTML elements, like html_select.
d9c8f425 31 *
32 * Handles the id and class attributes.
33 *
34 * @copyright 2009 Tim Hunt
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 * @since Moodle 2.0
37 */
6dd7d7f0 38class html_component {
d9c8f425 39 /**
40 * @var string value to use for the id attribute of this HTML tag.
41 */
42 public $id = '';
43 /**
44 * @var string $alt value to use for the alt attribute of this HTML tag.
45 */
46 public $alt = '';
47 /**
48 * @var string $style value to use for the style attribute of this HTML tag.
49 */
50 public $style = '';
51 /**
52 * @var array class names to add to this HTML element.
53 */
54 public $classes = array();
55 /**
56 * @var string $title The title attributes applicable to any XHTML element
57 */
58 public $title = '';
59 /**
60 * An optional array of component_action objects handling the action part of this component.
61 * @var array $actions
62 */
63 protected $actions = array();
d9c8f425 64
65 /**
66 * Ensure some class names are an array.
67 * @param mixed $classes either an array of class names or a space-separated
68 * string containing class names.
69 * @return array the class names as an array.
70 */
71 public static function clean_classes($classes) {
642816a6 72 if (empty($classes)) {
3bd6b994 73 return array();
642816a6 74 } else if (is_array($classes)) {
d9c8f425 75 return $classes;
76 } else {
77 return explode(' ', trim($classes));
78 }
79 }
80
81 /**
82 * Set the class name array.
83 * @param mixed $classes either an array of class names or a space-separated
84 * string containing class names.
85 * @return void
86 */
87 public function set_classes($classes) {
88 $this->classes = self::clean_classes($classes);
89 }
90
91 /**
92 * Add a class name to the class names array.
93 * @param string $class the new class name to add.
94 * @return void
95 */
96 public function add_class($class) {
97 $this->classes[] = $class;
98 }
99
100 /**
101 * Add a whole lot of class names to the class names array.
102 * @param mixed $classes either an array of class names or a space-separated
103 * string containing class names.
104 * @return void
105 */
106 public function add_classes($classes) {
eeecf5a7 107 $this->classes = array_merge($this->classes, self::clean_classes($classes));
d9c8f425 108 }
109
110 /**
111 * Get the class names as a string.
112 * @return string the class names as a space-separated string. Ready to be put in the class="" attribute.
113 */
114 public function get_classes_string() {
115 return implode(' ', $this->classes);
116 }
117
118 /**
119 * Perform any cleanup or final processing that should be done before an
34059565
PS
120 * instance of this class is output. This method is supposed to be called
121 * only from renderers.
122 *
123 * @param renderer_base $output output renderer
124 * @param moodle_page $page
125 * @param string $target rendering target
d9c8f425 126 * @return void
127 */
34059565 128 public function prepare(renderer_base $output, moodle_page $page, $target) {
d9c8f425 129 $this->classes = array_unique(self::clean_classes($this->classes));
130 }
131
132 /**
133 * This checks developer do not try to assign a property directly
134 * if we have a setter for it. Otherwise, the property is set as expected.
135 * @param string $name The name of the variable to set
136 * @param mixed $value The value to assign to the variable
137 * @return void
138 */
139 public function __set($name, $value) {
140 if ($name == 'class') {
141 debugging('this way of setting css class has been deprecated. use set_classes() method instead.');
142 $this->set_classes($value);
143 } else {
144 $this->{$name} = $value;
145 }
146 }
147
148 /**
149 * Adds a JS action to this component.
150 * Note: the JS function you write must have only two arguments: (string)event and (object|array)args
151 * If you want to add an instantiated component_action (or one of its subclasses), give the object as the only parameter
152 *
153 * @param mixed $event a DOM event (click, mouseover etc.) or a component_action object
154 * @param string $jsfunction The name of the JS function to call. required if argument 1 is a string (event)
155 * @param array $jsfunctionargs An optional array of JS arguments to pass to the function
156 */
157 public function add_action($event, $jsfunction=null, $jsfunctionargs=array()) {
158 if (empty($this->id)) {
159 $this->generate_id();
160 }
161
162 if ($event instanceof component_action) {
163 $this->actions[] = $event;
164 } else {
165 if (empty($jsfunction)) {
6dd7d7f0 166 throw new coding_exception('html_component::add_action requires a JS function argument if the first argument is a string event');
d9c8f425 167 }
168 $this->actions[] = new component_action($event, $jsfunction, $jsfunctionargs);
169 }
170 }
171
172 /**
173 * Internal method for generating a unique ID for the purpose of event handlers.
174 */
175 protected function generate_id() {
0c868b08 176 $this->id = uniqid(get_class($this));
d9c8f425 177 }
178
179 /**
180 * Returns the array of component_actions.
181 * @return array Component actions
182 */
183 public function get_actions() {
184 return $this->actions;
185 }
186
7a5c78e0 187 /**
188 * Shortcut for adding a JS confirm dialog when the component is clicked.
189 * The message must be a yes/no question.
190 * @param string $message The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
a0ead5eb 191 * @param string $callback The name of a JS function whose scope will be set to the simpleDialog object and have this
5529f787 192 * function's arguments set as this.args.
7a5c78e0 193 * @return void
194 */
5529f787 195 public function add_confirm_action($message, $callback=null) {
196 $this->add_action(new component_action('click', 'confirm_dialog', array('message' => $message, 'callback' => $callback)));
7a5c78e0 197 }
db49be13 198
199 /**
200 * Returns true if this component has an action of the requested type (component_action by default).
201 * @param string $class The class of the action we are looking for
202 * @return boolean True if action is found
203 */
204 public function has_action($class='component_action') {
205 foreach ($this->actions as $action) {
206 if (get_class($action) == $class) {
207 return true;
208 }
209 }
210 return false;
211 }
7a5c78e0 212}
213
34059565 214
6dd7d7f0 215class labelled_html_component extends html_component {
7a5c78e0 216 /**
217 * @var mixed $label The label for that component. String or html_label object
218 */
219 public $label;
220
d9c8f425 221 /**
222 * Adds a descriptive label to the component.
223 *
224 * This can be used in two ways:
225 *
226 * <pre>
227 * $component->set_label($elementlabel, $elementid);
228 * // OR
229 * $label = new html_label();
230 * $label->for = $elementid;
231 * $label->text = $elementlabel;
232 * $component->set_label($label);
233 * </pre>
234 *
235 * Use the second form when you need to add additional HTML attributes
236 * to the label and/or JS actions.
237 *
238 * @param mixed $text Either the text of the label or a html_label object
239 * @param text $for The value of the "for" attribute (the associated element's id)
240 * @return void
241 */
242 public function set_label($text, $for=null) {
243 if ($text instanceof html_label) {
244 $this->label = $text;
245 } else if (!empty($text)) {
246 $this->label = new html_label();
247 $this->label->for = $for;
1ae3767a 248 if (empty($for)) {
3cc457db 249 if (empty($this->id)) {
250 $this->generate_id();
251 }
d9c8f425 252 $this->label->for = $this->id;
253 }
254 $this->label->text = $text;
255 }
256 }
257}
258
beb56299 259/// Components representing HTML elements
d9c8f425 260
261/**
beb56299 262 * This class represents a label element
d9c8f425 263 *
beb56299 264 * @copyright 2009 Nicolas Connault
d9c8f425 265 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
266 * @since Moodle 2.0
267 */
6dd7d7f0 268class html_label extends html_component {
d9c8f425 269 /**
beb56299 270 * @var string $text The text to display in the label
d9c8f425 271 */
beb56299 272 public $text;
d9c8f425 273 /**
beb56299 274 * @var string $for The name of the form field this label is associated with
d9c8f425 275 */
beb56299 276 public $for;
277
d9c8f425 278 /**
6dd7d7f0 279 * @see html_component::prepare()
beb56299 280 * @return void
d9c8f425 281 */
34059565 282 public function prepare(renderer_base $output, moodle_page $page, $target) {
beb56299 283 if (empty($this->text)) {
284 throw new coding_exception('html_label must have a $text value.');
285 }
34059565 286 parent::prepare($output, $page, $target);
beb56299 287 }
288}
289
34059565 290
beb56299 291/**
7b1f2c82 292 * This class hold all the information required to describe a <select> menu that
78946b9b 293 * will be printed by {@link core_renderer::select()}. (Or by an overridden
7b1f2c82 294 * version of that method in a subclass.)
beb56299 295 *
7b1f2c82 296 * This component can also hold enough metadata to be used as a popup form. It just
297 * needs a bit more setting up than for a simple menu. See the shortcut methods for
298 * developer-friendly usage.
299 *
300 * All the fields that are not set by the constructor have sensible defaults, so
301 * you only need to set the properties where you want non-default behaviour.
302 *
303 * @copyright 2009 Tim Hunt
beb56299 304 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
305 * @since Moodle 2.0
306 */
7a5c78e0 307class html_select extends labelled_html_component {
d9c8f425 308 /**
7b1f2c82 309 * The html_select object parses an array of options into component objects
310 * @see nested attribute
311 * @var mixed $options the choices to show in the menu. An array $value => $display, of html_select_option or of html_select_optgroup objects.
d9c8f425 312 */
7b1f2c82 313 public $options;
d9c8f425 314 /**
7b1f2c82 315 * @var string $name the name of this form control. That is, the name of the GET/POST
316 * variable that will be set if this select is submitted as part of a form.
d9c8f425 317 */
7b1f2c82 318 public $name;
d9c8f425 319 /**
7b1f2c82 320 * @var string $selectedvalue the option to select initially. Should match one
321 * of the $options array keys. Default none.
d9c8f425 322 */
7b1f2c82 323 public $selectedvalue;
d9c8f425 324 /**
7b1f2c82 325 * Defaults to get_string('choosedots').
326 * Set this to '' if you do not want a 'nothing is selected' option.
327 * This is ignored if the rendertype is 'radio' or 'checkbox'
328 * @var string The label for the 'nothing is selected' option.
d9c8f425 329 */
7b1f2c82 330 public $nothinglabel = null;
d9c8f425 331 /**
7b1f2c82 332 * @var string The value returned by the 'nothing is selected' option. Defaults to 0.
d9c8f425 333 */
7b1f2c82 334 public $nothingvalue = 0;
d9c8f425 335 /**
7b1f2c82 336 * @var boolean set this to true if you want the control to appear disabled.
d9c8f425 337 */
7b1f2c82 338 public $disabled = false;
d9c8f425 339 /**
7b1f2c82 340 * @var integer if non-zero, sets the tabindex attribute on the <select> element. Default 0.
d9c8f425 341 */
7b1f2c82 342 public $tabindex = 0;
d9c8f425 343 /**
7b1f2c82 344 * @var mixed Defaults to false, which means display the select as a dropdown menu.
345 * If true, display this select as a list box whose size is chosen automatically.
346 * If an integer, display as list box of that size.
d9c8f425 347 */
7b1f2c82 348 public $listbox = false;
d9c8f425 349 /**
7b1f2c82 350 * @var integer if you are using $listbox === true to get an automatically
351 * sized list box, the size of the list box will be the number of options,
352 * or this number, whichever is smaller.
d9c8f425 353 */
7b1f2c82 354 public $maxautosize = 10;
d9c8f425 355 /**
7b1f2c82 356 * @var boolean if true, allow multiple selection. Only used if $listbox is true, or if
357 * the select is to be output as checkboxes.
d9c8f425 358 */
7b1f2c82 359 public $multiple = false;
beb56299 360 /**
7b1f2c82 361 * Another way to use nested menu is to prefix optgroup labels with -- and end the optgroup with --
362 * Leave this setting to false if you are using the latter method.
363 * @var boolean $nested if true, uses $options' keys as option headings (optgroup)
beb56299 364 */
7b1f2c82 365 public $nested = false;
366 /**
367 * @var html_form $form An optional html_form component
368 */
369 public $form;
370 /**
371 * @var moodle_help_icon $form An optional moodle_help_icon component
372 */
373 public $helpicon;
374 /**
375 * @var boolean $rendertype How the select element should be rendered: menu or radio (checkbox is just radio + multiple)
376 */
377 public $rendertype = 'menu';
d9c8f425 378
379 /**
6dd7d7f0 380 * @see html_component::prepare()
d9c8f425 381 * @return void
382 */
34059565 383 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 384 global $CFG;
385
386 // name may contain [], which would make an invalid id. e.g. numeric question type editing form, assignment quickgrading
beb56299 387 if (empty($this->id)) {
7b1f2c82 388 $this->id = 'menu' . str_replace(array('[', ']'), '', $this->name);
389 }
390
391 if (empty($this->classes)) {
392 $this->set_classes(array('menu' . str_replace(array('[', ']'), '', $this->name)));
393 }
394
395 if (is_null($this->nothinglabel)) {
396 $this->nothinglabel = get_string('choosedots');
397 }
398
399 if (!empty($this->label) && !($this->label instanceof html_label)) {
400 $label = new html_label();
401 $label->text = $this->label;
402 $label->for = $this->name;
403 $this->label = $label;
d9c8f425 404 }
7b1f2c82 405
406 $this->add_class('select');
407
408 $this->initialise_options();
34059565 409 parent::prepare($output, $page, $target);
d9c8f425 410 }
411
412 /**
7b1f2c82 413 * This is a shortcut for making a simple select menu. It lets you specify
414 * the options, name and selected option in one line of code.
415 * @param array $options used to initialise {@link $options}.
416 * @param string $name used to initialise {@link $name}.
417 * @param string $selected used to initialise {@link $selected}.
54b16692 418 * @param string $nothinglabel The label for the 'nothing is selected' option. Defaults to "Choose..."
7b1f2c82 419 * @return html_select A html_select object with the three common fields initialised.
d9c8f425 420 */
54b16692 421 public static function make($options, $name, $selected = '', $nothinglabel='choosedots') {
7b1f2c82 422 $menu = new html_select();
423 $menu->options = $options;
424 $menu->name = $name;
425 $menu->selectedvalue = $selected;
426 return $menu;
d9c8f425 427 }
428
429 /**
7b1f2c82 430 * This is a shortcut for making a yes/no select menu.
431 * @param string $name used to initialise {@link $name}.
432 * @param string $selected used to initialise {@link $selected}.
433 * @return html_select A menu initialised with yes/no options.
beb56299 434 */
7b1f2c82 435 public static function make_yes_no($name, $selected) {
436 return self::make(array(0 => get_string('no'), 1 => get_string('yes')), $name, $selected);
437 }
438
d9c8f425 439 /**
7b1f2c82 440 * This is a shortcut for making an hour selector menu.
441 * @param string $type The type of selector (years, months, days, hours, minutes)
442 * @param string $name fieldname
443 * @param int $currenttime A default timestamp in GMT
444 * @param int $step minute spacing
445 * @return html_select A menu initialised with hour options.
d9c8f425 446 */
7b1f2c82 447 public static function make_time_selector($type, $name, $currenttime=0, $step=5) {
448
449 if (!$currenttime) {
450 $currenttime = time();
451 }
452 $currentdate = usergetdate($currenttime);
453 $userdatetype = $type;
454
455 switch ($type) {
456 case 'years':
457 for ($i=1970; $i<=2020; $i++) {
458 $timeunits[$i] = $i;
459 }
460 $userdatetype = 'year';
461 break;
462 case 'months':
463 for ($i=1; $i<=12; $i++) {
464 $timeunits[$i] = userdate(gmmktime(12,0,0,$i,15,2000), "%B");
465 }
466 $userdatetype = 'month';
1ae3767a 467 $currentdate['month'] = $currentdate['mon'];
7b1f2c82 468 break;
469 case 'days':
470 for ($i=1; $i<=31; $i++) {
471 $timeunits[$i] = $i;
472 }
473 $userdatetype = 'mday';
474 break;
475 case 'hours':
476 for ($i=0; $i<=23; $i++) {
477 $timeunits[$i] = sprintf("%02d",$i);
478 }
479 break;
480 case 'minutes':
481 if ($step != 1) {
482 $currentdate['minutes'] = ceil($currentdate['minutes']/$step)*$step;
483 }
484
485 for ($i=0; $i<=59; $i+=$step) {
486 $timeunits[$i] = sprintf("%02d",$i);
487 }
488 break;
489 default:
490 throw new coding_exception("Time type $type is not supported by html_select::make_time_selector().");
491 }
492
493 $timerselector = self::make($timeunits, $name, $currentdate[$userdatetype]);
494 $timerselector->label = new html_label();
1ae3767a 495
496 $timerselector->label->text = get_string(substr($type, 0, -1), 'form');
7b1f2c82 497 $timerselector->label->for = "menu$timerselector->name";
498 $timerselector->label->add_class('accesshide');
499 $timerselector->nothinglabel = '';
500
501 return $timerselector;
502 }
503
504 /**
505 * Given an associative array of type => fieldname and an optional timestamp,
506 * returns an array of html_select components representing date/time selectors.
507 * @param array $selectors Arrays of type => fieldname. Selectors will be returned in the order of the types given
508 * @param int $currenttime A UNIX timestamp
509 * @param int $step minute spacing
510 * @return array Instantiated date/time selectors
511 */
512 public function make_time_selectors($selectors, $currenttime=0, $step=5) {
513 $selects = array();
514 foreach ($selectors as $type => $name) {
515 $selects[] = html_select::make_time_selector($type, $name, $currenttime, $step);
516 }
517 return $selects;
518 }
519
520 /**
521 * This is a shortcut for making a select popup form.
522 * @param mixed $baseurl The target URL, string or moodle_url
523 * @param string $name The variable which this select's options are changing in the URL
524 * @param array $options A list of value-label pairs for the popup list
525 * @param string $formid id for the control. Must be unique on the page. Used in the HTML.
526 * @param string $selected The option that is initially selected
527 * @return html_select A menu initialised as a popup form.
528 */
529 public function make_popup_form($baseurl, $name, $options, $formid, $selected=null) {
530 global $CFG;
531
532 $selectedurl = null;
533
534 if (!($baseurl instanceof moodle_url)) {
535 $baseurl = new moodle_url($baseurl);
536 }
537
538 if (!empty($selected)) {
539 $selectedurl = $baseurl->out(false, array($name => $selected), false);
540 }
541
542 if (!($baseurl instanceof moodle_url)) {
543 $baseurl = new moodle_url($baseurl);
544 }
545
546 // Replace real value by formatted URLs
547 foreach ($options as $value => $label) {
548 $options[$baseurl->out(false, array($name => $value), false)] = $label;
549 unset($options[$value]);
550 }
551
552 $select = self::make($options, 'jump', $selectedurl);
553
554 $select->form = new html_form();
555 $select->form->id = $formid;
556 $select->form->method = 'get';
b65bfc3e 557 $select->form->jssubmitaction = true;
7b1f2c82 558 $select->form->add_class('popupform');
559 $select->form->url = new moodle_url($CFG->wwwroot . '/course/jumpto.php', array('sesskey' => sesskey()));
560 $select->form->button->text = get_string('go');
561
562 $select->id = $formid . '_jump';
563
564 $select->add_action('change', 'submit_form_by_id', array('id' => $formid, 'selectid' => $select->id));
565
566 return $select;
567 }
568
569 /**
570 * Override the URLs of the default popup_form, which only supports one base URL
571 * @param array $options value=>label pairs representing select options
572 * @return void
573 */
574 public function override_option_values($options) {
e4c5abdc 575 $originalcount = count($options);
7b1f2c82 576 $this->initialise_options();
e4c5abdc 577 $newcount = count($this->options);
578 $first = true;
7b1f2c82 579
580 reset($options);
581
582 foreach ($this->options as $optkey => $optgroup) {
583 if ($optgroup instanceof html_select_optgroup) {
584 foreach ($optgroup->options as $key => $option) {
585 next($options);
586 $this->options[$optkey]->options[$key]->value = key($options);
587
588 $optionurl = new moodle_url(key($options));
589
34059565 590 if ($optionurl->compare($page->url, URL_MATCH_PARAMS)) {
7b1f2c82 591 $this->options[$optkey]->options[$key]->selected = 'selected';
592 }
593 }
594 next($options);
e4c5abdc 595 } else if ($optgroup instanceof html_select_option && !($first && $originalcount < $newcount)) {
7b1f2c82 596 $this->options[$optkey]->value = key($options);
597 $optionurl = new moodle_url(key($options));
598
34059565 599 if ($optionurl->compare($page->url, URL_MATCH_PARAMS)) {
7b1f2c82 600 $this->options[$optkey]->selected = 'selected';
601 }
e4c5abdc 602 next($options);
7b1f2c82 603 }
e4c5abdc 604 $first = false;
7b1f2c82 605 }
606 }
607
608 /**
609 * Adds a help icon next to the select menu.
610 *
611 * This can be used in two ways:
612 *
613 * <pre>
614 * $select->set_help_icon($page, $text, $linktext);
615 * // OR
616 * $helpicon = new moodle_help_icon();
617 * $helpicon->page = $page;
618 * $helpicon->text = $text;
619 * $helpicon->linktext = $linktext;
620 * $select->set_help_icon($helpicon);
621 * </pre>
622 *
623 * Use the second form when you need to add additional HTML attributes
624 * to the label and/or JS actions.
625 *
626 * @param mixed $page Either the keyword that defines a help page or a moodle_help_icon object
627 * @param text $text The text of the help icon
628 * @param boolean $linktext Whether or not to show text next to the icon
629 * @return void
630 */
631 public function set_help_icon($page, $text, $linktext=false) {
632 if ($page instanceof moodle_help_icon) {
633 $this->helpicon = $page;
634 } else if (!empty($page)) {
635 $this->helpicon = new moodle_help_icon();
636 $this->helpicon->page = $page;
637 $this->helpicon->text = $text;
638 $this->helpicon->linktext = $linktext;
639 }
640 }
641
642 /**
643 * Parses the $options array and instantiates html_select_option objects in
644 * the place of the original value => label pairs. This is useful for when you
645 * need to setup extra html attributes and actions on individual options before
646 * the component is sent to the renderer
647 * @return void;
648 */
649 public function initialise_options() {
650 // If options are already instantiated objects, stop here
651 $firstoption = reset($this->options);
652 if ($firstoption instanceof html_select_option || $firstoption instanceof html_select_optgroup) {
653 return;
654 }
655
656 if ($this->rendertype == 'radio' && $this->multiple) {
657 $this->rendertype = 'checkbox';
658 }
659
660 // If nested is on, or if radio/checkbox rendertype is set, remove the default Choose option
661 if ($this->nested || $this->rendertype == 'radio' || $this->rendertype == 'checkbox') {
662 $this->nothinglabel = '';
663 }
664
665 $options = $this->options;
666
667 $this->options = array();
668
669 if ($this->nested && $this->rendertype != 'menu') {
670 throw new coding_exception('html_select cannot render nested options as radio buttons or checkboxes.');
671 } else if ($this->nested) {
672 foreach ($options as $section => $values) {
673 $optgroup = new html_select_optgroup();
674 $optgroup->text = $section;
675
676 foreach ($values as $value => $display) {
677 $option = new html_select_option();
678 $option->value = s($value);
679 $option->text = $display;
680 if ($display === '') {
681 $option->text = $value;
682 }
683
684 if ((string) $value == (string) $this->selectedvalue ||
685 (is_array($this->selectedvalue) && in_array($value, $this->selectedvalue))) {
686 $option->selected = 'selected';
687 }
688
689 $optgroup->options[] = $option;
690 }
691
692 $this->options[] = $optgroup;
693 }
694 } else {
695 $inoptgroup = false;
696 $optgroup = false;
697
698 foreach ($options as $value => $display) {
699 if ($display == '--') { /// we are ending previous optgroup
700 // $this->options[] = $optgroup;
701 $inoptgroup = false;
702 continue;
703 } else if (substr($display,0,2) == '--') { /// we are starting a new optgroup
704 if (!empty($optgroup->options)) {
705 $this->options[] = $optgroup;
706 }
707
708 $optgroup = new html_select_optgroup();
709 $optgroup->text = substr($display,2); // stripping the --
710
711 $inoptgroup = true; /// everything following will be in an optgroup
712 continue;
713
714 } else {
715 // Add $nothing option if there are not optgroups
716 if ($this->nothinglabel && empty($this->options[0]) && !$inoptgroup) {
717 $nothingoption = new html_select_option();
718 $nothingoption->value = 0;
719 if (!empty($this->nothingvalue)) {
720 $nothingoption->value = $this->nothingvalue;
721 }
722 $nothingoption->text = $this->nothinglabel;
723 $this->options = array($nothingoption) + $this->options;
724 }
725
726 $option = new html_select_option();
727 $option->text = $display;
728
729 if ($display === '') {
730 $option->text = $value;
731 }
732
733 if ((string) $value == (string) $this->selectedvalue ||
734 (is_array($this->selectedvalue) && in_array($value, $this->selectedvalue))) {
735 $option->selected = 'selected';
736 }
737
738 $option->value = s($value);
739
740 if ($inoptgroup) {
741 $optgroup->options[] = $option;
742 } else {
743 $this->options[] = $option;
744 }
745 }
746 }
747
748 if ($optgroup) {
749 $this->options[] = $optgroup;
750 }
751 }
752 }
753}
754
34059565 755
7b1f2c82 756/**
757 * This class represents a select option element
758 *
759 * @copyright 2009 Nicolas Connault
760 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
761 * @since Moodle 2.0
762 */
7a5c78e0 763class html_select_option extends labelled_html_component {
7b1f2c82 764 /**
765 * @var string $value The value of this option (will be sent with form)
766 */
767 public $value;
768 /**
769 * @var string $text The display value of the option
770 */
771 public $text;
772 /**
773 * @var boolean $selected Whether or not this option is selected
774 */
775 public $selected = false;
a4998d01 776 /**
777 * @var boolean $disabled Whether or not this option is disabled
778 */
779 public $disabled = false;
7b1f2c82 780
781 public function __construct() {
782 $this->label = new html_label();
783 }
784
785 /**
6dd7d7f0 786 * @see html_component::prepare()
7b1f2c82 787 * @return void
788 */
34059565 789 public function prepare(renderer_base $output, moodle_page $page, $target) {
c7e4c7b7 790 if (empty($this->text) && (string)$this->text!=='0') {
7b1f2c82 791 throw new coding_exception('html_select_option requires a $text value.');
792 }
793
794 if (empty($this->label->text)) {
795 $this->set_label($this->text);
796 } else if (!($this->label instanceof html_label)) {
797 $this->set_label($this->label);
798 }
799 if (empty($this->id)) {
800 $this->generate_id();
801 }
802
34059565 803 parent::prepare($output, $page, $target);
7b1f2c82 804 }
805
806 /**
807 * Shortcut for making a checkbox-ready option
808 * @param string $value The value of the checkbox
809 * @param boolean $checked
810 * @param string $label
811 * @param string $alt
812 * @return html_select_option A component ready for $OUTPUT->checkbox()
813 */
7a5c78e0 814 public function make_checkbox($value, $checked, $label, $alt='') {
7b1f2c82 815 $checkbox = new html_select_option();
816 $checkbox->value = $value;
817 $checkbox->selected = $checked;
818 $checkbox->text = $label;
819 $checkbox->label->text = $label;
820 $checkbox->alt = $alt;
821 return $checkbox;
822 }
823}
824
34059565 825
7b1f2c82 826/**
827 * This class represents a select optgroup element
828 *
829 * @copyright 2009 Nicolas Connault
830 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
831 * @since Moodle 2.0
832 */
6dd7d7f0 833class html_select_optgroup extends html_component {
7b1f2c82 834 /**
835 * @var string $text The display value of the optgroup
836 */
837 public $text;
838 /**
839 * @var array $options An array of html_select_option objects
840 */
841 public $options = array();
842
34059565 843 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 844 if (empty($this->text)) {
845 throw new coding_exception('html_select_optgroup requires a $text value.');
846 }
847 if (empty($this->options)) {
848 throw new coding_exception('html_select_optgroup requires at least one html_select_option object');
849 }
34059565 850 parent::prepare($output, $page, $target);
7b1f2c82 851 }
852}
853
34059565 854
7b1f2c82 855/**
856 * This class represents an input field
857 *
858 * @copyright 2009 Nicolas Connault
859 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
860 * @since Moodle 2.0
861 */
7a5c78e0 862class html_field extends labelled_html_component {
7b1f2c82 863 /**
864 * @var string $name The name attribute of the field
865 */
866 public $name;
867 /**
868 * @var string $value The value attribute of the field
869 */
870 public $value;
871 /**
872 * @var string $type The type attribute of the field (text, submit, checkbox etc)
873 */
874 public $type;
875 /**
876 * @var string $maxlength The maxlength attribute of the field (only applies to text type)
877 */
878 public $maxlength;
5fc6d585 879 /**
880 * @var boolean $disabled Whether or not this field is disabled
881 */
882 public $disabled = false;
7b1f2c82 883
884 public function __construct() {
885 $this->label = new html_label();
886 }
887
888 /**
6dd7d7f0 889 * @see html_component::prepare()
7b1f2c82 890 * @return void
891 */
34059565 892 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 893 if (empty($this->style)) {
894 $this->style = 'width: 4em;';
895 }
896 if (empty($this->id)) {
897 $this->generate_id();
898 }
34059565 899 parent::prepare($output, $page, $target);
7b1f2c82 900 }
901
902 /**
903 * Shortcut for creating a text input component.
904 * @param string $name The name of the text field
905 * @param string $value The value of the text field
906 * @param string $alt The info to be inserted in the alt tag
907 * @param int $maxlength Sets the maxlength attribute of the field. Not set by default
908 * @return html_field The field component
909 */
a0ead5eb 910 public static function make_text($name='unnamed', $value='', $alt='', $maxlength=0) {
7b1f2c82 911 $field = new html_field();
912 if (empty($alt)) {
a0ead5eb 913 $alt = $name;
7b1f2c82 914 }
915 $field->type = 'text';
916 $field->name = $name;
917 $field->value = $value;
918 $field->alt = $alt;
919 $field->maxlength = $maxlength;
920 return $field;
921 }
922}
923
34059565 924
7b1f2c82 925/**
926 * Holds all the information required to render a <table> by
78946b9b 927 * {@see core_renderer::table()} or by an overridden version of that
7b1f2c82 928 * method in a subclass.
929 *
930 * Example of usage:
931 * $t = new html_table();
932 * ... // set various properties of the object $t as described below
933 * echo $OUTPUT->table($t);
934 *
935 * @copyright 2009 David Mudrak <david.mudrak@gmail.com>
936 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
937 * @since Moodle 2.0
938 */
7a5c78e0 939class html_table extends labelled_html_component {
7b1f2c82 940 /**
a0ead5eb 941 * For more control over the rendering of the headers, an array of html_table_cell objects
54a007e8 942 * can be passed instead of an array of strings.
7b1f2c82 943 * @var array of headings. The n-th array item is used as a heading of the n-th column.
944 *
945 * Example of usage:
946 * $t->head = array('Student', 'Grade');
947 */
948 public $head;
949 /**
950 * @var array can be used to make a heading span multiple columns
951 *
952 * Example of usage:
953 * $t->headspan = array(2,1);
954 *
955 * In this example, {@see html_table:$data} is supposed to have three columns. For the first two columns,
956 * the same heading is used. Therefore, {@see html_table::$head} should consist of two items.
957 */
958 public $headspan;
959 /**
960 * @var array of column alignments. The value is used as CSS 'text-align' property. Therefore, possible
961 * values are 'left', 'right', 'center' and 'justify'. Specify 'right' or 'left' from the perspective
962 * of a left-to-right (LTR) language. For RTL, the values are flipped automatically.
963 *
beb56299 964 * Examples of usage:
965 * $t->align = array(null, 'right');
966 * or
967 * $t->align[1] = 'right';
968 *
d9c8f425 969 */
beb56299 970 public $align;
d9c8f425 971 /**
beb56299 972 * @var array of column sizes. The value is used as CSS 'size' property.
973 *
974 * Examples of usage:
975 * $t->size = array('50%', '50%');
976 * or
977 * $t->size[1] = '120px';
d9c8f425 978 */
beb56299 979 public $size;
d9c8f425 980 /**
beb56299 981 * @var array of wrapping information. The only possible value is 'nowrap' that sets the
982 * CSS property 'white-space' to the value 'nowrap' in the given column.
983 *
984 * Example of usage:
985 * $t->wrap = array(null, 'nowrap');
d9c8f425 986 */
beb56299 987 public $wrap;
d9c8f425 988 /**
beb56299 989 * @var array of arrays or html_table_row objects containing the data. Alternatively, if you have
990 * $head specified, the string 'hr' (for horizontal ruler) can be used
991 * instead of an array of cells data resulting in a divider rendered.
d9c8f425 992 *
beb56299 993 * Example of usage with array of arrays:
994 * $row1 = array('Harry Potter', '76 %');
995 * $row2 = array('Hermione Granger', '100 %');
996 * $t->data = array($row1, $row2);
d9c8f425 997 *
beb56299 998 * Example with array of html_table_row objects: (used for more fine-grained control)
999 * $cell1 = new html_table_cell();
1000 * $cell1->text = 'Harry Potter';
1001 * $cell1->colspan = 2;
1002 * $row1 = new html_table_row();
1003 * $row1->cells[] = $cell1;
1004 * $cell2 = new html_table_cell();
1005 * $cell2->text = 'Hermione Granger';
1006 * $cell3 = new html_table_cell();
1007 * $cell3->text = '100 %';
1008 * $row2 = new html_table_row();
1009 * $row2->cells = array($cell2, $cell3);
1010 * $t->data = array($row1, $row2);
1011 */
1012 public $data;
1013 /**
1014 * @var string width of the table, percentage of the page preferred. Defaults to 80% of the page width.
1015 * @deprecated since Moodle 2.0. Styling should be in the CSS.
1016 */
1017 public $width = null;
1018 /**
1019 * @var string alignment the whole table. Can be 'right', 'left' or 'center' (default).
1020 * @deprecated since Moodle 2.0. Styling should be in the CSS.
1021 */
1022 public $tablealign = null;
1023 /**
1024 * @var int padding on each cell, in pixels
1025 * @deprecated since Moodle 2.0. Styling should be in the CSS.
1026 */
1027 public $cellpadding = null;
1028 /**
1029 * @var int spacing between cells, in pixels
1030 * @deprecated since Moodle 2.0. Styling should be in the CSS.
1031 */
1032 public $cellspacing = null;
1033 /**
1034 * @var array classes to add to particular rows, space-separated string.
1035 * Classes 'r0' or 'r1' are added automatically for every odd or even row,
1036 * respectively. Class 'lastrow' is added automatically for the last row
1037 * in the table.
d9c8f425 1038 *
beb56299 1039 * Example of usage:
1040 * $t->rowclasses[9] = 'tenth'
1041 */
1042 public $rowclasses;
1043 /**
1044 * @var array classes to add to every cell in a particular column,
1045 * space-separated string. Class 'cell' is added automatically by the renderer.
1046 * Classes 'c0' or 'c1' are added automatically for every odd or even column,
1047 * respectively. Class 'lastcol' is added automatically for all last cells
1048 * in a row.
d9c8f425 1049 *
beb56299 1050 * Example of usage:
1051 * $t->colclasses = array(null, 'grade');
d9c8f425 1052 */
beb56299 1053 public $colclasses;
1054 /**
1055 * @var string description of the contents for screen readers.
1056 */
1057 public $summary;
1058 /**
1059 * @var bool true causes the contents of the heading cells to be rotated 90 degrees.
1060 */
1061 public $rotateheaders = false;
319770d7 1062 /**
1063 * @var array $headclasses Array of CSS classes to apply to the table's thead.
1064 */
1065 public $headclasses = array();
1066 /**
1067 * @var array $bodyclasses Array of CSS classes to apply to the table's tbody.
1068 */
1069 public $bodyclasses = array();
1070 /**
1071 * @var array $footclasses Array of CSS classes to apply to the table's tfoot.
1072 */
1073 public $footclasses = array();
a0ead5eb 1074
d9c8f425 1075
1076 /**
6dd7d7f0 1077 * @see html_component::prepare()
beb56299 1078 * @return void
d9c8f425 1079 */
34059565 1080 public function prepare(renderer_base $output, moodle_page $page, $target) {
beb56299 1081 if (!empty($this->align)) {
1082 foreach ($this->align as $key => $aa) {
1083 if ($aa) {
1084 $this->align[$key] = 'text-align:'. fix_align_rtl($aa) .';'; // Fix for RTL languages
1085 } else {
1086 $this->align[$key] = '';
1087 }
1088 }
d9c8f425 1089 }
beb56299 1090 if (!empty($this->size)) {
1091 foreach ($this->size as $key => $ss) {
1092 if ($ss) {
1093 $this->size[$key] = 'width:'. $ss .';';
1094 } else {
1095 $this->size[$key] = '';
1096 }
1097 }
d9c8f425 1098 }
beb56299 1099 if (!empty($this->wrap)) {
1100 foreach ($this->wrap as $key => $ww) {
1101 if ($ww) {
1102 $this->wrap[$key] = 'white-space:nowrap;';
1103 } else {
1104 $this->wrap[$key] = '';
1105 }
1106 }
d9c8f425 1107 }
beb56299 1108 if (!empty($this->head)) {
1109 foreach ($this->head as $key => $val) {
1110 if (!isset($this->align[$key])) {
1111 $this->align[$key] = '';
1112 }
1113 if (!isset($this->size[$key])) {
1114 $this->size[$key] = '';
1115 }
1116 if (!isset($this->wrap[$key])) {
1117 $this->wrap[$key] = '';
d9c8f425 1118 }
1119
d9c8f425 1120 }
beb56299 1121 }
1122 if (empty($this->classes)) { // must be done before align
1123 $this->set_classes(array('generaltable'));
1124 }
1125 if (!empty($this->tablealign)) {
1126 $this->add_class('boxalign' . $this->tablealign);
1127 }
1128 if (!empty($this->rotateheaders)) {
1129 $this->add_class('rotateheaders');
d9c8f425 1130 } else {
beb56299 1131 $this->rotateheaders = false; // Makes life easier later.
1132 }
34059565 1133 parent::prepare($output, $page, $target);
beb56299 1134 }
1135 /**
1136 * @param string $name The name of the variable to set
1137 * @param mixed $value The value to assign to the variable
1138 * @return void
1139 */
1140 public function __set($name, $value) {
1141 if ($name == 'rowclass') {
1142 debugging('rowclass[] has been deprecated for html_table ' .
7b1f2c82 1143 'and should be replaced with rowclasses[]. please fix the code.');
1144 $this->rowclasses = $value;
1145 } else {
1146 parent::__set($name, $value);
d9c8f425 1147 }
d9c8f425 1148 }
d9c8f425 1149}
1150
34059565 1151
d9c8f425 1152/**
7b1f2c82 1153 * Component representing a table row.
d9c8f425 1154 *
1155 * @copyright 2009 Nicolas Connault
1156 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1157 * @since Moodle 2.0
1158 */
6dd7d7f0 1159class html_table_row extends html_component {
d9c8f425 1160 /**
7b1f2c82 1161 * @var array $cells Array of html_table_cell objects
d9c8f425 1162 */
7b1f2c82 1163 public $cells = array();
d9c8f425 1164
beb56299 1165 /**
6dd7d7f0 1166 * @see lib/html_component#prepare()
beb56299 1167 * @return void
1168 */
34059565
PS
1169 public function prepare(renderer_base $output, moodle_page $page, $target) {
1170 parent::prepare($output, $page, $target);
d9c8f425 1171 }
a0ead5eb 1172
54a007e8 1173 /**
a019627a 1174 * Shortcut method for creating a row with an array of cells. Converts cells to html_table_cell objects.
54a007e8 1175 * @param array $cells
1176 * @return html_table_row
1177 */
1178 public function make($cells=array()) {
1179 $row = new html_table_row();
a019627a 1180 foreach ($cells as $celltext) {
1181 if (!($celltext instanceof html_table_cell)) {
1182 $cell = new html_table_cell();
1183 $cell->text = $celltext;
1184 $row->cells[] = $cell;
1185 } else {
1186 $row->cells[] = $celltext;
1187 }
1188 }
54a007e8 1189 return $row;
1190 }
d9c8f425 1191}
1192
34059565 1193
d9c8f425 1194/**
7b1f2c82 1195 * Component representing a table cell.
d9c8f425 1196 *
1197 * @copyright 2009 Nicolas Connault
1198 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1199 * @since Moodle 2.0
1200 */
6dd7d7f0 1201class html_table_cell extends html_component {
d9c8f425 1202 /**
7b1f2c82 1203 * @var string $text The contents of the cell
d9c8f425 1204 */
7b1f2c82 1205 public $text;
d9c8f425 1206 /**
7b1f2c82 1207 * @var string $abbr Abbreviated version of the contents of the cell
d9c8f425 1208 */
7b1f2c82 1209 public $abbr = '';
d9c8f425 1210 /**
7b1f2c82 1211 * @var int $colspan Number of columns this cell should span
d9c8f425 1212 */
7b1f2c82 1213 public $colspan = '';
d9c8f425 1214 /**
7b1f2c82 1215 * @var int $rowspan Number of rows this cell should span
d9c8f425 1216 */
7b1f2c82 1217 public $rowspan = '';
d9c8f425 1218 /**
7b1f2c82 1219 * @var string $scope Defines a way to associate header cells and data cells in a table
d9c8f425 1220 */
7b1f2c82 1221 public $scope = '';
1ae3767a 1222 /**
1223 * @var boolean $header Whether or not this cell is a header cell
1224 */
a4998d01 1225 public $header = null;
d9c8f425 1226
1227 /**
6dd7d7f0 1228 * @see lib/html_component#prepare()
d9c8f425 1229 * @return void
1230 */
34059565 1231 public function prepare(renderer_base $output, moodle_page $page, $target) {
54a007e8 1232 if ($this->header && empty($this->scope)) {
1233 $this->scope = 'col';
1234 }
34059565 1235 parent::prepare($output, $page, $target);
d9c8f425 1236 }
1237}
1238
34059565 1239
d9c8f425 1240/**
7b1f2c82 1241 * Component representing a XHTML link.
d9c8f425 1242 *
beb56299 1243 * @copyright 2009 Nicolas Connault
d9c8f425 1244 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1245 * @since Moodle 2.0
1246 */
6dd7d7f0 1247class html_link extends html_component {
d9c8f425 1248 /**
7b1f2c82 1249 * URL can be simple text or a moodle_url object
1250 * @var mixed $url
d9c8f425 1251 */
beb56299 1252 public $url;
d9c8f425 1253
1254 /**
7b1f2c82 1255 * @var string $text The text that will appear between the link tags
d9c8f425 1256 */
7b1f2c82 1257 public $text;
d9c8f425 1258
1259 /**
a0ead5eb 1260 * @var boolean $disabled Whether or not this link is disabled (will be rendered as plain text)
1261 */
1262 public $disabled = false;
1263
284943fc 1264 /**
1265 * @var boolean $disableifcurrent Whether or not this link should be disabled if it the same as the current page
1266 */
1267 public $disableifcurrent = false;
1268
a0ead5eb 1269 /**
6dd7d7f0 1270 * @see lib/html_component#prepare() Disables the link if it links to the current page.
beb56299 1271 * @return void
d9c8f425 1272 */
34059565 1273 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 1274 // We can't accept an empty text value
1275 if (empty($this->text)) {
1276 throw new coding_exception('A html_link must have a descriptive text value!');
beb56299 1277 }
1278
a0ead5eb 1279 if (!($this->url instanceof moodle_url)) {
1280 $this->url = new moodle_url($this->url);
1281 }
1282
34059565 1283 if ($this->url->compare($page->url, URL_MATCH_PARAMS) && $this->disableifcurrent) {
a0ead5eb 1284 $this->disabled = true;
1285 }
34059565 1286 parent::prepare($output, $page, $target);
beb56299 1287 }
d9c8f425 1288
1289 /**
7b1f2c82 1290 * Shortcut for creating a link component.
1291 * @param mixed $url String or moodle_url
1292 * @param string $text The text of the link
1293 * @return html_link The link component
d9c8f425 1294 */
7b1f2c82 1295 public function make($url, $text) {
1296 $link = new html_link();
1297 $link->url = $url;
1298 $link->text = $text;
a0ead5eb 1299
7b1f2c82 1300 return $link;
d9c8f425 1301 }
1302}
1303
34059565 1304
d9c8f425 1305/**
7b1f2c82 1306 * Component representing a XHTML button (input of type 'button').
1307 * The renderer will either output it as a button with an onclick event,
1308 * or as a form with hidden inputs.
d9c8f425 1309 *
beb56299 1310 * @copyright 2009 Nicolas Connault
d9c8f425 1311 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1312 * @since Moodle 2.0
1313 */
7a5c78e0 1314class html_button extends labelled_html_component {
d9c8f425 1315 /**
7b1f2c82 1316 * @var string $text
d9c8f425 1317 */
7b1f2c82 1318 public $text;
d9c8f425 1319
d9c8f425 1320 /**
7b1f2c82 1321 * @var boolean $disabled Whether or not this button is disabled
d9c8f425 1322 */
beb56299 1323 public $disabled = false;
7b1f2c82 1324
d9c8f425 1325 /**
6dd7d7f0 1326 * @see lib/html_component#prepare()
7b1f2c82 1327 * @return void
d9c8f425 1328 */
34059565 1329 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 1330 $this->add_class('singlebutton');
1331
1332 if (empty($this->text)) {
b65bfc3e 1333 $this->text = get_string('submit');
7b1f2c82 1334 }
1335
1336 if ($this->disabled) {
1337 $this->disabled = 'disabled';
1338 }
1339
34059565 1340 parent::prepare($output, $page, $target);
7b1f2c82 1341 }
1342}
1343
1344/**
1345 * Component representing an image.
1346 *
1347 * @copyright 2009 Nicolas Connault
1348 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1349 * @since Moodle 2.0
1350 */
7a5c78e0 1351class html_image extends labelled_html_component {
d9c8f425 1352 /**
7b1f2c82 1353 * @var string $alt A descriptive text
d9c8f425 1354 */
7b1f2c82 1355 public $alt = HTML_ATTR_EMPTY;
d9c8f425 1356 /**
7b1f2c82 1357 * @var string $src The path to the image being used
d9c8f425 1358 */
7b1f2c82 1359 public $src;
1ba862ec
PS
1360 /**
1361 * @var int $width of image
1362 */
1363 public $width;
1364 /**
1365 * @var int $height of image
1366 */
1367 public $height;
7b1f2c82 1368
d9c8f425 1369 /**
6dd7d7f0 1370 * @see lib/html_component#prepare()
7b1f2c82 1371 * @return void
d9c8f425 1372 */
34059565 1373 public function prepare(renderer_base $output, moodle_page $page, $target) {
b65bfc3e 1374 if (empty($this->src)) {
1375 throw new coding_exception('html_image requires a $src value (moodle_url).');
1376 }
1377
1ba862ec 1378 // no general class here, use custom class instead or img element directly in css selectors
34059565 1379 parent::prepare($output, $page, $target);
7b1f2c82 1380 }
cae83708 1381
1382 /**
1383 * Shortcut for initialising a html_image.
1384 *
1385 * @param mixed $url The URL to the image (string or moodle_url)
1386 */
1387 public function make($url) {
1388 $image = new html_image();
1389 $image->src = $url;
1390 return $image;
1391 }
7b1f2c82 1392}
1393
34059565 1394
7b1f2c82 1395/**
1396 * Component representing a textarea.
1397 *
1398 * @copyright 2009 Nicolas Connault
1399 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1400 * @since Moodle 2.0
1401 */
6dd7d7f0 1402class html_textarea extends html_component {
d9c8f425 1403 /**
7b1f2c82 1404 * @param string $name Name to use for the textarea element.
d9c8f425 1405 */
7b1f2c82 1406 public $name;
d9c8f425 1407 /**
7b1f2c82 1408 * @param string $value Initial content to display in the textarea.
d9c8f425 1409 */
7b1f2c82 1410 public $value;
d9c8f425 1411 /**
7b1f2c82 1412 * @param int $rows Number of rows to display (minimum of 10 when $height is non-null)
d9c8f425 1413 */
7b1f2c82 1414 public $rows;
beb56299 1415 /**
7b1f2c82 1416 * @param int $cols Number of columns to display (minimum of 65 when $width is non-null)
beb56299 1417 */
7b1f2c82 1418 public $cols;
1419 /**
1420 * @param bool $usehtmleditor Enables the use of the htmleditor for this field.
1421 */
1422 public $usehtmleditor;
d9c8f425 1423
1424 /**
6dd7d7f0 1425 * @see lib/html_component#prepare()
d9c8f425 1426 * @return void
1427 */
34059565 1428 public function prepare(renderer_base $output, moodle_page $page, $target) {
7b1f2c82 1429 $this->add_class('form-textarea');
d9c8f425 1430
beb56299 1431 if (empty($this->id)) {
7b1f2c82 1432 $this->id = "edit-$this->name";
d9c8f425 1433 }
beb56299 1434
7b1f2c82 1435 if ($this->usehtmleditor) {
1436 editors_head_setup();
1437 $editor = get_preferred_texteditor(FORMAT_HTML);
1438 $editor->use_editor($this->id, array('legacy'=>true));
1439 $this->value = htmlspecialchars($value);
d9c8f425 1440 }
beb56299 1441
34059565 1442 parent::prepare($output, $page, $target);
d9c8f425 1443 }
7b1f2c82 1444}
beb56299 1445
34059565 1446
7b1f2c82 1447/**
1448 * Component representing a simple form wrapper. Its purpose is mainly to enclose
1449 * a submit input with the appropriate action and hidden inputs.
1450 *
1451 * @copyright 2009 Nicolas Connault
1452 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1453 * @since Moodle 2.0
1454 */
6dd7d7f0 1455class html_form extends html_component {
d9c8f425 1456 /**
7b1f2c82 1457 * @var string $method post or get
d9c8f425 1458 */
7b1f2c82 1459 public $method = 'post';
d9c8f425 1460 /**
7b1f2c82 1461 * If a string is given, it will be converted to a moodle_url during prepare()
1462 * @var mixed $url A moodle_url including params or a string
d9c8f425 1463 */
7b1f2c82 1464 public $url;
d9c8f425 1465 /**
7b1f2c82 1466 * @var array $params Optional array of parameters. Ignored if $url instanceof moodle_url
d9c8f425 1467 */
7b1f2c82 1468 public $params = array();
1469 /**
1470 * @var boolean $showbutton If true, the submit button will always be shown even if JavaScript is available
1471 */
1472 public $showbutton = false;
1473 /**
1474 * @var string $targetwindow The name of the target page to open the linked page in.
1475 */
1476 public $targetwindow = 'self';
1477 /**
1478 * @var html_button $button A submit button
1479 */
1480 public $button;
b65bfc3e 1481 /**
1482 * @var boolean $jssubmitaction If true, the submit button will be hidden when JS is enabled
1483 */
1484 public $jssubmitaction = false;
d9c8f425 1485 /**
7b1f2c82 1486 * Constructor: sets up the other components in case they are needed
1487 * @return void
d9c8f425 1488 */
7b1f2c82 1489 public function __construct() {
7b1f2c82 1490 $this->button = new html_button();
319770d7 1491 $this->button->text = get_string('yes');
beb56299 1492 }
1493
d9c8f425 1494 /**
6dd7d7f0 1495 * @see lib/html_component#prepare()
7b1f2c82 1496 * @return void
d9c8f425 1497 */
34059565 1498 public function prepare(renderer_base $output, moodle_page $page, $target) {
beb56299 1499
7b1f2c82 1500 if (empty($this->url)) {
1501 throw new coding_exception('A html_form must have a $url value (string or moodle_url).');
beb56299 1502 }
1503
7b1f2c82 1504 if (!($this->url instanceof moodle_url)) {
1505 $this->url = new moodle_url($this->url, $this->params);
beb56299 1506 }
1507
7b1f2c82 1508 if ($this->method == 'post') {
1509 $this->url->param('sesskey', sesskey());
beb56299 1510 }
d9c8f425 1511
34059565 1512 parent::prepare($output, $page, $target);
7b1f2c82 1513 }
642816a6 1514
1515 public static function make_button($url, $options, $label='OK', $method='post') {
1516 $form = new html_form();
1517 $form->url = new moodle_url($url, $options);
1518 $form->button->text = $label;
1519 $form->method = $method;
1520 return $form;
1521 }
7b1f2c82 1522}
d9c8f425 1523
34059565 1524
7b1f2c82 1525/**
1526 * Component representing a list.
1527 *
1528 * The advantage of using this object instead of a flat array is that you can load it
1529 * with metadata (CSS classes, event handlers etc.) which can be used by the renderers.
1530 *
1531 * @copyright 2009 Nicolas Connault
1532 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1533 * @since Moodle 2.0
1534 */
6dd7d7f0 1535class html_list extends html_component {
d9c8f425 1536
7b1f2c82 1537 /**
1538 * @var array $items An array of html_list_item or html_list objects
1539 */
1540 public $items = array();
d9c8f425 1541
7b1f2c82 1542 /**
1543 * @var string $type The type of list (ordered|unordered), definition type not yet supported
1544 */
1545 public $type = 'unordered';
d9c8f425 1546
b65bfc3e 1547 /**
1548 * @var string $text An optional descriptive text for the list. Will be output as a list item before opening the new list
1549 */
1550 public $text = false;
1551
7b1f2c82 1552 /**
6dd7d7f0 1553 * @see lib/html_component#prepare()
7b1f2c82 1554 * @return void
1555 */
34059565
PS
1556 public function prepare(renderer_base $output, moodle_page $page, $target) {
1557 parent::prepare($output, $page, $target);
d9c8f425 1558 }
1559
1560 /**
7b1f2c82 1561 * This function takes a nested array of data and maps it into this list's $items array
1562 * as proper html_list_item and html_list objects, with appropriate metadata.
1563 *
1564 * @param array $tree A nested array (array keys are ignored);
1565 * @param int $row Used in identifying the iteration level and in ul classes
beb56299 1566 * @return void
d9c8f425 1567 */
7b1f2c82 1568 public function load_data($tree, $level=0) {
beb56299 1569
7b1f2c82 1570 $this->add_class("list-$level");
beb56299 1571
b65bfc3e 1572 $i = 1;
7b1f2c82 1573 foreach ($tree as $key => $element) {
1574 if (is_array($element)) {
1575 $newhtmllist = new html_list();
b65bfc3e 1576 $newhtmllist->type = $this->type;
7b1f2c82 1577 $newhtmllist->load_data($element, $level + 1);
b65bfc3e 1578 $newhtmllist->text = $key;
7b1f2c82 1579 $this->items[] = $newhtmllist;
1580 } else {
1581 $listitem = new html_list_item();
1582 $listitem->value = $element;
b65bfc3e 1583 $listitem->add_class("list-item-$level-$i");
7b1f2c82 1584 $this->items[] = $listitem;
beb56299 1585 }
b65bfc3e 1586 $i++;
beb56299 1587 }
1588 }
d9c8f425 1589
1590 /**
7b1f2c82 1591 * Adds a html_list_item or html_list to this list.
1592 * If the param is a string, a html_list_item will be added.
1593 * @param mixed $item String, html_list or html_list_item object
d9c8f425 1594 * @return void
1595 */
7b1f2c82 1596 public function add_item($item) {
1597 if ($item instanceof html_list_item || $item instanceof html_list) {
1598 $this->items[] = $item;
1599 } else {
1600 $listitem = new html_list_item();
1601 $listitem->value = $item;
1602 $this->items[] = $item;
beb56299 1603 }
d9c8f425 1604 }
7b1f2c82 1605}
d9c8f425 1606
34059565 1607
7b1f2c82 1608/**
1609 * Component representing a list item.
1610 *
1611 * @copyright 2009 Nicolas Connault
1612 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1613 * @since Moodle 2.0
1614 */
6dd7d7f0 1615class html_list_item extends html_component {
d9c8f425 1616 /**
7b1f2c82 1617 * @var string $value The value of the list item
d9c8f425 1618 */
7b1f2c82 1619 public $value;
d9c8f425 1620
7b1f2c82 1621 /**
6dd7d7f0 1622 * @see lib/html_component#prepare()
7b1f2c82 1623 * @return void
1624 */
34059565
PS
1625 public function prepare(renderer_base $output, moodle_page $page, $target) {
1626 parent::prepare($output, $page, $target);
d9c8f425 1627 }
1628}
1629
34059565 1630
54a007e8 1631/**
a0ead5eb 1632 * Component representing a span element. It has no special attributes, so
54a007e8 1633 * it is very low-level and can be used for styling and JS actions.
1634 *
1635 * @copyright 2009 Nicolas Connault
1636 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1637 * @since Moodle 2.0
1638 */
6dd7d7f0 1639class html_span extends html_component {
54a007e8 1640 /**
1641 * @var string $text The contents of the span
1642 */
1643 public $contents;
1644 /**
6dd7d7f0 1645 * @see lib/html_component#prepare()
54a007e8 1646 * @return void
1647 */
34059565
PS
1648 public function prepare(renderer_base $output, moodle_page $page, $target) {
1649 parent::prepare($output, $page, $target);
54a007e8 1650 }
1651}
1652
7b1f2c82 1653/// Complex components aggregating simpler components
1654
34059565 1655
d9c8f425 1656/**
beb56299 1657 * Component representing a paging bar.
d9c8f425 1658 *
1659 * @copyright 2009 Nicolas Connault
1660 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1661 * @since Moodle 2.0
1662 */
6dd7d7f0 1663class moodle_paging_bar extends html_component {
d9c8f425 1664 /**
beb56299 1665 * @var int $maxdisplay The maximum number of pagelinks to display
d9c8f425 1666 */
beb56299 1667 public $maxdisplay = 18;
d9c8f425 1668 /**
beb56299 1669 * @var int $totalcount post or get
d9c8f425 1670 */
beb56299 1671 public $totalcount;
d9c8f425 1672 /**
beb56299 1673 * @var int $page The page you are currently viewing
d9c8f425 1674 */
beb56299 1675 public $page = 0;
d9c8f425 1676 /**
beb56299 1677 * @var int $perpage The number of entries that should be shown per page
d9c8f425 1678 */
beb56299 1679 public $perpage;
d9c8f425 1680 /**
beb56299 1681 * @var string $baseurl If this is a string then it is the url which will be appended with $pagevar, an equals sign and the page number.
1682 * If this is a moodle_url object then the pagevar param will be replaced by the page no, for each page.
d9c8f425 1683 */
beb56299 1684 public $baseurl;
d9c8f425 1685 /**
beb56299 1686 * @var string $pagevar This is the variable name that you use for the page number in your code (ie. 'tablepage', 'blogpage', etc)
d9c8f425 1687 */
beb56299 1688 public $pagevar = 'page';
beb56299 1689 /**
1690 * @var html_link $previouslink A HTML link representing the "previous" page
1691 */
1692 public $previouslink = null;
1693 /**
1694 * @var html_link $nextlink A HTML link representing the "next" page
1695 */
1696 public $nextlink = null;
1697 /**
1698 * @var html_link $firstlink A HTML link representing the first page
1699 */
1700 public $firstlink = null;
1701 /**
1702 * @var html_link $lastlink A HTML link representing the last page
1703 */
1704 public $lastlink = null;
1705 /**
1706 * @var array $pagelinks An array of html_links. One of them is just a string: the current page
1707 */
1708 public $pagelinks = array();
d9c8f425 1709
1710 /**
6dd7d7f0 1711 * @see lib/html_component#prepare()
d9c8f425 1712 * @return void
1713 */
34059565 1714 public function prepare(renderer_base $output, moodle_page $page, $target) {
1c1f64a2 1715 if (!isset($this->totalcount) || is_null($this->totalcount)) {
beb56299 1716 throw new coding_exception('moodle_paging_bar requires a totalcount value.');
1717 }
1718 if (!isset($this->page) || is_null($this->page)) {
1719 throw new coding_exception('moodle_paging_bar requires a page value.');
1720 }
1721 if (empty($this->perpage)) {
1722 throw new coding_exception('moodle_paging_bar requires a perpage value.');
1723 }
1724 if (empty($this->baseurl)) {
1725 throw new coding_exception('moodle_paging_bar requires a baseurl value.');
1726 }
1727 if (!($this->baseurl instanceof moodle_url)) {
1728 $this->baseurl = new moodle_url($this->baseurl);
1729 }
d9c8f425 1730
beb56299 1731 if ($this->totalcount > $this->perpage) {
1732 $pagenum = $this->page - 1;
d9c8f425 1733
beb56299 1734 if ($this->page > 0) {
1735 $this->previouslink = new html_link();
1736 $this->previouslink->add_class('previous');
1737 $this->previouslink->url = clone($this->baseurl);
1738 $this->previouslink->url->param($this->pagevar, $pagenum);
1739 $this->previouslink->text = get_string('previous');
1740 }
d9c8f425 1741
beb56299 1742 if ($this->perpage > 0) {
1743 $lastpage = ceil($this->totalcount / $this->perpage);
1744 } else {
1745 $lastpage = 1;
1746 }
1747
1748 if ($this->page > 15) {
1749 $startpage = $this->page - 10;
1750
1751 $this->firstlink = new html_link();
1752 $this->firstlink->url = clone($this->baseurl);
1753 $this->firstlink->url->param($this->pagevar, 0);
1754 $this->firstlink->text = 1;
1755 $this->firstlink->add_class('first');
1756 } else {
1757 $startpage = 0;
1758 }
1759
1760 $currpage = $startpage;
1761 $displaycount = $displaypage = 0;
1762
1763 while ($displaycount < $this->maxdisplay and $currpage < $lastpage) {
1764 $displaypage = $currpage + 1;
1765
f43cdceb 1766 if ($this->page == $currpage) {
beb56299 1767 $this->pagelinks[] = $displaypage;
1768 } else {
1769 $pagelink = new html_link();
1770 $pagelink->url = clone($this->baseurl);
1771 $pagelink->url->param($this->pagevar, $currpage);
1772 $pagelink->text = $displaypage;
1773 $this->pagelinks[] = $pagelink;
1774 }
1775
1776 $displaycount++;
1777 $currpage++;
1778 }
1779
1780 if ($currpage < $lastpage) {
1781 $lastpageactual = $lastpage - 1;
1782 $this->lastlink = new html_link();
1783 $this->lastlink->url = clone($this->baseurl);
1784 $this->lastlink->url->param($this->pagevar, $lastpageactual);
1785 $this->lastlink->text = $lastpage;
1786 $this->lastlink->add_class('last');
1787 }
1788
1789 $pagenum = $this->page + 1;
1790
1791 if ($pagenum != $displaypage) {
1792 $this->nextlink = new html_link();
1793 $this->nextlink->url = clone($this->baseurl);
1794 $this->nextlink->url->param($this->pagevar, $pagenum);
1795 $this->nextlink->text = get_string('next');
1796 $this->nextlink->add_class('next');
1797 }
d9c8f425 1798 }
1799 }
d9c8f425 1800
1801 /**
beb56299 1802 * Shortcut for initialising a moodle_paging_bar with only the required params.
1803 *
1804 * @param int $totalcount Thetotal number of entries available to be paged through
1805 * @param int $page The page you are currently viewing
1806 * @param int $perpage The number of entries that should be shown per page
1807 * @param mixed $baseurl If this is a string then it is the url which will be appended with $pagevar, an equals sign and the page number.
1808 * If this is a moodle_url object then the pagevar param will be replaced by the page no, for each page.
d9c8f425 1809 */
beb56299 1810 public function make($totalcount, $page, $perpage, $baseurl) {
1811 $pagingbar = new moodle_paging_bar();
1812 $pagingbar->totalcount = $totalcount;
1813 $pagingbar->page = $page;
1814 $pagingbar->perpage = $perpage;
1815 $pagingbar->baseurl = $baseurl;
1816 return $pagingbar;
d9c8f425 1817 }
1818}
1819
34059565 1820
d9c8f425 1821/**
1822 * Component representing a user picture.
1823 *
1824 * @copyright 2009 Nicolas Connault
1825 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1826 * @since Moodle 2.0
1827 */
812dbaf7 1828class user_picture extends html_image {
d9c8f425 1829 /**
812dbaf7 1830 * @var mixed $user A user object with at least fields id, picture, imagealt, firstname and lastname set.
d9c8f425 1831 */
1832 public $user;
1833 /**
812dbaf7
PS
1834 * @var int $courseid The course id. Used when constructing the link to the user's profile,
1835 * page course id used if not specified.
d9c8f425 1836 */
1837 public $courseid;
1838 /**
812dbaf7 1839 * @var bool $link add course profile link to image
d9c8f425 1840 */
812dbaf7 1841 public $link = true;
d9c8f425 1842 /**
1843 * @var int $size Size in pixels. Special values are (true/1 = 100px) and (false/0 = 35px) for backward compatibility
1844 */
812dbaf7 1845 public $size = 35;
d9c8f425 1846 /**
812dbaf7
PS
1847 * @var boolean $alttext add non-blank alt-text to the image.
1848 * Default true, set to false when image alt just duplicates text in screenreaders.
d9c8f425 1849 */
1850 public $alttext = true;
1851 /**
812dbaf7 1852 * @var boolean $popup Whether or not to open the link in a popup window.
d9c8f425 1853 */
1854 public $popup = false;
1855
1856 /**
812dbaf7 1857 * @var link to profile if link requested
d9c8f425 1858 */
812dbaf7 1859 public $url;
d9c8f425 1860
1861 /**
6dd7d7f0 1862 * @see lib/html_component#prepare()
d9c8f425 1863 * @return void
1864 */
34059565
PS
1865 public function prepare(renderer_base $output, moodle_page $page, $target) {
1866 global $CFG, $DB;
d9c8f425 1867
1868 if (empty($this->user)) {
812dbaf7 1869 throw new coding_exception('A user_picture object must have a $user object before being rendered.');
d9c8f425 1870 }
1871
812dbaf7
PS
1872 if (empty($this->user->id)) {
1873 throw new coding_exception('User id missing in $user object.');
d9c8f425 1874 }
1875
812dbaf7
PS
1876 if (empty($this->courseid)) {
1877 $courseid = $page->course->id;
1878 } else {
1879 $courseid = $this->courseid;
d9c8f425 1880 }
1881
812dbaf7 1882 // only touch the DB if we are missing data and complain loudly...
d9c8f425 1883 $needrec = false;
812dbaf7
PS
1884
1885 if (!array_key_exists('picture', $this->user)) {
1886 $needrec = true;
1887 debugging('Missing picture property in $user object, this is a performance problem that needs to be fixed by a developer.', DEBUG_DEVELOPER);
1888 }
1889 if ($this->alttext) {
1890 if (!array_key_exists('firstname', $this->user) || !array_key_exists('lastname', $this->user) || !array_key_exists('imagealt', $this->user)) {
d9c8f425 1891 $needrec = true;
812dbaf7 1892 debugging('Missing firstname, lastname or imagealt property in $user object, this is a performance problem that needs to be fixed by a developer.', DEBUG_DEVELOPER);
d9c8f425 1893 }
1894 }
812dbaf7 1895
d9c8f425 1896 if ($needrec) {
812dbaf7 1897 $this->user = $DB->get_record('user', array('id'=>$this->user->id), 'id, firstname, lastname, imagealt');
d9c8f425 1898 }
1899
812dbaf7
PS
1900 if ($this->alttext) {
1901 if (!empty($user->imagealt)) {
1902 $this->alt = $user->imagealt;
1903 } else {
1904 $this->alt = get_string('pictureof', '', fullname($this->user));
1905 }
1906 } else {
1907 $this->alt = HTML_ATTR_EMPTY;
d9c8f425 1908 }
1909
812dbaf7
PS
1910 if ($this->link) {
1911 $this->url = new moodle_url('/user/view.php', array('id' => $this->user->id, 'course' => $courseid));
1912 } else {
1913 $this->url = null;
1914 $this->popup = false;
d9c8f425 1915 }
1916
1917 if (empty($this->size)) {
1918 $file = 'f2';
1919 $this->size = 35;
1920 } else if ($this->size === true or $this->size == 1) {
1921 $file = 'f1';
1922 $this->size = 100;
1923 } else if ($this->size >= 50) {
1924 $file = 'f1';
1925 } else {
1926 $file = 'f2';
1927 }
1928
1929 if (!empty($this->size)) {
812dbaf7
PS
1930 $this->width = $this->size;
1931 $this->height = $this->size;
d9c8f425 1932 }
1933
1934 $this->add_class('userpicture');
1935
812dbaf7 1936 if (!empty($this->user->picture)) {
d9c8f425 1937 require_once($CFG->libdir.'/filelib.php');
812dbaf7 1938 $this->src = new moodle_url(get_file_url($this->user->id.'/'.$file.'.jpg', null, 'user'));
d9c8f425 1939 } else { // Print default user pictures (use theme version if available)
1940 $this->add_class('defaultuserpic');
812dbaf7 1941 $this->src = $output->pix_url('u/' . $file);
d9c8f425 1942 }
1943
34059565 1944 parent::prepare($output, $page, $target);
d9c8f425 1945 }
1946}
1947
34059565 1948
d9c8f425 1949/**
beb56299 1950 * Component representing a help icon.
d9c8f425 1951 *
1952 * @copyright 2009 Nicolas Connault
1953 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1954 * @since Moodle 2.0
1955 */
7a5c78e0 1956class moodle_help_icon extends labelled_html_component {
d9c8f425 1957 /**
beb56299 1958 * @var html_link $link A html_link object that will hold the URL info
d9c8f425 1959 */
beb56299 1960 public $link;
d9c8f425 1961 /**
beb56299 1962 * @var string $text A descriptive text
d9c8f425 1963 */
beb56299 1964 public $text;
d9c8f425 1965 /**
beb56299 1966 * @var string $page The keyword that defines a help page
d9c8f425 1967 */
beb56299 1968 public $page;
d9c8f425 1969 /**
beb56299 1970 * @var string $module Which module is the page defined in
d9c8f425 1971 */
beb56299 1972 public $module = 'moodle';
d9c8f425 1973 /**
beb56299 1974 * @var boolean $linktext Whether or not to show text next to the icon
d9c8f425 1975 */
beb56299 1976 public $linktext = false;
d9c8f425 1977 /**
beb56299 1978 * @var mixed $image The help icon. Can be set to true (will use default help icon),
1979 * false (will not use any icon), the URL to an image, or a full
1980 * html_image object.
d9c8f425 1981 */
beb56299 1982 public $image;
d9c8f425 1983
1984 /**
1985 * Constructor: sets up the other components in case they are needed
1986 * @return void
1987 */
1988 public function __construct() {
beb56299 1989 $this->link = new html_link();
1990 $this->image = new html_image();
d9c8f425 1991 }
1992
1993 /**
6dd7d7f0 1994 * @see lib/html_component#prepare()
d9c8f425 1995 * @return void
1996 */
34059565
PS
1997 public function prepare(renderer_base $output, moodle_page $page, $target) {
1998 global $CFG;
d9c8f425 1999
beb56299 2000 if (empty($this->page)) {
2001 throw new coding_exception('A moodle_help_icon object requires a $page parameter');
d9c8f425 2002 }
2003
b65bfc3e 2004 if (empty($this->text) && empty($this->link->text)) {
2005 throw new coding_exception('A moodle_help_icon object (or its $link attribute) requires a $text parameter');
2006 } else if (!empty($this->text) && empty($this->link->text)) {
2007 $this->link->text = $this->text;
d9c8f425 2008 }
2009
beb56299 2010 // fix for MDL-7734
ac06c0a3 2011 $this->link->url = new moodle_url($CFG->wwwroot.'/help.php', array('module' => $this->module, 'file' => $this->page .'.html'));
d9c8f425 2012
beb56299 2013 // fix for MDL-7734
34059565
PS
2014 if (!empty($page->course->lang)) {
2015 $this->link->url->param('forcelang', $page->course->lang);
d9c8f425 2016 }
2017
beb56299 2018 // Catch references to the old text.html and emoticons.html help files that
2019 // were renamed in MDL-13233.
2020 if (in_array($this->page, array('text', 'emoticons', 'richtext'))) {
2021 $oldname = $this->page;
2022 $this->page .= '2';
2023 debugging("You are referring to the old help file '$oldname'. " .
2024 "This was renamed to '$this->page' because of MDL-13233. " .
2025 "Please update your code.", DEBUG_DEVELOPER);
2026 }
d9c8f425 2027
beb56299 2028 if ($this->module == '') {
2029 $this->module = 'moodle';
2030 }
d9c8f425 2031
beb56299 2032 // Warn users about new window for Accessibility
2033 $this->title = get_string('helpprefix2', '', trim($this->text, ". \t")) .' ('.get_string('newwindow').')';
d9c8f425 2034
beb56299 2035 // Prepare image and linktext
2036 if ($this->image && !($this->image instanceof html_image)) {
2037 $image = fullclone($this->image);
2038 $this->image = new html_image();
d9c8f425 2039
beb56299 2040 if ($image instanceof moodle_url) {
2041 $this->image->src = $image->out();
2042 } else if ($image === true) {
34059565 2043 $this->image->src = $output->pix_url('help');
beb56299 2044 } else if (is_string($image)) {
2045 $this->image->src = $image;
d9c8f425 2046 }
beb56299 2047 $this->image->alt = $this->text;
d9c8f425 2048
beb56299 2049 if ($this->linktext) {
2050 $this->image->alt = get_string('helpwiththis');
2051 } else {
2052 $this->image->alt = $this->title;
d9c8f425 2053 }
beb56299 2054 $this->image->add_class('iconhelp');
2055 } else if (empty($this->image->src)) {
2056 if (!($this->image instanceof html_image)) {
2057 $this->image = new html_image();
d9c8f425 2058 }
34059565 2059 $this->image->src = $output->pix_url('help');
d9c8f425 2060 }
beb56299 2061
34059565 2062 parent::prepare($output, $page, $target);
d9c8f425 2063 }
2064
aa9a6867 2065 /**
2066 * This is a shortcut for creating a help_icon with only the 2 required params
2067 * @param string $page The keyword that defines a help page
2068 * @param string $text A descriptive text
2069 * @return moodle_help_icon A moodle_help_icon object with the two common fields initialised.
2070 */
2071 public static function make($page, $text, $module='moodle', $linktext=false) {
2072 $helpicon = new moodle_help_icon();
2073 $helpicon->page = $page;
2074 $helpicon->text = $text;
2075 $helpicon->module = $module;
2076 $helpicon->linktext = $linktext;
2077 return $helpicon;
2078 }
2079
beb56299 2080 public static function make_scale_menu($courseid, $scale) {
2081 $helpbutton = new moodle_help_icon();
2082 $strscales = get_string('scales');
2083 $helpbutton->image->alt = $scale->name;
2084 $helpbutton->link->url = new moodle_url('/course/scales.php', array('id' => $courseid, 'list' => true, 'scaleid' => $scale->id));
2085 $popupaction = new popup_action('click', $helpbutton->url, 'ratingscale', $popupparams);
2086 $popupaction->width = 500;
2087 $popupaction->height = 400;
2088 $helpbutton->link->add_action($popupaction);
2089 $helpbutton->link->title = $scale->name;
2090 return $helpbutton;
d9c8f425 2091 }
2092}
2093
34059565 2094
d9c8f425 2095/**
beb56299 2096 * Component representing an icon linking to a Moodle page.
d9c8f425 2097 *
2098 * @copyright 2009 Nicolas Connault
2099 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2100 * @since Moodle 2.0
2101 */
7a5c78e0 2102class moodle_action_icon extends labelled_html_component {
d9c8f425 2103 /**
beb56299 2104 * @var string $linktext Optional text to display next to the icon
d9c8f425 2105 */
beb56299 2106 public $linktext;
d9c8f425 2107 /**
beb56299 2108 * @var html_image $image The icon
d9c8f425 2109 */
beb56299 2110 public $image;
2111 /**
2112 * @var html_link $link The link
2113 */
2114 public $link;
d9c8f425 2115
2116 /**
beb56299 2117 * Constructor: sets up the other components in case they are needed
d9c8f425 2118 * @return void
2119 */
beb56299 2120 public function __construct() {
2121 $this->image = new html_image();
2122 $this->link = new html_link();
d9c8f425 2123 }
2124
2125 /**
6dd7d7f0 2126 * @see lib/html_component#prepare()
d9c8f425 2127 * @return void
2128 */
34059565 2129 public function prepare(renderer_base $output, moodle_page $page, $target) {
beb56299 2130 $this->image->add_class('action-icon');
d9c8f425 2131
7a5c78e0 2132 if (!empty($this->actions)) {
2133 foreach ($this->actions as $action) {
2134 $this->link->add_action($action);
2135 }
2136 unset($this->actions);
2137 }
2138
34059565 2139 parent::prepare($output, $page, $target);
d9c8f425 2140
beb56299 2141 if (empty($this->image->src)) {
2142 throw new coding_exception('moodle_action_icon->image->src must not be empty');
d9c8f425 2143 }
d9c8f425 2144
beb56299 2145 if (empty($this->image->alt) && !empty($this->linktext)) {
2146 $this->image->alt = $this->linktext;
2147 } else if (empty($this->image->alt)) {
2148 debugging('moodle_action_icon->image->alt should not be empty.', DEBUG_DEVELOPER);
d9c8f425 2149 }
2150 }
2151}
2152
34059565 2153
d9c8f425 2154/**
beb56299 2155 * This class represents how a block appears on a page.
d9c8f425 2156 *
beb56299 2157 * During output, each block instance is asked to return a block_contents object,
2158 * those are then passed to the $OUTPUT->block function for display.
2159 *
2160 * {@link $contents} should probably be generated using a moodle_block_..._renderer.
2161 *
2162 * Other block-like things that need to appear on the page, for example the
2163 * add new block UI, are also represented as block_contents objects.
2164 *
2165 * @copyright 2009 Tim Hunt
d9c8f425 2166 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2167 * @since Moodle 2.0
2168 */
6dd7d7f0 2169class block_contents extends html_component {
beb56299 2170 /** @var int used to set $skipid. */
2171 protected static $idcounter = 1;
2172
2173 const NOT_HIDEABLE = 0;
2174 const VISIBLE = 1;
2175 const HIDDEN = 2;
2176
d9c8f425 2177 /**
beb56299 2178 * @param integer $skipid All the blocks (or things that look like blocks)
2179 * printed on a page are given a unique number that can be used to construct
2180 * id="" attributes. This is set automatically be the {@link prepare()} method.
2181 * Do not try to set it manually.
d9c8f425 2182 */
beb56299 2183 public $skipid;
d9c8f425 2184
2185 /**
beb56299 2186 * @var integer If this is the contents of a real block, this should be set to
2187 * the block_instance.id. Otherwise this should be set to 0.
2188 */
2189 public $blockinstanceid = 0;
2190
2191 /**
2192 * @var integer if this is a real block instance, and there is a corresponding
2193 * block_position.id for the block on this page, this should be set to that id.
2194 * Otherwise it should be 0.
2195 */
2196 public $blockpositionid = 0;
2197
2198 /**
2199 * @param array $attributes an array of attribute => value pairs that are put on the
2200 * outer div of this block. {@link $id} and {@link $classes} attributes should be set separately.
2201 */
2202 public $attributes = array();
2203
2204 /**
2205 * @param string $title The title of this block. If this came from user input,
2206 * it should already have had format_string() processing done on it. This will
2207 * be output inside <h2> tags. Please do not cause invalid XHTML.
2208 */
2209 public $title = '';
2210
2211 /**
2212 * @param string $content HTML for the content
2213 */
2214 public $content = '';
2215
2216 /**
2217 * @param array $list an alternative to $content, it you want a list of things with optional icons.
2218 */
2219 public $footer = '';
2220
2221 /**
2222 * Any small print that should appear under the block to explain to the
2223 * teacher about the block, for example 'This is a sticky block that was
2224 * added in the system context.'
2225 * @var string
2226 */
2227 public $annotation = '';
2228
2229 /**
2230 * @var integer one of the constants NOT_HIDEABLE, VISIBLE, HIDDEN. Whether
2231 * the user can toggle whether this block is visible.
2232 */
2233 public $collapsible = self::NOT_HIDEABLE;
2234
2235 /**
2236 * A (possibly empty) array of editing controls. Each element of this array
2237 * should be an array('url' => $url, 'icon' => $icon, 'caption' => $caption).
b5d0cafc 2238 * $icon is the icon name. Fed to $OUTPUT->pix_url.
beb56299 2239 * @var array
2240 */
2241 public $controls = array();
2242
2243 /**
6dd7d7f0 2244 * @see html_component::prepare()
d9c8f425 2245 * @return void
2246 */
34059565 2247 public function prepare(renderer_base $output, moodle_page $page, $target) {
beb56299 2248 $this->skipid = self::$idcounter;
2249 self::$idcounter += 1;
2250 $this->add_class('sideblock');
2251 if (empty($this->blockinstanceid) || !strip_tags($this->title)) {
2252 $this->collapsible = self::NOT_HIDEABLE;
2253 }
2254 if ($this->collapsible == self::HIDDEN) {
2255 $this->add_class('hidden');
2256 }
2257 if (!empty($this->controls)) {
2258 $this->add_class('block_with_controls');
2259 }
34059565 2260 parent::prepare($output, $page, $target);
d9c8f425 2261 }
2262}
beb56299 2263
34059565 2264
beb56299 2265/**
2266 * This class represents a target for where a block can go when it is being moved.
2267 *
2268 * This needs to be rendered as a form with the given hidden from fields, and
2269 * clicking anywhere in the form should submit it. The form action should be
2270 * $PAGE->url.
2271 *
2272 * @copyright 2009 Tim Hunt
2273 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2274 * @since Moodle 2.0
2275 */
6dd7d7f0 2276class block_move_target extends html_component {
beb56299 2277 /**
2278 * List of hidden form fields.
2279 * @var array
2280 */
2281 public $url = array();
2282 /**
2283 * List of hidden form fields.
2284 * @var array
2285 */
2286 public $text = '';
2287}