Now scheduled backup emails set the priotity header if something was wrong.
[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 */
9b4b78fd 54 var $content_type = NULL;
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
c7e3bc51 173 /**
174 * First sets the current value of $this->content to NULL
175 * then calls the block's {@link get_content()} function
176 * to set its value back.
177 *
178 * @return stdObject
179 */
0f3fe4b6 180 function refresh_content() {
181 // Nothing special here, depends on content()
182 $this->content = NULL;
183 return $this->get_content();
184 }
c7e3bc51 185
186 /**
187 * Display the block!
188 */
1345403a 189 function _print_block() {
ca319818 190 // Wrap the title in a floating DIV, in case we have edit controls to display
191 // These controls will always be wrapped on a right-floating DIV
0f3fe4b6 192 $title = '<div style="float: left;">'.$this->title.'</div>';
c7e3bc51 193 if ($this->edit_controls !== NULL) {
0f3fe4b6 194 $title .= $this->edit_controls;
195 }
ca319818 196
0f3fe4b6 197 $this->get_content();
c7e3bc51 198 if (!isset($this->content->footer)) {
4153708f 199 $this->content->footer = '';
200 }
0f3fe4b6 201
202 switch($this->content_type) {
828c4e09 203 case BLOCK_TYPE_NUKE:
0f3fe4b6 204 case BLOCK_TYPE_TEXT:
c7e3bc51 205 if (empty($this->content->text) && empty($this->content->footer)) {
206 if (empty($this->edit_controls)) {
22931cf4 207 // No content, no edit controls, so just shut up
208 break;
c7e3bc51 209 } else {
22931cf4 210 // No content but editing, so show something at least
1345403a 211 $this->_print_shadow();
22931cf4 212 }
c7e3bc51 213 } else {
214 if ($this->hide_header() && empty($this->edit_controls)) {
22931cf4 215 // Header wants to hide, no edit controls to show, so no header it is
216 print_side_block(NULL, $this->content->text, NULL, NULL, $this->content->footer, $this->html_attributes());
c7e3bc51 217 } else {
22931cf4 218 // The full treatment, please
219 print_side_block($title, $this->content->text, NULL, NULL, $this->content->footer, $this->html_attributes());
220 }
0f3fe4b6 221 }
222 break;
223 case BLOCK_TYPE_LIST:
c7e3bc51 224 if (empty($this->content->items) && empty($this->content->footer)) {
225 if (empty($this->edit_controls)) {
22931cf4 226 // No content, no edit controls, so just shut up
227 break;
c7e3bc51 228 } else {
22931cf4 229 // No content but editing, so show something at least
1345403a 230 $this->_print_shadow();
22931cf4 231 }
c7e3bc51 232 } else {
233 if ($this->hide_header() && empty($this->edit_controls)) {
22931cf4 234 // Header wants to hide, no edit controls to show, so no header it is
235 print_side_block(NULL, '', $this->content->items, $this->content->icons, $this->content->footer, $this->html_attributes());
c7e3bc51 236 } else {
22931cf4 237 // The full treatment, please
238 print_side_block($title, '', $this->content->items, $this->content->icons, $this->content->footer, $this->html_attributes());
239 }
0f3fe4b6 240 }
241 break;
242 }
243 }
c7e3bc51 244
245 /**
246 * Block contents are missing. Simply display an empty block so that
247 * edit controls are accessbile to the user and they are aware that this
248 * block is in place, even if empty.
249 */
1345403a 250 function _print_shadow() {
0f3fe4b6 251 $title = '<div style="float: left;">'.$this->title.'</div>';
c7e3bc51 252 if ($this->edit_controls !== NULL) {
0f3fe4b6 253 $title .= $this->edit_controls;
254 }
255 print_side_block($title, '&nbsp;', NULL, NULL, '');
256 }
89adb174 257
c7e3bc51 258 /**
259 * Sets class $edit_controls var with correct block manipulation links.
260 *
261 * @uses $CFG
c7e3bc51 262 * @uses $USER
263 * @param stdObject $options ?
264 * @todo complete documenting this function. Define $options.
265 */
1345403a 266 function _add_edit_controls($options) {
0705dcc0 267 global $CFG, $USER;
0f3fe4b6 268
0f3fe4b6 269 if (!isset($this->str)) {
270 $this->str->delete = get_string('delete');
271 $this->str->moveup = get_string('moveup');
272 $this->str->movedown = get_string('movedown');
273 $this->str->moveright = get_string('moveright');
274 $this->str->moveleft = get_string('moveleft');
275 $this->str->hide = get_string('hide');
276 $this->str->show = get_string('show');
9b4b78fd 277 $this->str->configure = get_string('configuration');
0f3fe4b6 278 }
279
abea5d69 280 $movebuttons = '<div style="float: right; font-size: 0.75em; margin-top: 0.3em;">';
0f3fe4b6 281
c7e3bc51 282 if ($this->instance->visible) {
0f3fe4b6 283 $icon = '/t/hide.gif';
284 $title = $this->str->hide;
c7e3bc51 285 } else {
0f3fe4b6 286 $icon = '/t/show.gif';
287 $title = $this->str->show;
288 }
289
9b128500 290 $page = page_create_object($this->instance->pagetype, $this->instance->pageid);
f032aa7a 291 $script = $page->url_get_full(array('instanceid' => $this->instance->id, 'sesskey' => $USER->sesskey));
9b4b78fd 292
f032aa7a 293 $movebuttons .= '<a style="margin-right: 6px; margin-left: 2px;" title="'. $title .'" href="'.$script.'&amp;blockaction=toggle">' .
0705dcc0 294 '<img src="'. $CFG->pixpath.$icon .'" alt="'.$title.'" /></a>';
0f3fe4b6 295
c7e3bc51 296 if ($options & BLOCK_CONFIGURE) {
f032aa7a 297 $movebuttons .= '<a style="margin-right: 6px; margin-left: 2px;" title="'. $this->str->configure .'" href="'.$script.'&amp;blockaction=config">' .
0705dcc0 298 '<img src="'. $CFG->pixpath .'/t/edit.gif" alt="'. $this->str->configure .'" /></a>';
9b4b78fd 299 }
300
f032aa7a 301 $movebuttons .= '<a style="margin-right: 2px; margin-left: 2px;" title="'. $this->str->delete .'" href="'.$script.'&amp;blockaction=delete">' .
0705dcc0 302 '<img src="'. $CFG->pixpath .'/t/delete.gif" alt="'. $this->str->delete .'" /></a> ';
0f3fe4b6 303
304 if ($options & BLOCK_MOVE_LEFT) {
f032aa7a 305 $movebuttons .= '<a style="margin-right: 2px; margin-left: 2px;" title="'. $this->str->moveleft .'" href="'.$script.'&amp;blockaction=moveleft">' .
0705dcc0 306 '<img src="'. $CFG->pixpath .'/t/left.gif" alt="'. $this->str->moveleft .'" /></a>';
0f3fe4b6 307 }
308 if ($options & BLOCK_MOVE_UP) {
f032aa7a 309 $movebuttons .= '<a style="margin-right: 2px; margin-left: 2px;" title="'. $this->str->moveup .'" href="'.$script.'&amp;blockaction=moveup">' .
0705dcc0 310 '<img src="'. $CFG->pixpath .'/t/up.gif" alt="'. $this->str->moveup .'" /></a>';
0f3fe4b6 311 }
312 if ($options & BLOCK_MOVE_DOWN) {
f032aa7a 313 $movebuttons .= '<a style="margin-right: 2px; margin-left: 2px;" title="'. $this->str->movedown .'" href="'.$script.'&amp;blockaction=movedown">' .
0705dcc0 314 '<img src="'. $CFG->pixpath .'/t/down.gif" alt="'. $this->str->movedown .'" /></a>';
0f3fe4b6 315 }
316 if ($options & BLOCK_MOVE_RIGHT) {
f032aa7a 317 $movebuttons .= '<a style="margin-right: 2px; margin-left: 2px;" title="'. $this->str->moveright .'" href="'.$script.'&amp;blockaction=moveright">' .
0705dcc0 318 '<img src="'. $CFG->pixpath .'/t/right.gif" alt="'. $this->str->moveright .'" /></a>';
0f3fe4b6 319 }
320
321 $movebuttons .= '</div>';
322 $this->edit_controls = $movebuttons;
323 }
324
c7e3bc51 325 /**
326 * Tests if this block has been implemented correctly.
327 * Also, $errors isn't used right now
328 *
329 * @return boolean
330 */
331
0f3fe4b6 332 function _self_test() {
333 // Tests if this block has been implemented correctly.
334 // Also, $errors isn't used right now
335 $errors = array();
336
337 $correct = true;
c7e3bc51 338 if ($this->get_title() === NULL) {
0f3fe4b6 339 $errors[] = 'title_not_set';
340 $correct = false;
341 }
c7e3bc51 342 if (!in_array($this->get_content_type(), array(BLOCK_TYPE_LIST, BLOCK_TYPE_TEXT, BLOCK_TYPE_NUKE))) {
0f3fe4b6 343 $errors[] = 'invalid_content_type';
344 $correct = false;
345 }
c7e3bc51 346 if ($this->get_content() === NULL) {
0f3fe4b6 347 $errors[] = 'content_not_set';
348 $correct = false;
349 }
c7e3bc51 350 if ($this->get_version() === NULL) {
0f3fe4b6 351 $errors[] = 'version_not_set';
352 $correct = false;
353 }
2b0d60ec 354
355 $formats = $this->applicable_formats();
c7e3bc51 356 if (empty($formats) || array_sum($formats) === 0) {
8a47e075 357 $errors[] = 'no_formats';
0f3fe4b6 358 $correct = false;
359 }
2b0d60ec 360
0f3fe4b6 361 $width = $this->preferred_width();
c7e3bc51 362 if (!is_int($width) || $width <= 0) {
0f3fe4b6 363 $errors[] = 'invalid_width';
364 $correct = false;
365 }
366 return $correct;
367 }
368
c7e3bc51 369 /**
370 * Subclasses should override this and return true if the
371 * subclass block has a config_global.html file.
372 *
373 * @return boolean
374 */
0f3fe4b6 375 function has_config() {
376 return false;
377 }
c7e3bc51 378
379 /**
380 * Default behavior: print the config_global.html file
381 * You don't need to override this if you're satisfied with the above
382 *
383 * @uses $CFG
c7e3bc51 384 * @return boolean
385 */
f8582e3e 386 function config_print() {
9b4b78fd 387 // Default behavior: print the config_global.html file
c7e3bc51 388 // You don't need to override this if you're satisfied with the above
389 if (!$this->has_config()) {
9b4b78fd 390 return false;
391 }
0705dcc0 392 global $CFG;
393 print_simple_box_start('center', '', '', 5, 'blockconfigglobal');
59b29207 394 include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
9b4b78fd 395 print_simple_box_end();
396 return true;
0f3fe4b6 397 }
59b29207 398
c7e3bc51 399 /**
400 * Default behavior: save all variables as $CFG properties
401 * You don't need to override this if you 're satisfied with the above
402 *
f8582e3e 403 * @param array $data
c7e3bc51 404 * @return boolean
405 */
f8582e3e 406 function config_save($data) {
9b4b78fd 407 // Default behavior: save all variables as $CFG properties
408 // You don't need to override this if you 're satisfied with the above
f8582e3e 409 foreach ($data as $name => $value) {
9b4b78fd 410 set_config($name, $value);
411 }
412 return true;
0f3fe4b6 413 }
59b29207 414
c7e3bc51 415 /**
416 * Default case: the block can be used in all course types
417 * @return array
418 * @todo finish documenting this function
419 */
0f3fe4b6 420 function applicable_formats() {
d232b8c7 421 // Default case: the block can be used in courses and site index, but not in activities
8a47e075 422 return array('all' => true, 'mod' => false);
0f3fe4b6 423 }
59b29207 424
c7e3bc51 425
426 /**
427 * Default case: the block wants to be 180 pixels wide
428 * @return int
429 */
0f3fe4b6 430 function preferred_width() {
431 // Default case: the block wants to be 180 pixels wide
432 return 180;
433 }
59b29207 434
c7e3bc51 435 /**
436 * Default return is false - header will be shown
437 * @return boolean
438 */
0f3fe4b6 439 function hide_header() {
4e60e777 440 //Default, false--> the header is shown
0f3fe4b6 441 return false;
442 }
c7e3bc51 443
444 /**
445 * Default case: just an id for the block, with our name in it
446 * @return array
447 * @todo finish documenting this function
448 */
c5507e52 449 function html_attributes() {
d232b8c7 450 // Default case: an id with the instance and a class with our name in it
29ba5158 451 return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
c5507e52 452 }
59b29207 453
c7e3bc51 454 /**
455 * Given an instance set the class var $instance to it and
456 * load class var $config
457 * @param block $instance
458 * @todo add additional documentation to further explain the format of instance and config
459 */
1345403a 460 function _load_instance($instance) {
c7e3bc51 461 if (!empty($instance->configdata)) {
9b4b78fd 462 $this->config = unserialize(base64_decode($instance->configdata));
463 }
673c1b2f 464 // [pj] This line below is supposed to be an optimization (we don't need configdata anymore)
465 // but what it does is break in PHP5 because the same instance object will be passed to
466 // this function twice in each page view, and the second time it won't have any configdata
467 // so it won't work correctly. Thus it's commented out.
468 // unset($instance->configdata);
9b4b78fd 469 $this->instance = $instance;
470 $this->specialization();
471 }
59b29207 472
43038ce6 473 /**
474 * This function is called on your subclass right after an instance is loaded
475 * Use this function to act on instance data just after it's loaded and before anything else is done
67677908 476 * For instance: if your block will have different title's depending on location (site, course, blog, etc)
43038ce6 477 */
9b4b78fd 478 function specialization() {
479 // Just to make sure that this method exists.
9b4b78fd 480 }
481
c7e3bc51 482 /**
f032aa7a 483 * Is each block of this type going to have instance-specific configuration?
484 * Normally, this setting is controlled by {@link instance_allow_multiple}: if multiple
485 * instances are allowed, then each will surely need its own configuration. However, in some
486 * cases it may be necessary to provide instance configuration to blocks that do not want to
487 * allow multiple instances. In that case, make this function return true.
488 * I stress again that this makes a difference ONLY if {@link instance_allow_multiple} returns false.
489 * @return boolean
490 * @todo finish documenting this function by explaining per-instance configuration further
491 */
492 function instance_allow_config() {
493 return false;
494 }
495
496 /**
497 * Are you going to allow multiple instances of each block?
c7e3bc51 498 * If yes, then it is assumed that the block WILL USE per-instance configuration
499 * @return boolean
500 * @todo finish documenting this function by explaining per-instance configuration further
501 */
9b4b78fd 502 function instance_allow_multiple() {
503 // Are you going to allow multiple instances of each block?
504 // If yes, then it is assumed that the block WILL USE per-instance configuration
505 return false;
506 }
59b29207 507
c7e3bc51 508 /**
509 * Default behavior: print the config_instance.html file
510 * You don't need to override this if you're satisfied with the above
511 *
512 * @uses $CFG
c7e3bc51 513 * @return boolean
514 * @todo finish documenting this function
515 */
9b4b78fd 516 function instance_config_print() {
517 // Default behavior: print the config_instance.html file
e1b8bdf8 518 // You don't need to override this if you're satisfied with the above
f032aa7a 519 if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
9b4b78fd 520 return false;
521 }
0705dcc0 522 global $CFG;
9b4b78fd 523
c7e3bc51 524 if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
0705dcc0 525 print_simple_box_start('center', '', '', 5, 'blockconfiginstance');
6195e04a 526 include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
9b4b78fd 527 print_simple_box_end();
6195e04a 528 } else {
9b4b78fd 529 notice(get_string('blockconfigbad'), str_replace('blockaction=', 'dummy=', qualified_me()));
530 }
531
532 return true;
533 }
c7e3bc51 534
535 /**
536 * Serialize and store config data
537 * @return boolean
538 * @todo finish documenting this function
539 */
9b4b78fd 540 function instance_config_save($data) {
541 $data = stripslashes_recursive($data);
542 $this->config = $data;
543 return set_field('block_instance', 'configdata', base64_encode(serialize($data)), 'id', $this->instance->id);
544 }
545
0144a0a7 546 /**
547 * Replace the instance's configuration data with those currently in $this->config;
548 * @return boolean
549 * @todo finish documenting this function
550 */
551 function instance_config_commit() {
552 return set_field('block_instance', 'configdata', base64_encode(serialize($this->config)), 'id', $this->instance->id);
553 }
554
0f3fe4b6 555}
556
c7e3bc51 557/**
558 * Class for supporting a postnuke style block as a moodle block
559 *
560 * @author Jon Papaioannou
561 * @package blocks
562 */
e89d741a 563class block_nuke extends block_base {
828c4e09 564 function get_content() {
565
c7e3bc51 566 if ($this->content !== NULL) {
d4950608 567 return $this->content;
568 }
828c4e09 569
570 global $CFG;
d4950608 571 $this->content = &New stdClass;
572
573 // This whole thing begs to be written for PHP >= 4.3.0 using glob();
59b29207 574 $dir = $CFG->dirroot .'/blocks/'. $this->name() .'/nuke/';
c7e3bc51 575 if ($dh = @opendir($dir)) {
828c4e09 576 while (($file = readdir($dh)) !== false) {
577 $regs = array();
c7e3bc51 578 if (ereg('^block\-(.*)\.php$', $file, $regs)) {
d4950608 579 // Found it! Let's prepare the environment...
828c4e09 580
d4950608 581 $oldvals = array();
c7e3bc51 582 if (isset($GLOBALS['admin'])) {
d4950608 583 $oldvals['admin'] = $GLOBALS['admin'];
584 }
585
586 $GLOBALS['admin'] = isteacher($this->course->id);
828c4e09 587 @include($dir.$file);
d4950608 588
589 foreach($oldvals as $key => $val) {
590 $GLOBALS[$key] = $val;
591 }
828c4e09 592
593 // We should have $content set now
c7e3bc51 594 if (!isset($content)) {
828c4e09 595 return NULL;
596 }
597 return $this->content->text = $content;
598 }
599 }
600 }
d4950608 601
602 // If we reached here, we couldn't find the nuke block for some reason
603 return $this->content->text = get_string('blockmissingnuke');
828c4e09 604 }
605}
606
73554752 607?>