3 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
19 * Block Class and Functions
21 * This file defines the {@link block_manager} class,
25 * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
29 defined('MOODLE_INTERNAL') ||
die();
32 * @deprecated since Moodle 2.0. No longer used.
34 define('BLOCK_MOVE_LEFT', 0x01);
35 define('BLOCK_MOVE_RIGHT', 0x02);
36 define('BLOCK_MOVE_UP', 0x04);
37 define('BLOCK_MOVE_DOWN', 0x08);
38 define('BLOCK_CONFIGURE', 0x10);
42 * Default names for the block regions in the standard theme.
44 define('BLOCK_POS_LEFT', 'side-pre');
45 define('BLOCK_POS_RIGHT', 'side-post');
49 * @deprecated since Moodle 2.0. No longer used.
51 define('BLOCKS_PINNED_TRUE',0);
52 define('BLOCKS_PINNED_FALSE',1);
53 define('BLOCKS_PINNED_BOTH',2);
56 define('BUI_CONTEXTS_FRONTPAGE_ONLY', 0);
57 define('BUI_CONTEXTS_FRONTPAGE_SUBS', 1);
58 define('BUI_CONTEXTS_ENTIRE_SITE', 2);
60 define('BUI_CONTEXTS_CURRENT', 0);
61 define('BUI_CONTEXTS_CURRENT_SUBS', 1);
64 * Exception thrown when someone tried to do something with a block that does
65 * not exist on a page.
67 * @copyright 2009 Tim Hunt
68 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
71 class block_not_on_page_exception
extends moodle_exception
{
74 * @param int $instanceid the block instance id of the block that was looked for.
75 * @param object $page the current page.
77 public function __construct($instanceid, $page) {
79 $a->instanceid
= $instanceid;
80 $a->url
= $page->url
->out();
81 parent
::__construct('blockdoesnotexistonpage', '', $page->url
->out(), $a);
86 * This class keeps track of the block that should appear on a moodle_page.
88 * The page to work with as passed to the constructor.
90 * @copyright 2009 Tim Hunt
91 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
96 * The UI normally only shows block weights between -MAX_WEIGHT and MAX_WEIGHT,
97 * although other weights are valid.
99 const MAX_WEIGHT
= 10;
101 /// Field declarations =========================================================
104 * the moodle_page we are managing blocks for.
109 /** @var array region name => 1.*/
110 protected $regions = array();
112 /** @var string the region where new blocks are added.*/
113 protected $defaultregion = null;
115 /** @var array will be $DB->get_records('blocks') */
116 protected $allblocks = null;
119 * @var array blocks that this user can add to this page. Will be a subset
120 * of $allblocks, but with array keys block->name. Access this via the
121 * {@link get_addable_blocks()} method to ensure it is lazy-loaded.
123 protected $addableblocks = null;
126 * Will be an array region-name => array(db rows loaded in load_blocks);
129 protected $birecordsbyregion = null;
132 * array region-name => array(block objects); populated as necessary by
133 * the ensure_instances_exist method.
136 protected $blockinstances = array();
139 * array region-name => array(block_contents objects) what actually needs to
140 * be displayed in each region.
143 protected $visibleblockcontent = array();
146 * array region-name => array(block_contents objects) extra block-like things
147 * to be displayed in each region, before the real blocks.
150 protected $extracontent = array();
153 * Used by the block move id, to track whether a block is currently being moved.
155 * When you click on the move icon of a block, first the page needs to reload with
156 * extra UI for choosing a new position for a particular block. In that situation
157 * this field holds the id of the block being moved.
161 protected $movingblock = null;
164 * Show only fake blocks
166 protected $fakeblocksonly = false;
168 /// Constructor ================================================================
172 * @param object $page the moodle_page object object we are managing the blocks for,
173 * or a reasonable faxilimily. (See the comment at the top of this class
174 * and {@link http://en.wikipedia.org/wiki/Duck_typing})
176 public function __construct($page) {
180 /// Getter methods =============================================================
183 * Get an array of all region names on this page where a block may appear
185 * @return array the internal names of the regions on this page where block may appear.
187 public function get_regions() {
188 if (is_null($this->defaultregion
)) {
189 $this->page
->initialise_theme_and_output();
191 return array_keys($this->regions
);
195 * Get the region name of the region blocks are added to by default
197 * @return string the internal names of the region where new blocks are added
198 * by default, and where any blocks from an unrecognised region are shown.
199 * (Imagine that blocks were added with one theme selected, then you switched
200 * to a theme with different block positions.)
202 public function get_default_region() {
203 $this->page
->initialise_theme_and_output();
204 return $this->defaultregion
;
208 * The list of block types that may be added to this page.
210 * @return array block name => record from block table.
212 public function get_addable_blocks() {
213 $this->check_is_loaded();
215 if (!is_null($this->addableblocks
)) {
216 return $this->addableblocks
;
220 $this->addableblocks
= array();
222 $allblocks = blocks_get_record();
223 if (empty($allblocks)) {
224 return $this->addableblocks
;
227 $pageformat = $this->page
->pagetype
;
228 foreach($allblocks as $block) {
229 if ($block->visible
&&
230 (block_method_result($block->name
, 'instance_allow_multiple') ||
!$this->is_block_present($block->name
)) &&
231 blocks_name_allowed_in_format($block->name
, $pageformat) &&
232 block_method_result($block->name
, 'user_can_addto', $this->page
)) {
233 $this->addableblocks
[$block->name
] = $block;
237 return $this->addableblocks
;
241 * Given a block name, find out of any of them are currently present in the page
243 * @param string $blockname - the basic name of a block (eg "navigation")
244 * @return boolean - is there one of these blocks in the current page?
246 public function is_block_present($blockname) {
247 if (empty($this->blockinstances
)) {
251 foreach ($this->blockinstances
as $region) {
252 foreach ($region as $instance) {
253 if (empty($instance->instance
->blockname
)) {
256 if ($instance->instance
->blockname
== $blockname) {
265 * Find out if a block type is known by the system
267 * @param string $blockname the name of the type of block.
268 * @param boolean $includeinvisible if false (default) only check 'visible' blocks, that is, blocks enabled by the admin.
269 * @return boolean true if this block in installed.
271 public function is_known_block_type($blockname, $includeinvisible = false) {
272 $blocks = $this->get_installed_blocks();
273 foreach ($blocks as $block) {
274 if ($block->name
== $blockname && ($includeinvisible ||
$block->visible
)) {
282 * Find out if a region exists on a page
284 * @param string $region a region name
285 * @return boolean true if this region exists on this page.
287 public function is_known_region($region) {
288 return array_key_exists($region, $this->regions
);
292 * Get an array of all blocks within a given region
294 * @param string $region a block region that exists on this page.
295 * @return array of block instances.
297 public function get_blocks_for_region($region) {
298 $this->check_is_loaded();
299 $this->ensure_instances_exist($region);
300 return $this->blockinstances
[$region];
304 * Returns an array of block content objects that exist in a region
306 * @param string $region a block region that exists on this page.
307 * @return array of block block_contents objects for all the blocks in a region.
309 public function get_content_for_region($region, $output) {
310 $this->check_is_loaded();
311 $this->ensure_content_created($region, $output);
312 return $this->visibleblockcontent
[$region];
316 * Helper method used by get_content_for_region.
317 * @param string $region region name
318 * @param float $weight weight. May be fractional, since you may want to move a block
319 * between ones with weight 2 and 3, say ($weight would be 2.5).
320 * @return string URL for moving block $this->movingblock to this position.
322 protected function get_move_target_url($region, $weight) {
323 return new moodle_url($this->page
->url
, array('bui_moveid' => $this->movingblock
,
324 'bui_newregion' => $region, 'bui_newweight' => $weight, 'sesskey' => sesskey()));
328 * Determine whether a region contains anything. (Either any real blocks, or
329 * the add new block UI.)
331 * (You may wonder why the $output parameter is required. Unfortunately,
332 * because of the way that blocks work, the only reliable way to find out
333 * if a block will be visible is to get the content for output, and to
334 * get the content, you need a renderer. Fortunately, this is not a
335 * performance problem, because we cache the output that is generated, and
336 * in almost every case where we call region_has_content, we are about to
337 * output the blocks anyway, so we are not doing wasted effort.)
339 * @param string $region a block region that exists on this page.
340 * @param object $output a core_renderer. normally the global $OUTPUT.
341 * @return boolean Whether there is anything in this region.
343 public function region_has_content($region, $output) {
345 if (!$this->is_known_region($region)) {
348 $this->check_is_loaded();
349 $this->ensure_content_created($region, $output);
350 // if ($this->page->user_is_editing() && $this->page->user_can_edit_blocks()) {
351 // Mark Nielsen's patch - part 1
352 if ($this->page
->user_is_editing() && $this->page
->user_can_edit_blocks() && $this->movingblock
) {
353 // If editing is on, we need all the block regions visible, for the
357 return !empty($this->visibleblockcontent
[$region]) ||
!empty($this->extracontent
[$region]);
361 * Get an array of all of the installed blocks.
363 * @return array contents of the block table.
365 public function get_installed_blocks() {
367 if (is_null($this->allblocks
)) {
368 $this->allblocks
= $DB->get_records('block');
370 return $this->allblocks
;
373 /// Setter methods =============================================================
376 * Add a region to a page
378 * @param string $region add a named region where blocks may appear on the
379 * current page. This is an internal name, like 'side-pre', not a string to
382 public function add_region($region) {
383 $this->check_not_yet_loaded();
384 $this->regions
[$region] = 1;
388 * Add an array of regions
391 * @param array $regions this utility method calls add_region for each array element.
393 public function add_regions($regions) {
394 foreach ($regions as $region) {
395 $this->add_region($region);
400 * Set the default region for new blocks on the page
402 * @param string $defaultregion the internal names of the region where new
403 * blocks should be added by default, and where any blocks from an
404 * unrecognised region are shown.
406 public function set_default_region($defaultregion) {
407 $this->check_not_yet_loaded();
408 if ($defaultregion) {
409 $this->check_region_is_known($defaultregion);
411 $this->defaultregion
= $defaultregion;
415 * Add something that looks like a block, but which isn't an actual block_instance,
418 * @param block_contents $bc the content of the block-like thing.
419 * @param string $region a block region that exists on this page.
421 public function add_fake_block($bc, $region) {
422 $this->page
->initialise_theme_and_output();
423 if (!$this->is_known_region($region)) {
424 $region = $this->get_default_region();
426 if (array_key_exists($region, $this->visibleblockcontent
)) {
427 throw new coding_exception('block_manager has already prepared the blocks in region ' .
428 $region . 'for output. It is too late to add a fake block.');
430 $this->extracontent
[$region][] = $bc;
434 * When the block_manager class was created, the {@link add_fake_block()}
435 * was called add_pretend_block, which is inconsisted with
436 * {@link show_only_fake_blocks()}. To fix this inconsistency, this method
437 * was renamed to add_fake_block. Please update your code.
438 * @param block_contents $bc the content of the block-like thing.
439 * @param string $region a block region that exists on this page.
441 public function add_pretend_block($bc, $region) {
442 debugging(DEBUG_DEVELOPER
, 'add_pretend_block has been renamed to add_fake_block. Please rename the method call in your code.');
443 $this->add_fake_block($bc, $region);
447 * Checks to see whether all of the blocks within the given region are docked
449 * @see region_uses_dock
450 * @param string $region
451 * @return bool True if all of the blocks within that region are docked
453 public function region_completely_docked($region, $output) {
454 if (!$this->page
->theme
->enable_dock
) {
457 $this->check_is_loaded();
458 $this->ensure_content_created($region, $output);
459 foreach($this->visibleblockcontent
[$region] as $instance) {
460 if (!empty($instance->content
) && !get_user_preferences('docked_block_instance_'.$instance->blockinstanceid
, 0)) {
468 * Checks to see whether any of the blocks within the given regions are docked
470 * @see region_completely_docked
471 * @param array|string $regions array of regions (or single region)
472 * @return bool True if any of the blocks within that region are docked
474 public function region_uses_dock($regions, $output) {
475 if (!$this->page
->theme
->enable_dock
) {
478 $this->check_is_loaded();
479 foreach((array)$regions as $region) {
480 $this->ensure_content_created($region, $output);
481 foreach($this->visibleblockcontent
[$region] as $instance) {
482 if(!empty($instance->content
) && get_user_preferences('docked_block_instance_'.$instance->blockinstanceid
, 0)) {
490 /// Actions ====================================================================
493 * This method actually loads the blocks for our page from the database.
495 * @param boolean|null $includeinvisible
496 * null (default) - load hidden blocks if $this->page->user_is_editing();
497 * true - load hidden blocks.
498 * false - don't load hidden blocks.
500 public function load_blocks($includeinvisible = null) {
503 if (!is_null($this->birecordsbyregion
)) {
508 if ($CFG->version
< 2009050619) {
509 // Upgrade/install not complete. Don't try too show any blocks.
510 $this->birecordsbyregion
= array();
514 // Ensure we have been initialised.
515 if (is_null($this->defaultregion
)) {
516 $this->page
->initialise_theme_and_output();
517 // If there are still no block regions, then there are no blocks on this page.
518 if (empty($this->regions
)) {
519 $this->birecordsbyregion
= array();
524 // Check if we need to load normal blocks
525 if ($this->fakeblocksonly
) {
526 $this->birecordsbyregion
= $this->prepare_per_region_arrays();
530 if (is_null($includeinvisible)) {
531 $includeinvisible = $this->page
->user_is_editing();
533 if ($includeinvisible) {
536 $visiblecheck = 'AND (bp.visible = 1 OR bp.visible IS NULL)';
539 $context = $this->page
->context
;
540 $contexttest = 'bi.parentcontextid = :contextid2';
541 $parentcontextparams = array();
542 $parentcontextids = get_parent_contexts($context);
543 if ($parentcontextids) {
544 list($parentcontexttest, $parentcontextparams) =
545 $DB->get_in_or_equal($parentcontextids, SQL_PARAMS_NAMED
, 'parentcontext');
546 $contexttest = "($contexttest OR (bi.showinsubcontexts = 1 AND bi.parentcontextid $parentcontexttest))";
549 $pagetypepatterns = matching_page_type_patterns($this->page
->pagetype
);
550 list($pagetypepatterntest, $pagetypepatternparams) =
551 $DB->get_in_or_equal($pagetypepatterns, SQL_PARAMS_NAMED
, 'pagetypepatterntest');
553 list($ccselect, $ccjoin) = context_instance_preload_sql('bi.id', CONTEXT_BLOCK
, 'ctx');
556 'subpage1' => $this->page
->subpage
,
557 'subpage2' => $this->page
->subpage
,
558 'contextid1' => $context->id
,
559 'contextid2' => $context->id
,
560 'pagetype' => $this->page
->pagetype
,
562 if ($this->page
->subpage
=== '') {
563 $params['subpage1'] = $DB->sql_empty();
564 $params['subpage2'] = $DB->sql_empty();
568 bp.id AS blockpositionid,
571 bi.showinsubcontexts,
576 COALESCE(bp.visible, 1) AS visible,
577 COALESCE(bp.region, bi.defaultregion) AS region,
578 COALESCE(bp.weight, bi.defaultweight) AS weight,
582 FROM {block_instances} bi
583 JOIN {block} b ON bi.blockname = b.name
584 LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
585 AND bp.contextid = :contextid1
586 AND bp.pagetype = :pagetype
587 AND bp.subpage = :subpage1
592 AND bi.pagetypepattern $pagetypepatterntest
593 AND (bi.subpagepattern IS NULL OR bi.subpagepattern = :subpage2)
598 COALESCE(bp.region, bi.defaultregion),
599 COALESCE(bp.weight, bi.defaultweight),
601 $blockinstances = $DB->get_recordset_sql($sql, $params +
$parentcontextparams +
$pagetypepatternparams);
603 $this->birecordsbyregion
= $this->prepare_per_region_arrays();
605 foreach ($blockinstances as $bi) {
606 context_instance_preload($bi);
607 if ($this->is_known_region($bi->region
)) {
608 $this->birecordsbyregion
[$bi->region
][] = $bi;
614 // Pages don't necessarily have a defaultregion. The one time this can
615 // happen is when there are no theme block regions, but the script itself
616 // has a block region in the main content area.
617 if (!empty($this->defaultregion
)) {
618 $this->birecordsbyregion
[$this->defaultregion
] =
619 array_merge($this->birecordsbyregion
[$this->defaultregion
], $unknown);
624 * Add a block to the current page, or related pages. The block is added to
625 * context $this->page->contextid. If $pagetypepattern $subpagepattern
627 * @param string $blockname The type of block to add.
628 * @param string $region the block region on this page to add the block to.
629 * @param integer $weight determines the order where this block appears in the region.
630 * @param boolean $showinsubcontexts whether this block appears in subcontexts, or just the current context.
631 * @param string|null $pagetypepattern which page types this block should appear on. Defaults to just the current page type.
632 * @param string|null $subpagepattern which subpage this block should appear on. NULL = any (the default), otherwise only the specified subpage.
634 public function add_block($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern = NULL, $subpagepattern = NULL) {
636 // Allow invisible blocks because this is used when adding default page blocks, which
637 // might include invisible ones if the user makes some default blocks invisible
638 $this->check_known_block_type($blockname, true);
639 $this->check_region_is_known($region);
641 if (empty($pagetypepattern)) {
642 $pagetypepattern = $this->page
->pagetype
;
645 $blockinstance = new stdClass
;
646 $blockinstance->blockname
= $blockname;
647 $blockinstance->parentcontextid
= $this->page
->context
->id
;
648 $blockinstance->showinsubcontexts
= !empty($showinsubcontexts);
649 $blockinstance->pagetypepattern
= $pagetypepattern;
650 $blockinstance->subpagepattern
= $subpagepattern;
651 $blockinstance->defaultregion
= $region;
652 $blockinstance->defaultweight
= $weight;
653 $blockinstance->configdata
= '';
654 $blockinstance->id
= $DB->insert_record('block_instances', $blockinstance);
656 // Ensure the block context is created.
657 get_context_instance(CONTEXT_BLOCK
, $blockinstance->id
);
659 // If the new instance was created, allow it to do additional setup
660 if ($block = block_instance($blockname, $blockinstance)) {
661 $block->instance_create();
665 public function add_block_at_end_of_default_region($blockname) {
666 $defaulregion = $this->get_default_region();
668 $lastcurrentblock = end($this->birecordsbyregion
[$defaulregion]);
669 if ($lastcurrentblock) {
670 $weight = $lastcurrentblock->weight +
1;
675 if ($this->page
->subpage
) {
676 $subpage = $this->page
->subpage
;
681 // Special case. Course view page type include the course format, but we
682 // want to add the block non-format-specifically.
683 $pagetypepattern = $this->page
->pagetype
;
684 if (strpos($pagetypepattern, 'course-view') === 0) {
685 $pagetypepattern = 'course-view-*';
688 // We should end using this for ALL the blocks, making always the 1st option
689 // the default one to be used. Until then, this is one hack to avoid the
690 // 'pagetypewarning' message on blocks initial edition (MDL-27829) caused by
691 // non-existing $pagetypepattern set. This way at least we guarantee one "valid"
692 // (the FIRST $pagetypepattern will be set)
694 // We are applying it to all blocks created in mod pages for now and only if the
695 // default pagetype is not one of the available options
696 if (preg_match('/^mod-.*-/', $pagetypepattern)) {
697 $pagetypelist = generate_page_type_patterns($this->page
->pagetype
, null, $this->page
->context
);
698 // Only go for the first if the pagetype is not a valid option
699 if (is_array($pagetypelist) && !array_key_exists($pagetypepattern, $pagetypelist)) {
700 $pagetypepattern = key($pagetypelist);
703 // Surely other pages like course-report will need this too, they just are not important
704 // enough now. This will be decided in the coming days. (MDL-27829, MDL-28150)
706 $this->add_block($blockname, $defaulregion, $weight, false, $pagetypepattern, $subpage);
710 * Convenience method, calls add_block repeatedly for all the blocks in $blocks.
712 * @param array $blocks array with array keys the region names, and values an array of block names.
713 * @param string $pagetypepattern optional. Passed to @see add_block()
714 * @param string $subpagepattern optional. Passed to @see add_block()
716 public function add_blocks($blocks, $pagetypepattern = NULL, $subpagepattern = NULL, $showinsubcontexts=false, $weight=0) {
717 $this->add_regions(array_keys($blocks));
718 foreach ($blocks as $region => $regionblocks) {
720 foreach ($regionblocks as $blockname) {
721 $this->add_block($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern, $subpagepattern);
728 * Move a block to a new position on this page.
730 * If this block cannot appear on any other pages, then we change defaultposition/weight
731 * in the block_instances table. Otherwise we just set the position on this page.
733 * @param $blockinstanceid the block instance id.
734 * @param $newregion the new region name.
735 * @param $newweight the new weight.
737 public function reposition_block($blockinstanceid, $newregion, $newweight) {
740 $this->check_region_is_known($newregion);
741 $inst = $this->find_instance($blockinstanceid);
743 $bi = $inst->instance
;
744 if ($bi->weight
== $bi->defaultweight
&& $bi->region
== $bi->defaultregion
&&
745 !$bi->showinsubcontexts
&& strpos($bi->pagetypepattern
, '*') === false &&
746 (!$this->page
->subpage ||
$bi->subpagepattern
)) {
748 // Set default position
749 $newbi = new stdClass
;
750 $newbi->id
= $bi->id
;
751 $newbi->defaultregion
= $newregion;
752 $newbi->defaultweight
= $newweight;
753 $DB->update_record('block_instances', $newbi);
755 if ($bi->blockpositionid
) {
757 $bp->id
= $bi->blockpositionid
;
758 $bp->region
= $newregion;
759 $bp->weight
= $newweight;
760 $DB->update_record('block_positions', $bp);
764 // Just set position on this page.
766 $bp->region
= $newregion;
767 $bp->weight
= $newweight;
769 if ($bi->blockpositionid
) {
770 $bp->id
= $bi->blockpositionid
;
771 $DB->update_record('block_positions', $bp);
774 $bp->blockinstanceid
= $bi->id
;
775 $bp->contextid
= $this->page
->context
->id
;
776 $bp->pagetype
= $this->page
->pagetype
;
777 if ($this->page
->subpage
) {
778 $bp->subpage
= $this->page
->subpage
;
782 $bp->visible
= $bi->visible
;
783 $DB->insert_record('block_positions', $bp);
789 * Find a given block by its instance id
791 * @param integer $instanceid
794 public function find_instance($instanceid) {
795 foreach ($this->regions
as $region => $notused) {
796 $this->ensure_instances_exist($region);
797 foreach($this->blockinstances
[$region] as $instance) {
798 if ($instance->instance
->id
== $instanceid) {
803 throw new block_not_on_page_exception($instanceid, $this->page
);
806 /// Inner workings =============================================================
809 * Check whether the page blocks have been loaded yet
811 * @return void Throws coding exception if already loaded
813 protected function check_not_yet_loaded() {
814 if (!is_null($this->birecordsbyregion
)) {
815 throw new coding_exception('block_manager has already loaded the blocks, to it is too late to change things that might affect which blocks are visible.');
820 * Check whether the page blocks have been loaded yet
822 * Nearly identical to the above function {@link check_not_yet_loaded()} except different message
824 * @return void Throws coding exception if already loaded
826 protected function check_is_loaded() {
827 if (is_null($this->birecordsbyregion
)) {
828 throw new coding_exception('block_manager has not yet loaded the blocks, to it is too soon to request the information you asked for.');
833 * Check if a block type is known and usable
835 * @param string $blockname The block type name to search for
836 * @param bool $includeinvisible Include disabled block types in the initial pass
837 * @return void Coding Exception thrown if unknown or not enabled
839 protected function check_known_block_type($blockname, $includeinvisible = false) {
840 if (!$this->is_known_block_type($blockname, $includeinvisible)) {
841 if ($this->is_known_block_type($blockname, true)) {
842 throw new coding_exception('Unknown block type ' . $blockname);
844 throw new coding_exception('Block type ' . $blockname . ' has been disabled by the administrator.');
850 * Check if a region is known by its name
852 * @param string $region
853 * @return void Coding Exception thrown if the region is not known
855 protected function check_region_is_known($region) {
856 if (!$this->is_known_region($region)) {
857 throw new coding_exception('Trying to reference an unknown block region ' . $region);
862 * Returns an array of region names as keys and nested arrays for values
864 * @return array an array where the array keys are the region names, and the array
865 * values are empty arrays.
867 protected function prepare_per_region_arrays() {
869 foreach ($this->regions
as $region => $notused) {
870 $result[$region] = array();
876 * Create a set of new block instance from a record array
878 * @param array $birecords An array of block instance records
879 * @return array An array of instantiated block_instance objects
881 protected function create_block_instances($birecords) {
883 foreach ($birecords as $record) {
884 if ($blockobject = block_instance($record->blockname
, $record, $this->page
)) {
885 $results[] = $blockobject;
892 * Create all the block instances for all the blocks that were loaded by
893 * load_blocks. This is used, for example, to ensure that all blocks get a
894 * chance to initialise themselves via the {@link block_base::specialize()}
895 * method, before any output is done.
897 public function create_all_block_instances() {
898 foreach ($this->get_regions() as $region) {
899 $this->ensure_instances_exist($region);
904 * Return an array of content objects from a set of block instances
906 * @param array $instances An array of block instances
907 * @param renderer_base The renderer to use.
908 * @param string $region the region name.
909 * @return array An array of block_content (and possibly block_move_target) objects.
911 protected function create_block_contents($instances, $output, $region) {
916 if ($this->movingblock
) {
917 $first = reset($instances);
919 $lastweight = $first->instance
->weight
- 2;
922 $strmoveblockhere = get_string('moveblockhere', 'block');
925 foreach ($instances as $instance) {
926 $content = $instance->get_content_for_output($output);
927 if (empty($content)) {
931 if ($this->movingblock
&& $lastweight != $instance->instance
->weight
&&
932 $content->blockinstanceid
!= $this->movingblock
&& $lastblock != $this->movingblock
) {
933 $results[] = new block_move_target($strmoveblockhere, $this->get_move_target_url($region, ($lastweight +
$instance->instance
->weight
)/2));
936 if ($content->blockinstanceid
== $this->movingblock
) {
937 $content->add_class('beingmoved');
938 $content->annotation
.= get_string('movingthisblockcancel', 'block',
939 html_writer
::link($this->page
->url
, get_string('cancel')));
942 $results[] = $content;
943 $lastweight = $instance->instance
->weight
;
944 $lastblock = $instance->instance
->id
;
947 if ($this->movingblock
&& $lastblock != $this->movingblock
) {
948 $results[] = new block_move_target($strmoveblockhere, $this->get_move_target_url($region, $lastweight +
1));
954 * Ensure block instances exist for a given region
956 * @param string $region Check for bi's with the instance with this name
958 protected function ensure_instances_exist($region) {
959 $this->check_region_is_known($region);
960 if (!array_key_exists($region, $this->blockinstances
)) {
961 $this->blockinstances
[$region] =
962 $this->create_block_instances($this->birecordsbyregion
[$region]);
967 * Ensure that there is some content within the given region
969 * @param string $region The name of the region to check
971 protected function ensure_content_created($region, $output) {
972 $this->ensure_instances_exist($region);
973 if (!array_key_exists($region, $this->visibleblockcontent
)) {
975 if (array_key_exists($region, $this->extracontent
)) {
976 $contents = $this->extracontent
[$region];
978 $contents = array_merge($contents, $this->create_block_contents($this->blockinstances
[$region], $output, $region));
979 if ($region == $this->defaultregion
) {
980 $addblockui = block_add_block_ui($this->page
, $output);
982 $contents[] = $addblockui;
985 $this->visibleblockcontent
[$region] = $contents;
989 /// Process actions from the URL ===============================================
992 * Get the appropriate list of editing icons for a block. This is used
993 * to set {@link block_contents::$controls} in {@link block_base::get_contents_for_output()}.
995 * @param $output The core_renderer to use when generating the output. (Need to get icon paths.)
996 * @return an array in the format for {@link block_contents::$controls}
998 public function edit_controls($block) {
1001 if (!isset($CFG->undeletableblocktypes
) ||
(!is_array($CFG->undeletableblocktypes
) && !is_string($CFG->undeletableblocktypes
))) {
1002 $undeletableblocktypes = array('navigation','settings');
1003 } else if (is_string($CFG->undeletableblocktypes
)) {
1004 $undeletableblocktypes = explode(',', $CFG->undeletableblocktypes
);
1006 $undeletableblocktypes = $CFG->undeletableblocktypes
;
1009 $controls = array();
1010 $actionurl = $this->page
->url
->out(false, array('sesskey'=> sesskey()));
1012 if ($this->page
->user_can_edit_blocks()) {
1014 $controls[] = array('url' => $actionurl . '&bui_moveid=' . $block->instance
->id
,
1015 'icon' => 't/move', 'caption' => get_string('move'));
1018 if ($this->page
->user_can_edit_blocks() ||
$block->user_can_edit()) {
1019 // Edit config icon - always show - needed for positioning UI.
1020 $controls[] = array('url' => $actionurl . '&bui_editid=' . $block->instance
->id
,
1021 'icon' => 't/edit', 'caption' => get_string('configuration'));
1024 if ($this->page
->user_can_edit_blocks() && $block->user_can_edit() && $block->user_can_addto($this->page
)) {
1025 if (!in_array($block->instance
->blockname
, $undeletableblocktypes)
1026 ||
!in_array($block->instance
->pagetypepattern
, array('*', 'site-index'))
1027 ||
$block->instance
->parentcontextid
!= SITEID
) {
1029 $controls[] = array('url' => $actionurl . '&bui_deleteid=' . $block->instance
->id
,
1030 'icon' => 't/delete', 'caption' => get_string('delete'));
1034 if ($this->page
->user_can_edit_blocks() && $block->instance_can_be_hidden()) {
1036 if ($block->instance
->visible
) {
1037 $controls[] = array('url' => $actionurl . '&bui_hideid=' . $block->instance
->id
,
1038 'icon' => 't/hide', 'caption' => get_string('hide'));
1040 $controls[] = array('url' => $actionurl . '&bui_showid=' . $block->instance
->id
,
1041 'icon' => 't/show', 'caption' => get_string('show'));
1045 // Assign roles icon.
1046 if (has_capability('moodle/role:assign', $block->context
)) {
1047 //TODO: please note it is sloppy to pass urls through page parameters!!
1048 // it is shortened because some web servers (e.g. IIS by default) give
1049 // a 'security' error if you try to pass a full URL as a GET parameter in another URL.
1050 $return = $this->page
->url
->out(false);
1051 $return = str_replace($CFG->wwwroot
. '/', '', $return);
1053 $controls[] = array('url' => $CFG->wwwroot
. '/' . $CFG->admin
.
1054 '/roles/assign.php?contextid=' . $block->context
->id
. '&returnurl=' . urlencode($return),
1055 'icon' => 'i/roles', 'caption' => get_string('assignroles', 'role'));
1062 * Process any block actions that were specified in the URL.
1064 * This can only be done given a valid $page object.
1066 * @param moodle_page $page the page to add blocks to.
1067 * @return boolean true if anything was done. False if not.
1069 public function process_url_actions() {
1070 if (!$this->page
->user_is_editing()) {
1073 return $this->process_url_add() ||
$this->process_url_delete() ||
1074 $this->process_url_show_hide() ||
$this->process_url_edit() ||
1075 $this->process_url_move();
1079 * Handle adding a block.
1080 * @return boolean true if anything was done. False if not.
1082 public function process_url_add() {
1083 $blocktype = optional_param('bui_addblock', null, PARAM_PLUGIN
);
1090 if (!$this->page
->user_can_edit_blocks()) {
1091 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('addblock'));
1094 if (!array_key_exists($blocktype, $this->get_addable_blocks())) {
1095 throw new moodle_exception('cannotaddthisblocktype', '', $this->page
->url
->out(), $blocktype);
1098 $this->add_block_at_end_of_default_region($blocktype);
1100 // If the page URL was a guess, it will contain the bui_... param, so we must make sure it is not there.
1101 $this->page
->ensure_param_not_in_url('bui_addblock');
1107 * Handle deleting a block.
1108 * @return boolean true if anything was done. False if not.
1110 public function process_url_delete() {
1111 $blockid = optional_param('bui_deleteid', null, PARAM_INTEGER
);
1118 $block = $this->page
->blocks
->find_instance($blockid);
1120 if (!$block->user_can_edit() ||
!$this->page
->user_can_edit_blocks() ||
!$block->user_can_addto($this->page
)) {
1121 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('deleteablock'));
1124 blocks_delete_instance($block->instance
);
1126 // If the page URL was a guess, it will contain the bui_... param, so we must make sure it is not there.
1127 $this->page
->ensure_param_not_in_url('bui_deleteid');
1133 * Handle showing or hiding a block.
1134 * @return boolean true if anything was done. False if not.
1136 public function process_url_show_hide() {
1137 if ($blockid = optional_param('bui_hideid', null, PARAM_INTEGER
)) {
1139 } else if ($blockid = optional_param('bui_showid', null, PARAM_INTEGER
)) {
1147 $block = $this->page
->blocks
->find_instance($blockid);
1149 if (!$this->page
->user_can_edit_blocks()) {
1150 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('hideshowblocks'));
1151 } else if (!$block->instance_can_be_hidden()) {
1155 blocks_set_visibility($block->instance
, $this->page
, $newvisibility);
1157 // If the page URL was a guses, it will contain the bui_... param, so we must make sure it is not there.
1158 $this->page
->ensure_param_not_in_url('bui_hideid');
1159 $this->page
->ensure_param_not_in_url('bui_showid');
1165 * Handle showing/processing the submission from the block editing form.
1166 * @return boolean true if the form was submitted and the new config saved. Does not
1167 * return if the editing form was displayed. False otherwise.
1169 public function process_url_edit() {
1170 global $CFG, $DB, $PAGE, $OUTPUT;
1172 $blockid = optional_param('bui_editid', null, PARAM_INTEGER
);
1178 require_once($CFG->dirroot
. '/blocks/edit_form.php');
1180 $block = $this->find_instance($blockid);
1182 if (!$block->user_can_edit() && !$this->page
->user_can_edit_blocks()) {
1183 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('editblock'));
1186 $editpage = new moodle_page();
1187 $editpage->set_pagelayout('admin');
1188 $editpage->set_course($this->page
->course
);
1189 //$editpage->set_context($block->context);
1190 $editpage->set_context($this->page
->context
);
1191 if ($this->page
->cm
) {
1192 $editpage->set_cm($this->page
->cm
);
1194 $editurlbase = str_replace($CFG->wwwroot
. '/', '/', $this->page
->url
->out_omit_querystring());
1195 $editurlparams = $this->page
->url
->params();
1196 $editurlparams['bui_editid'] = $blockid;
1197 $editpage->set_url($editurlbase, $editurlparams);
1198 $editpage->set_block_actions_done();
1199 // At this point we are either going to redirect, or display the form, so
1200 // overwrite global $PAGE ready for this. (Formslib refers to it.)
1202 //some functions like MoodleQuickForm::addHelpButton use $OUTPUT so we need to replace that to
1203 $output = $editpage->get_renderer('core');
1206 $formfile = $CFG->dirroot
. '/blocks/' . $block->name() . '/edit_form.php';
1207 if (is_readable($formfile)) {
1208 require_once($formfile);
1209 $classname = 'block_' . $block->name() . '_edit_form';
1210 if (!class_exists($classname)) {
1211 $classname = 'block_edit_form';
1214 $classname = 'block_edit_form';
1217 $mform = new $classname($editpage->url
, $block, $this->page
);
1218 $mform->set_data($block->instance
);
1220 if ($mform->is_cancelled()) {
1221 redirect($this->page
->url
);
1223 } else if ($data = $mform->get_data()) {
1225 $bi->id
= $block->instance
->id
;
1226 $bi->pagetypepattern
= $data->bui_pagetypepattern
;
1227 if (empty($data->bui_subpagepattern
) ||
$data->bui_subpagepattern
== '%@NULL@%') {
1228 $bi->subpagepattern
= null;
1230 $bi->subpagepattern
= $data->bui_subpagepattern
;
1233 $parentcontext = get_context_instance_by_id($data->bui_parentcontextid
);
1234 $systemcontext = get_context_instance(CONTEXT_SYSTEM
);
1236 // Updating stickiness and contexts. See MDL-21375 for details.
1237 if (has_capability('moodle/site:manageblocks', $parentcontext)) { // Check permissions in destination
1238 // Explicitly set the context
1239 $bi->parentcontextid
= $parentcontext->id
;
1241 // If the context type is > 0 then we'll explicitly set the block as sticky, otherwise not
1242 $bi->showinsubcontexts
= (int)(!empty($data->bui_contexts
));
1244 // If the block wants to be system-wide, then explicitly set that
1245 if ($data->bui_contexts
== BUI_CONTEXTS_ENTIRE_SITE
) { // Only possible on a frontpage or system page
1246 $bi->parentcontextid
= $systemcontext->id
;
1247 $bi->showinsubcontexts
= BUI_CONTEXTS_CURRENT_SUBS
; //show in current and sub contexts
1248 $bi->pagetypepattern
= '*';
1250 } else { // The block doesn't want to be system-wide, so let's ensure that
1251 if ($parentcontext->id
== $systemcontext->id
) { // We need to move it to the front page
1252 $frontpagecontext = get_context_instance(CONTEXT_COURSE
, SITEID
);
1253 $bi->parentcontextid
= $frontpagecontext->id
;
1254 $bi->pagetypepattern
= 'site-index';
1259 $bits = explode('-', $bi->pagetypepattern
);
1260 // hacks for some contexts
1261 if (($parentcontext->contextlevel
== CONTEXT_COURSE
) && ($parentcontext->instanceid
!= SITEID
)) {
1262 // For course context
1263 // is page type pattern is mod-*, change showinsubcontext to 1
1264 if ($bits[0] == 'mod' ||
$bi->pagetypepattern
== '*') {
1265 $bi->showinsubcontexts
= 1;
1267 $bi->showinsubcontexts
= 0;
1269 } else if ($parentcontext->contextlevel
== CONTEXT_USER
) {
1271 // subpagepattern should be null
1272 if ($bits[0] == 'user' or $bits[0] == 'my') {
1273 // we don't need subpagepattern in usercontext
1274 $bi->subpagepattern
= null;
1278 $bi->defaultregion
= $data->bui_defaultregion
;
1279 $bi->defaultweight
= $data->bui_defaultweight
;
1280 $DB->update_record('block_instances', $bi);
1282 if (!empty($block->config
)) {
1283 $config = clone($block->config
);
1285 $config = new stdClass
;
1287 foreach ($data as $configfield => $value) {
1288 if (strpos($configfield, 'config_') !== 0) {
1291 $field = substr($configfield, 7);
1292 $config->$field = $value;
1294 $block->instance_config_save($config);
1297 $bp->visible
= $data->bui_visible
;
1298 $bp->region
= $data->bui_region
;
1299 $bp->weight
= $data->bui_weight
;
1300 $needbprecord = !$data->bui_visible ||
$data->bui_region
!= $data->bui_defaultregion ||
1301 $data->bui_weight
!= $data->bui_defaultweight
;
1303 if ($block->instance
->blockpositionid
&& !$needbprecord) {
1304 $DB->delete_records('block_positions', array('id' => $block->instance
->blockpositionid
));
1306 } else if ($block->instance
->blockpositionid
&& $needbprecord) {
1307 $bp->id
= $block->instance
->blockpositionid
;
1308 $DB->update_record('block_positions', $bp);
1310 } else if ($needbprecord) {
1311 $bp->blockinstanceid
= $block->instance
->id
;
1312 $bp->contextid
= $this->page
->context
->id
;
1313 $bp->pagetype
= $this->page
->pagetype
;
1314 if ($this->page
->subpage
) {
1315 $bp->subpage
= $this->page
->subpage
;
1319 $DB->insert_record('block_positions', $bp);
1322 redirect($this->page
->url
);
1325 $strheading = get_string('blockconfiga', 'moodle', $block->get_title());
1326 $editpage->set_title($strheading);
1327 $editpage->set_heading($strheading);
1328 $bits = explode('-', $this->page
->pagetype
);
1329 if ($bits[0] == 'tag' && !empty($this->page
->subpage
)) {
1330 // better navbar for tag pages
1331 $editpage->navbar
->add(get_string('tags'), new moodle_url('/tag/'));
1332 $tag = tag_get('id', $this->page
->subpage
, '*');
1333 // tag search page doesn't have subpageid
1335 $editpage->navbar
->add($tag->name
, new moodle_url('/tag/index.php', array('id'=>$tag->id
)));
1338 $editpage->navbar
->add($block->get_title());
1339 $editpage->navbar
->add(get_string('configuration'));
1340 echo $output->header();
1341 echo $output->heading($strheading, 2);
1343 echo $output->footer();
1349 * Handle showing/processing the submission from the block editing form.
1350 * @return boolean true if the form was submitted and the new config saved. Does not
1351 * return if the editing form was displayed. False otherwise.
1353 public function process_url_move() {
1354 global $CFG, $DB, $PAGE;
1356 $blockid = optional_param('bui_moveid', null, PARAM_INTEGER
);
1363 $block = $this->find_instance($blockid);
1365 if (!$this->page
->user_can_edit_blocks()) {
1366 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('editblock'));
1369 $newregion = optional_param('bui_newregion', '', PARAM_ALPHANUMEXT
);
1370 $newweight = optional_param('bui_newweight', null, PARAM_FLOAT
);
1371 if (!$newregion ||
is_null($newweight)) {
1372 // Don't have a valid target position yet, must be just starting the move.
1373 $this->movingblock
= $blockid;
1374 $this->page
->ensure_param_not_in_url('bui_moveid');
1378 if (!$this->is_known_region($newregion)) {
1379 throw new moodle_exception('unknownblockregion', '', $this->page
->url
, $newregion);
1382 // Move this block. This may involve moving other nearby blocks.
1383 $blocks = $this->birecordsbyregion
[$newregion];
1385 $maxweight = self
::MAX_WEIGHT
;
1386 $minweight = -self
::MAX_WEIGHT
;
1388 // Initialise the used weights and spareweights array with the default values
1389 $spareweights = array();
1390 $usedweights = array();
1391 for ($i = $minweight; $i <= $maxweight; $i++
) {
1392 $spareweights[$i] = $i;
1393 $usedweights[$i] = array();
1396 // Check each block and sort out where we have used weights
1397 foreach ($blocks as $bi) {
1398 if ($bi->weight
> $maxweight) {
1399 // If this statement is true then the blocks weight is more than the
1400 // current maximum. To ensure that we can get the best block position
1401 // we will initialise elements within the usedweights and spareweights
1402 // arrays between the blocks weight (which will then be the new max) and
1404 $parseweight = $bi->weight
;
1405 while (!array_key_exists($parseweight, $usedweights)) {
1406 $usedweights[$parseweight] = array();
1407 $spareweights[$parseweight] = $parseweight;
1410 $maxweight = $bi->weight
;
1411 } else if ($bi->weight
< $minweight) {
1412 // As above except this time the blocks weight is LESS than the
1413 // the current minimum, so we will initialise the array from the
1414 // blocks weight (new minimum) to the current minimum
1415 $parseweight = $bi->weight
;
1416 while (!array_key_exists($parseweight, $usedweights)) {
1417 $usedweights[$parseweight] = array();
1418 $spareweights[$parseweight] = $parseweight;
1421 $minweight = $bi->weight
;
1423 if ($bi->id
!= $block->instance
->id
) {
1424 unset($spareweights[$bi->weight
]);
1425 $usedweights[$bi->weight
][] = $bi->id
;
1429 // First we find the nearest gap in the list of weights.
1430 $bestdistance = max(abs($newweight - self
::MAX_WEIGHT
), abs($newweight + self
::MAX_WEIGHT
)) +
1;
1432 foreach ($spareweights as $spareweight) {
1433 if (abs($newweight - $spareweight) < $bestdistance) {
1434 $bestdistance = abs($newweight - $spareweight);
1435 $bestgap = $spareweight;
1439 // If there is no gap, we have to go outside -self::MAX_WEIGHT .. self::MAX_WEIGHT.
1440 if (is_null($bestgap)) {
1441 $bestgap = self
::MAX_WEIGHT +
1;
1442 while (!empty($usedweights[$bestgap])) {
1447 // Now we know the gap we are aiming for, so move all the blocks along.
1448 if ($bestgap < $newweight) {
1449 $newweight = floor($newweight);
1450 for ($weight = $bestgap +
1; $weight <= $newweight; $weight++
) {
1451 foreach ($usedweights[$weight] as $biid) {
1452 $this->reposition_block($biid, $newregion, $weight - 1);
1455 $this->reposition_block($block->instance
->id
, $newregion, $newweight);
1457 $newweight = ceil($newweight);
1458 for ($weight = $bestgap - 1; $weight >= $newweight; $weight--) {
1459 foreach ($usedweights[$weight] as $biid) {
1460 $this->reposition_block($biid, $newregion, $weight +
1);
1463 $this->reposition_block($block->instance
->id
, $newregion, $newweight);
1466 $this->page
->ensure_param_not_in_url('bui_moveid');
1467 $this->page
->ensure_param_not_in_url('bui_newregion');
1468 $this->page
->ensure_param_not_in_url('bui_newweight');
1473 * Turns the display of normal blocks either on or off.
1475 * @param bool $setting
1477 public function show_only_fake_blocks($setting = true) {
1478 $this->fakeblocksonly
= $setting;
1482 /// Helper functions for working with block classes ============================
1485 * Call a class method (one that does not require a block instance) on a block class.
1487 * @param string $blockname the name of the block.
1488 * @param string $method the method name.
1489 * @param array $param parameters to pass to the method.
1490 * @return mixed whatever the method returns.
1492 function block_method_result($blockname, $method, $param = NULL) {
1493 if(!block_load_class($blockname)) {
1496 return call_user_func(array('block_'.$blockname, $method), $param);
1500 * Creates a new instance of the specified block class.
1502 * @param string $blockname the name of the block.
1503 * @param $instance block_instances DB table row (optional).
1504 * @param moodle_page $page the page this block is appearing on.
1505 * @return block_base the requested block instance.
1507 function block_instance($blockname, $instance = NULL, $page = NULL) {
1508 if(!block_load_class($blockname)) {
1511 $classname = 'block_'.$blockname;
1512 $retval = new $classname;
1513 if($instance !== NULL) {
1514 if (is_null($page)) {
1518 $retval->_load_instance($instance, $page);
1524 * Load the block class for a particular type of block.
1526 * @param string $blockname the name of the block.
1527 * @return boolean success or failure.
1529 function block_load_class($blockname) {
1532 if(empty($blockname)) {
1536 $classname = 'block_'.$blockname;
1538 if(class_exists($classname)) {
1542 $blockpath = $CFG->dirroot
.'/blocks/'.$blockname.'/block_'.$blockname.'.php';
1544 if (file_exists($blockpath)) {
1545 require_once($CFG->dirroot
.'/blocks/moodleblock.class.php');
1546 include_once($blockpath);
1548 //debugging("$blockname code does not exist in $blockpath", DEBUG_DEVELOPER);
1552 return class_exists($classname);
1556 * Given a specific page type, return all the page type patterns that might
1559 * @param string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
1560 * @return array an array of all the page type patterns that might match this page type.
1562 function matching_page_type_patterns($pagetype) {
1563 $patterns = array($pagetype);
1564 $bits = explode('-', $pagetype);
1565 if (count($bits) == 3 && $bits[0] == 'mod') {
1566 if ($bits[2] == 'view') {
1567 $patterns[] = 'mod-*-view';
1568 } else if ($bits[2] == 'index') {
1569 $patterns[] = 'mod-*-index';
1572 while (count($bits) > 0) {
1573 $patterns[] = implode('-', $bits) . '-*';
1581 * Given a specific page type, parent context and currect context, return all the page type patterns
1582 * that might be used by this block.
1584 * @param string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
1585 * @param stdClass $parentcontext Block's parent context
1586 * @param stdClass $currentcontext Current context of block
1587 * @return array an array of all the page type patterns that might match this page type.
1589 function generate_page_type_patterns($pagetype, $parentcontext = null, $currentcontext = null) {
1592 $bits = explode('-', $pagetype);
1594 $core = get_core_subsystems();
1595 $plugins = get_plugin_types();
1597 //progressively strip pieces off the page type looking for a match
1598 $componentarray = null;
1599 for ($i = count($bits); $i > 0; $i--) {
1600 $possiblecomponentarray = array_slice($bits, 0, $i);
1601 $possiblecomponent = implode('', $possiblecomponentarray);
1603 // Check to see if the component is a core component
1604 if (array_key_exists($possiblecomponent, $core) && !empty($core[$possiblecomponent])) {
1605 $libfile = $CFG->dirroot
.'/'.$core[$possiblecomponent].'/lib.php';
1606 if (file_exists($libfile)) {
1607 require_once($libfile);
1608 $function = $possiblecomponent.'_page_type_list';
1609 if (function_exists($function)) {
1610 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1617 //check the plugin directory and look for a callback
1618 if (array_key_exists($possiblecomponent, $plugins) && !empty($plugins[$possiblecomponent])) {
1620 //We've found a plugin type. Look for a plugin name by getting the next section of page type
1621 if (count($bits) > $i) {
1622 $pluginname = $bits[$i];
1623 $directory = get_plugin_directory($possiblecomponent, $pluginname);
1624 if (!empty($directory)){
1625 $libfile = $directory.'/lib.php';
1626 if (file_exists($libfile)) {
1627 require_once($libfile);
1628 $function = $possiblecomponent.'_'.$pluginname.'_page_type_list';
1629 if (!function_exists($function)) {
1630 $function = $pluginname.'_page_type_list';
1632 if (function_exists($function)) {
1633 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1641 //we'll only get to here if we still don't have any patterns
1642 //the plugin type may have a callback
1643 $directory = get_plugin_directory($possiblecomponent, null);
1644 if (!empty($directory)){
1645 $libfile = $directory.'/lib.php';
1646 if (file_exists($libfile)) {
1647 require_once($libfile);
1648 $function = $possiblecomponent.'_page_type_list';
1649 if (function_exists($function)) {
1650 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1659 if (empty($patterns)) {
1660 $patterns = default_page_type_list($pagetype, $parentcontext, $currentcontext);
1667 * Generates a default page type list when a more appropriate callback cannot be decided upon.
1669 * @param string $pagetype
1670 * @param stdClass $parentcontext
1671 * @param stdClass $currentcontext
1674 function default_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1675 // Generate page type patterns based on current page type if
1676 // callbacks haven't been defined
1677 $patterns = array($pagetype => $pagetype);
1678 $bits = explode('-', $pagetype);
1679 while (count($bits) > 0) {
1680 $pattern = implode('-', $bits) . '-*';
1681 $pagetypestringname = 'page-'.str_replace('*', 'x', $pattern);
1682 // guessing page type description
1683 if (get_string_manager()->string_exists($pagetypestringname, 'pagetype')) {
1684 $patterns[$pattern] = get_string($pagetypestringname, 'pagetype');
1686 $patterns[$pattern] = $pattern;
1690 $patterns['*'] = get_string('page-x', 'pagetype');
1695 * Generates the page type list for the my moodle page
1697 * @param string $pagetype
1698 * @param stdClass $parentcontext
1699 * @param stdClass $currentcontext
1702 function my_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1703 return array('my-index' => 'my-index');
1707 * Generates the page type list for a module by either locating and using the modules callback
1708 * or by generating a default list.
1710 * @param string $pagetype
1711 * @param stdClass $parentcontext
1712 * @param stdClass $currentcontext
1715 function mod_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1716 $patterns = plugin_page_type_list($pagetype, $parentcontext, $currentcontext);
1717 if (empty($patterns)) {
1718 // if modules don't have callbacks
1719 // generate two default page type patterns for modules only
1720 $bits = explode('-', $pagetype);
1721 $patterns = array($pagetype => $pagetype);
1722 if ($bits[2] == 'view') {
1723 $patterns['mod-*-view'] = get_string('page-mod-x-view', 'pagetype');
1724 } else if ($bits[2] == 'index') {
1725 $patterns['mod-*-index'] = get_string('page-mod-x-index', 'pagetype');
1730 /// Functions update the blocks if required by the request parameters ==========
1733 * Return a {@link block_contents} representing the add a new block UI, if
1734 * this user is allowed to see it.
1736 * @return block_contents an appropriate block_contents, or null if the user
1737 * cannot add any blocks here.
1739 function block_add_block_ui($page, $output) {
1740 global $CFG, $OUTPUT;
1741 if (!$page->user_is_editing() ||
!$page->user_can_edit_blocks()) {
1745 $bc = new block_contents();
1746 $bc->title
= get_string('addblock');
1747 $bc->add_class('block_adminblock');
1749 $missingblocks = $page->blocks
->get_addable_blocks();
1750 if (empty($missingblocks)) {
1751 $bc->content
= get_string('noblockstoaddhere');
1756 foreach ($missingblocks as $block) {
1757 $blockobject = block_instance($block->name
);
1758 if ($blockobject !== false && $blockobject->user_can_addto($page)) {
1759 $menu[$block->name
] = $blockobject->get_title();
1762 collatorlib
::asort($menu);
1764 $actionurl = new moodle_url($page->url
, array('sesskey'=>sesskey()));
1765 $select = new single_select($actionurl, 'bui_addblock', $menu, null, array(''=>get_string('adddots')), 'add_block');
1766 $bc->content
= $OUTPUT->render($select);
1770 // Functions that have been deprecated by block_manager =======================
1773 * @deprecated since Moodle 2.0 - use $page->blocks->get_addable_blocks();
1775 * This function returns an array with the IDs of any blocks that you can add to your page.
1776 * Parameters are passed by reference for speed; they are not modified at all.
1778 * @param $page the page object.
1779 * @param $blockmanager Not used.
1780 * @return array of block type ids.
1782 function blocks_get_missing(&$page, &$blockmanager) {
1783 debugging('blocks_get_missing is deprecated. Please use $page->blocks->get_addable_blocks() instead.', DEBUG_DEVELOPER
);
1784 $blocks = $page->blocks
->get_addable_blocks();
1786 foreach ($blocks as $block) {
1787 $ids[] = $block->id
;
1793 * Actually delete from the database any blocks that are currently on this page,
1794 * but which should not be there according to blocks_name_allowed_in_format.
1796 * @todo Write/Fix this function. Currently returns immediately
1799 function blocks_remove_inappropriate($course) {
1803 $blockmanager = blocks_get_by_page($page);
1805 if (empty($blockmanager)) {
1809 if (($pageformat = $page->pagetype) == NULL) {
1813 foreach($blockmanager as $region) {
1814 foreach($region as $instance) {
1815 $block = blocks_get_record($instance->blockid);
1816 if(!blocks_name_allowed_in_format($block->name, $pageformat)) {
1817 blocks_delete_instance($instance->instance);
1824 * Check that a given name is in a permittable format
1826 * @param string $name
1827 * @param string $pageformat
1830 function blocks_name_allowed_in_format($name, $pageformat) {
1833 $formats = block_method_result($name, 'applicable_formats');
1837 foreach ($formats as $format => $allowed) {
1838 $formatregex = '/^'.str_replace('*', '[^-]*', $format).'.*$/';
1839 $depth = substr_count($format, '-');
1840 if (preg_match($formatregex, $pageformat) && $depth > $maxdepth) {
1845 if ($accept === NULL) {
1846 $accept = !empty($formats['all']);
1852 * Delete a block, and associated data.
1854 * @param object $instance a row from the block_instances table
1855 * @param bool $nolongerused legacy parameter. Not used, but kept for backwards compatibility.
1856 * @param bool $skipblockstables for internal use only. Makes @see blocks_delete_all_for_context() more efficient.
1858 function blocks_delete_instance($instance, $nolongerused = false, $skipblockstables = false) {
1861 if ($block = block_instance($instance->blockname
, $instance)) {
1862 $block->instance_delete();
1864 delete_context(CONTEXT_BLOCK
, $instance->id
);
1866 if (!$skipblockstables) {
1867 $DB->delete_records('block_positions', array('blockinstanceid' => $instance->id
));
1868 $DB->delete_records('block_instances', array('id' => $instance->id
));
1869 $DB->delete_records_list('user_preferences', 'name', array('block'.$instance->id
.'hidden','docked_block_instance_'.$instance->id
));
1874 * Delete all the blocks that belong to a particular context.
1876 * @param int $contextid the context id.
1878 function blocks_delete_all_for_context($contextid) {
1880 $instances = $DB->get_recordset('block_instances', array('parentcontextid' => $contextid));
1881 foreach ($instances as $instance) {
1882 blocks_delete_instance($instance, true);
1884 $instances->close();
1885 $DB->delete_records('block_instances', array('parentcontextid' => $contextid));
1886 $DB->delete_records('block_positions', array('contextid' => $contextid));
1890 * Set a block to be visible or hidden on a particular page.
1892 * @param object $instance a row from the block_instances, preferably LEFT JOINed with the
1893 * block_positions table as return by block_manager.
1894 * @param moodle_page $page the back to set the visibility with respect to.
1895 * @param integer $newvisibility 1 for visible, 0 for hidden.
1897 function blocks_set_visibility($instance, $page, $newvisibility) {
1899 if (!empty($instance->blockpositionid
)) {
1900 // Already have local information on this page.
1901 $DB->set_field('block_positions', 'visible', $newvisibility, array('id' => $instance->blockpositionid
));
1905 // Create a new block_positions record.
1907 $bp->blockinstanceid
= $instance->id
;
1908 $bp->contextid
= $page->context
->id
;
1909 $bp->pagetype
= $page->pagetype
;
1910 if ($page->subpage
) {
1911 $bp->subpage
= $page->subpage
;
1913 $bp->visible
= $newvisibility;
1914 $bp->region
= $instance->defaultregion
;
1915 $bp->weight
= $instance->defaultweight
;
1916 $DB->insert_record('block_positions', $bp);
1920 * @deprecated since 2.0
1921 * Delete all the blocks from a particular page.
1923 * @param string $pagetype the page type.
1924 * @param integer $pageid the page id.
1925 * @return bool success or failure.
1927 function blocks_delete_all_on_page($pagetype, $pageid) {
1930 debugging('Call to deprecated function blocks_delete_all_on_page. ' .
1931 'This function cannot work any more. Doing nothing. ' .
1932 'Please update your code to use a block_manager method $PAGE->blocks->....', DEBUG_DEVELOPER
);
1937 * Dispite what this function is called, it seems to be mostly used to populate
1938 * the default blocks when a new course (or whatever) is created.
1940 * @deprecated since 2.0
1942 * @param object $page the page to add default blocks to.
1943 * @return boolean success or failure.
1945 function blocks_repopulate_page($page) {
1948 debugging('Call to deprecated function blocks_repopulate_page. ' .
1949 'Use a more specific method like blocks_add_default_course_blocks, ' .
1950 'or just call $PAGE->blocks->add_blocks()', DEBUG_DEVELOPER
);
1952 /// If the site override has been defined, it is the only valid one.
1953 if (!empty($CFG->defaultblocks_override
)) {
1954 $blocknames = $CFG->defaultblocks_override
;
1956 $blocknames = $page->blocks_get_default();
1959 $blocks = blocks_parse_default_blocks_list($blocknames);
1960 $page->blocks
->add_blocks($blocks);
1966 * Get the block record for a particular blockid - that is, a particular type os block.
1968 * @param $int blockid block type id. If null, an array of all block types is returned.
1969 * @param bool $notusedanymore No longer used.
1970 * @return array|object row from block table, or all rows.
1972 function blocks_get_record($blockid = NULL, $notusedanymore = false) {
1974 $blocks = $PAGE->blocks
->get_installed_blocks();
1975 if ($blockid === NULL) {
1977 } else if (isset($blocks[$blockid])) {
1978 return $blocks[$blockid];
1985 * Find a given block by its blockid within a provide array
1987 * @param int $blockid
1988 * @param array $blocksarray
1989 * @return bool|object Instance if found else false
1991 function blocks_find_block($blockid, $blocksarray) {
1992 if (empty($blocksarray)) {
1995 foreach($blocksarray as $blockgroup) {
1996 if (empty($blockgroup)) {
1999 foreach($blockgroup as $instance) {
2000 if($instance->blockid
== $blockid) {
2008 // Functions for programatically adding default blocks to pages ================
2011 * Parse a list of default blocks. See config-dist for a description of the format.
2013 * @param string $blocksstr
2016 function blocks_parse_default_blocks_list($blocksstr) {
2018 $bits = explode(':', $blocksstr);
2019 if (!empty($bits)) {
2020 $leftbits = trim(array_shift($bits));
2021 if ($leftbits != '') {
2022 $blocks[BLOCK_POS_LEFT
] = explode(',', $leftbits);
2025 if (!empty($bits)) {
2026 $rightbits =trim(array_shift($bits));
2027 if ($rightbits != '') {
2028 $blocks[BLOCK_POS_RIGHT
] = explode(',', $rightbits);
2035 * @return array the blocks that should be added to the site course by default.
2037 function blocks_get_default_site_course_blocks() {
2040 if (!empty($CFG->defaultblocks_site
)) {
2041 return blocks_parse_default_blocks_list($CFG->defaultblocks_site
);
2044 BLOCK_POS_LEFT
=> array('site_main_menu'),
2045 BLOCK_POS_RIGHT
=> array('course_summary', 'calendar_month')
2051 * Add the default blocks to a course.
2053 * @param object $course a course object.
2055 function blocks_add_default_course_blocks($course) {
2058 if (!empty($CFG->defaultblocks_override
)) {
2059 $blocknames = blocks_parse_default_blocks_list($CFG->defaultblocks_override
);
2061 } else if ($course->id
== SITEID
) {
2062 $blocknames = blocks_get_default_site_course_blocks();
2065 $defaultblocks = 'defaultblocks_' . $course->format
;
2066 if (!empty($CFG->$defaultblocks)) {
2067 $blocknames = blocks_parse_default_blocks_list($CFG->$defaultblocks);
2070 $formatconfig = $CFG->dirroot
.'/course/format/'.$course->format
.'/config.php';
2071 $format = array(); // initialize array in external file
2072 if (is_readable($formatconfig)) {
2073 include($formatconfig);
2075 if (!empty($format['defaultblocks'])) {
2076 $blocknames = blocks_parse_default_blocks_list($format['defaultblocks']);
2078 } else if (!empty($CFG->defaultblocks
)){
2079 $blocknames = blocks_parse_default_blocks_list($CFG->defaultblocks
);
2082 $blocknames = array(
2083 BLOCK_POS_LEFT
=> array(),
2084 BLOCK_POS_RIGHT
=> array('search_forums', 'news_items', 'calendar_upcoming', 'recent_activity')
2090 if ($course->id
== SITEID
) {
2091 $pagetypepattern = 'site-index';
2093 $pagetypepattern = 'course-view-*';
2095 $page = new moodle_page();
2096 $page->set_course($course);
2097 $page->blocks
->add_blocks($blocknames, $pagetypepattern);
2101 * Add the default system-context blocks. E.g. the admin tree.
2103 function blocks_add_default_system_blocks() {
2106 $page = new moodle_page();
2107 $page->set_context(get_context_instance(CONTEXT_SYSTEM
));
2108 $page->blocks
->add_blocks(array(BLOCK_POS_LEFT
=> array('navigation', 'settings')), '*', null, true);
2109 $page->blocks
->add_blocks(array(BLOCK_POS_LEFT
=> array('admin_bookmarks')), 'admin-*', null, null, 2);
2111 if ($defaultmypage = $DB->get_record('my_pages', array('userid'=>null, 'name'=>'__default', 'private'=>1))) {
2112 $subpagepattern = $defaultmypage->id
;
2114 $subpagepattern = null;
2117 $page->blocks
->add_blocks(array(BLOCK_POS_RIGHT
=> array('private_files', 'online_users'), 'content' => array('course_overview')), 'my-index', $subpagepattern, false);