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

Inheritance diagram for 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.

Copyright: 2009 Tim Hunt

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 $page the 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	$blockname	The type of block to add.
string	$region	the block region on this page to add the block to.
integer	$weight	determines the order where this block appears in the region.
boolean	$showinsubcontexts	whether this block appears in subcontexts, or just the current context.
string \| null	$pagetypepattern	which page types this block should appear on. Defaults to just the current page type.
string \| null	$subpagepattern	which 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	$blockname	Name of the block to add.
null \| string	$blockregion	If 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 $blockname the 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	$blocks	array with array keys the region names, and values an array of block names.
string \| null	$pagetypepattern	optional. Passed to {

See also: self\add_block()}

Parameters

string | null $subpagepattern optional. Passed to {

See also: self\add_block()}

Parameters

bool $showinsubcontexts optional. Passed to {

See also: self\add_block()}

Parameters

int $weight optional. 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	$bc	the content of the block-like thing.
string	$region	a 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	$region	add 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	$custom	True 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 $regions this 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

void	Throws 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	$blockname	The block type name to search for
bool	$includeinvisible	Include disabled block types in the initial pass

Return values

void	Coding 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

void	Throws 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

void	Coding 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	$instances	An array of block instances
	renderer_base	The renderer to use.
string	$region	the region name.

Return values

array An 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 $birecords An array of block instance records

Return values

array An 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

array an 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 $region The 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 $region Check 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

array block 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 $blockname name 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 $region a block region that exists on this page.

Return values

array of 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 $output the rendered to use

Return values

array of 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 $region a block region that exists on this page.

Return values

array of 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

string the 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

array contents 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	$region	region name
float	$weight	weight. 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_url URL 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

array the 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

array names 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

array A 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

array names 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	$blockname	the name of the type of block.
boolean	$includeinvisible	if false (default) only check 'visible' blocks, that is, blocks enabled by the admin.

Return values

boolean true 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 $region a region name

Return values

boolean true 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 $includeinvisible null (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

array an 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

boolean true if anything was done. False if not.

◆ process_url_add()

block_manager::process_url_add ( )

Handle adding a block.

Return values

boolean true if anything was done. False if not.

◆ process_url_delete()

block_manager::process_url_delete ( )

Handle deleting a block.

Return values

boolean true 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

boolean true 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

boolean true 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

boolean true 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 $blockidorname string 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

bool	True 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	$region	a block region that exists on this page.
core_renderer	$output	a core_renderer. normally the global $OUTPUT.

Return values

boolean Whether 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 $region a block region that exists on this page.

Return values

boolean Whether 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 $regions array of regions (or single region)

Return values

bool	True 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

$blockinstanceid	the block instance id.
$newregion	the new region name.
$newweight	the 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	$data	data 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 $defaultregion the 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 $blockidorname string or int

◆ user_can_delete_block()

block_manager::user_can_delete_block ( $block )

protected

Parameters

block_base $block a block that appears on this page.

Return values

boolean boolean 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:

lib/blocklib.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ add_block()

◆ add_block_at_end_of_default_region()

◆ add_block_required_by_theme()

◆ add_blocks()

◆ add_custom_regions_for_pagetype()

◆ add_fake_block()

◆ add_region()

◆ add_regions()

◆ check_is_loaded()

◆ check_known_block_type()

◆ check_not_yet_loaded()

◆ check_region_is_known()

◆ create_all_block_instances()

◆ create_block_contents()

◆ create_block_instances()

◆ edit_controls()

◆ ensure_content_created()

◆ ensure_instances_exist()

◆ find_instance()

◆ get_addable_blocks()

◆ get_block_edit_form_class()

◆ get_blocks_for_region()

◆ get_content_for_all_regions()

◆ get_content_for_region()

◆ get_default_region()

◆ get_installed_blocks()

◆ get_move_target_url()

◆ get_regions()

◆ get_required_by_theme_block_types()

◆ get_secondarynav()

◆ get_unaddable_by_theme_block_types()

◆ get_undeletable_block_types()

◆ is_block_present()

◆ is_known_block_type()

◆ is_known_region()

◆ load_blocks()

◆ prepare_per_region_arrays()

◆ process_url_actions()

◆ process_url_add()

◆ process_url_delete()

◆ process_url_edit()

◆ process_url_move()

◆ process_url_show_hide()

◆ protect_block()

◆ region_completely_docked()

◆ region_has_content()

◆ region_has_fakeblocks()

◆ region_uses_dock()

◆ reposition_block()

◆ save_block_data()

◆ set_default_region()

◆ show_only_fake_blocks()

◆ unprotect_block()

◆ user_can_delete_block()

Member Data Documentation

◆ $addableblocks

◆ $movingblock

◆ $page