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