Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/lib/ -> blocklib.php (source)

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

Block Class and Functions This file defines the {@link block_manager} class,

Copyright: 1999 onwards Martin Dougiamas http://dougiamas.com
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2759 lines (108 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 3 classes

block_not_on_page_exception:: (1 method):
  __construct()

block_manager:: (51 methods):
  __construct()
  get_regions()
  get_default_region()
  get_addable_blocks()
  is_block_present()
  is_known_block_type()
  is_known_region()
  get_blocks_for_region()
  get_content_for_region()
  get_content_for_all_regions()
  get_move_target_url()
  region_has_content()
  region_has_fakeblocks()
  get_installed_blocks()
  get_required_by_theme_block_types()
  get_unaddable_by_theme_block_types()
  protect_block()
  unprotect_block()
  get_undeletable_block_types()
  add_region()
  add_regions()
  add_custom_regions_for_pagetype()
  set_default_region()
  add_fake_block()
  region_completely_docked()
  region_uses_dock()
  load_blocks()
  add_block()
  add_block_at_end_of_default_region()
  add_blocks()
  reposition_block()
  find_instance()
  check_not_yet_loaded()
  check_is_loaded()
  check_known_block_type()
  check_region_is_known()
  prepare_per_region_arrays()
  create_block_instances()
  create_all_block_instances()
  add_block_required_by_theme()
  create_block_contents()
  ensure_instances_exist()
  ensure_content_created()
  edit_controls()
  user_can_delete_block()
  process_url_actions()
  process_url_add()
  process_url_delete()
  get_block_edit_form_class()
  process_url_show_hide()
  get_secondarynav()

block_:: (27 methods):
  process_url_edit()
  save_block_data()
  process_url_move()
  show_only_fake_blocks()
  block_method_result()
  block_instance_by_id()
  block_instance()
  block_load_class()
  matching_page_type_patterns()
  matching_page_type_patterns_from_pattern()
  generate_page_type_patterns()
  default_page_type_list()
  my_page_type_list()
  mod_page_type_list()
  block_add_block_ui()
  blocks_remove_inappropriate()
  blocks_name_allowed_in_format()
  blocks_delete_instance()
  blocks_delete_instances()
  blocks_delete_all_for_context()
  blocks_set_visibility()
  blocks_get_record()
  blocks_find_block()
  blocks_parse_default_blocks_list()
  blocks_get_default_site_course_blocks()
  blocks_add_default_course_blocks()
  blocks_add_default_system_blocks()


Class: block_not_on_page_exception  - X-Ref

Exception thrown when someone tried to do something with a block that does
not exist on a page.

__construct($instanceid, $page)   X-Ref
Constructor

param: int $instanceid the block instance id of the block that was looked for.
param: object $page the current page.

Class: block_manager  - X-Ref

This class keeps track of the block that should appear on a moodle_page.

The page to work with as passed to the constructor.

__construct($page)   X-Ref
Constructor.

param: object $page the moodle_page object object we are managing the blocks for,

get_regions()   X-Ref
Get an array of all region names on this page where a block may appear

return: array the internal names of the regions on this page where block may appear.

get_default_region()   X-Ref
Get the region name of the region blocks are added to by default

return: string the internal names of the region where new blocks are added

get_addable_blocks()   X-Ref
The list of block types that may be added to this page.

return: array block name => record from block table.

is_block_present($blockname)   X-Ref
Given a block name, find out of any of them are currently present in the page

param: string $blockname - the basic name of a block (eg "navigation")
return: boolean - is there one of these blocks in the current page?

is_known_block_type($blockname, $includeinvisible = false)   X-Ref
Find out if a block type is known by the system

param: string $blockname the name of the type of block.
param: boolean $includeinvisible if false (default) only check 'visible' blocks, that is, blocks enabled by the admin.
return: boolean true if this block in installed.

is_known_region($region)   X-Ref
Find out if a region exists on a page

param: string $region a region name
return: boolean true if this region exists on this page.

get_blocks_for_region($region)   X-Ref
Get an array of all blocks within a given region

param: string $region a block region that exists on this page.
return: array of block instances.

get_content_for_region($region, $output)   X-Ref
Returns an array of block content objects that exist in a region

param: string $region a block region that exists on this page.
return: array of block block_contents objects for all the blocks in a region.

get_content_for_all_regions($output)   X-Ref
Returns an array of block content objects for all the existings regions

param: renderer_base $output the rendered to use
return: array of block block_contents objects for all the blocks in all regions.

get_move_target_url($region, $weight)   X-Ref
Helper method used by get_content_for_region.

param: string $region region name
param: float $weight weight. May be fractional, since you may want to move a block
return: moodle_url URL for moving block $this->movingblock to this position.

region_has_content($region, $output)   X-Ref
Determine whether a region contains anything. (Either any real blocks, or
the add new block UI.)

(You may wonder why the $output parameter is required. Unfortunately,
because of the way that blocks work, the only reliable way to find out
if a block will be visible is to get the content for output, and to
get the content, you need a renderer. Fortunately, this is not a
performance problem, because we cache the output that is generated, and
in almost every case where we call region_has_content, we are about to
output the blocks anyway, so we are not doing wasted effort.)

param: string $region a block region that exists on this page.
param: core_renderer $output a core_renderer. normally the global $OUTPUT.
return: boolean Whether there is anything in this region.

region_has_fakeblocks($region)   X-Ref
Determine whether a region contains any fake blocks.

(Fake blocks are typically added to the extracontent array per region)

param: string $region a block region that exists on this page.
return: boolean Whether there are fake blocks in this region.

get_installed_blocks()   X-Ref
Get an array of all of the installed blocks.

return: array contents of the block table.

get_required_by_theme_block_types()   X-Ref

return: array names of block types that must exist on every page with this theme.

get_unaddable_by_theme_block_types()   X-Ref
It returns the list of blocks that can't be displayed in the "Add a block" list.
This information is taken from the unaddableblocks theme setting.

return: array A list with the blocks that won't be displayed in the "Add a block" list.

protect_block($blockidorname)   X-Ref
Make this block type undeletable and unaddable.

param: mixed $blockidorname string or int

unprotect_block($blockidorname)   X-Ref
Make this block type deletable and addable.

param: mixed $blockidorname string or int

get_undeletable_block_types()   X-Ref
Get the list of "protected" blocks via admin block manager ui.

return: array names of block types that cannot be added or deleted. E.g. array('navigation','settings').

add_region($region, $custom = true)   X-Ref
Add a region to a page

param: string $region add a named region where blocks may appear on the current page.
param: bool $custom True if this is a custom block region, being added by the page rather than the theme layout.

add_regions($regions, $custom = true)   X-Ref
Add an array of regions

param: array $regions this utility method calls add_region for each array element.

add_custom_regions_for_pagetype($pagetype)   X-Ref
Finds custom block regions associated with a page type and registers them with this block manager.

param: string $pagetype

set_default_region($defaultregion)   X-Ref
Set the default region for new blocks on the page

param: string $defaultregion the internal names of the region where new

add_fake_block($bc, $region)   X-Ref
Add something that looks like a block, but which isn't an actual block_instance,
to this page.

param: block_contents $bc the content of the block-like thing.
param: string $region a block region that exists on this page.

region_completely_docked($region, $output)   X-Ref
Checks to see whether all of the blocks within the given region are docked

param: string $region
return: bool True if all of the blocks within that region are docked

region_uses_dock($regions, $output)   X-Ref
Checks to see whether any of the blocks within the given regions are docked

param: array|string $regions array of regions (or single region)
return: bool True if any of the blocks within that region are docked

load_blocks($includeinvisible = null)   X-Ref
This method actually loads the blocks for our page from the database.

param: boolean|null $includeinvisible

add_block($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern = NULL, $subpagepattern = NULL)   X-Ref
Add a block to the current page, or related pages. The block is added to
context $this->page->contextid. If $pagetypepattern $subpagepattern

param: string $blockname The type of block to add.
param: string $region the block region on this page to add the block to.
param: integer $weight determines the order where this block appears in the region.
param: boolean $showinsubcontexts whether this block appears in subcontexts, or just the current context.
param: string|null $pagetypepattern which page types this block should appear on. Defaults to just the current page type.
param: string|null $subpagepattern which subpage this block should appear on. NULL = any (the default), otherwise only the specified subpage.
return: block_base

add_block_at_end_of_default_region($blockname, $blockregion = null)   X-Ref
When passed a block name create a new instance of the block in the specified region.

param: string $blockname Name of the block to add.
param: null|string $blockregion If defined add the new block to the specified region.
return: ?block_base

add_blocks($blocks, $pagetypepattern = NULL, $subpagepattern = NULL, $showinsubcontexts=false, $weight=0)   X-Ref
Convenience method, calls add_block repeatedly for all the blocks in $blocks. Optionally, a starting weight
can be used to decide the starting point that blocks are added in the region, the weight is passed to {@link add_block}
and incremented by the position of the block in the $blocks array

param: array $blocks array with array keys the region names, and values an array of block names.
param: string $pagetypepattern optional. Passed to {@link add_block()}
param: string $subpagepattern optional. Passed to {@link add_block()}
param: boolean $showinsubcontexts optional. Passed to {@link add_block()}
param: integer $weight optional. Determines the starting point that the blocks are added in the region.

reposition_block($blockinstanceid, $newregion, $newweight)   X-Ref
Move a block to a new position on this page.

If this block cannot appear on any other pages, then we change defaultposition/weight
in the block_instances table. Otherwise we just set the position on this page.

param: $blockinstanceid the block instance id.
param: $newregion the new region name.
param: $newweight the new weight.

find_instance($instanceid)   X-Ref
Find a given block by its instance id

param: integer $instanceid
return: block_base

check_not_yet_loaded()   X-Ref
Check whether the page blocks have been loaded yet

return: void Throws coding exception if already loaded

check_is_loaded()   X-Ref
Check whether the page blocks have been loaded yet

Nearly identical to the above function {@link check_not_yet_loaded()} except different message

return: void Throws coding exception if already loaded

check_known_block_type($blockname, $includeinvisible = false)   X-Ref
Check if a block type is known and usable

param: string $blockname The block type name to search for
param: bool $includeinvisible Include disabled block types in the initial pass
return: void Coding Exception thrown if unknown or not enabled

check_region_is_known($region)   X-Ref
Check if a region is known by its name

param: string $region
return: void Coding Exception thrown if the region is not known

prepare_per_region_arrays()   X-Ref
Returns an array of region names as keys and nested arrays for values

return: array an array where the array keys are the region names, and the array

create_block_instances($birecords)   X-Ref
Create a set of new block instance from a record array

param: array $birecords An array of block instance records
return: array An array of instantiated block_instance objects

create_all_block_instances()   X-Ref
Create all the block instances for all the blocks that were loaded by
load_blocks. This is used, for example, to ensure that all blocks get a
chance to initialise themselves via the {@link block_base::specialize()}
method, before any output is done.

It is also used to create any blocks that are "requiredbytheme" by the current theme.
These blocks that are auto-created have requiredbytheme set on the block instance
so they are only visible on themes that require them.

add_block_required_by_theme($blockname)   X-Ref
Add a block that is required by the current theme but has not been
created yet. This is a special type of block that only shows in themes that
require it (by listing it in undeletable_block_types).

param: string $blockname the name of the block type.

create_block_contents($instances, $output, $region)   X-Ref
Return an array of content objects from a set of block instances

param: array $instances An array of block instances
param: renderer_base The renderer to use.
param: string $region the region name.
return: array An array of block_content (and possibly block_move_target) objects.

ensure_instances_exist($region)   X-Ref
Ensure block instances exist for a given region

param: string $region Check for bi's with the instance with this name

ensure_content_created($region, $output)   X-Ref
Ensure that there is some content within the given region

param: string $region The name of the region to check

edit_controls($block)   X-Ref
Get the appropriate list of editing icons for a block. This is used
to set {@link block_contents::$controls} in {@link block_base::get_contents_for_output()}.

param: block_base $block
return: array an array in the format for {@link block_contents::$controls}

user_can_delete_block($block)   X-Ref

param: block_base $block a block that appears on this page.
return: boolean boolean whether the currently logged in user is allowed to delete this block.

process_url_actions()   X-Ref
Process any block actions that were specified in the URL.

return: boolean true if anything was done. False if not.

process_url_add()   X-Ref
Handle adding a block.

return: boolean true if anything was done. False if not.

process_url_delete()   X-Ref
Handle deleting a block.

return: boolean true if anything was done. False if not.

get_block_edit_form_class(string $blockname)   X-Ref
Returns the name of the class for block editing and makes sure it is autoloaded

param: string $blockname name of the block plugin (without block_ prefix)
return: string

process_url_show_hide()   X-Ref
Handle showing or hiding a block.

return: boolean true if anything was done. False if not.

get_secondarynav(block_base $block)   X-Ref
Convenience function to check whether a block is implementing a secondary nav class and return it
initialised to the calling function

param: block_base $block
return: \core\navigation\views\secondary

Class: block_  - X-Ref

process_url_edit()   X-Ref
Handle showing/processing the submission from the block editing form.

return: boolean true if the form was submitted and the new config saved. Does not

save_block_data(block_base $block, stdClass $data)   X-Ref
Updates block configuration in the database

param: block_base $block
param: stdClass $data data from the block edit form
return: void

process_url_move()   X-Ref
Handle showing/processing the submission from the block editing form.

return: boolean true if the form was submitted and the new config saved. Does not

show_only_fake_blocks($setting = true)   X-Ref
Turns the display of normal blocks either on or off.

param: bool $setting

block_method_result($blockname, $method, $param = NULL)   X-Ref
Call a class method (one that does not require a block instance) on a block class.

param: string $blockname the name of the block.
param: string $method the method name.
param: array $param parameters to pass to the method.
return: mixed whatever the method returns.

block_instance_by_id($blockinstanceid)   X-Ref
Returns a new instance of the specified block instance id.

param: int $blockinstanceid
return: block_base the requested block instance.

block_instance($blockname, $instance = NULL, $page = NULL)   X-Ref
Creates a new instance of the specified block class.

param: string $blockname the name of the block.
param: stdClass $instance block_instances DB table row (optional).
param: moodle_page $page the page this block is appearing on.
return: block_base the requested block instance.

block_load_class($blockname)   X-Ref
Load the block class for a particular type of block.

param: string $blockname the name of the block.
return: boolean success or failure.

matching_page_type_patterns($pagetype)   X-Ref
Given a specific page type, return all the page type patterns that might
match it.

param: string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
return: array an array of all the page type patterns that might match this page type.

matching_page_type_patterns_from_pattern($pattern)   X-Ref
Give an specific pattern, return all the page type patterns that would also match it.

param: string $pattern the pattern, e.g. 'mod-forum-*' or 'mod-quiz-view'.
return: array of all the page type patterns matching.

generate_page_type_patterns($pagetype, $parentcontext = null, $currentcontext = null)   X-Ref
Given a specific page type, parent context and currect context, return all the page type patterns
that might be used by this block.

param: string $pagetype for example 'course-view-weeks' or 'mod-quiz-view'.
param: stdClass $parentcontext Block's parent context
param: stdClass $currentcontext Current context of block
return: array an array of all the page type patterns that might match this page type.

default_page_type_list($pagetype, $parentcontext = null, $currentcontext = null)   X-Ref
Generates a default page type list when a more appropriate callback cannot be decided upon.

param: string $pagetype
param: stdClass $parentcontext
param: stdClass $currentcontext
return: array

my_page_type_list($pagetype, $parentcontext = null, $currentcontext = null)   X-Ref
Generates the page type list for the my moodle page

param: string $pagetype
param: stdClass $parentcontext
param: stdClass $currentcontext
return: array

mod_page_type_list($pagetype, $parentcontext = null, $currentcontext = null)   X-Ref
Generates the page type list for a module by either locating and using the modules callback
or by generating a default list.

param: string $pagetype
param: stdClass $parentcontext
param: stdClass $currentcontext
return: array

block_add_block_ui($page, $output)   X-Ref
Return a {@link block_contents} representing the add a new block UI, if
this user is allowed to see it.

return: block_contents an appropriate block_contents, or null if the user

blocks_remove_inappropriate($course)   X-Ref
Actually delete from the database any blocks that are currently on this page,
but which should not be there according to blocks_name_allowed_in_format.

param: $course

blocks_name_allowed_in_format($name, $pageformat)   X-Ref
Check that a given name is in a permittable format

param: string $name
param: string $pageformat
return: bool

blocks_delete_instance($instance, $nolongerused = false, $skipblockstables = false)   X-Ref
Delete a block, and associated data.

param: object $instance a row from the block_instances table
param: bool $nolongerused legacy parameter. Not used, but kept for backwards compatibility.
param: bool $skipblockstables for internal use only. Makes @see blocks_delete_all_for_context() more efficient.

blocks_delete_instances($instanceids)   X-Ref
Delete multiple blocks at once.

param: array $instanceids A list of block instance ID.

blocks_delete_all_for_context($contextid)   X-Ref
Delete all the blocks that belong to a particular context.

param: int $contextid the context id.

blocks_set_visibility($instance, $page, $newvisibility)   X-Ref
Set a block to be visible or hidden on a particular page.

param: object $instance a row from the block_instances, preferably LEFT JOINed with the
param: moodle_page $page the back to set the visibility with respect to.
param: integer $newvisibility 1 for visible, 0 for hidden.

blocks_get_record($blockid = NULL, $notusedanymore = false)   X-Ref
Get the block record for a particular blockid - that is, a particular type os block.

param: $int blockid block type id. If null, an array of all block types is returned.
param: bool $notusedanymore No longer used.
return: array|object row from block table, or all rows.

blocks_find_block($blockid, $blocksarray)   X-Ref
Find a given block by its blockid within a provide array

param: int $blockid
param: array $blocksarray
return: bool|object Instance if found else false

blocks_parse_default_blocks_list($blocksstr)   X-Ref
Parse a list of default blocks. See config-dist for a description of the format.

param: string $blocksstr Determines the starting point that the blocks are added in the region.
return: array the parsed list of default blocks

blocks_get_default_site_course_blocks()   X-Ref

return: array the blocks that should be added to the site course by default.

blocks_add_default_course_blocks($course)   X-Ref
Add the default blocks to a course.

param: object $course a course object.

blocks_add_default_system_blocks()   X-Ref
Add the default system-context blocks. E.g. the admin tree.