Adding a little more checking to the session switching trap code.
[moodle.git] / blocks / moodleblock.class.php
CommitLineData
56e29ea0 1<?php // $Id$
0f3fe4b6 2
c7e3bc51 3/**
67677908 4 * This file contains the parent class for moodle blocks, block_base,
5 * as well as the block_nuke subclass.
c7e3bc51 6 *
7 * @author Jon Papaioannou
8 * @version $Id$
9 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
10 * @package blocks
11 */
12
13/// Constants
14
15/**
16 * 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.
17 */
0f3fe4b6 18define('BLOCK_TYPE_LIST', 1);
c7e3bc51 19
20/**
21 * 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.
22 */
0f3fe4b6 23define('BLOCK_TYPE_TEXT', 2);
c7e3bc51 24
25/**
26 * Block type of nuke. Compitibility with post nuke blocks. Basically treated as BLOCK_TYPE_TEXT.
27 */
828c4e09 28define('BLOCK_TYPE_NUKE', 3);
0f3fe4b6 29
c7e3bc51 30/**
e0134f84 31 * Class for describing a moodle block, all Moodle blocks derive from this class
c7e3bc51 32 *
33 * @author Jon Papaioannou
34 * @package blocks
35 */
e89d741a 36class block_base {
c7e3bc51 37
38 /**
39 * Internal var for storing/caching translated strings
40 * @var string $str
41 */
0f3fe4b6 42 var $str;
c7e3bc51 43
44 /**
f8582e3e 45 * The title of the block to be displayed in the block title area.
c7e3bc51 46 * @var string $title
47 */
9b4b78fd 48 var $title = NULL;
c7e3bc51 49
c7e3bc51 50 /**
51 * The type of content that this block creates. Currently support options - BLOCK_TYPE_LIST, BLOCK_TYPE_TEXT, BLOCK_TYPE_NUKE
52 * @var int $content_type
53 */
3ef642d9 54 var $content_type = BLOCK_TYPE_TEXT;
c7e3bc51 55
56 /**
57 * An object to contain the information to be displayed in the block.
58 * @var stdObject $content
59 */
9b4b78fd 60 var $content = NULL;
c7e3bc51 61
62 /**
1345403a 63 * A string generated by {@link _add_edit_controls()} to display block manipulation links when the user is in editing mode.
c7e3bc51 64 * @var string $edit_controls
65 */
0f3fe4b6 66 var $edit_controls = NULL;
c7e3bc51 67
68 /**
69 * The current version that the block type defines.
70 * @var string $version
71 */
9b4b78fd 72 var $version = NULL;
c7e3bc51 73
74 /**
75 * The initialized instance of this block object.
76 * @var block $instance
77 */
9b4b78fd 78 var $instance = NULL;
c7e3bc51 79
80 /**
81 * An object containing the instance configuration information for the current instance of this block.
82 * @var stdObject $config
83 */
9b4b78fd 84 var $config = NULL;
85
c7e3bc51 86
e0134f84 87/// Class Functions
c7e3bc51 88
89 /**
90 * The class constructor
91 *
92 */
e89d741a 93 function block_base() {
9b4b78fd 94 $this->init();
95 }
0f3fe4b6 96
73554752 97 /**
98 * Fake constructor to keep PHP5 happy
99 *
100 */
101 function __construct() {
e89d741a 102 $this->block_base();
73554752 103 }
104
c7e3bc51 105 /**
106 * Returns the block name, as present in the class name,
107 * the database, the block directory, etc etc.
108 *
109 * @return string
110 */
0f3fe4b6 111 function name() {
112 // Returns the block name, as present in the class name,
113 // the database, the block directory, etc etc.
114 static $myname;
c7e3bc51 115 if ($myname === NULL) {
0f3fe4b6 116 $myname = strtolower(get_class($this));
117 $myname = substr($myname, strpos($myname, '_') + 1);
118 }
119 return $myname;
120 }
121
c7e3bc51 122 /**
123 * Parent class version of this function simply returns NULL
124 * This should be implemented by the derived class to return
125 * the content object.
126 *
127 * @return stdObject
128 */
0f3fe4b6 129 function get_content() {
130 // This should be implemented by the derived class.
131 return NULL;
132 }
c7e3bc51 133
134 /**
135 * Returns the class $title var value.
136 *
137 * Intentionally doesn't check if a title is set.
138 * This is already done in {@link _self_test()}
139 *
140 * @return string $this->title
141 */
0f3fe4b6 142 function get_title() {
6195e04a 143 // Intentionally doesn't check if a title is set. This is already done in _self_test()
0f3fe4b6 144 return $this->title;
145 }
c7e3bc51 146
147 /**
148 * Returns the class $content_type var value.
149 *
150 * Intentionally doesn't check if content_type is set.
151 * This is already done in {@link _self_test()}
152 *
153 * @return string $this->content_type
154 */
0f3fe4b6 155 function get_content_type() {
6195e04a 156 // Intentionally doesn't check if a content_type is set. This is already done in _self_test()
0f3fe4b6 157 return $this->content_type;
158 }
c7e3bc51 159
160 /**
161 * Returns the class $version var value.
162 *
163 * Intentionally doesn't check if a version is set.
164 * This is already done in {@link _self_test()}
165 *
166 * @return string $this->version
167 */
0f3fe4b6 168 function get_version() {
6195e04a 169 // Intentionally doesn't check if a version is set. This is already done in _self_test()
0f3fe4b6 170 return $this->version;
171 }
c7e3bc51 172
3ef642d9 173 /**
174 * Returns true or false, depending on whether this block has any content to display
175 *
176 * @return boolean
177 */
178 function is_empty() {
179 $this->get_content();
180 return(empty($this->content->text) && empty($this->content->footer));
181 }
182
c7e3bc51 183 /**
184 * First sets the current value of $this->content to NULL
185 * then calls the block's {@link get_content()} function
186 * to set its value back.
187 *
188 * @return stdObject
189 */
0f3fe4b6 190 function refresh_content() {
191 // Nothing special here, depends on content()
192 $this->content = NULL;
193 return $this->get_content();
194 }
c7e3bc51 195
196 /**
197 * Display the block!
198 */
1345403a 199 function _print_block() {
3ef642d9 200 // is_empty() includes a call to get_content()
201 if ($this->is_empty()) {
202 if (empty($this->edit_controls)) {
203 // No content, no edit controls, so just shut up
76a8339a 204 return;
3ef642d9 205 } else {
206 // No content but editing, so show something at least
207 $this->_print_shadow();
208 }
209 } else {
210 if ($this->hide_header() && empty($this->edit_controls)) {
211 // Header wants to hide, no edit controls to show, so no header it is
212 print_side_block(NULL, $this->content->text, NULL, NULL, $this->content->footer, $this->html_attributes());
213 } else {
214 // The full treatment, please
c4d951e1 215 print_side_block($this->_title_html(), $this->content->text, NULL, NULL, $this->content->footer, $this->html_attributes());
3ef642d9 216 }
0f3fe4b6 217 }
218 }
c7e3bc51 219
220 /**
221 * Block contents are missing. Simply display an empty block so that
222 * edit controls are accessbile to the user and they are aware that this
223 * block is in place, even if empty.
224 */
1345403a 225 function _print_shadow() {
c4d951e1 226 print_side_block($this->_title_html(), '&nbsp;', NULL, NULL, '', array('class' => 'hidden'));
227 }
228
229
230 function _title_html() {
231 global $CFG;
232
233 $title = '<div class="title">';
234
235 if (!empty($CFG->allowuserblockhiding)) {
236 $title .= '<div class="hide-show"><a href="#" onclick="elementToggleHide(this, true, function(el) {return findParentNode(el, \'DIV\', \'sideblock\'); } ); return false;"><img src="'.$CFG->pixpath.'/spacer.gif" alt="" class="hide-show-image" /></a></div>';
237 }
238
239 $title .= $this->title;
240
c7e3bc51 241 if ($this->edit_controls !== NULL) {
0f3fe4b6 242 $title .= $this->edit_controls;
243 }
c4d951e1 244
245 $title .= '</div>';
246
247 return $title;
0f3fe4b6 248 }
89adb174 249
c7e3bc51 250 /**
251 * Sets class $edit_controls var with correct block manipulation links.
252 *
253 * @uses $CFG
c7e3bc51 254 * @uses $USER
255 * @param stdObject $options ?
256 * @todo complete documenting this function. Define $options.
257 */
1345403a 258 function _add_edit_controls($options) {
0705dcc0 259 global $CFG, $USER;
0f3fe4b6 260
0f3fe4b6 261 if (!isset($this->str)) {
262 $this->str->delete = get_string('delete');
263 $this->str->moveup = get_string('moveup');
264 $this->str->movedown = get_string('movedown');
265 $this->str->moveright = get_string('moveright');
266 $this->str->moveleft = get_string('moveleft');
267 $this->str->hide = get_string('hide');
268 $this->str->show = get_string('show');
9b4b78fd 269 $this->str->configure = get_string('configuration');
0f3fe4b6 270 }
271
96803c88 272 $movebuttons = '<div class="commands">';
0f3fe4b6 273
c7e3bc51 274 if ($this->instance->visible) {
0f3fe4b6 275 $icon = '/t/hide.gif';
276 $title = $this->str->hide;
c7e3bc51 277 } else {
0f3fe4b6 278 $icon = '/t/show.gif';
279 $title = $this->str->show;
280 }
281
9b128500 282 $page = page_create_object($this->instance->pagetype, $this->instance->pageid);
f032aa7a 283 $script = $page->url_get_full(array('instanceid' => $this->instance->id, 'sesskey' => $USER->sesskey));
9b4b78fd 284
5a46b156 285 $movebuttons .= '<a class="icon hide" title="'. $title .'" href="'.$script.'&amp;blockaction=toggle">' .
0705dcc0 286 '<img src="'. $CFG->pixpath.$icon .'" alt="'.$title.'" /></a>';
0f3fe4b6 287
c7e3bc51 288 if ($options & BLOCK_CONFIGURE) {
5a46b156 289 $movebuttons .= '<a class="icon edit" title="'. $this->str->configure .'" href="'.$script.'&amp;blockaction=config">' .
0705dcc0 290 '<img src="'. $CFG->pixpath .'/t/edit.gif" alt="'. $this->str->configure .'" /></a>';
9b4b78fd 291 }
292
5a46b156 293 $movebuttons .= '<a class="icon delete" title="'. $this->str->delete .'" href="'.$script.'&amp;blockaction=delete">' .
294 '<img src="'. $CFG->pixpath .'/t/delete.gif" alt="'. $this->str->delete .'" /></a>';
0f3fe4b6 295
296 if ($options & BLOCK_MOVE_LEFT) {
5a46b156 297 $movebuttons .= '<a class="icon left" title="'. $this->str->moveleft .'" href="'.$script.'&amp;blockaction=moveleft">' .
0705dcc0 298 '<img src="'. $CFG->pixpath .'/t/left.gif" alt="'. $this->str->moveleft .'" /></a>';
0f3fe4b6 299 }
300 if ($options & BLOCK_MOVE_UP) {
5a46b156 301 $movebuttons .= '<a class="icon up" title="'. $this->str->moveup .'" href="'.$script.'&amp;blockaction=moveup">' .
0705dcc0 302 '<img src="'. $CFG->pixpath .'/t/up.gif" alt="'. $this->str->moveup .'" /></a>';
0f3fe4b6 303 }
304 if ($options & BLOCK_MOVE_DOWN) {
5a46b156 305 $movebuttons .= '<a class="icon down" title="'. $this->str->movedown .'" href="'.$script.'&amp;blockaction=movedown">' .
0705dcc0 306 '<img src="'. $CFG->pixpath .'/t/down.gif" alt="'. $this->str->movedown .'" /></a>';
0f3fe4b6 307 }
308 if ($options & BLOCK_MOVE_RIGHT) {
5a46b156 309 $movebuttons .= '<a class="icon right" title="'. $this->str->moveright .'" href="'.$script.'&amp;blockaction=moveright">' .
0705dcc0 310 '<img src="'. $CFG->pixpath .'/t/right.gif" alt="'. $this->str->moveright .'" /></a>';
0f3fe4b6 311 }
312
313 $movebuttons .= '</div>';
314 $this->edit_controls = $movebuttons;
315 }
316
c7e3bc51 317 /**
318 * Tests if this block has been implemented correctly.
319 * Also, $errors isn't used right now
320 *
321 * @return boolean
322 */
323
0f3fe4b6 324 function _self_test() {
325 // Tests if this block has been implemented correctly.
326 // Also, $errors isn't used right now
327 $errors = array();
328
329 $correct = true;
c7e3bc51 330 if ($this->get_title() === NULL) {
0f3fe4b6 331 $errors[] = 'title_not_set';
332 $correct = false;
333 }
c7e3bc51 334 if (!in_array($this->get_content_type(), array(BLOCK_TYPE_LIST, BLOCK_TYPE_TEXT, BLOCK_TYPE_NUKE))) {
0f3fe4b6 335 $errors[] = 'invalid_content_type';
336 $correct = false;
337 }
c7e3bc51 338 if ($this->get_content() === NULL) {
0f3fe4b6 339 $errors[] = 'content_not_set';
340 $correct = false;
341 }
c7e3bc51 342 if ($this->get_version() === NULL) {
0f3fe4b6 343 $errors[] = 'version_not_set';
344 $correct = false;
345 }
2b0d60ec 346
347 $formats = $this->applicable_formats();
c7e3bc51 348 if (empty($formats) || array_sum($formats) === 0) {
8a47e075 349 $errors[] = 'no_formats';
0f3fe4b6 350 $correct = false;
351 }
2b0d60ec 352
0f3fe4b6 353 $width = $this->preferred_width();
c7e3bc51 354 if (!is_int($width) || $width <= 0) {
0f3fe4b6 355 $errors[] = 'invalid_width';
356 $correct = false;
357 }
358 return $correct;
359 }
360
c7e3bc51 361 /**
362 * Subclasses should override this and return true if the
363 * subclass block has a config_global.html file.
364 *
365 * @return boolean
366 */
0f3fe4b6 367 function has_config() {
368 return false;
369 }
c7e3bc51 370
371 /**
372 * Default behavior: print the config_global.html file
373 * You don't need to override this if you're satisfied with the above
374 *
375 * @uses $CFG
c7e3bc51 376 * @return boolean
377 */
f8582e3e 378 function config_print() {
9b4b78fd 379 // Default behavior: print the config_global.html file
c7e3bc51 380 // You don't need to override this if you're satisfied with the above
381 if (!$this->has_config()) {
9b4b78fd 382 return false;
383 }
0705dcc0 384 global $CFG;
385 print_simple_box_start('center', '', '', 5, 'blockconfigglobal');
59b29207 386 include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
9b4b78fd 387 print_simple_box_end();
388 return true;
0f3fe4b6 389 }
59b29207 390
c7e3bc51 391 /**
392 * Default behavior: save all variables as $CFG properties
393 * You don't need to override this if you 're satisfied with the above
394 *
f8582e3e 395 * @param array $data
c7e3bc51 396 * @return boolean
397 */
f8582e3e 398 function config_save($data) {
9b4b78fd 399 // Default behavior: save all variables as $CFG properties
400 // You don't need to override this if you 're satisfied with the above
f8582e3e 401 foreach ($data as $name => $value) {
9b4b78fd 402 set_config($name, $value);
403 }
404 return true;
0f3fe4b6 405 }
59b29207 406
c7e3bc51 407 /**
408 * Default case: the block can be used in all course types
409 * @return array
410 * @todo finish documenting this function
411 */
0f3fe4b6 412 function applicable_formats() {
d232b8c7 413 // Default case: the block can be used in courses and site index, but not in activities
8a47e075 414 return array('all' => true, 'mod' => false);
0f3fe4b6 415 }
59b29207 416
c7e3bc51 417
418 /**
419 * Default case: the block wants to be 180 pixels wide
420 * @return int
421 */
0f3fe4b6 422 function preferred_width() {
423 // Default case: the block wants to be 180 pixels wide
424 return 180;
425 }
59b29207 426
c7e3bc51 427 /**
428 * Default return is false - header will be shown
429 * @return boolean
430 */
0f3fe4b6 431 function hide_header() {
4e60e777 432 //Default, false--> the header is shown
0f3fe4b6 433 return false;
434 }
c7e3bc51 435
436 /**
437 * Default case: just an id for the block, with our name in it
438 * @return array
439 * @todo finish documenting this function
440 */
c5507e52 441 function html_attributes() {
d232b8c7 442 // Default case: an id with the instance and a class with our name in it
29ba5158 443 return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
c5507e52 444 }
59b29207 445
c7e3bc51 446 /**
447 * Given an instance set the class var $instance to it and
448 * load class var $config
449 * @param block $instance
450 * @todo add additional documentation to further explain the format of instance and config
451 */
1345403a 452 function _load_instance($instance) {
c7e3bc51 453 if (!empty($instance->configdata)) {
9b4b78fd 454 $this->config = unserialize(base64_decode($instance->configdata));
455 }
673c1b2f 456 // [pj] This line below is supposed to be an optimization (we don't need configdata anymore)
457 // but what it does is break in PHP5 because the same instance object will be passed to
458 // this function twice in each page view, and the second time it won't have any configdata
459 // so it won't work correctly. Thus it's commented out.
460 // unset($instance->configdata);
9b4b78fd 461 $this->instance = $instance;
462 $this->specialization();
463 }
59b29207 464
43038ce6 465 /**
466 * This function is called on your subclass right after an instance is loaded
467 * Use this function to act on instance data just after it's loaded and before anything else is done
67677908 468 * For instance: if your block will have different title's depending on location (site, course, blog, etc)
43038ce6 469 */
9b4b78fd 470 function specialization() {
471 // Just to make sure that this method exists.
9b4b78fd 472 }
473
c7e3bc51 474 /**
f032aa7a 475 * Is each block of this type going to have instance-specific configuration?
476 * Normally, this setting is controlled by {@link instance_allow_multiple}: if multiple
477 * instances are allowed, then each will surely need its own configuration. However, in some
478 * cases it may be necessary to provide instance configuration to blocks that do not want to
479 * allow multiple instances. In that case, make this function return true.
480 * I stress again that this makes a difference ONLY if {@link instance_allow_multiple} returns false.
481 * @return boolean
482 * @todo finish documenting this function by explaining per-instance configuration further
483 */
484 function instance_allow_config() {
485 return false;
486 }
487
488 /**
489 * Are you going to allow multiple instances of each block?
c7e3bc51 490 * If yes, then it is assumed that the block WILL USE per-instance configuration
491 * @return boolean
492 * @todo finish documenting this function by explaining per-instance configuration further
493 */
9b4b78fd 494 function instance_allow_multiple() {
495 // Are you going to allow multiple instances of each block?
496 // If yes, then it is assumed that the block WILL USE per-instance configuration
497 return false;
498 }
59b29207 499
c7e3bc51 500 /**
501 * Default behavior: print the config_instance.html file
502 * You don't need to override this if you're satisfied with the above
503 *
504 * @uses $CFG
c7e3bc51 505 * @return boolean
506 * @todo finish documenting this function
507 */
9b4b78fd 508 function instance_config_print() {
509 // Default behavior: print the config_instance.html file
e1b8bdf8 510 // You don't need to override this if you're satisfied with the above
f032aa7a 511 if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
9b4b78fd 512 return false;
513 }
0705dcc0 514 global $CFG;
9b4b78fd 515
c7e3bc51 516 if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
0705dcc0 517 print_simple_box_start('center', '', '', 5, 'blockconfiginstance');
6195e04a 518 include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
9b4b78fd 519 print_simple_box_end();
6195e04a 520 } else {
9b4b78fd 521 notice(get_string('blockconfigbad'), str_replace('blockaction=', 'dummy=', qualified_me()));
522 }
523
524 return true;
525 }
c7e3bc51 526
527 /**
528 * Serialize and store config data
529 * @return boolean
530 * @todo finish documenting this function
531 */
9b4b78fd 532 function instance_config_save($data) {
533 $data = stripslashes_recursive($data);
534 $this->config = $data;
535 return set_field('block_instance', 'configdata', base64_encode(serialize($data)), 'id', $this->instance->id);
536 }
537
0144a0a7 538 /**
539 * Replace the instance's configuration data with those currently in $this->config;
540 * @return boolean
541 * @todo finish documenting this function
542 */
543 function instance_config_commit() {
544 return set_field('block_instance', 'configdata', base64_encode(serialize($this->config)), 'id', $this->instance->id);
545 }
546
0f3fe4b6 547}
548
c7e3bc51 549/**
3ef642d9 550 * Specialized class for displaying a block with a list of icons/text labels
551 *
552 * @author Jon Papaioannou
553 * @package blocks
554 */
555
556class block_list extends block_base {
557 var $content_type = BLOCK_TYPE_LIST;
558
559 function is_empty() {
560 $this->get_content();
561 return (empty($this->content->items) && empty($this->content->footer));
562 }
563
564 function _print_block() {
3ef642d9 565 // is_empty() includes a call to get_content()
566 if ($this->is_empty()) {
567 if (empty($this->edit_controls)) {
568 // No content, no edit controls, so just shut up
76a8339a 569 return;
3ef642d9 570 } else {
571 // No content but editing, so show something at least
572 $this->_print_shadow();
573 }
574 } else {
575 if ($this->hide_header() && empty($this->edit_controls)) {
576 // Header wants to hide, no edit controls to show, so no header it is
577 print_side_block(NULL, '', $this->content->items, $this->content->icons, $this->content->footer, $this->html_attributes());
578 } else {
579 // The full treatment, please
c4d951e1 580 print_side_block($this->_title_html(), '', $this->content->items, $this->content->icons, $this->content->footer, $this->html_attributes());
3ef642d9 581 }
582 }
583 }
584
585}
586
587/**
588 * Class for supporting a phpnuke style block as a moodle block
c7e3bc51 589 *
590 * @author Jon Papaioannou
591 * @package blocks
592 */
e89d741a 593class block_nuke extends block_base {
3ef642d9 594
595 var $content_type = BLOCK_TYPE_NUKE;
596
828c4e09 597 function get_content() {
598
c7e3bc51 599 if ($this->content !== NULL) {
d4950608 600 return $this->content;
601 }
828c4e09 602
603 global $CFG;
d4950608 604 $this->content = &New stdClass;
605
606 // This whole thing begs to be written for PHP >= 4.3.0 using glob();
59b29207 607 $dir = $CFG->dirroot .'/blocks/'. $this->name() .'/nuke/';
c7e3bc51 608 if ($dh = @opendir($dir)) {
828c4e09 609 while (($file = readdir($dh)) !== false) {
610 $regs = array();
c7e3bc51 611 if (ereg('^block\-(.*)\.php$', $file, $regs)) {
d4950608 612 // Found it! Let's prepare the environment...
828c4e09 613
d4950608 614 $oldvals = array();
c7e3bc51 615 if (isset($GLOBALS['admin'])) {
d4950608 616 $oldvals['admin'] = $GLOBALS['admin'];
617 }
618
619 $GLOBALS['admin'] = isteacher($this->course->id);
828c4e09 620 @include($dir.$file);
d4950608 621
622 foreach($oldvals as $key => $val) {
623 $GLOBALS[$key] = $val;
624 }
828c4e09 625
626 // We should have $content set now
c7e3bc51 627 if (!isset($content)) {
828c4e09 628 return NULL;
629 }
630 return $this->content->text = $content;
631 }
632 }
633 }
d4950608 634
635 // If we reached here, we couldn't find the nuke block for some reason
636 return $this->content->text = get_string('blockmissingnuke');
828c4e09 637 }
638}
639
73554752 640?>