Search moodle.org's
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.

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]

This file contains the parent class for moodle blocks, block_base.

License: http://www.gnu.org/copyleft/gpl.html GNU Public License
File Size: 863 lines (29 kb)
Included or required: 13 times
Referenced: 1 time
Includes or requires: 0 files

Defines 3 classes


Class: block_base  - X-Ref

Class for describing a moodle block, all Moodle blocks derive from this class

__construct()   X-Ref
Fake constructor to keep PHP5 happy


before_delete()   X-Ref
Function that can be overridden to do extra cleanup before
the database tables are deleted. (Called once per block, not per instance!)


name()   X-Ref
Returns the block name, as present in the class name,
the database, the block directory, etc etc.

return: string

get_content()   X-Ref
Parent class version of this function simply returns NULL
This should be implemented by the derived class to return
the content object.

return: stdObject

get_title()   X-Ref
Returns the class $title var value.

Intentionally doesn't check if a title is set.
This is already done in {@link _self_test()}

return: string $this->title

get_content_type()   X-Ref
Returns the class $content_type var value.

Intentionally doesn't check if content_type is set.
This is already done in {@link _self_test()}

return: string $this->content_type

is_empty()   X-Ref
Returns true or false, depending on whether this block has any content to display
and whether the user has permission to view the block

return: boolean

refresh_content()   X-Ref
First sets the current value of $this->content to NULL
then calls the block's {@link get_content()} function
to set its value back.

return: stdObject

get_content_for_output($output)   X-Ref
Return a block_contents object representing the full contents of this block.

This internally calls ->get_content(), and then adds the editing controls etc.

You probably should not override this method, but instead override
{@link html_attributes()}, {@link formatted_contents()} or {@link get_content()},
{@link hide_header()}, {@link (get_edit_controls)}, etc.

return: block_contents a representation of the block, for rendering.

get_content_for_external($output)   X-Ref
Return an object containing all the block content to be returned by external functions.

If your block is returning formatted content or provide files for download, you should override this method to use the
external_format_text, external_format_string functions for formatting or external_util::get_area_files for files.

param: core_renderer $output the rendered used for output
return: stdClass      object containing the block title, central content, footer and linked files (if any).

get_config_for_external()   X-Ref
Return the plugin config settings for external functions.

In some cases the configs will need formatting or be returned only if the current user has some capabilities enabled.

return: stdClass the configs for both the block instance and plugin (as object with name -> value)

formatted_contents($output)   X-Ref
Convert the contents of the block to HTML.

This is used by block base classes like block_list to convert the structured
$this->content->list and $this->content->icons arrays to HTML. So, in most
blocks, you probaby want to override the {@link get_contents()} method,
which generates that structured representation of the contents.

param: $output The core_renderer to use when generating the output.
return: string the HTML that should appearn in the body of the block.

_self_test()   X-Ref
Tests if this block has been implemented correctly.
Also, $errors isn't used right now

return: boolean

has_config()   X-Ref
Subclasses should override this and return true if the
subclass block has a settings.php file.

return: boolean

config_save($data)   X-Ref
Default behavior: save all variables as $CFG properties
You don't need to override this if you 're satisfied with the above


applicable_formats()   X-Ref
Which page types this block may appear on.

The information returned here is processed by the
{@link blocks_name_allowed_in_format()} function. Look there if you need
to know exactly how this works.

Default case: everything except mod and tag.

return: array page-type prefix => true/false.

hide_header()   X-Ref
Default return is false - header will be shown

return: boolean

html_attributes()   X-Ref
Return any HTML attributes that you want added to the outer <div> that
of the block when it is output.

Because of the way certain JS events are wired it is a good idea to ensure
that the default values here still get set.
I found the easiest way to do this and still set anything you want is to
override it within your block in the following way

<code php>
function html_attributes() {
$attributes = parent::html_attributes();
$attributes['class'] .= ' mynewclass';
return $attributes;
}
</code>

return: array attribute name => value.

_load_instance($instance, $page)   X-Ref
Set up a particular instance of this class given data from the block_insances
table and the current page. (See {@link block_manager::load_blocks()}.)

param: stdClass $instance data from block_insances, block_positions, etc.
param: moodle_page $the page this block is on.

get_required_javascript()   X-Ref
Allows the block to load any JS it requires into the page.

By default this function simply permits the user to dock the block if it is dockable.

Left null as of MDL-64506.

specialization()   X-Ref
This function is called on your subclass right after an instance is loaded
Use this function to act on instance data just after it's loaded and before anything else is done
For instance: if your block will have different title's depending on location (site, course, blog, etc)


instance_allow_config()   X-Ref
Is each block of this type going to have instance-specific configuration?
Normally, this setting is controlled by {@link instance_allow_multiple()}: if multiple
instances are allowed, then each will surely need its own configuration. However, in some
cases it may be necessary to provide instance configuration to blocks that do not want to
allow multiple instances. In that case, make this function return true.
I stress again that this makes a difference ONLY if {@link instance_allow_multiple()} returns false.

return: boolean

instance_allow_multiple()   X-Ref
Are you going to allow multiple instances of each block?
If yes, then it is assumed that the block WILL USE per-instance configuration

return: boolean

instance_config_save($data, $nolongerused = false)   X-Ref
Serialize and store config data


instance_config_commit($nolongerused = false)   X-Ref
Replace the instance's configuration data with those currently in $this->config;


instance_create()   X-Ref
Do any additional initialization you may need at the time a new block instance is created

return: boolean

instance_copy($fromid)   X-Ref
Copy any block-specific data when copying to a new block instance.

param: int $fromid the id number of the block instance to copy from
return: boolean

instance_delete()   X-Ref
Delete everything related to this instance if you have been using persistent storage other than the configdata field.

return: boolean

user_can_edit()   X-Ref
Allows the block class to have a say in the user's ability to edit (i.e., configure) blocks of this type.
The framework has first say in whether this will be allowed (e.g., no editing allowed unless in edit mode)
but if the framework does allow it, the block can still decide to refuse.

return: boolean

user_can_addto($page)   X-Ref
Allows the block class to have a say in the user's ability to create new instances of this block.
The framework has first say in whether this will be allowed (e.g., no adding allowed unless in edit mode)
but if the framework does allow it, the block can still decide to refuse.
This function has access to the complete page object, the creation related to which is being determined.

param: moodle_page $page
return: boolean

has_add_block_capability($page, $capability)   X-Ref
Returns true if the user can add a block to a page.

param: moodle_page $page
param: string $capability the capability to check
return: boolean true if user can add a block, false otherwise.

get_extra_capabilities()   X-Ref
No description

instance_can_be_docked()   X-Ref
Can be overridden by the block to prevent the block from being dockable.

return: bool

instance_can_be_hidden()   X-Ref
If overridden and set to false by the block it will not be hidable when
editing is turned on.

return: bool

instance_can_be_collapsed()   X-Ref
If overridden and set to false by the block it will not be collapsible.

return: bool

instance_can_be_edited()   X-Ref
If overridden and set to false by the block it will not be editable.

return: bool

comment_template($options)   X-Ref
No description

comment_permissions($options)   X-Ref
No description

comment_url($options)   X-Ref
No description

comment_display($comments, $options)   X-Ref
No description

comment_add(&$comments, $options)   X-Ref
No description

get_aria_role()   X-Ref
Returns the aria role attribute that best describes this block.

Region is the default, but this should be overridden by a block is there is a region child, or even better
a landmark child.

Options are as follows:
- landmark
- application
- banner
- complementary
- contentinfo
- form
- main
- navigation
- search

return: string

can_block_be_added(moodle_page $page)   X-Ref
This method can be overriden to add some extra checks to decide whether the block can be added or not to a page.
It doesn't need to do the standard capability checks as they will be performed by has_add_block_capability().
This method is user agnostic. If you want to check if a user can add a block or not, you should use user_can_addto().

param: moodle_page $page The page where this block will be added.
return: bool Whether the block can be added or not to the given page.

Class: block_list  - X-Ref

Specialized class for displaying a block with a list of icons/text labels

The get_content method should set $this->content->items and (optionally)
$this->content->icons, instead of $this->content->text.

is_empty()   X-Ref
No description

formatted_contents($output)   X-Ref
No description

html_attributes()   X-Ref
No description

Class: block_tree  - X-Ref

Specialized class for displaying a tree menu.

The {@link get_content()} method involves setting the content of
<code>$this->content->items</code> with an array of {@link tree_item}
objects (these are the top-level nodes). The {@link tree_item::children}
property may contain more tree_item objects, and so on. The tree_item class
itself is abstract and not intended for use, use one of it's subclasses.

Unlike {@link block_list}, the icons are specified as part of the items,
not in a separate array.

formatted_contents($output)   X-Ref
Make the formatted HTML ouput.

Also adds the required javascript call to the page output.

param: core_renderer $output
return: string HTML