Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
block_manager Class Reference

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

Inheritance diagram for block_manager:
my_syspage_block_manager

Public Member Functions

 __construct ($page)
 Constructor ================================================================.
 
 add_block ($blockname, $region, $weight, $showinsubcontexts, $pagetypepattern=NULL, $subpagepattern=NULL)
 Add a block to the current page, or related pages.
 
 add_block_at_end_of_default_region ($blockname, $blockregion=null)
 When passed a block name create a new instance of the block in the specified region.
 
 add_blocks ($blocks, $pagetypepattern=NULL, $subpagepattern=NULL, $showinsubcontexts=false, $weight=0)
 Convenience method, calls add_block repeatedly for all the blocks in $blocks.
 
 add_custom_regions_for_pagetype ($pagetype)
 Finds custom block regions associated with a page type and registers them with this block manager.
 
 add_fake_block ($bc, $region)
 Add something that looks like a block, but which isn't an actual block_instance, to this page.
 
 add_region ($region, $custom=true)
 Setter methods =============================================================.
 
 add_regions ($regions, $custom=true)
 Add an array of regions.
 
 create_all_block_instances ()
 Create all the block instances for all the blocks that were loaded by load_blocks.
 
 edit_controls ($block)
 Process actions from the URL ===============================================.
 
 ensure_content_created ($region, $output)
 Ensure that there is some content within the given region.
 
 find_instance ($instanceid)
 Find a given block by its instance id.
 
 get_addable_blocks ()
 The list of block types that may be added to this page.
 
 get_blocks_for_region ($region)
 Get an array of all blocks within a given region.
 
 get_content_for_all_regions ($output)
 Returns an array of block content objects for all the existings regions.
 
 get_content_for_region ($region, $output)
 Returns an array of block content objects that exist in a region.
 
 get_default_region ()
 Get the region name of the region blocks are added to by default.
 
 get_installed_blocks ()
 Get an array of all of the installed blocks.
 
 get_regions ()
 Getter methods =============================================================.
 
 get_required_by_theme_block_types ()
 
 get_unaddable_by_theme_block_types ()
 It returns the list of blocks that can't be displayed in the "Add a block" list.
 
 is_block_present ($blockname)
 Given a block name, find out of any of them are currently present in the page.
 
 is_known_block_type ($blockname, $includeinvisible=false)
 Find out if a block type is known by the system.
 
 is_known_region ($region)
 Find out if a region exists on a page.
 
 load_blocks ($includeinvisible=null)
 Actions ====================================================================.
 
 process_url_actions ()
 Process any block actions that were specified in the URL.
 
 process_url_add ()
 Handle adding a block.
 
 process_url_delete ()
 Handle deleting a block.
 
 process_url_edit ()
 Handle showing/processing the submission from the block editing form.
 
 process_url_move ()
 Handle showing/processing the submission from the block editing form.
 
 process_url_show_hide ()
 Handle showing or hiding a block.
 
 region_completely_docked ($region, $output)
 Checks to see whether all of the blocks within the given region are docked.
 
 region_has_content ($region, $output)
 Determine whether a region contains anything.
 
 region_has_fakeblocks ($region)
 Determine whether a region contains any fake blocks.
 
 region_uses_dock ($regions, $output)
 Checks to see whether any of the blocks within the given regions are docked.
 
 reposition_block ($blockinstanceid, $newregion, $newweight)
 Move a block to a new position on this page.
 
 save_block_data (block_base $block, stdClass $data)
 Updates block configuration in the database.
 
 set_default_region ($defaultregion)
 Set the default region for new blocks on the page.
 
 show_only_fake_blocks ($setting=true)
 Turns the display of normal blocks either on or off.
 

Static Public Member Functions

static get_block_edit_form_class (string $blockname)
 Returns the name of the class for block editing and makes sure it is autoloaded.
 
static get_undeletable_block_types ()
 Get the list of "protected" blocks via admin block manager ui.
 
static protect_block ($blockidorname)
 Make this block type undeletable and unaddable.
 
static unprotect_block ($blockidorname)
 Make this block type deletable and addable.
 

Public Attributes

const MAX_WEIGHT = 10
 The UI normally only shows block weights between -MAX_WEIGHT and MAX_WEIGHT, although other weights are valid.
 

Protected Member Functions

 add_block_required_by_theme ($blockname)
 Add a block that is required by the current theme but has not been created yet.
 
 check_is_loaded ()
 Check whether the page blocks have been loaded yet.
 
 check_known_block_type ($blockname, $includeinvisible=false)
 Check if a block type is known and usable.
 
 check_not_yet_loaded ()
 Inner workings =============================================================.
 
 check_region_is_known ($region)
 Check if a region is known by its name.
 
 create_block_contents ($instances, $output, $region)
 Return an array of content objects from a set of block instances.
 
 create_block_instances ($birecords)
 Create a set of new block instance from a record array.
 
 ensure_instances_exist ($region)
 Ensure block instances exist for a given region.
 
 get_move_target_url ($region, $weight)
 Helper method used by get_content_for_region.
 
 get_secondarynav (block_base $block)
 Convenience function to check whether a block is implementing a secondary nav class and return it initialised to the calling function.
 
 prepare_per_region_arrays ()
 Returns an array of region names as keys and nested arrays for values.
 
 user_can_delete_block ($block)
 

Protected Attributes

array $addableblocks = null
 blocks that this user can add to this page.
 
array $allblocks = null
 will be $DB->get_records('blocks')
 
array $birecordsbyregion = null
 Will be an array region-name => array(db rows loaded in load_blocks);.
 
array $blockinstances = array()
 array region-name => array(block objects); populated as necessary by the ensure_instances_exist method.
 
string $defaultregion = null
 the region where new blocks are added.
 
array $extracontent = array()
 array region-name => array(block_contents objects) extra block-like things to be displayed in each region, before the real blocks.
 
 $fakeblocksonly = false
 Show only fake blocks.
 
integer null $movingblock = null
 Used by the block move id, to track whether a block is currently being moved.
 
moodle_page $page
 Field declarations =========================================================.
 
array $regions = array()
 region name => 1.
 
array $visibleblockcontent = array()
 array region-name => array(block_contents objects) what actually needs to be displayed in each region.
 

Detailed Description

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

The page to work with as passed to the constructor.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Since
Moodle 2.0

Constructor & Destructor Documentation

◆ __construct()

block_manager::__construct ( $page)

Constructor ================================================================.

Constructor.

Parameters
object$pagethe moodle_page object object we are managing the blocks for, or a reasonable faxilimily. (See the comment at the top of this class and )

Member Function Documentation

◆ add_block()

block_manager::add_block ( $blockname,
$region,
$weight,
$showinsubcontexts,
$pagetypepattern = NULL,
$subpagepattern = NULL )

Add a block to the current page, or related pages.

The block is added to context $this->page->contextid. If $pagetypepattern $subpagepattern

Parameters
string$blocknameThe type of block to add.
string$regionthe block region on this page to add the block to.
integer$weightdetermines the order where this block appears in the region.
boolean$showinsubcontextswhether this block appears in subcontexts, or just the current context.
string | null$pagetypepatternwhich page types this block should appear on. Defaults to just the current page type.
string | null$subpagepatternwhich subpage this block should appear on. NULL = any (the default), otherwise only the specified subpage.
Return values
block_base

◆ add_block_at_end_of_default_region()

block_manager::add_block_at_end_of_default_region ( $blockname,
$blockregion = null )

When passed a block name create a new instance of the block in the specified region.

Parameters
string$blocknameName of the block to add.
null | string$blockregionIf defined add the new block to the specified region.
Return values
?block_base

◆ add_block_required_by_theme()

block_manager::add_block_required_by_theme ( $blockname)
protected

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).

Parameters
string$blocknamethe name of the block type.

◆ add_blocks()

block_manager::add_blocks ( $blocks,
$pagetypepattern = NULL,
$subpagepattern = NULL,
$showinsubcontexts = false,
$weight = 0 )

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 add_block and incremented by the position of the block in the $blocks array

Parameters
array$blocksarray with array keys the region names, and values an array of block names.
string$pagetypepatternoptional. Passed to add_block()
string$subpagepatternoptional. Passed to add_block()
boolean$showinsubcontextsoptional. Passed to add_block()
integer$weightoptional. Determines the starting point that the blocks are added in the region.

◆ add_custom_regions_for_pagetype()

block_manager::add_custom_regions_for_pagetype ( $pagetype)

Finds custom block regions associated with a page type and registers them with this block manager.

Parameters
string$pagetype

◆ add_fake_block()

block_manager::add_fake_block ( $bc,
$region )

Add something that looks like a block, but which isn't an actual block_instance, to this page.

Parameters
block_contents$bcthe content of the block-like thing.
string$regiona block region that exists on this page.

◆ add_region()

block_manager::add_region ( $region,
$custom = true )

Setter methods =============================================================.

Add a region to a page

Parameters
string$regionadd a named region where blocks may appear on the current page. This is an internal name, like 'side-pre', not a string to display in the UI.
bool$customTrue if this is a custom block region, being added by the page rather than the theme layout.

◆ add_regions()

block_manager::add_regions ( $regions,
$custom = true )

Add an array of regions.

See also
add_region()
Parameters
array$regionsthis utility method calls add_region for each array element.

◆ check_is_loaded()

block_manager::check_is_loaded ( )
protected

Check whether the page blocks have been loaded yet.

Nearly identical to the above function check_not_yet_loaded() except different message

Return values
voidThrows coding exception if already loaded

◆ check_known_block_type()

block_manager::check_known_block_type ( $blockname,
$includeinvisible = false )
protected

Check if a block type is known and usable.

Parameters
string$blocknameThe block type name to search for
bool$includeinvisibleInclude disabled block types in the initial pass
Return values
voidCoding Exception thrown if unknown or not enabled

◆ check_not_yet_loaded()

block_manager::check_not_yet_loaded ( )
protected

Inner workings =============================================================.

Check whether the page blocks have been loaded yet

Return values
voidThrows coding exception if already loaded

◆ check_region_is_known()

block_manager::check_region_is_known ( $region)
protected

Check if a region is known by its name.

Parameters
string$region
Return values
voidCoding Exception thrown if the region is not known

◆ create_all_block_instances()

block_manager::create_all_block_instances ( )

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 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.

◆ create_block_contents()

block_manager::create_block_contents ( $instances,
$output,
$region )
protected

Return an array of content objects from a set of block instances.

Parameters
array$instancesAn array of block instances
renderer_baseThe renderer to use.
string$regionthe region name.
Return values
arrayAn array of block_content (and possibly block_move_target) objects.

◆ create_block_instances()

block_manager::create_block_instances ( $birecords)
protected

Create a set of new block instance from a record array.

Parameters
array$birecordsAn array of block instance records
Return values
arrayAn array of instantiated block_instance objects

◆ edit_controls()

block_manager::edit_controls ( $block)

Process actions from the URL ===============================================.

Get the appropriate list of editing icons for a block. This is used to set block_contents::$controls in block_base::get_contents_for_output().

Parameters
block_base$block
Return values
arrayan array in the format for block_contents::$controls

◆ ensure_content_created()

block_manager::ensure_content_created ( $region,
$output )

Ensure that there is some content within the given region.

Parameters
string$regionThe name of the region to check

◆ ensure_instances_exist()

block_manager::ensure_instances_exist ( $region)
protected

Ensure block instances exist for a given region.

Parameters
string$regionCheck for bi's with the instance with this name

◆ find_instance()

block_manager::find_instance ( $instanceid)

Find a given block by its instance id.

Parameters
integer$instanceid
Return values
block_base

◆ get_addable_blocks()

block_manager::get_addable_blocks ( )

The list of block types that may be added to this page.

Return values
arrayblock name => record from block table.

◆ get_block_edit_form_class()

static block_manager::get_block_edit_form_class ( string $blockname)
static

Returns the name of the class for block editing and makes sure it is autoloaded.

Parameters
string$blocknamename of the block plugin (without block_ prefix)
Return values
string

◆ get_blocks_for_region()

block_manager::get_blocks_for_region ( $region)

Get an array of all blocks within a given region.

Parameters
string$regiona block region that exists on this page.
Return values
arrayof block instances.

◆ get_content_for_all_regions()

block_manager::get_content_for_all_regions ( $output)

Returns an array of block content objects for all the existings regions.

Parameters
renderer_base$outputthe rendered to use
Return values
arrayof block block_contents objects for all the blocks in all regions.
Since
Moodle 3.3

◆ get_content_for_region()

block_manager::get_content_for_region ( $region,
$output )

Returns an array of block content objects that exist in a region.

Parameters
string$regiona block region that exists on this page.
Return values
arrayof block block_contents objects for all the blocks in a region.

◆ get_default_region()

block_manager::get_default_region ( )

Get the region name of the region blocks are added to by default.

Return values
stringthe internal names of the region where new blocks are added by default, and where any blocks from an unrecognised region are shown. (Imagine that blocks were added with one theme selected, then you switched to a theme with different block positions.)

◆ get_installed_blocks()

block_manager::get_installed_blocks ( )

Get an array of all of the installed blocks.

Return values
arraycontents of the block table.

◆ get_move_target_url()

block_manager::get_move_target_url ( $region,
$weight )
protected

Helper method used by get_content_for_region.

Parameters
string$regionregion name
float$weightweight. May be fractional, since you may want to move a block between ones with weight 2 and 3, say ($weight would be 2.5).
Return values
moodle_urlURL for moving block $this->movingblock to this position.

◆ get_regions()

block_manager::get_regions ( )

Getter methods =============================================================.

Get an array of all region names on this page where a block may appear

Return values
arraythe internal names of the regions on this page where block may appear.

◆ get_required_by_theme_block_types()

block_manager::get_required_by_theme_block_types ( )
Return values
arraynames of block types that must exist on every page with this theme.

◆ get_secondarynav()

block_manager::get_secondarynav ( block_base $block)
protected

Convenience function to check whether a block is implementing a secondary nav class and return it initialised to the calling function.

Todo
MDL-74939 Remove support for old 'local\views\secondary' class location
Parameters
block_base$block
Return values
core\navigation\views\secondary

◆ get_unaddable_by_theme_block_types()

block_manager::get_unaddable_by_theme_block_types ( )

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 values
arrayA list with the blocks that won't be displayed in the "Add a block" list.

◆ get_undeletable_block_types()

static block_manager::get_undeletable_block_types ( )
static

Get the list of "protected" blocks via admin block manager ui.

Return values
arraynames of block types that cannot be added or deleted. E.g. array('navigation','settings').

◆ is_block_present()

block_manager::is_block_present ( $blockname)

Given a block name, find out of any of them are currently present in the page.

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

◆ is_known_block_type()

block_manager::is_known_block_type ( $blockname,
$includeinvisible = false )

Find out if a block type is known by the system.

Parameters
string$blocknamethe name of the type of block.
boolean$includeinvisibleif false (default) only check 'visible' blocks, that is, blocks enabled by the admin.
Return values
booleantrue if this block in installed.

◆ is_known_region()

block_manager::is_known_region ( $region)

Find out if a region exists on a page.

Parameters
string$regiona region name
Return values
booleantrue if this region exists on this page.

◆ load_blocks()

block_manager::load_blocks ( $includeinvisible = null)

Actions ====================================================================.

This method actually loads the blocks for our page from the database.

Parameters
boolean | null$includeinvisiblenull (default) - load hidden blocks if $this->page->user_is_editing(); true - load hidden blocks. false - don't load hidden blocks.

Reimplemented in my_syspage_block_manager.

◆ prepare_per_region_arrays()

block_manager::prepare_per_region_arrays ( )
protected

Returns an array of region names as keys and nested arrays for values.

Return values
arrayan array where the array keys are the region names, and the array values are empty arrays.

◆ process_url_actions()

block_manager::process_url_actions ( )

Process any block actions that were specified in the URL.

Return values
booleantrue if anything was done. False if not.

◆ process_url_add()

block_manager::process_url_add ( )

Handle adding a block.

Return values
booleantrue if anything was done. False if not.

◆ process_url_delete()

block_manager::process_url_delete ( )

Handle deleting a block.

Return values
booleantrue if anything was done. False if not.

◆ process_url_edit()

block_manager::process_url_edit ( )

Handle showing/processing the submission from the block editing form.

Return values
booleantrue if the form was submitted and the new config saved. Does not return if the editing form was displayed. False otherwise.

◆ process_url_move()

block_manager::process_url_move ( )

Handle showing/processing the submission from the block editing form.

Return values
booleantrue if the form was submitted and the new config saved. Does not return if the editing form was displayed. False otherwise.

◆ process_url_show_hide()

block_manager::process_url_show_hide ( )

Handle showing or hiding a block.

Return values
booleantrue if anything was done. False if not.

◆ protect_block()

static block_manager::protect_block ( $blockidorname)
static

Make this block type undeletable and unaddable.

Parameters
mixed$blockidornamestring or int

◆ region_completely_docked()

block_manager::region_completely_docked ( $region,
$output )

Checks to see whether all of the blocks within the given region are docked.

See also
region_uses_dock
Parameters
string$region
Return values
boolTrue if all of the blocks within that region are docked

Return false as from MDL-64506

◆ region_has_content()

block_manager::region_has_content ( $region,
$output )

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.)

Parameters
string$regiona block region that exists on this page.
core_renderer$outputa core_renderer. normally the global $OUTPUT.
Return values
booleanWhether there is anything in this region.

◆ region_has_fakeblocks()

block_manager::region_has_fakeblocks ( $region)

Determine whether a region contains any fake blocks.

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

Parameters
string$regiona block region that exists on this page.
Return values
booleanWhether there are fake blocks in this region.

◆ region_uses_dock()

block_manager::region_uses_dock ( $regions,
$output )

Checks to see whether any of the blocks within the given regions are docked.

See also
region_completely_docked
Parameters
array | string$regionsarray of regions (or single region)
Return values
boolTrue if any of the blocks within that region are docked

Return false as from MDL-64506

◆ reposition_block()

block_manager::reposition_block ( $blockinstanceid,
$newregion,
$newweight )

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.

Parameters
$blockinstanceidthe block instance id.
$newregionthe new region name.
$newweightthe new weight.

◆ save_block_data()

block_manager::save_block_data ( block_base $block,
stdClass $data )

Updates block configuration in the database.

Parameters
block_base$block
stdClass$datadata from the block edit form
Return values
void

◆ set_default_region()

block_manager::set_default_region ( $defaultregion)

Set the default region for new blocks on the page.

Parameters
string$defaultregionthe internal names of the region where new blocks should be added by default, and where any blocks from an unrecognised region are shown.

◆ show_only_fake_blocks()

block_manager::show_only_fake_blocks ( $setting = true)

Turns the display of normal blocks either on or off.

Parameters
bool$setting

◆ unprotect_block()

static block_manager::unprotect_block ( $blockidorname)
static

Make this block type deletable and addable.

Parameters
mixed$blockidornamestring or int

◆ user_can_delete_block()

block_manager::user_can_delete_block ( $block)
protected
Parameters
block_base$blocka block that appears on this page.
Return values
booleanboolean whether the currently logged in user is allowed to delete this block.

Member Data Documentation

◆ $addableblocks

array block_manager::$addableblocks = null
protected

blocks that this user can add to this page.

Will be a subset of $allblocks, but with array keys block->name. Access this via the get_addable_blocks() method to ensure it is lazy-loaded.

◆ $movingblock

integer null block_manager::$movingblock = null
protected

Used by the block move id, to track whether a block is currently being moved.

When you click on the move icon of a block, first the page needs to reload with extra UI for choosing a new position for a particular block. In that situation this field holds the id of the block being moved.

◆ $page

moodle_page block_manager::$page
protected

Field declarations =========================================================.

the moodle_page we are managing blocks for.


The documentation for this class was generated from the following file: