Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/ -> blocklib.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
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: | 2713 lines (107 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:: (50 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()
process_url_show_hide()
get_secondarynav()
block_:: (26 methods):
process_url_edit()
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 doesnot 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: string 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. |
| 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. |
| 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: $output The core_renderer to use when generating the output. (Need to get icon paths.) return: 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. |
| 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 |
| 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 |
| 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: $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. |
