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 // If editing is on, we need all the block regions visible, for the
355 return !empty($this->visibleblockcontent
[$region]) ||
!empty($this->extracontent
[$region]);
359 * Get an array of all of the installed blocks.
361 * @return array contents of the block table.
363 public function get_installed_blocks() {
365 if (is_null($this->allblocks
)) {
366 $this->allblocks
= $DB->get_records('block');
368 return $this->allblocks
;
371 /// Setter methods =============================================================
374 * Add a region to a page
376 * @param string $region add a named region where blocks may appear on the
377 * current page. This is an internal name, like 'side-pre', not a string to
380 public function add_region($region) {
381 $this->check_not_yet_loaded();
382 $this->regions
[$region] = 1;
386 * Add an array of regions
389 * @param array $regions this utility method calls add_region for each array element.
391 public function add_regions($regions) {
392 foreach ($regions as $region) {
393 $this->add_region($region);
398 * Set the default region for new blocks on the page
400 * @param string $defaultregion the internal names of the region where new
401 * blocks should be added by default, and where any blocks from an
402 * unrecognised region are shown.
404 public function set_default_region($defaultregion) {
405 $this->check_not_yet_loaded();
406 if ($defaultregion) {
407 $this->check_region_is_known($defaultregion);
409 $this->defaultregion
= $defaultregion;
413 * Add something that looks like a block, but which isn't an actual block_instance,
416 * @param block_contents $bc the content of the block-like thing.
417 * @param string $region a block region that exists on this page.
419 public function add_fake_block($bc, $region) {
420 $this->page
->initialise_theme_and_output();
421 if (!$this->is_known_region($region)) {
422 $region = $this->get_default_region();
424 if (array_key_exists($region, $this->visibleblockcontent
)) {
425 throw new coding_exception('block_manager has already prepared the blocks in region ' .
426 $region . 'for output. It is too late to add a fake block.');
428 $this->extracontent
[$region][] = $bc;
432 * When the block_manager class was created, the {@link add_fake_block()}
433 * was called add_pretend_block, which is inconsisted with
434 * {@link show_only_fake_blocks()}. To fix this inconsistency, this method
435 * was renamed to add_fake_block. Please update your code.
436 * @param block_contents $bc the content of the block-like thing.
437 * @param string $region a block region that exists on this page.
439 public function add_pretend_block($bc, $region) {
440 debugging(DEBUG_DEVELOPER
, 'add_pretend_block has been renamed to add_fake_block. Please rename the method call in your code.');
441 $this->add_fake_block($bc, $region);
445 * Checks to see whether all of the blocks within the given region are docked
447 * @see region_uses_dock
448 * @param string $region
449 * @return bool True if all of the blocks within that region are docked
451 public function region_completely_docked($region, $output) {
452 if (!$this->page
->theme
->enable_dock
) {
455 $this->check_is_loaded();
456 $this->ensure_content_created($region, $output);
457 foreach($this->visibleblockcontent
[$region] as $instance) {
458 if (!empty($instance->content
) && !get_user_preferences('docked_block_instance_'.$instance->blockinstanceid
, 0)) {
466 * Checks to see whether any of the blocks within the given regions are docked
468 * @see region_completely_docked
469 * @param array|string $regions array of regions (or single region)
470 * @return bool True if any of the blocks within that region are docked
472 public function region_uses_dock($regions, $output) {
473 if (!$this->page
->theme
->enable_dock
) {
476 $this->check_is_loaded();
477 foreach((array)$regions as $region) {
478 $this->ensure_content_created($region, $output);
479 foreach($this->visibleblockcontent
[$region] as $instance) {
480 if(!empty($instance->content
) && get_user_preferences('docked_block_instance_'.$instance->blockinstanceid
, 0)) {
488 /// Actions ====================================================================
491 * This method actually loads the blocks for our page from the database.
493 * @param boolean|null $includeinvisible
494 * null (default) - load hidden blocks if $this->page->user_is_editing();
495 * true - load hidden blocks.
496 * false - don't load hidden blocks.
498 public function load_blocks($includeinvisible = null) {
501 if (!is_null($this->birecordsbyregion
)) {
506 if ($CFG->version
< 2009050619) {
507 // Upgrade/install not complete. Don't try too show any blocks.
508 $this->birecordsbyregion
= array();
512 // Ensure we have been initialised.
513 if (is_null($this->defaultregion
)) {
514 $this->page
->initialise_theme_and_output();
515 // If there are still no block regions, then there are no blocks on this page.
516 if (empty($this->regions
)) {
517 $this->birecordsbyregion
= array();
522 // Check if we need to load normal blocks
523 if ($this->fakeblocksonly
) {
524 $this->birecordsbyregion
= $this->prepare_per_region_arrays();
528 if (is_null($includeinvisible)) {
529 $includeinvisible = $this->page
->user_is_editing();
531 if ($includeinvisible) {
534 $visiblecheck = 'AND (bp.visible = 1 OR bp.visible IS NULL)';
537 $context = $this->page
->context
;
538 $contexttest = 'bi.parentcontextid = :contextid2';
539 $parentcontextparams = array();
540 $parentcontextids = get_parent_contexts($context);
541 if ($parentcontextids) {
542 list($parentcontexttest, $parentcontextparams) =
543 $DB->get_in_or_equal($parentcontextids, SQL_PARAMS_NAMED
, 'parentcontext');
544 $contexttest = "($contexttest OR (bi.showinsubcontexts = 1 AND bi.parentcontextid $parentcontexttest))";
547 $pagetypepatterns = matching_page_type_patterns($this->page
->pagetype
);
548 list($pagetypepatterntest, $pagetypepatternparams) =
549 $DB->get_in_or_equal($pagetypepatterns, SQL_PARAMS_NAMED
, 'pagetypepatterntest');
551 list($ccselect, $ccjoin) = context_instance_preload_sql('bi.id', CONTEXT_BLOCK
, 'ctx');
554 'subpage1' => $this->page
->subpage
,
555 'subpage2' => $this->page
->subpage
,
556 'contextid1' => $context->id
,
557 'contextid2' => $context->id
,
558 'pagetype' => $this->page
->pagetype
,
560 if ($this->page
->subpage
=== '') {
561 $params['subpage1'] = $DB->sql_empty();
562 $params['subpage2'] = $DB->sql_empty();
566 bp.id AS blockpositionid,
569 bi.showinsubcontexts,
574 COALESCE(bp.visible, 1) AS visible,
575 COALESCE(bp.region, bi.defaultregion) AS region,
576 COALESCE(bp.weight, bi.defaultweight) AS weight,
580 FROM {block_instances} bi
581 JOIN {block} b ON bi.blockname = b.name
582 LEFT JOIN {block_positions} bp ON bp.blockinstanceid = bi.id
583 AND bp.contextid = :contextid1
584 AND bp.pagetype = :pagetype
585 AND bp.subpage = :subpage1
590 AND bi.pagetypepattern $pagetypepatterntest
591 AND (bi.subpagepattern IS NULL OR bi.subpagepattern = :subpage2)
596 COALESCE(bp.region, bi.defaultregion),
597 COALESCE(bp.weight, bi.defaultweight),
599 $blockinstances = $DB->get_recordset_sql($sql, $params +
$parentcontextparams +
$pagetypepatternparams);
601 $this->birecordsbyregion
= $this->prepare_per_region_arrays();
603 foreach ($blockinstances as $bi) {
604 context_instance_preload($bi);
605 if ($this->is_known_region($bi->region
)) {
606 $this->birecordsbyregion
[$bi->region
][] = $bi;
612 // Pages don't necessarily have a defaultregion. The one time this can
613 // happen is when there are no theme block regions, but the script itself
614 // has a block region in the main content area.
615 if (!empty($this->defaultregion
)) {
616 $this->birecordsbyregion
[$this->defaultregion
] =
617 array_merge($this->birecordsbyregion
[$this->defaultregion
], $unknown);
622 * Add a block to the current page, or related pages. The block is added to
623 * context $this->page->contextid. If $pagetypepattern $subpagepattern
625 * @param string $blockname The type of block to add.
626 * @param string $region the block region on this page to add the block to.
627 * @param integer $weight determines the order where this block appears in the region.
628 * @param boolean $showinsubcontexts whether this block appears in subcontexts, or just the current context.
629 * @param string|null $pagetypepattern which page types this block should appear on. Defaults to just the current page type.
630 * @param string|null $subpagepattern which subpage this block should appear on. NULL = any (the default), otherwise only the specified subpage.
632 public function add_block($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern = NULL, $subpagepattern = NULL) {
634 // Allow invisible blocks because this is used when adding default page blocks, which
635 // might include invisible ones if the user makes some default blocks invisible
636 $this->check_known_block_type($blockname, true);
637 $this->check_region_is_known($region);
639 if (empty($pagetypepattern)) {
640 $pagetypepattern = $this->page
->pagetype
;
643 $blockinstance = new stdClass
;
644 $blockinstance->blockname
= $blockname;
645 $blockinstance->parentcontextid
= $this->page
->context
->id
;
646 $blockinstance->showinsubcontexts
= !empty($showinsubcontexts);
647 $blockinstance->pagetypepattern
= $pagetypepattern;
648 $blockinstance->subpagepattern
= $subpagepattern;
649 $blockinstance->defaultregion
= $region;
650 $blockinstance->defaultweight
= $weight;
651 $blockinstance->configdata
= '';
652 $blockinstance->id
= $DB->insert_record('block_instances', $blockinstance);
654 // Ensure the block context is created.
655 get_context_instance(CONTEXT_BLOCK
, $blockinstance->id
);
657 // If the new instance was created, allow it to do additional setup
658 if ($block = block_instance($blockname, $blockinstance)) {
659 $block->instance_create();
663 public function add_block_at_end_of_default_region($blockname) {
664 $defaulregion = $this->get_default_region();
666 $lastcurrentblock = end($this->birecordsbyregion
[$defaulregion]);
667 if ($lastcurrentblock) {
668 $weight = $lastcurrentblock->weight +
1;
673 if ($this->page
->subpage
) {
674 $subpage = $this->page
->subpage
;
679 // Special case. Course view page type include the course format, but we
680 // want to add the block non-format-specifically.
681 $pagetypepattern = $this->page
->pagetype
;
682 if (strpos($pagetypepattern, 'course-view') === 0) {
683 $pagetypepattern = 'course-view-*';
686 // We should end using this for ALL the blocks, making always the 1st option
687 // the default one to be used. Until then, this is one hack to avoid the
688 // 'pagetypewarning' message on blocks initial edition (MDL-27829) caused by
689 // non-existing $pagetypepattern set. This way at least we guarantee one "valid"
690 // (the FIRST $pagetypepattern will be set)
692 // We are applying it to all blocks created in mod pages for now and only if the
693 // default pagetype is not one of the available options
694 if (preg_match('/^mod-.*-/', $pagetypepattern)) {
695 $pagetypelist = generate_page_type_patterns($this->page
->pagetype
, null, $this->page
->context
);
696 // Only go for the first if the pagetype is not a valid option
697 if (is_array($pagetypelist) && !array_key_exists($pagetypepattern, $pagetypelist)) {
698 $pagetypepattern = key($pagetypelist);
701 // Surely other pages like course-report will need this too, they just are not important
702 // enough now. This will be decided in the coming days. (MDL-27829, MDL-28150)
704 $this->add_block($blockname, $defaulregion, $weight, false, $pagetypepattern, $subpage);
708 * Convenience method, calls add_block repeatedly for all the blocks in $blocks.
710 * @param array $blocks array with array keys the region names, and values an array of block names.
711 * @param string $pagetypepattern optional. Passed to @see add_block()
712 * @param string $subpagepattern optional. Passed to @see add_block()
714 public function add_blocks($blocks, $pagetypepattern = NULL, $subpagepattern = NULL, $showinsubcontexts=false, $weight=0) {
715 $this->add_regions(array_keys($blocks));
716 foreach ($blocks as $region => $regionblocks) {
718 foreach ($regionblocks as $blockname) {
719 $this->add_block($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern, $subpagepattern);
726 * Move a block to a new position on this page.
728 * If this block cannot appear on any other pages, then we change defaultposition/weight
729 * in the block_instances table. Otherwise we just set the position on this page.
731 * @param $blockinstanceid the block instance id.
732 * @param $newregion the new region name.
733 * @param $newweight the new weight.
735 public function reposition_block($blockinstanceid, $newregion, $newweight) {
738 $this->check_region_is_known($newregion);
739 $inst = $this->find_instance($blockinstanceid);
741 $bi = $inst->instance
;
742 if ($bi->weight
== $bi->defaultweight
&& $bi->region
== $bi->defaultregion
&&
743 !$bi->showinsubcontexts
&& strpos($bi->pagetypepattern
, '*') === false &&
744 (!$this->page
->subpage ||
$bi->subpagepattern
)) {
746 // Set default position
747 $newbi = new stdClass
;
748 $newbi->id
= $bi->id
;
749 $newbi->defaultregion
= $newregion;
750 $newbi->defaultweight
= $newweight;
751 $DB->update_record('block_instances', $newbi);
753 if ($bi->blockpositionid
) {
755 $bp->id
= $bi->blockpositionid
;
756 $bp->region
= $newregion;
757 $bp->weight
= $newweight;
758 $DB->update_record('block_positions', $bp);
762 // Just set position on this page.
764 $bp->region
= $newregion;
765 $bp->weight
= $newweight;
767 if ($bi->blockpositionid
) {
768 $bp->id
= $bi->blockpositionid
;
769 $DB->update_record('block_positions', $bp);
772 $bp->blockinstanceid
= $bi->id
;
773 $bp->contextid
= $this->page
->context
->id
;
774 $bp->pagetype
= $this->page
->pagetype
;
775 if ($this->page
->subpage
) {
776 $bp->subpage
= $this->page
->subpage
;
780 $bp->visible
= $bi->visible
;
781 $DB->insert_record('block_positions', $bp);
787 * Find a given block by its instance id
789 * @param integer $instanceid
792 public function find_instance($instanceid) {
793 foreach ($this->regions
as $region => $notused) {
794 $this->ensure_instances_exist($region);
795 foreach($this->blockinstances
[$region] as $instance) {
796 if ($instance->instance
->id
== $instanceid) {
801 throw new block_not_on_page_exception($instanceid, $this->page
);
804 /// Inner workings =============================================================
807 * Check whether the page blocks have been loaded yet
809 * @return void Throws coding exception if already loaded
811 protected function check_not_yet_loaded() {
812 if (!is_null($this->birecordsbyregion
)) {
813 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.');
818 * Check whether the page blocks have been loaded yet
820 * Nearly identical to the above function {@link check_not_yet_loaded()} except different message
822 * @return void Throws coding exception if already loaded
824 protected function check_is_loaded() {
825 if (is_null($this->birecordsbyregion
)) {
826 throw new coding_exception('block_manager has not yet loaded the blocks, to it is too soon to request the information you asked for.');
831 * Check if a block type is known and usable
833 * @param string $blockname The block type name to search for
834 * @param bool $includeinvisible Include disabled block types in the initial pass
835 * @return void Coding Exception thrown if unknown or not enabled
837 protected function check_known_block_type($blockname, $includeinvisible = false) {
838 if (!$this->is_known_block_type($blockname, $includeinvisible)) {
839 if ($this->is_known_block_type($blockname, true)) {
840 throw new coding_exception('Unknown block type ' . $blockname);
842 throw new coding_exception('Block type ' . $blockname . ' has been disabled by the administrator.');
848 * Check if a region is known by its name
850 * @param string $region
851 * @return void Coding Exception thrown if the region is not known
853 protected function check_region_is_known($region) {
854 if (!$this->is_known_region($region)) {
855 throw new coding_exception('Trying to reference an unknown block region ' . $region);
860 * Returns an array of region names as keys and nested arrays for values
862 * @return array an array where the array keys are the region names, and the array
863 * values are empty arrays.
865 protected function prepare_per_region_arrays() {
867 foreach ($this->regions
as $region => $notused) {
868 $result[$region] = array();
874 * Create a set of new block instance from a record array
876 * @param array $birecords An array of block instance records
877 * @return array An array of instantiated block_instance objects
879 protected function create_block_instances($birecords) {
881 foreach ($birecords as $record) {
882 if ($blockobject = block_instance($record->blockname
, $record, $this->page
)) {
883 $results[] = $blockobject;
890 * Create all the block instances for all the blocks that were loaded by
891 * load_blocks. This is used, for example, to ensure that all blocks get a
892 * chance to initialise themselves via the {@link block_base::specialize()}
893 * method, before any output is done.
895 public function create_all_block_instances() {
896 foreach ($this->get_regions() as $region) {
897 $this->ensure_instances_exist($region);
902 * Return an array of content objects from a set of block instances
904 * @param array $instances An array of block instances
905 * @param renderer_base The renderer to use.
906 * @param string $region the region name.
907 * @return array An array of block_content (and possibly block_move_target) objects.
909 protected function create_block_contents($instances, $output, $region) {
914 if ($this->movingblock
) {
915 $first = reset($instances);
917 $lastweight = $first->instance
->weight
- 2;
920 $strmoveblockhere = get_string('moveblockhere', 'block');
923 foreach ($instances as $instance) {
924 $content = $instance->get_content_for_output($output);
925 if (empty($content)) {
929 if ($this->movingblock
&& $lastweight != $instance->instance
->weight
&&
930 $content->blockinstanceid
!= $this->movingblock
&& $lastblock != $this->movingblock
) {
931 $results[] = new block_move_target($strmoveblockhere, $this->get_move_target_url($region, ($lastweight +
$instance->instance
->weight
)/2));
934 if ($content->blockinstanceid
== $this->movingblock
) {
935 $content->add_class('beingmoved');
936 $content->annotation
.= get_string('movingthisblockcancel', 'block',
937 html_writer
::link($this->page
->url
, get_string('cancel')));
940 $results[] = $content;
941 $lastweight = $instance->instance
->weight
;
942 $lastblock = $instance->instance
->id
;
945 if ($this->movingblock
&& $lastblock != $this->movingblock
) {
946 $results[] = new block_move_target($strmoveblockhere, $this->get_move_target_url($region, $lastweight +
1));
952 * Ensure block instances exist for a given region
954 * @param string $region Check for bi's with the instance with this name
956 protected function ensure_instances_exist($region) {
957 $this->check_region_is_known($region);
958 if (!array_key_exists($region, $this->blockinstances
)) {
959 $this->blockinstances
[$region] =
960 $this->create_block_instances($this->birecordsbyregion
[$region]);
965 * Ensure that there is some content within the given region
967 * @param string $region The name of the region to check
969 protected function ensure_content_created($region, $output) {
970 $this->ensure_instances_exist($region);
971 if (!array_key_exists($region, $this->visibleblockcontent
)) {
973 if (array_key_exists($region, $this->extracontent
)) {
974 $contents = $this->extracontent
[$region];
976 $contents = array_merge($contents, $this->create_block_contents($this->blockinstances
[$region], $output, $region));
977 if ($region == $this->defaultregion
) {
978 $addblockui = block_add_block_ui($this->page
, $output);
980 $contents[] = $addblockui;
983 $this->visibleblockcontent
[$region] = $contents;
987 /// Process actions from the URL ===============================================
990 * Get the appropriate list of editing icons for a block. This is used
991 * to set {@link block_contents::$controls} in {@link block_base::get_contents_for_output()}.
993 * @param $output The core_renderer to use when generating the output. (Need to get icon paths.)
994 * @return an array in the format for {@link block_contents::$controls}
996 public function edit_controls($block) {
999 if (!isset($CFG->undeletableblocktypes
) ||
(!is_array($CFG->undeletableblocktypes
) && !is_string($CFG->undeletableblocktypes
))) {
1000 $undeletableblocktypes = array('navigation','settings');
1001 } else if (is_string($CFG->undeletableblocktypes
)) {
1002 $undeletableblocktypes = explode(',', $CFG->undeletableblocktypes
);
1004 $undeletableblocktypes = $CFG->undeletableblocktypes
;
1007 $controls = array();
1008 $actionurl = $this->page
->url
->out(false, array('sesskey'=> sesskey()));
1010 if ($this->page
->user_can_edit_blocks()) {
1012 $controls[] = array('url' => $actionurl . '&bui_moveid=' . $block->instance
->id
,
1013 'icon' => 't/move', 'caption' => get_string('move'));
1016 if ($this->page
->user_can_edit_blocks() ||
$block->user_can_edit()) {
1017 // Edit config icon - always show - needed for positioning UI.
1018 $controls[] = array('url' => $actionurl . '&bui_editid=' . $block->instance
->id
,
1019 'icon' => 't/edit', 'caption' => get_string('configuration'));
1022 if ($this->page
->user_can_edit_blocks() && $block->user_can_edit() && $block->user_can_addto($this->page
)) {
1023 if (!in_array($block->instance
->blockname
, $undeletableblocktypes)
1024 ||
!in_array($block->instance
->pagetypepattern
, array('*', 'site-index'))
1025 ||
$block->instance
->parentcontextid
!= SITEID
) {
1027 $controls[] = array('url' => $actionurl . '&bui_deleteid=' . $block->instance
->id
,
1028 'icon' => 't/delete', 'caption' => get_string('delete'));
1032 if ($this->page
->user_can_edit_blocks() && $block->instance_can_be_hidden()) {
1034 if ($block->instance
->visible
) {
1035 $controls[] = array('url' => $actionurl . '&bui_hideid=' . $block->instance
->id
,
1036 'icon' => 't/hide', 'caption' => get_string('hide'));
1038 $controls[] = array('url' => $actionurl . '&bui_showid=' . $block->instance
->id
,
1039 'icon' => 't/show', 'caption' => get_string('show'));
1043 // Assign roles icon.
1044 if (has_capability('moodle/role:assign', $block->context
)) {
1045 //TODO: please note it is sloppy to pass urls through page parameters!!
1046 // it is shortened because some web servers (e.g. IIS by default) give
1047 // a 'security' error if you try to pass a full URL as a GET parameter in another URL.
1048 $return = $this->page
->url
->out(false);
1049 $return = str_replace($CFG->wwwroot
. '/', '', $return);
1051 $controls[] = array('url' => $CFG->wwwroot
. '/' . $CFG->admin
.
1052 '/roles/assign.php?contextid=' . $block->context
->id
. '&returnurl=' . urlencode($return),
1053 'icon' => 'i/roles', 'caption' => get_string('assignroles', 'role'));
1060 * Process any block actions that were specified in the URL.
1062 * This can only be done given a valid $page object.
1064 * @param moodle_page $page the page to add blocks to.
1065 * @return boolean true if anything was done. False if not.
1067 public function process_url_actions() {
1068 if (!$this->page
->user_is_editing()) {
1071 return $this->process_url_add() ||
$this->process_url_delete() ||
1072 $this->process_url_show_hide() ||
$this->process_url_edit() ||
1073 $this->process_url_move();
1077 * Handle adding a block.
1078 * @return boolean true if anything was done. False if not.
1080 public function process_url_add() {
1081 $blocktype = optional_param('bui_addblock', null, PARAM_PLUGIN
);
1088 if (!$this->page
->user_can_edit_blocks()) {
1089 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('addblock'));
1092 if (!array_key_exists($blocktype, $this->get_addable_blocks())) {
1093 throw new moodle_exception('cannotaddthisblocktype', '', $this->page
->url
->out(), $blocktype);
1096 $this->add_block_at_end_of_default_region($blocktype);
1098 // If the page URL was a guess, it will contain the bui_... param, so we must make sure it is not there.
1099 $this->page
->ensure_param_not_in_url('bui_addblock');
1105 * Handle deleting a block.
1106 * @return boolean true if anything was done. False if not.
1108 public function process_url_delete() {
1109 $blockid = optional_param('bui_deleteid', null, PARAM_INTEGER
);
1116 $block = $this->page
->blocks
->find_instance($blockid);
1118 if (!$block->user_can_edit() ||
!$this->page
->user_can_edit_blocks() ||
!$block->user_can_addto($this->page
)) {
1119 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('deleteablock'));
1122 blocks_delete_instance($block->instance
);
1124 // If the page URL was a guess, it will contain the bui_... param, so we must make sure it is not there.
1125 $this->page
->ensure_param_not_in_url('bui_deleteid');
1131 * Handle showing or hiding a block.
1132 * @return boolean true if anything was done. False if not.
1134 public function process_url_show_hide() {
1135 if ($blockid = optional_param('bui_hideid', null, PARAM_INTEGER
)) {
1137 } else if ($blockid = optional_param('bui_showid', null, PARAM_INTEGER
)) {
1145 $block = $this->page
->blocks
->find_instance($blockid);
1147 if (!$this->page
->user_can_edit_blocks()) {
1148 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('hideshowblocks'));
1149 } else if (!$block->instance_can_be_hidden()) {
1153 blocks_set_visibility($block->instance
, $this->page
, $newvisibility);
1155 // If the page URL was a guses, it will contain the bui_... param, so we must make sure it is not there.
1156 $this->page
->ensure_param_not_in_url('bui_hideid');
1157 $this->page
->ensure_param_not_in_url('bui_showid');
1163 * Handle showing/processing the submission from the block editing form.
1164 * @return boolean true if the form was submitted and the new config saved. Does not
1165 * return if the editing form was displayed. False otherwise.
1167 public function process_url_edit() {
1168 global $CFG, $DB, $PAGE, $OUTPUT;
1170 $blockid = optional_param('bui_editid', null, PARAM_INTEGER
);
1176 require_once($CFG->dirroot
. '/blocks/edit_form.php');
1178 $block = $this->find_instance($blockid);
1180 if (!$block->user_can_edit() && !$this->page
->user_can_edit_blocks()) {
1181 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('editblock'));
1184 $editpage = new moodle_page();
1185 $editpage->set_pagelayout('admin');
1186 $editpage->set_course($this->page
->course
);
1187 //$editpage->set_context($block->context);
1188 $editpage->set_context($this->page
->context
);
1189 if ($this->page
->cm
) {
1190 $editpage->set_cm($this->page
->cm
);
1192 $editurlbase = str_replace($CFG->wwwroot
. '/', '/', $this->page
->url
->out_omit_querystring());
1193 $editurlparams = $this->page
->url
->params();
1194 $editurlparams['bui_editid'] = $blockid;
1195 $editpage->set_url($editurlbase, $editurlparams);
1196 $editpage->set_block_actions_done();
1197 // At this point we are either going to redirect, or display the form, so
1198 // overwrite global $PAGE ready for this. (Formslib refers to it.)
1200 //some functions like MoodleQuickForm::addHelpButton use $OUTPUT so we need to replace that to
1201 $output = $editpage->get_renderer('core');
1204 $formfile = $CFG->dirroot
. '/blocks/' . $block->name() . '/edit_form.php';
1205 if (is_readable($formfile)) {
1206 require_once($formfile);
1207 $classname = 'block_' . $block->name() . '_edit_form';
1208 if (!class_exists($classname)) {
1209 $classname = 'block_edit_form';
1212 $classname = 'block_edit_form';
1215 $mform = new $classname($editpage->url
, $block, $this->page
);
1216 $mform->set_data($block->instance
);
1218 if ($mform->is_cancelled()) {
1219 redirect($this->page
->url
);
1221 } else if ($data = $mform->get_data()) {
1223 $bi->id
= $block->instance
->id
;
1224 $bi->pagetypepattern
= $data->bui_pagetypepattern
;
1225 if (empty($data->bui_subpagepattern
) ||
$data->bui_subpagepattern
== '%@NULL@%') {
1226 $bi->subpagepattern
= null;
1228 $bi->subpagepattern
= $data->bui_subpagepattern
;
1231 $parentcontext = get_context_instance_by_id($data->bui_parentcontextid
);
1232 $systemcontext = get_context_instance(CONTEXT_SYSTEM
);
1234 // Updating stickiness and contexts. See MDL-21375 for details.
1235 if (has_capability('moodle/site:manageblocks', $parentcontext)) { // Check permissions in destination
1236 // Explicitly set the context
1237 $bi->parentcontextid
= $parentcontext->id
;
1239 // If the context type is > 0 then we'll explicitly set the block as sticky, otherwise not
1240 $bi->showinsubcontexts
= (int)(!empty($data->bui_contexts
));
1242 // If the block wants to be system-wide, then explicitly set that
1243 if ($data->bui_contexts
== BUI_CONTEXTS_ENTIRE_SITE
) { // Only possible on a frontpage or system page
1244 $bi->parentcontextid
= $systemcontext->id
;
1245 $bi->showinsubcontexts
= BUI_CONTEXTS_CURRENT_SUBS
; //show in current and sub contexts
1246 $bi->pagetypepattern
= '*';
1248 } else { // The block doesn't want to be system-wide, so let's ensure that
1249 if ($parentcontext->id
== $systemcontext->id
) { // We need to move it to the front page
1250 $frontpagecontext = get_context_instance(CONTEXT_COURSE
, SITEID
);
1251 $bi->parentcontextid
= $frontpagecontext->id
;
1252 $bi->pagetypepattern
= 'site-index';
1257 $bits = explode('-', $bi->pagetypepattern
);
1258 // hacks for some contexts
1259 if (($parentcontext->contextlevel
== CONTEXT_COURSE
) && ($parentcontext->instanceid
!= SITEID
)) {
1260 // For course context
1261 // is page type pattern is mod-*, change showinsubcontext to 1
1262 if ($bits[0] == 'mod' ||
$bi->pagetypepattern
== '*') {
1263 $bi->showinsubcontexts
= 1;
1265 $bi->showinsubcontexts
= 0;
1267 } else if ($parentcontext->contextlevel
== CONTEXT_USER
) {
1269 // subpagepattern should be null
1270 if ($bits[0] == 'user' or $bits[0] == 'my') {
1271 // we don't need subpagepattern in usercontext
1272 $bi->subpagepattern
= null;
1276 $bi->defaultregion
= $data->bui_defaultregion
;
1277 $bi->defaultweight
= $data->bui_defaultweight
;
1278 $DB->update_record('block_instances', $bi);
1280 if (!empty($block->config
)) {
1281 $config = clone($block->config
);
1283 $config = new stdClass
;
1285 foreach ($data as $configfield => $value) {
1286 if (strpos($configfield, 'config_') !== 0) {
1289 $field = substr($configfield, 7);
1290 $config->$field = $value;
1292 $block->instance_config_save($config);
1295 $bp->visible
= $data->bui_visible
;
1296 $bp->region
= $data->bui_region
;
1297 $bp->weight
= $data->bui_weight
;
1298 $needbprecord = !$data->bui_visible ||
$data->bui_region
!= $data->bui_defaultregion ||
1299 $data->bui_weight
!= $data->bui_defaultweight
;
1301 if ($block->instance
->blockpositionid
&& !$needbprecord) {
1302 $DB->delete_records('block_positions', array('id' => $block->instance
->blockpositionid
));
1304 } else if ($block->instance
->blockpositionid
&& $needbprecord) {
1305 $bp->id
= $block->instance
->blockpositionid
;
1306 $DB->update_record('block_positions', $bp);
1308 } else if ($needbprecord) {
1309 $bp->blockinstanceid
= $block->instance
->id
;
1310 $bp->contextid
= $this->page
->context
->id
;
1311 $bp->pagetype
= $this->page
->pagetype
;
1312 if ($this->page
->subpage
) {
1313 $bp->subpage
= $this->page
->subpage
;
1317 $DB->insert_record('block_positions', $bp);
1320 redirect($this->page
->url
);
1323 $strheading = get_string('blockconfiga', 'moodle', $block->get_title());
1324 $editpage->set_title($strheading);
1325 $editpage->set_heading($strheading);
1326 $bits = explode('-', $this->page
->pagetype
);
1327 if ($bits[0] == 'tag' && !empty($this->page
->subpage
)) {
1328 // better navbar for tag pages
1329 $editpage->navbar
->add(get_string('tags'), new moodle_url('/tag/'));
1330 $tag = tag_get('id', $this->page
->subpage
, '*');
1331 // tag search page doesn't have subpageid
1333 $editpage->navbar
->add($tag->name
, new moodle_url('/tag/index.php', array('id'=>$tag->id
)));
1336 $editpage->navbar
->add($block->get_title());
1337 $editpage->navbar
->add(get_string('configuration'));
1338 echo $output->header();
1339 echo $output->heading($strheading, 2);
1341 echo $output->footer();
1347 * Handle showing/processing the submission from the block editing form.
1348 * @return boolean true if the form was submitted and the new config saved. Does not
1349 * return if the editing form was displayed. False otherwise.
1351 public function process_url_move() {
1352 global $CFG, $DB, $PAGE;
1354 $blockid = optional_param('bui_moveid', null, PARAM_INTEGER
);
1361 $block = $this->find_instance($blockid);
1363 if (!$this->page
->user_can_edit_blocks()) {
1364 throw new moodle_exception('nopermissions', '', $this->page
->url
->out(), get_string('editblock'));
1367 $newregion = optional_param('bui_newregion', '', PARAM_ALPHANUMEXT
);
1368 $newweight = optional_param('bui_newweight', null, PARAM_FLOAT
);
1369 if (!$newregion ||
is_null($newweight)) {
1370 // Don't have a valid target position yet, must be just starting the move.
1371 $this->movingblock
= $blockid;
1372 $this->page
->ensure_param_not_in_url('bui_moveid');
1376 if (!$this->is_known_region($newregion)) {
1377 throw new moodle_exception('unknownblockregion', '', $this->page
->url
, $newregion);
1380 // Move this block. This may involve moving other nearby blocks.
1381 $blocks = $this->birecordsbyregion
[$newregion];
1383 $maxweight = self
::MAX_WEIGHT
;
1384 $minweight = -self
::MAX_WEIGHT
;
1386 // Initialise the used weights and spareweights array with the default values
1387 $spareweights = array();
1388 $usedweights = array();
1389 for ($i = $minweight; $i <= $maxweight; $i++
) {
1390 $spareweights[$i] = $i;
1391 $usedweights[$i] = array();
1394 // Check each block and sort out where we have used weights
1395 foreach ($blocks as $bi) {
1396 if ($bi->weight
> $maxweight) {
1397 // If this statement is true then the blocks weight is more than the
1398 // current maximum. To ensure that we can get the best block position
1399 // we will initialise elements within the usedweights and spareweights
1400 // arrays between the blocks weight (which will then be the new max) and
1402 $parseweight = $bi->weight
;
1403 while (!array_key_exists($parseweight, $usedweights)) {
1404 $usedweights[$parseweight] = array();
1405 $spareweights[$parseweight] = $parseweight;
1408 $maxweight = $bi->weight
;
1409 } else if ($bi->weight
< $minweight) {
1410 // As above except this time the blocks weight is LESS than the
1411 // the current minimum, so we will initialise the array from the
1412 // blocks weight (new minimum) to the current minimum
1413 $parseweight = $bi->weight
;
1414 while (!array_key_exists($parseweight, $usedweights)) {
1415 $usedweights[$parseweight] = array();
1416 $spareweights[$parseweight] = $parseweight;
1419 $minweight = $bi->weight
;
1421 if ($bi->id
!= $block->instance
->id
) {
1422 unset($spareweights[$bi->weight
]);
1423 $usedweights[$bi->weight
][] = $bi->id
;
1427 // First we find the nearest gap in the list of weights.
1428 $bestdistance = max(abs($newweight - self
::MAX_WEIGHT
), abs($newweight + self
::MAX_WEIGHT
)) +
1;
1430 foreach ($spareweights as $spareweight) {
1431 if (abs($newweight - $spareweight) < $bestdistance) {
1432 $bestdistance = abs($newweight - $spareweight);
1433 $bestgap = $spareweight;
1437 // If there is no gap, we have to go outside -self::MAX_WEIGHT .. self::MAX_WEIGHT.
1438 if (is_null($bestgap)) {
1439 $bestgap = self
::MAX_WEIGHT +
1;
1440 while (!empty($usedweights[$bestgap])) {
1445 // Now we know the gap we are aiming for, so move all the blocks along.
1446 if ($bestgap < $newweight) {
1447 $newweight = floor($newweight);
1448 for ($weight = $bestgap +
1; $weight <= $newweight; $weight++
) {
1449 foreach ($usedweights[$weight] as $biid) {
1450 $this->reposition_block($biid, $newregion, $weight - 1);
1453 $this->reposition_block($block->instance
->id
, $newregion, $newweight);
1455 $newweight = ceil($newweight);
1456 for ($weight = $bestgap - 1; $weight >= $newweight; $weight--) {
1457 foreach ($usedweights[$weight] as $biid) {
1458 $this->reposition_block($biid, $newregion, $weight +
1);
1461 $this->reposition_block($block->instance
->id
, $newregion, $newweight);
1464 $this->page
->ensure_param_not_in_url('bui_moveid');
1465 $this->page
->ensure_param_not_in_url('bui_newregion');
1466 $this->page
->ensure_param_not_in_url('bui_newweight');
1471 * Turns the display of normal blocks either on or off.
1473 * @param bool $setting
1475 public function show_only_fake_blocks($setting = true) {
1476 $this->fakeblocksonly
= $setting;
1480 /// Helper functions for working with block classes ============================
1483 * Call a class method (one that does not require a block instance) on a block class.
1485 * @param string $blockname the name of the block.
1486 * @param string $method the method name.
1487 * @param array $param parameters to pass to the method.
1488 * @return mixed whatever the method returns.
1490 function block_method_result($blockname, $method, $param = NULL) {
1491 if(!block_load_class($blockname)) {
1494 return call_user_func(array('block_'.$blockname, $method), $param);
1498 * Creates a new instance of the specified block class.
1500 * @param string $blockname the name of the block.
1501 * @param $instance block_instances DB table row (optional).
1502 * @param moodle_page $page the page this block is appearing on.
1503 * @return block_base the requested block instance.
1505 function block_instance($blockname, $instance = NULL, $page = NULL) {
1506 if(!block_load_class($blockname)) {
1509 $classname = 'block_'.$blockname;
1510 $retval = new $classname;
1511 if($instance !== NULL) {
1512 if (is_null($page)) {
1516 $retval->_load_instance($instance, $page);
1522 * Load the block class for a particular type of block.
1524 * @param string $blockname the name of the block.
1525 * @return boolean success or failure.
1527 function block_load_class($blockname) {
1530 if(empty($blockname)) {
1534 $classname = 'block_'.$blockname;
1536 if(class_exists($classname)) {
1540 $blockpath = $CFG->dirroot
.'/blocks/'.$blockname.'/block_'.$blockname.'.php';
1542 if (file_exists($blockpath)) {
1543 require_once($CFG->dirroot
.'/blocks/moodleblock.class.php');
1544 include_once($blockpath);
1546 //debugging("$blockname code does not exist in $blockpath", DEBUG_DEVELOPER);
1550 return class_exists($classname);
1554 * Given a specific page type, return all the page type patterns that might
1557 * @param string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
1558 * @return array an array of all the page type patterns that might match this page type.
1560 function matching_page_type_patterns($pagetype) {
1561 $patterns = array($pagetype);
1562 $bits = explode('-', $pagetype);
1563 if (count($bits) == 3 && $bits[0] == 'mod') {
1564 if ($bits[2] == 'view') {
1565 $patterns[] = 'mod-*-view';
1566 } else if ($bits[2] == 'index') {
1567 $patterns[] = 'mod-*-index';
1570 while (count($bits) > 0) {
1571 $patterns[] = implode('-', $bits) . '-*';
1579 * Given a specific page type, parent context and currect context, return all the page type patterns
1580 * that might be used by this block.
1582 * @param string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
1583 * @param stdClass $parentcontext Block's parent context
1584 * @param stdClass $currentcontext Current context of block
1585 * @return array an array of all the page type patterns that might match this page type.
1587 function generate_page_type_patterns($pagetype, $parentcontext = null, $currentcontext = null) {
1590 $bits = explode('-', $pagetype);
1592 $core = get_core_subsystems();
1593 $plugins = get_plugin_types();
1595 //progressively strip pieces off the page type looking for a match
1596 $componentarray = null;
1597 for ($i = count($bits); $i > 0; $i--) {
1598 $possiblecomponentarray = array_slice($bits, 0, $i);
1599 $possiblecomponent = implode('', $possiblecomponentarray);
1601 // Check to see if the component is a core component
1602 if (array_key_exists($possiblecomponent, $core) && !empty($core[$possiblecomponent])) {
1603 $libfile = $CFG->dirroot
.'/'.$core[$possiblecomponent].'/lib.php';
1604 if (file_exists($libfile)) {
1605 require_once($libfile);
1606 $function = $possiblecomponent.'_page_type_list';
1607 if (function_exists($function)) {
1608 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1615 //check the plugin directory and look for a callback
1616 if (array_key_exists($possiblecomponent, $plugins) && !empty($plugins[$possiblecomponent])) {
1618 //We've found a plugin type. Look for a plugin name by getting the next section of page type
1619 if (count($bits) > $i) {
1620 $pluginname = $bits[$i];
1621 $directory = get_plugin_directory($possiblecomponent, $pluginname);
1622 if (!empty($directory)){
1623 $libfile = $directory.'/lib.php';
1624 if (file_exists($libfile)) {
1625 require_once($libfile);
1626 $function = $pluginname.'_page_type_list';
1627 if (function_exists($function)) {
1628 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1636 //we'll only get to here if we still don't have any patterns
1637 //the plugin type may have a callback
1638 $directory = get_plugin_directory($possiblecomponent, null);
1639 if (!empty($directory)){
1640 $libfile = $directory.'/lib.php';
1641 if (file_exists($libfile)) {
1642 require_once($libfile);
1643 $function = $possiblecomponent.'_page_type_list';
1644 if (function_exists($function)) {
1645 if ($patterns = $function($pagetype, $parentcontext, $currentcontext)) {
1654 if (empty($patterns)) {
1655 $patterns = default_page_type_list($pagetype, $parentcontext, $currentcontext);
1662 * Generates a default page type list when a more appropriate callback cannot be decided upon.
1664 * @param string $pagetype
1665 * @param stdClass $parentcontext
1666 * @param stdClass $currentcontext
1669 function default_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1670 // Generate page type patterns based on current page type if
1671 // callbacks haven't been defined
1672 $patterns = array($pagetype => $pagetype);
1673 $bits = explode('-', $pagetype);
1674 while (count($bits) > 0) {
1675 $pattern = implode('-', $bits) . '-*';
1676 $pagetypestringname = 'page-'.str_replace('*', 'x', $pattern);
1677 // guessing page type description
1678 if (get_string_manager()->string_exists($pagetypestringname, 'pagetype')) {
1679 $patterns[$pattern] = get_string($pagetypestringname, 'pagetype');
1681 $patterns[$pattern] = $pattern;
1685 $patterns['*'] = get_string('page-x', 'pagetype');
1690 * Generates the page type list for the my moodle page
1692 * @param string $pagetype
1693 * @param stdClass $parentcontext
1694 * @param stdClass $currentcontext
1697 function my_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1698 return array('my-index' => 'my-index');
1702 * Generates the page type list for a module by either locating and using the modules callback
1703 * or by generating a default list.
1705 * @param string $pagetype
1706 * @param stdClass $parentcontext
1707 * @param stdClass $currentcontext
1710 function mod_page_type_list($pagetype, $parentcontext = null, $currentcontext = null) {
1711 $patterns = plugin_page_type_list($pagetype, $parentcontext, $currentcontext);
1712 if (empty($patterns)) {
1713 // if modules don't have callbacks
1714 // generate two default page type patterns for modules only
1715 $bits = explode('-', $pagetype);
1716 $patterns = array($pagetype => $pagetype);
1717 if ($bits[2] == 'view') {
1718 $patterns['mod-*-view'] = get_string('page-mod-x-view', 'pagetype');
1719 } else if ($bits[2] == 'index') {
1720 $patterns['mod-*-index'] = get_string('page-mod-x-index', 'pagetype');
1725 /// Functions update the blocks if required by the request parameters ==========
1728 * Return a {@link block_contents} representing the add a new block UI, if
1729 * this user is allowed to see it.
1731 * @return block_contents an appropriate block_contents, or null if the user
1732 * cannot add any blocks here.
1734 function block_add_block_ui($page, $output) {
1735 global $CFG, $OUTPUT;
1736 if (!$page->user_is_editing() ||
!$page->user_can_edit_blocks()) {
1740 $bc = new block_contents();
1741 $bc->title
= get_string('addblock');
1742 $bc->add_class('block_adminblock');
1744 $missingblocks = $page->blocks
->get_addable_blocks();
1745 if (empty($missingblocks)) {
1746 $bc->content
= get_string('noblockstoaddhere');
1751 foreach ($missingblocks as $block) {
1752 $blockobject = block_instance($block->name
);
1753 if ($blockobject !== false && $blockobject->user_can_addto($page)) {
1754 $menu[$block->name
] = $blockobject->get_title();
1757 collatorlib
::asort($menu);
1759 $actionurl = new moodle_url($page->url
, array('sesskey'=>sesskey()));
1760 $select = new single_select($actionurl, 'bui_addblock', $menu, null, array(''=>get_string('adddots')), 'add_block');
1761 $bc->content
= $OUTPUT->render($select);
1765 // Functions that have been deprecated by block_manager =======================
1768 * @deprecated since Moodle 2.0 - use $page->blocks->get_addable_blocks();
1770 * This function returns an array with the IDs of any blocks that you can add to your page.
1771 * Parameters are passed by reference for speed; they are not modified at all.
1773 * @param $page the page object.
1774 * @param $blockmanager Not used.
1775 * @return array of block type ids.
1777 function blocks_get_missing(&$page, &$blockmanager) {
1778 debugging('blocks_get_missing is deprecated. Please use $page->blocks->get_addable_blocks() instead.', DEBUG_DEVELOPER
);
1779 $blocks = $page->blocks
->get_addable_blocks();
1781 foreach ($blocks as $block) {
1782 $ids[] = $block->id
;
1788 * Actually delete from the database any blocks that are currently on this page,
1789 * but which should not be there according to blocks_name_allowed_in_format.
1791 * @todo Write/Fix this function. Currently returns immediately
1794 function blocks_remove_inappropriate($course) {
1798 $blockmanager = blocks_get_by_page($page);
1800 if (empty($blockmanager)) {
1804 if (($pageformat = $page->pagetype) == NULL) {
1808 foreach($blockmanager as $region) {
1809 foreach($region as $instance) {
1810 $block = blocks_get_record($instance->blockid);
1811 if(!blocks_name_allowed_in_format($block->name, $pageformat)) {
1812 blocks_delete_instance($instance->instance);
1819 * Check that a given name is in a permittable format
1821 * @param string $name
1822 * @param string $pageformat
1825 function blocks_name_allowed_in_format($name, $pageformat) {
1828 $formats = block_method_result($name, 'applicable_formats');
1832 foreach ($formats as $format => $allowed) {
1833 $formatregex = '/^'.str_replace('*', '[^-]*', $format).'.*$/';
1834 $depth = substr_count($format, '-');
1835 if (preg_match($formatregex, $pageformat) && $depth > $maxdepth) {
1840 if ($accept === NULL) {
1841 $accept = !empty($formats['all']);
1847 * Delete a block, and associated data.
1849 * @param object $instance a row from the block_instances table
1850 * @param bool $nolongerused legacy parameter. Not used, but kept for backwards compatibility.
1851 * @param bool $skipblockstables for internal use only. Makes @see blocks_delete_all_for_context() more efficient.
1853 function blocks_delete_instance($instance, $nolongerused = false, $skipblockstables = false) {
1856 if ($block = block_instance($instance->blockname
, $instance)) {
1857 $block->instance_delete();
1859 delete_context(CONTEXT_BLOCK
, $instance->id
);
1861 if (!$skipblockstables) {
1862 $DB->delete_records('block_positions', array('blockinstanceid' => $instance->id
));
1863 $DB->delete_records('block_instances', array('id' => $instance->id
));
1864 $DB->delete_records_list('user_preferences', 'name', array('block'.$instance->id
.'hidden','docked_block_instance_'.$instance->id
));
1869 * Delete all the blocks that belong to a particular context.
1871 * @param int $contextid the context id.
1873 function blocks_delete_all_for_context($contextid) {
1875 $instances = $DB->get_recordset('block_instances', array('parentcontextid' => $contextid));
1876 foreach ($instances as $instance) {
1877 blocks_delete_instance($instance, true);
1879 $instances->close();
1880 $DB->delete_records('block_instances', array('parentcontextid' => $contextid));
1881 $DB->delete_records('block_positions', array('contextid' => $contextid));
1885 * Set a block to be visible or hidden on a particular page.
1887 * @param object $instance a row from the block_instances, preferably LEFT JOINed with the
1888 * block_positions table as return by block_manager.
1889 * @param moodle_page $page the back to set the visibility with respect to.
1890 * @param integer $newvisibility 1 for visible, 0 for hidden.
1892 function blocks_set_visibility($instance, $page, $newvisibility) {
1894 if (!empty($instance->blockpositionid
)) {
1895 // Already have local information on this page.
1896 $DB->set_field('block_positions', 'visible', $newvisibility, array('id' => $instance->blockpositionid
));
1900 // Create a new block_positions record.
1902 $bp->blockinstanceid
= $instance->id
;
1903 $bp->contextid
= $page->context
->id
;
1904 $bp->pagetype
= $page->pagetype
;
1905 if ($page->subpage
) {
1906 $bp->subpage
= $page->subpage
;
1908 $bp->visible
= $newvisibility;
1909 $bp->region
= $instance->defaultregion
;
1910 $bp->weight
= $instance->defaultweight
;
1911 $DB->insert_record('block_positions', $bp);
1915 * @deprecated since 2.0
1916 * Delete all the blocks from a particular page.
1918 * @param string $pagetype the page type.
1919 * @param integer $pageid the page id.
1920 * @return bool success or failure.
1922 function blocks_delete_all_on_page($pagetype, $pageid) {
1925 debugging('Call to deprecated function blocks_delete_all_on_page. ' .
1926 'This function cannot work any more. Doing nothing. ' .
1927 'Please update your code to use a block_manager method $PAGE->blocks->....', DEBUG_DEVELOPER
);
1932 * Dispite what this function is called, it seems to be mostly used to populate
1933 * the default blocks when a new course (or whatever) is created.
1935 * @deprecated since 2.0
1937 * @param object $page the page to add default blocks to.
1938 * @return boolean success or failure.
1940 function blocks_repopulate_page($page) {
1943 debugging('Call to deprecated function blocks_repopulate_page. ' .
1944 'Use a more specific method like blocks_add_default_course_blocks, ' .
1945 'or just call $PAGE->blocks->add_blocks()', DEBUG_DEVELOPER
);
1947 /// If the site override has been defined, it is the only valid one.
1948 if (!empty($CFG->defaultblocks_override
)) {
1949 $blocknames = $CFG->defaultblocks_override
;
1951 $blocknames = $page->blocks_get_default();
1954 $blocks = blocks_parse_default_blocks_list($blocknames);
1955 $page->blocks
->add_blocks($blocks);
1961 * Get the block record for a particular blockid - that is, a particular type os block.
1963 * @param $int blockid block type id. If null, an array of all block types is returned.
1964 * @param bool $notusedanymore No longer used.
1965 * @return array|object row from block table, or all rows.
1967 function blocks_get_record($blockid = NULL, $notusedanymore = false) {
1969 $blocks = $PAGE->blocks
->get_installed_blocks();
1970 if ($blockid === NULL) {
1972 } else if (isset($blocks[$blockid])) {
1973 return $blocks[$blockid];
1980 * Find a given block by its blockid within a provide array
1982 * @param int $blockid
1983 * @param array $blocksarray
1984 * @return bool|object Instance if found else false
1986 function blocks_find_block($blockid, $blocksarray) {
1987 if (empty($blocksarray)) {
1990 foreach($blocksarray as $blockgroup) {
1991 if (empty($blockgroup)) {
1994 foreach($blockgroup as $instance) {
1995 if($instance->blockid
== $blockid) {
2003 // Functions for programatically adding default blocks to pages ================
2006 * Parse a list of default blocks. See config-dist for a description of the format.
2008 * @param string $blocksstr
2011 function blocks_parse_default_blocks_list($blocksstr) {
2013 $bits = explode(':', $blocksstr);
2014 if (!empty($bits)) {
2015 $leftbits = trim(array_shift($bits));
2016 if ($leftbits != '') {
2017 $blocks[BLOCK_POS_LEFT
] = explode(',', $leftbits);
2020 if (!empty($bits)) {
2021 $rightbits =trim(array_shift($bits));
2022 if ($rightbits != '') {
2023 $blocks[BLOCK_POS_RIGHT
] = explode(',', $rightbits);
2030 * @return array the blocks that should be added to the site course by default.
2032 function blocks_get_default_site_course_blocks() {
2035 if (!empty($CFG->defaultblocks_site
)) {
2036 return blocks_parse_default_blocks_list($CFG->defaultblocks_site
);
2039 BLOCK_POS_LEFT
=> array('site_main_menu'),
2040 BLOCK_POS_RIGHT
=> array('course_summary', 'calendar_month')
2046 * Add the default blocks to a course.
2048 * @param object $course a course object.
2050 function blocks_add_default_course_blocks($course) {
2053 if (!empty($CFG->defaultblocks_override
)) {
2054 $blocknames = blocks_parse_default_blocks_list($CFG->defaultblocks_override
);
2056 } else if ($course->id
== SITEID
) {
2057 $blocknames = blocks_get_default_site_course_blocks();
2060 $defaultblocks = 'defaultblocks_' . $course->format
;
2061 if (!empty($CFG->$defaultblocks)) {
2062 $blocknames = blocks_parse_default_blocks_list($CFG->$defaultblocks);
2065 $formatconfig = $CFG->dirroot
.'/course/format/'.$course->format
.'/config.php';
2066 $format = array(); // initialize array in external file
2067 if (is_readable($formatconfig)) {
2068 include($formatconfig);
2070 if (!empty($format['defaultblocks'])) {
2071 $blocknames = blocks_parse_default_blocks_list($format['defaultblocks']);
2073 } else if (!empty($CFG->defaultblocks
)){
2074 $blocknames = blocks_parse_default_blocks_list($CFG->defaultblocks
);
2077 $blocknames = array(
2078 BLOCK_POS_LEFT
=> array(),
2079 BLOCK_POS_RIGHT
=> array('search_forums', 'news_items', 'calendar_upcoming', 'recent_activity')
2085 if ($course->id
== SITEID
) {
2086 $pagetypepattern = 'site-index';
2088 $pagetypepattern = 'course-view-*';
2090 $page = new moodle_page();
2091 $page->set_course($course);
2092 $page->blocks
->add_blocks($blocknames, $pagetypepattern);
2096 * Add the default system-context blocks. E.g. the admin tree.
2098 function blocks_add_default_system_blocks() {
2101 $page = new moodle_page();
2102 $page->set_context(get_context_instance(CONTEXT_SYSTEM
));
2103 $page->blocks
->add_blocks(array(BLOCK_POS_LEFT
=> array('navigation', 'settings')), '*', null, true);
2104 $page->blocks
->add_blocks(array(BLOCK_POS_LEFT
=> array('admin_bookmarks')), 'admin-*', null, null, 2);
2106 if ($defaultmypage = $DB->get_record('my_pages', array('userid'=>null, 'name'=>'__default', 'private'=>1))) {
2107 $subpagepattern = $defaultmypage->id
;
2109 $subpagepattern = null;
2112 $page->blocks
->add_blocks(array(BLOCK_POS_RIGHT
=> array('private_files', 'online_users'), 'content' => array('course_overview')), 'my-index', $subpagepattern, false);