Course formats

Course formats are plugins that determine the layout of course resources.

Course formats determine how the course main page looks like (/course/view.php) in both view and editing mode. They are also responsible for building navigation tree inside the course (displayed to user in navigation block and breadcrumb). They can organise the course content in sections. Course creator or teacher can specify course format for the course in course edit form.

Moodle 2.4 and above: Course formats also can add it's own options fields to the course edit form. They can add course dependend content to header/footer of any page inside the course, not only /course/view.php

Components

course/format/FORMATNAME/lang/en/format_FORMATNAME.php

Contains the English language strings used in the format. You can also define strings for other languages.

course/format/FORMATNAME/config.php (deprecated since 2.4)

Contains $format['defaultblocks'] which defines the default blocks loaded with the format.

course/format/FORMATNAME/format.php

This is is the layout itself. It is included in course/view.php.

course/format/FORMATNAME/lib.php

The main library of the format. In Moodle versions up to 2.3 it should contain implementations of course format callbacks. In versions 2.4 and above it should contain a class format_FORMATNAME extending format_base. Also it may contain callbacks for other core and contributed APIs if necessary

course/format/FORMATNAME/styles.css, styles_THEMENAME.css

Optional stylesheet. Note that this file is included on all pages on the site, even in the courses that use other formats. In 2.4+ the class format-FORMATNAME is automatically added to body for all pages inside the course, it is recommended to prefix all directives in your styles.css with body.format-FORMATNAME

File styles.css will be included always, styles_THEMENAME.css only if theme_THEMENAME is used for the site (or for the course).

course/format/FORMATNAME/settings.php (version 2.4 and above)

Optional plugin administrative settings

course/format/FORMATNAME/renderer.php

Optional but very recommended file containing renderer for this course format. This file will contain class format_FORMATNAME_renderer extends plugin_renderer_base. See Output renderers

course/format/FORMATNAME/version.php

Version definitions, see version.php. It is highly recommended always to have it and it is required if you have any files in db folder

course/format/db/install.xml, course/format/db/install.php, course/format/db/upgrade.php

Definitions of tables used by this plugin and upgrade script, see Upgrade API

course/format/backup/

Implementation of backup and restore for additional tables defined in your plugin. See Backup API. This is only needed if you define additional tables in your db folder. Data from table course_format_options is backed up for your plugin automatically

course/format/db/access.php

Capabilities introduced by this plugin, see Access API. Please note that if you define new capabilities inside course format they should not affect accessibility of course modules because other components (for example reports and/or gradebook) will not know about them

Also your course format may contain Javascript files and/or YUI modules.

Creating a New Format

The easiest way to create a new course format is to copy an existing one.

1. Copy the folder containing the format files.

2. Rename the folder to the new name. Course format names cannot exceed 21 characters. (In Moodle 2.3 and below the limit is 10 characters)

3. Rename language files in course/format/FORMATNAME/lang/

4. Change $string['pluginname'] in course/format/FORMATNAME/lang/en/format_FORMATNAME.php to the new name.

5. Moodle 2.3 and below: Rename callback functions in lib.php. The names of the functions is formed as callback_FORMATNAME_CALLBACKNAME()

Moodle 2.4 and above: Rename class name in lib.php to format_FORMATNAME.

6. Search and replace other occurences of the old format name, for example in renderer, capabilities names, etc.

7. The new format is ready for modification.

Upgrading format to the next Moodle version

Read the files course/format/upgrade.txt, lib/upgrade.txt and also upgrade.txt of the core APIs that you use in your course format plugin and make changes according to them. When testing don't forget to enable Developer debugging level and error display (Settings->Developer->Debugging)

If you upgrade your course format plugin from Moodle 2.3 to Moodle 2.4 - copy class format_legacy to your lib.php and rename it to format_FORMATNAME. Then go through the class functions and replace calling of functions with the corresponding callbacks' code. Move blocks list from config.php to the function format_FORMATNAME::get_default_blocks()

Using renderer

Since course format is all about the display it is very important to separate HTML and PHP. All HTML code should be in your format_FORMATNAME_renderer class in renderer.php. Ideally format.php will only call one function from renderer.

Developing course formats for Moodle 2.4 and above

File lib.php in your course format will contain class format_FORMATNAME extends format_base. The parent class is located in course/format/lib.php and has detailed PHPdocs for each functions that you can override. Some functions are defined as final and you can not override them. Some functions such as get_course(), get_format_options(), update_format_options() and get_renderer() usually do not need to be overriden unless you know exactly what you are doing.

Here are the main features in course formats and responsible for them format_base functions

Course sections

There is existing functionality in Moodle core to support organising course modules into sections. Course format plugins do not have to use them but the most of them do. Database table {course_sections} stores basic information about sections. Also sections info is cached and returned by get_fast_modinfo() so every action changing the sections must be followed by rebuild_course_cache(). Course module must always belong to the section. Even if your course format does not use sections, the section with number 0 is always created.

You must define $string['sectionname'] if your language file even if format does not use sections because it can be called unconditionally from other parts of the code, even though it won't be displayed.

format_base method in 2.4+	description	Moodle 2.3- callback
uses_sections()	returns true or false if the format uses sections or not. There is a global function course_format_uses_secions() that invokes it. It affects default navigation tree building. Various modules and reports may call this function to know whether to display section name for the particular module or not.	callback_FORMATNAME_uses_sections()
get_section_name()		callback_FORMATNAME_get_section_name()
get_view_url()=		2.3 only: callback_FORMATNAME_get_section_url(). Prior to Moodle 2.3 sections could not have separate URLs
ajax_section_move()		callback_FORMATNAME_ajax_section_move()
is_section_current()	Specifies if the section is current, for example current week or highlighted topic. This function is only used if your renderer uses it for example if your renderer extends format_section_renderer_base. This function is not called from anywhere else in Moodle core.	format_section_renderer_base::is_section_current()

supports_ajax()

...

In Moodle 2.3 and below developer would define function callback_FORMATNAME_ajax_support()

get_default_blocks()

...

In Moodle 2.3 and below developer needed to create file config.php with $format['defaultblocks'] in it

Extending course navigation

...

In Moodle 2.3 and below developer would define functions callback_FORMATNAME_display_content() and/or callback_FORMATNAME_load_content()

Course format options

The core table {course_format_options} in Moodle database is designed to store additional options for course formats. This may be options for the whole course or options for course section. In order to use this functionality course format:

• should define options used for the course and for section and their default values
• make sure options appear as form elements in course and/or section edit form
• if necessary define additional validation for those forms
• may create rules how to calculate the values of course options when format of the course is changed

Also course format may completely overwrite the section edit form

Course format options must not have the same names as fields in database table {course}

Some facts about course format options in core classes:

• Core formats format_weeks and format_topics have options: numsections, hiddensections, coursedisplay. They are also defined as default in class format_legacy because prior to 2.4 they were fields in {course} table and were part of course edit form.
• Class format_base by default does not define any options.
• Core formats format_social and format_scorm do not have have any options.
• Neither core course format uses additional section options. You may find some examples though in plugins database.

When teacher changes the course format in the course edit form AND the old and the new course formats share the same option name, the value of this option is copied from one format to another. For example, if course had format Topics and had 8 sections in it and teacher changes format to weeks, the course will have 8 weeks in it.

During backup the course format options are stored as if they were additional fields in {course} table. Therefore courses in topics and weeks formats that were backed up in Moodle 2.3 will be restored in 2.4 without data loss even though the values of numsections, hiddensections and coursedisplay will be stored in another table.

Webservices expect course format options to be passed in additional entity but for backward compartibility numsections, hiddensections and coursedisplay can also be passed as if they were fields in {course} table.

...

Executing code before output

It is often needed to execute some code before output started. You may want to

• redirect from one page to another. Examples are format_scorm format_singleactivity that don't have course view page and redirect /course/view.php to module view page
• perform an action that results in changes in navigation tree or other output. Example is when /course/view.php has a parameter in query that tells to change section visibility
• include additional JS or CSS files in the page head rather than body

File format.php is included after the output is started and the above cases can not be solved inside it.

There are two functions format_base::page_set_cm() and format_base::page_set_course(). Every module or page inside a course must call require_login() or otherwise specify the current course and module on the page. As soon as page knows the current module and/or course, the callbacks from current course format are invoked.

There is no similar functionality in Moodle 2.3 or below

Additional footer or header on any page inside the course

Course format may add content header and footer to any page inside the course (including modules pages). They will be displayed right above or below the page main content, right or left from side blocks. Also course formats may add course header and footer. They will be displayed above or below both content and blocks. Typical usages may be:

• course navigation (prev/next/back)
• course custom menu
• disclaimer information or other text in the bottom of each course page
• etc

This is a new feature in Moodle 2.4, you have to make sure that if the site uses the custom theme, it supports it. Refer to theme/upgrade.txt. Also theme may specify that some pagelayouts (report, print, etc) do NOT display the course header/footer.

Using this functionality REQUIRES use of renderers. Example of using the course headers/footers you can find in tracker issue MDL-36048