Blocks
A Step-by-step Guide To Creating Blocks
Original Author: Jon Papaioannou (pj@moodle.org)
Updated to Moodle 2.0 and above by: Greg J Preece (greg.preece@blackboard.com)
Moodle 2.0
The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) only, as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under Blocks for 1.5 to 1.9.
The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It’s targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.
Experienced developers and those who just want a programmer’s reference text should refer to Appendix A because the main guide has a rather low concentration of pure information in the text.
block_simplehtml.php
This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.
We start by creating the main object file, ‘block_simplehtml.php’. We then begin coding the block:
title = get_string(‘simplehtml’, ‘block_simplehtml’);
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
The first line is our block class definition; it must be named exactly in the manner shown. Again, only the «simplehtml» part can (and indeed must) change; everything else is standardised.
Our class is then given a small method: init(). This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.
In this very basic example, we only want to set $this->title, which is the title displayed in the header of our block. We can set it to whatever we like; in this case it’s set to read the actual title from the language file mentioned below, which is then distributed along with the block. I’ll skip ahead a bit here and say that if you want your block to display no title at all, then you should set this to any descriptive value you want (but not make it an empty string). We will later see how to disable the title’s display.
db/access.php
This file will hold the new capabilities created by the block.
Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the ‘My Moodle page’ (ie, your applicable_formats function (discussed later) has ‘my’ set to false.) then the myaddinstance capability is not required. The following is the capabilities array and how it should look for any new blocks.
array(
‘captype’ => ‘write’,
‘contextlevel’ => CONTEXT_SYSTEM,
‘archetypes’ => array(
‘user’ => CAP_ALLOW
),
‘clonepermissionsfrom’ => ‘moodle/my:manageblocks’
),
‘block/simplehtml:addinstance’ => array(
‘riskbitmask’ => RISK_SPAM | RISK_XSS,
‘captype’ => ‘write’,
‘contextlevel’ => CONTEXT_BLOCK,
‘archetypes’ => array(
‘editingteacher’ => CAP_ALLOW,
‘manager’ => CAP_ALLOW
),
‘clonepermissionsfrom’ => ‘moodle/site:manageblocks’
),
);
lang/en/block_simplehtml.php
This is the English language file for your block. If you are not an English speaker, you can replace ‘en’ with your appropriate language code. All language files for blocks go under the /lang subfolder of the block’s installation folder.
Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).
The capabilities added above need descriptions for pages that allow setting of capabilities. These should also be added to the language file.
component = ‘block_simplehtml’; // Recommended since 2.0.2 (MDL-26035). Required since 3.0 (MDL-48494)
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
This file contains object field definitions that denote the full frankenstyle component name in the form of plugintype_pluginname and the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is always called $plugin, and that you do not need to create this object yourself within the version file. Note also we don’t include a closing «?>» tag. This is intentional, and a workaround for whitespace issues.
The exact Moodle version of a release can be found in Releases.
Back to top of page ↑
I Just Hear Static
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:
public function get_content() {
if ($this->content !== null) {
return $this->content;
}
$this->content = new stdClass;
$this->content->text = ‘The content of our SimpleHTML block!’;
$this->content->footer = ‘Footer here…’;
return $this->content;
}
https://docs.moodle.org/dev/Blocks