MDL-38788 behat: Generic form elements interaction compatibile with JS disabled
[moodle.git] / blocks / moodleblock.class.php
CommitLineData
ec972ade 1<?php
2
4ca6cfbf
PS
3// This file is part of Moodle - http://moodle.org/
4//
ec972ade 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.
4ca6cfbf 14//
ec972ade 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/>.
0f3fe4b6 17
c7e3bc51 18/**
ccd3dd0c 19 * This file contains the parent class for moodle blocks, block_base.
c7e3bc51 20 *
78bfb562
PS
21 * @package core
22 * @subpackage block
23 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
c7e3bc51 24 */
25
26/// Constants
27
28/**
29 * Block type of list. Contents of block should be set as an associative array in the content object as items ($this->content->items). Optionally include footer text in $this->content->footer.
30 */
0f3fe4b6 31define('BLOCK_TYPE_LIST', 1);
c7e3bc51 32
33/**
34 * Block type of text. Contents of block should be set to standard html text in the content object as items ($this->content->text). Optionally include footer text in $this->content->footer.
35 */
0f3fe4b6 36define('BLOCK_TYPE_TEXT', 2);
7d2a0492 37/**
38 * Block type of tree. $this->content->items is a list of tree_item objects and $this->content->footer is a string.
39 */
40define('BLOCK_TYPE_TREE', 3);
c7e3bc51 41
c7e3bc51 42/**
e0134f84 43 * Class for describing a moodle block, all Moodle blocks derive from this class
c7e3bc51 44 *
45 * @author Jon Papaioannou
46 * @package blocks
47 */
e89d741a 48class block_base {
c7e3bc51 49
50 /**
51 * Internal var for storing/caching translated strings
52 * @var string $str
53 */
0f3fe4b6 54 var $str;
c7e3bc51 55
56 /**
f8582e3e 57 * The title of the block to be displayed in the block title area.
c7e3bc51 58 * @var string $title
59 */
9b4b78fd 60 var $title = NULL;
c7e3bc51 61
c7e3bc51 62 /**
ccd3dd0c 63 * The type of content that this block creates. Currently support options - BLOCK_TYPE_LIST, BLOCK_TYPE_TEXT
c7e3bc51 64 * @var int $content_type
65 */
3ef642d9 66 var $content_type = BLOCK_TYPE_TEXT;
c7e3bc51 67
68 /**
69 * An object to contain the information to be displayed in the block.
70 * @var stdObject $content
71 */
9b4b78fd 72 var $content = NULL;
c7e3bc51 73
74 /**
1345403a 75 * A string generated by {@link _add_edit_controls()} to display block manipulation links when the user is in editing mode.
c7e3bc51 76 * @var string $edit_controls
77 */
0f3fe4b6 78 var $edit_controls = NULL;
c7e3bc51 79
c7e3bc51 80 /**
81 * The initialized instance of this block object.
82 * @var block $instance
83 */
9b4b78fd 84 var $instance = NULL;
c7e3bc51 85
3179b000 86 /**
87 * The page that this block is appearing on.
88 * @var moodle_page
89 */
90 public $page = NULL;
91
e92c286c 92 /**
93 * This blocks's context.
94 * @var stdClass
95 */
96 public $context = NULL;
97
c7e3bc51 98 /**
99 * An object containing the instance configuration information for the current instance of this block.
100 * @var stdObject $config
101 */
9b4b78fd 102 var $config = NULL;
103
4ca6cfbf 104 /**
f9648e77 105 * How often the cronjob should run, 0 if not at all.
106 * @var int $cron
107 */
108
109 var $cron = NULL;
110
e0134f84 111/// Class Functions
c7e3bc51 112
73554752 113 /**
114 * Fake constructor to keep PHP5 happy
115 *
116 */
117 function __construct() {
8571833f 118 $this->init();
73554752 119 }
4ca6cfbf 120
44c55d46 121 /**
122 * Function that can be overridden to do extra cleanup before
123 * the database tables are deleted. (Called once per block, not per instance!)
124 */
125 function before_delete() {
126 }
4ca6cfbf 127
c7e3bc51 128 /**
129 * Returns the block name, as present in the class name,
130 * the database, the block directory, etc etc.
131 *
132 * @return string
133 */
0f3fe4b6 134 function name() {
135 // Returns the block name, as present in the class name,
136 // the database, the block directory, etc etc.
137 static $myname;
c7e3bc51 138 if ($myname === NULL) {
0f3fe4b6 139 $myname = strtolower(get_class($this));
140 $myname = substr($myname, strpos($myname, '_') + 1);
141 }
142 return $myname;
143 }
144
c7e3bc51 145 /**
146 * Parent class version of this function simply returns NULL
147 * This should be implemented by the derived class to return
148 * the content object.
149 *
150 * @return stdObject
151 */
0f3fe4b6 152 function get_content() {
153 // This should be implemented by the derived class.
154 return NULL;
155 }
c7e3bc51 156
157 /**
158 * Returns the class $title var value.
159 *
4ca6cfbf 160 * Intentionally doesn't check if a title is set.
c7e3bc51 161 * This is already done in {@link _self_test()}
162 *
163 * @return string $this->title
164 */
0f3fe4b6 165 function get_title() {
6195e04a 166 // Intentionally doesn't check if a title is set. This is already done in _self_test()
0f3fe4b6 167 return $this->title;
168 }
c7e3bc51 169
170 /**
171 * Returns the class $content_type var value.
172 *
4ca6cfbf 173 * Intentionally doesn't check if content_type is set.
c7e3bc51 174 * This is already done in {@link _self_test()}
175 *
176 * @return string $this->content_type
177 */
0f3fe4b6 178 function get_content_type() {
6195e04a 179 // Intentionally doesn't check if a content_type is set. This is already done in _self_test()
0f3fe4b6 180 return $this->content_type;
181 }
c7e3bc51 182
3ef642d9 183 /**
184 * Returns true or false, depending on whether this block has any content to display
7e874772 185 * and whether the user has permission to view the block
3ef642d9 186 *
187 * @return boolean
188 */
189 function is_empty() {
e92c286c 190 if ( !has_capability('moodle/block:view', $this->context) ) {
7e874772 191 return true;
192 }
193
3ef642d9 194 $this->get_content();
195 return(empty($this->content->text) && empty($this->content->footer));
196 }
197
c7e3bc51 198 /**
199 * First sets the current value of $this->content to NULL
200 * then calls the block's {@link get_content()} function
201 * to set its value back.
202 *
203 * @return stdObject
204 */
0f3fe4b6 205 function refresh_content() {
206 // Nothing special here, depends on content()
207 $this->content = NULL;
208 return $this->get_content();
209 }
c7e3bc51 210
211 /**
9c14c1c5 212 * Return a block_contents object representing the full contents of this block.
d4a03c00 213 *
214 * This internally calls ->get_content(), and then adds the editing controls etc.
215 *
216 * You probably should not override this method, but instead override
217 * {@link html_attributes()}, {@link formatted_contents()} or {@link get_content()},
218 * {@link hide_header()}, {@link (get_edit_controls)}, etc.
219 *
9c14c1c5 220 * @return block_contents a representation of the block, for rendering.
d4a03c00 221 * @since Moodle 2.0.
c7e3bc51 222 */
d4a03c00 223 public function get_content_for_output($output) {
224 global $CFG;
0a0bb380 225
dd72b308
PS
226 $bc = new block_contents($this->html_attributes());
227
d4a03c00 228 $bc->blockinstanceid = $this->instance->id;
229 $bc->blockpositionid = $this->instance->blockpositionid;
c7e3bc51 230
e54f4a78 231 if ($this->instance->visible) {
232 $bc->content = $this->formatted_contents($output);
233 if (!empty($this->content->footer)) {
234 $bc->footer = $this->content->footer;
235 }
236 } else {
237 $bc->add_class('invisible');
238 }
239
d4a03c00 240 if (!$this->hide_header()) {
241 $bc->title = $this->title;
242 }
91d941c3
SH
243 if (empty($bc->title)) {
244 $bc->arialabel = new lang_string('pluginname', get_class($this));
245 }
ae42ff6f 246
d4a03c00 247 if ($this->page->user_is_editing()) {
00a24d44 248 $bc->controls = $this->page->blocks->edit_controls($this);
9c14c1c5
PS
249 } else {
250 // we must not use is_empty on hidden blocks
251 if ($this->is_empty() && !$bc->controls) {
252 return null;
253 }
f674ec86 254 }
255
0885166f
JC
256 if (empty($CFG->allowuserblockhiding)
257 || (empty($bc->content) && empty($bc->footer))
258 || !$this->instance_can_be_collapsed()) {
d4a03c00 259 $bc->collapsible = block_contents::NOT_HIDEABLE;
260 } else if (get_user_preferences('block' . $bc->blockinstanceid . 'hidden', false)) {
261 $bc->collapsible = block_contents::HIDDEN;
262 } else {
263 $bc->collapsible = block_contents::VISIBLE;
0f3fe4b6 264 }
c4d951e1 265
40928036 266 $bc->annotation = ''; // TODO MDL-19398 need to work out what to say here.
d4a03c00 267
268 return $bc;
0f3fe4b6 269 }
89adb174 270
c7e3bc51 271 /**
d4a03c00 272 * Convert the contents of the block to HTML.
c7e3bc51 273 *
d4a03c00 274 * This is used by block base classes like block_list to convert the structured
275 * $this->content->list and $this->content->icons arrays to HTML. So, in most
276 * blocks, you probaby want to override the {@link get_contents()} method,
277 * which generates that structured representation of the contents.
278 *
279 * @param $output The core_renderer to use when generating the output.
280 * @return string the HTML that should appearn in the body of the block.
281 * @since Moodle 2.0.
c7e3bc51 282 */
d4a03c00 283 protected function formatted_contents($output) {
284 $this->get_content();
dde36f9d 285 $this->get_required_javascript();
d4a03c00 286 if (!empty($this->content->text)) {
287 return $this->content->text;
288 } else {
289 return '';
290 }
291 }
292
c7e3bc51 293 /**
294 * Tests if this block has been implemented correctly.
295 * Also, $errors isn't used right now
296 *
297 * @return boolean
298 */
4ca6cfbf 299
0f3fe4b6 300 function _self_test() {
301 // Tests if this block has been implemented correctly.
302 // Also, $errors isn't used right now
303 $errors = array();
304
305 $correct = true;
c7e3bc51 306 if ($this->get_title() === NULL) {
0f3fe4b6 307 $errors[] = 'title_not_set';
308 $correct = false;
309 }
7d2a0492 310 if (!in_array($this->get_content_type(), array(BLOCK_TYPE_LIST, BLOCK_TYPE_TEXT, BLOCK_TYPE_TREE))) {
0f3fe4b6 311 $errors[] = 'invalid_content_type';
312 $correct = false;
313 }
4ca6cfbf 314 //following selftest was not working when roles&capabilities were used from block
35a518c5 315/* if ($this->get_content() === NULL) {
0f3fe4b6 316 $errors[] = 'content_not_set';
317 $correct = false;
35a518c5 318 }*/
2b0d60ec 319 $formats = $this->applicable_formats();
c7e3bc51 320 if (empty($formats) || array_sum($formats) === 0) {
8a47e075 321 $errors[] = 'no_formats';
0f3fe4b6 322 $correct = false;
323 }
2b0d60ec 324
0f3fe4b6 325 $width = $this->preferred_width();
c7e3bc51 326 if (!is_int($width) || $width <= 0) {
0f3fe4b6 327 $errors[] = 'invalid_width';
328 $correct = false;
329 }
330 return $correct;
331 }
332
c7e3bc51 333 /**
334 * Subclasses should override this and return true if the
335 * subclass block has a config_global.html file.
336 *
337 * @return boolean
338 */
0f3fe4b6 339 function has_config() {
340 return false;
341 }
c7e3bc51 342
c7e3bc51 343 /**
344 * Default behavior: save all variables as $CFG properties
345 * You don't need to override this if you 're satisfied with the above
346 *
f8582e3e 347 * @param array $data
c7e3bc51 348 * @return boolean
349 */
f8582e3e 350 function config_save($data) {
f8582e3e 351 foreach ($data as $name => $value) {
9b4b78fd 352 set_config($name, $value);
353 }
354 return true;
0f3fe4b6 355 }
4ca6cfbf 356
c7e3bc51 357 /**
40928036 358 * Which page types this block may appear on.
359 *
360 * The information returned here is processed by the
361 * {@link blocks_name_allowed_in_format()} function. Look there if you need
362 * to know exactly how this works.
363 *
364 * Default case: everything except mod and tag.
365 *
366 * @return array page-type prefix => true/false.
c7e3bc51 367 */
0f3fe4b6 368 function applicable_formats() {
d232b8c7 369 // Default case: the block can be used in courses and site index, but not in activities
9591bc3c 370 return array('all' => true, 'mod' => false, 'tag' => false);
0f3fe4b6 371 }
4ca6cfbf 372
c7e3bc51 373
c7e3bc51 374 /**
375 * Default return is false - header will be shown
376 * @return boolean
377 */
0f3fe4b6 378 function hide_header() {
0f3fe4b6 379 return false;
380 }
c7e3bc51 381
382 /**
d4a03c00 383 * Return any HTML attributes that you want added to the outer <div> that
384 * of the block when it is output.
7d2a0492 385 *
386 * Because of the way certain JS events are wired it is a good idea to ensure
387 * that the default values here still get set.
388 * I found the easiest way to do this and still set anything you want is to
389 * override it within your block in the following way
390 *
391 * <code php>
392 * function html_attributes() {
393 * $attributes = parent::html_attributes();
394 * $attributes['class'] .= ' mynewclass';
395 * return $attributes;
396 * }
397 * </code>
398 *
d4a03c00 399 * @return array attribute name => value.
c7e3bc51 400 */
c5507e52 401 function html_attributes() {
9d897331 402 $attributes = array(
4ca6cfbf 403 'id' => 'inst' . $this->instance->id,
697f7bd7
SH
404 'class' => 'block_' . $this->name(). ' block',
405 'role' => $this->get_aria_role()
2f747639 406 );
d2c394f3 407 if ($this->instance_can_be_docked() && get_user_preferences('docked_block_instance_'.$this->instance->id, 0)) {
9d897331
SH
408 $attributes['class'] .= ' dock_on_load';
409 }
410 return $attributes;
c5507e52 411 }
d4a03c00 412
c7e3bc51 413 /**
40928036 414 * Set up a particular instance of this class given data from the block_insances
4ca6cfbf 415 * table and the current page. (See {@link block_manager::load_blocks()}.)
40928036 416 *
417 * @param stdClass $instance data from block_insances, block_positions, etc.
418 * @param moodle_page $the page this block is on.
c7e3bc51 419 */
3179b000 420 function _load_instance($instance, $page) {
c7e3bc51 421 if (!empty($instance->configdata)) {
9b4b78fd 422 $this->config = unserialize(base64_decode($instance->configdata));
423 }
9b4b78fd 424 $this->instance = $instance;
fe2fdd11 425 $this->context = context_block::instance($instance->id);
3179b000 426 $this->page = $page;
9b4b78fd 427 $this->specialization();
9d897331
SH
428 }
429
430 function get_required_javascript() {
46de77b6 431 if ($this->instance_can_be_docked() && !$this->hide_header()) {
53fc3e70 432 $this->page->requires->js_init_call('M.core_dock.init_genericblock', array($this->instance->id));
9d897331
SH
433 user_preference_allow_ajax_update('docked_block_instance_'.$this->instance->id, PARAM_INT);
434 }
9b4b78fd 435 }
59b29207 436
43038ce6 437 /**
438 * This function is called on your subclass right after an instance is loaded
439 * Use this function to act on instance data just after it's loaded and before anything else is done
67677908 440 * For instance: if your block will have different title's depending on location (site, course, blog, etc)
43038ce6 441 */
9b4b78fd 442 function specialization() {
443 // Just to make sure that this method exists.
9b4b78fd 444 }
445
c7e3bc51 446 /**
f032aa7a 447 * Is each block of this type going to have instance-specific configuration?
40928036 448 * Normally, this setting is controlled by {@link instance_allow_multiple()}: if multiple
f032aa7a 449 * instances are allowed, then each will surely need its own configuration. However, in some
450 * cases it may be necessary to provide instance configuration to blocks that do not want to
451 * allow multiple instances. In that case, make this function return true.
40928036 452 * I stress again that this makes a difference ONLY if {@link instance_allow_multiple()} returns false.
f032aa7a 453 * @return boolean
f032aa7a 454 */
455 function instance_allow_config() {
456 return false;
457 }
458
459 /**
460 * Are you going to allow multiple instances of each block?
c7e3bc51 461 * If yes, then it is assumed that the block WILL USE per-instance configuration
462 * @return boolean
c7e3bc51 463 */
9b4b78fd 464 function instance_allow_multiple() {
465 // Are you going to allow multiple instances of each block?
466 // If yes, then it is assumed that the block WILL USE per-instance configuration
467 return false;
468 }
59b29207 469
c7e3bc51 470 /**
471 * Default behavior: print the config_instance.html file
472 * You don't need to override this if you're satisfied with the above
473 *
40928036 474 * @deprecated since Moodle 2.0.
475 * @return boolean whether anything was done. Blocks should use edit_form.php.
c7e3bc51 476 */
9b4b78fd 477 function instance_config_print() {
25c56af8 478 global $CFG, $DB, $OUTPUT;
9b4b78fd 479 // Default behavior: print the config_instance.html file
e1b8bdf8 480 // You don't need to override this if you're satisfied with the above
f032aa7a 481 if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
9b4b78fd 482 return false;
483 }
9b4b78fd 484
c7e3bc51 485 if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
25c56af8 486 echo $OUTPUT->box_start('generalbox boxaligncenter blockconfiginstance');
6195e04a 487 include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
25c56af8 488 echo $OUTPUT->box_end();
6195e04a 489 } else {
9b4b78fd 490 notice(get_string('blockconfigbad'), str_replace('blockaction=', 'dummy=', qualified_me()));
491 }
40928036 492
9b4b78fd 493 return true;
494 }
c7e3bc51 495
496 /**
497 * Serialize and store config data
c7e3bc51 498 */
f474a4e5 499 function instance_config_save($data, $nolongerused = false) {
a5d424df 500 global $DB;
f474a4e5 501 $DB->set_field('block_instances', 'configdata', base64_encode(serialize($data)),
e03c0c1d 502 array('id' => $this->instance->id));
9b4b78fd 503 }
504
0144a0a7 505 /**
506 * Replace the instance's configuration data with those currently in $this->config;
0144a0a7 507 */
f474a4e5 508 function instance_config_commit($nolongerused = false) {
a5d424df 509 global $DB;
f474a4e5 510 $this->instance_config_save($this->config);
0144a0a7 511 }
512
d4a03c00 513 /**
b33dd23a 514 * Do any additional initialization you may need at the time a new block instance is created
515 * @return boolean
b33dd23a 516 */
517 function instance_create() {
518 return true;
519 }
520
d4a03c00 521 /**
b33dd23a 522 * Delete everything related to this instance if you have been using persistent storage other than the configdata field.
523 * @return boolean
b33dd23a 524 */
525 function instance_delete() {
526 return true;
527 }
528
d4a03c00 529 /**
11306331 530 * Allows the block class to have a say in the user's ability to edit (i.e., configure) blocks of this type.
531 * The framework has first say in whether this will be allowed (e.g., no editing allowed unless in edit mode)
532 * but if the framework does allow it, the block can still decide to refuse.
533 * @return boolean
11306331 534 */
535 function user_can_edit() {
03d9401e
MD
536 global $USER;
537
538 if (has_capability('moodle/block:edit', $this->context)) {
539 return true;
540 }
541
542 // The blocks in My Moodle are a special case. We want them to inherit from the user context.
543 if (!empty($USER->id)
544 && $this->instance->parentcontextid == $this->page->context->id // Block belongs to this page
545 && $this->page->context->contextlevel == CONTEXT_USER // Page belongs to a user
546 && $this->page->context->instanceid == $USER->id) { // Page belongs to this user
547 return has_capability('moodle/my:manageblocks', $this->page->context);
548 }
549
550 return false;
11306331 551 }
552
d4a03c00 553 /**
11306331 554 * Allows the block class to have a say in the user's ability to create new instances of this block.
555 * The framework has first say in whether this will be allowed (e.g., no adding allowed unless in edit mode)
556 * but if the framework does allow it, the block can still decide to refuse.
557 * This function has access to the complete page object, the creation related to which is being determined.
10a92c39
SH
558 *
559 * @param moodle_page $page
11306331 560 * @return boolean
11306331 561 */
15a00b4b 562 function user_can_addto($page) {
03d9401e
MD
563 global $USER;
564
03d9401e
MD
565 // The blocks in My Moodle are a special case and use a different capability.
566 if (!empty($USER->id)
b291b59d 567 && $page->context->contextlevel == CONTEXT_USER // Page belongs to a user
9b06b507
MN
568 && $page->context->instanceid == $USER->id // Page belongs to this user
569 && $page->pagetype == 'my-index') { // Ensure we are on the My Moodle page
b291b59d
MN
570 $capability = 'block/' . $this->name() . ':myaddinstance';
571 return $this->has_add_block_capability($page, $capability)
572 && has_capability('moodle/my:manageblocks', $page->context);
03d9401e
MD
573 }
574
464e00be
MN
575 $capability = 'block/' . $this->name() . ':addinstance';
576 if ($this->has_add_block_capability($page, $capability)
577 && has_capability('moodle/block:edit', $page->context)) {
578 return true;
579 }
580
03d9401e 581 return false;
11306331 582 }
583
b291b59d
MN
584 /**
585 * Returns true if the user can add a block to a page.
586 *
587 * @param moodle_page $page
588 * @param string $capability the capability to check
589 * @return boolean true if user can add a block, false otherwise.
590 */
591 private function has_add_block_capability($page, $capability) {
592 // Check if the capability exists.
593 if (!get_capability_info($capability)) {
594 // Debug warning that the capability does not exist, but no more than once per page.
595 static $warned = array();
596 if (!isset($warned[$this->name()])) {
597 debugging('The block ' .$this->name() . ' does not define the standard capability ' .
598 $capability , DEBUG_DEVELOPER);
599 $warned[$this->name()] = 1;
600 }
601 // If the capability does not exist, the block can always be added.
602 return true;
603 } else {
604 return has_capability($capability, $page->context);
605 }
606 }
607
324d210f 608 static function get_extra_capabilities() {
d14edf06 609 return array('moodle/block:view', 'moodle/block:edit');
f432bebf 610 }
d4a03c00 611
612 // Methods deprecated in Moodle 2.0 ========================================
613
614 /**
615 * Default case: the block wants to be 180 pixels wide
616 * @deprecated since Moodle 2.0.
617 * @return int
618 */
619 function preferred_width() {
620 return 180;
621 }
622
623 /** @deprecated since Moodle 2.0. */
624 function _print_block() {
625 throw new coding_exception('_print_block is no longer used. It was a private ' .
626 'method of the block class, only for use by the blocks system. You ' .
627 'should not have been calling it anyway.');
628 }
629
630 /** @deprecated since Moodle 2.0. */
631 function _print_shadow() {
632 throw new coding_exception('_print_shadow is no longer used. It was a private ' .
633 'method of the block class, only for use by the blocks system. You ' .
634 'should not have been calling it anyway.');
635 }
636
637 /** @deprecated since Moodle 2.0. */
638 function _title_html() {
639 throw new coding_exception('_title_html is no longer used. It was a private ' .
640 'method of the block class, only for use by the blocks system. You ' .
641 'should not have been calling it anyway.');
642 }
643
644 /** @deprecated since Moodle 2.0. */
645 function _add_edit_controls() {
646 throw new coding_exception('_add_edit_controls is no longer used. It was a private ' .
647 'method of the block class, only for use by the blocks system. You ' .
648 'should not have been calling it anyway.');
649 }
650
7cf51142 651 /** @deprecated since Moodle 2.0. */
652 function config_print() {
653 throw new coding_exception('config_print() can no longer be used. Blocks should use a settings.php file.');
654 }
9d897331 655
d8ef60bd
SH
656 /**
657 * Can be overridden by the block to prevent the block from being dockable.
9c14c1c5 658 *
d8ef60bd
SH
659 * @return bool
660 */
d2c394f3
SH
661 public function instance_can_be_docked() {
662 global $CFG;
598ee317 663 return (!empty($CFG->allowblockstodock) && $this->page->theme->enable_dock);
9d897331
SH
664 }
665
d8ef60bd 666 /**
0885166f 667 * If overridden and set to false by the block it will not be hidable when
d8ef60bd
SH
668 * editing is turned on.
669 *
670 * @return bool
671 */
672 public function instance_can_be_hidden() {
673 return true;
674 }
675
0885166f
JC
676 /**
677 * If overridden and set to false by the block it will not be collapsible.
678 *
679 * @return bool
680 */
681 public function instance_can_be_collapsed() {
682 return true;
683 }
684
1bcb7eb5 685 /** @callback callback functions for comments api */
686 public static function comment_template($options) {
687 $ret = <<<EOD
4ca6cfbf 688<div class="comment-userpicture">___picture___</div>
1bcb7eb5 689<div class="comment-content">
690 ___name___ - <span>___time___</span>
691 <div>___content___</div>
692</div>
693EOD;
694 return $ret;
695 }
696 public static function comment_permissions($options) {
697 return array('view'=>true, 'post'=>true);
698 }
699 public static function comment_url($options) {
700 return null;
701 }
a0e68ffc
DC
702 public static function comment_display($comments, $options) {
703 return $comments;
1bcb7eb5 704 }
705 public static function comment_add(&$comments, $options) {
706 return true;
707 }
697f7bd7
SH
708
709 /**
710 * Returns the aria role attribute that best describes this block.
711 *
712 * Region is the default, but this should be overridden by a block is there is a region child, or even better
713 * a landmark child.
714 *
715 * Options are as follows:
697f7bd7
SH
716 * - landmark
717 * - application
718 * - banner
719 * - complementary
720 * - contentinfo
721 * - form
722 * - main
723 * - navigation
724 * - search
697f7bd7
SH
725 *
726 * @return string
727 */
728 public function get_aria_role() {
5c4581fc 729 return 'complementary';
697f7bd7 730 }
0f3fe4b6 731}
732
c7e3bc51 733/**
3ef642d9 734 * Specialized class for displaying a block with a list of icons/text labels
735 *
d4a03c00 736 * The get_content method should set $this->content->items and (optionally)
737 * $this->content->icons, instead of $this->content->text.
738 *
3ef642d9 739 * @author Jon Papaioannou
740 * @package blocks
741 */
742
743class block_list extends block_base {
744 var $content_type = BLOCK_TYPE_LIST;
745
746 function is_empty() {
e92c286c 747 if ( !has_capability('moodle/block:view', $this->context) ) {
25a7d980 748 return true;
749 }
750
3ef642d9 751 $this->get_content();
752 return (empty($this->content->items) && empty($this->content->footer));
753 }
754
d4a03c00 755 protected function formatted_contents($output) {
756 $this->get_content();
dde36f9d 757 $this->get_required_javascript();
d4a03c00 758 if (!empty($this->content->items)) {
759 return $output->list_block_contents($this->content->icons, $this->content->items);
3ef642d9 760 } else {
d4a03c00 761 return '';
3ef642d9 762 }
763 }
740952e4
SH
764
765 function html_attributes() {
766 $attributes = parent::html_attributes();
767 $attributes['class'] .= ' list_block';
768 return $attributes;
769 }
770
3ef642d9 771}
772
7d2a0492 773/**
774 * Specialized class for displaying a tree menu.
4ca6cfbf 775 *
7d2a0492 776 * The {@link get_content()} method involves setting the content of
777 * <code>$this->content->items</code> with an array of {@link tree_item}
778 * objects (these are the top-level nodes). The {@link tree_item::children}
779 * property may contain more tree_item objects, and so on. The tree_item class
780 * itself is abstract and not intended for use, use one of it's subclasses.
4ca6cfbf 781 *
7d2a0492 782 * Unlike {@link block_list}, the icons are specified as part of the items,
783 * not in a separate array.
784 *
785 * @author Alan Trick
786 * @package blocks
787 * @internal this extends block_list so we get is_empty() for free
788 */
789class block_tree extends block_list {
4ca6cfbf 790
7d2a0492 791 /**
792 * @var int specifies the manner in which contents should be added to this
793 * block type. In this case <code>$this->content->items</code> is used with
794 * {@link tree_item}s.
795 */
796 public $content_type = BLOCK_TYPE_TREE;
4ca6cfbf 797
7d2a0492 798 /**
799 * Make the formatted HTML ouput.
4ca6cfbf 800 *
7d2a0492 801 * Also adds the required javascript call to the page output.
802 *
78946b9b 803 * @param core_renderer $output
7d2a0492 804 * @return string HTML
805 */
806 protected function formatted_contents($output) {
807 // based of code in admin_tree
808 global $PAGE; // TODO change this when there is a proper way for blocks to get stuff into head.
809 static $eventattached;
810 if ($eventattached===null) {
811 $eventattached = true;
812 }
813 if (!$this->content) {
814 $this->content = new stdClass;
815 $this->content->items = array();
816 }
d5cbccb3 817 $this->get_required_javascript();
7d2a0492 818 $this->get_content();
1ce15fda 819 $content = $output->tree_block_contents($this->content->items,array('class'=>'block_tree list'));
7d2a0492 820 if (isset($this->id) && !is_numeric($this->id)) {
821 $content = $output->box($content, 'block_tree_box', $this->id);
822 }
823 return $content;
824 }
a0e68ffc 825}