View source

== Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

<code php>
class CourseBlock_online_users extends MoodleBlock { ... }
</code>

to

<code php> 
class block_online_users extends block_base { ... }
</code>

An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

<code php> 
class block_admin extends block_list { ... }
</code>

=== Constructor versus ''init()'' ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

<code php>
function CourseBlock_online_users ($course) {
  $this->title        = get_string('blockname','block_online_users');
  $this->content_type = BLOCK_TYPE_TEXT;
  $this->course       = $course;
  $this->version      = 2004052700;
}
</code>

In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an [[Development:Blocks/Appendix_A#init.28.29| init()]] method that takes no arguments:

<code php>
function init() {
  $this->title   = get_string('blockname','block_online_users');
  $this->version = 2004111600;
}
</code>

Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]], the way to retrieve it is by using this code:

<code php> 
  $course = get_record('course', 'id', $this->instance->pageid);
</code>

If you are going to need access to $course from inside other methods in addition to [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]], you might fetch the $course object inside the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

<code php>
function specialization() {
  $this->course = get_record('course', 'id', $this->instance->pageid);
}
</code>

=== Blocks with configuration ===

In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:

# Rename your '''config.html''' file to '''config_global.html'''.
# Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
# If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
# If you have overridden '''print_config''', rename your method to [[Development:Blocks/Appendix_A#config_print.28.29|config_print()]].
# If you have overridden '''handle_config''', rename your method to [[Development:Blocks/Appendix_A#config_save.28.29|config_save()]].

=== Blocks with customized applicable formats ===

The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Development:Blocks/Appendix_A#applicable_formats.28.29| applicable_formats()]] if they are used in your block:

# '''social''' should become '''course-view-social'''
# '''topics''' should become '''course-view-topics'''
# '''weeks''' should become '''course-view-weeks'''

You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Development:Blocks/Appendix_A#applicable_formats.28.29| applicable_formats()]], and for a more extended example read [[Development:Blocks#Authorized_Personnel_Only|Authorized Personnel Only]], the section dedicated to this subject.

That's everything; your block will now be ready for use in Moodle 1.5!

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック/付録B]]