Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.

Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

Base class for course format plugins

Copyright: 2012 Marina Glancy
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1468 lines (59 kb)
Included or required:0 times
Referenced: 10 times
Includes or requires: 0 files

Defines 2 classes

format_base:: (52 methods):
  __construct()
  get_format_or_default()
  get_class_name()
  instance()
  reset_course_cache()
  get_format()
  get_courseid()
  get_course()
  get_last_section_number()
  get_max_sections()
  has_view_page()
  uses_sections()
  get_sections()
  get_section()
  get_section_name()
  get_default_section_name()
  supports_ajax()
  ajax_section_move()
  get_view_url()
  extend_course_navigation()
  get_default_blocks()
  get_format_name()
  course_format_options()
  section_format_options()
  get_format_options()
  create_edit_form_elements()
  edit_form_validation()
  validate_format_options()
  validate_course_format_options()
  update_format_options()
  update_course_format_options()
  update_section_format_options()
  editsection_form()
  page_set_course()
  page_set_cm()
  course_header()
  course_footer()
  course_content_header()
  course_content_footer()
  get_renderer()
  is_section_current()
  section_get_available_hook()
  can_delete_section()
  delete_section()
  inplace_editable_render_section_name()
  inplace_editable_update_section_name()
  get_default_course_enddate()
  supports_news()
  get_form_start_date()
  allow_stealth_module_visibility()
  section_action()
  get_config_for_external()

format_site:: (8 methods):
  get_section_name()
  get_view_url()
  get_default_blocks()
  course_format_options()
  allow_stealth_module_visibility()
  contract_value()
  clean_param_if_not_null()
  expand_value()

Defines 8 functions


Class: format_base  - X-Ref

Base class for course formats

Each course format must declare class
class format_FORMATNAME extends format_base {}
in file lib.php

For each course just one instance of this class is created and it will always be returned by
course_get_format($courseorid). Format may store it's specific course-dependent options in
variables of this class.

In rare cases instance of child class may be created just for format without course id
i.e. to check if format supports AJAX.

Also course formats may extend class section_info and overwrite
format_base::build_section_cache() to return more information about sections.

If you are upgrading from Moodle 2.3 start with copying the class format_legacy and renaming
it to format_FORMATNAME, then move the code from your callback functions into
appropriate functions of the class.

__construct($format, $courseid)   X-Ref
Creates a new instance of class

Please use {@link course_get_format($courseorid)} to get an instance of the format class

param: string $format
param: int $courseid
return: format_base

get_format_or_default($format)   X-Ref
Validates that course format exists and enabled and returns either itself or default format

param: string $format
return: string

get_class_name($format)   X-Ref
Get class name for the format

If course format xxx does not declare class format_xxx, format_legacy will be returned.
This function also includes lib.php file from corresponding format plugin

param: string $format
return: string

instance($courseorid)   X-Ref
Returns an instance of the class

param: int|stdClass $courseorid either course id or
return: format_base

reset_course_cache($courseid = 0)   X-Ref
Resets cache for the course (or all caches)
To be called from {@link rebuild_course_cache()}

param: int $courseid

get_format()   X-Ref
Returns the format name used by this course

return: string

get_courseid()   X-Ref
Returns id of the course (0 if course is not specified)

return: int

get_course()   X-Ref
Returns a record from course database table plus additional fields
that course format defines

return: stdClass

get_last_section_number()   X-Ref
Method used in the rendered and during backup instead of legacy 'numsections'

Default renderer will treat sections with sectionnumber greater that the value returned by this
method as "orphaned" and not display them on the course page unless in editing mode.
Backup will store this value as 'numsections'.

This method ensures that 3rd party course format plugins that still use 'numsections' continue to
work but at the same time we no longer expect formats to have 'numsections' property.

return: int

get_max_sections()   X-Ref
Method used to get the maximum number of sections for this course format.

return: int

has_view_page()   X-Ref
Returns true if the course has a front page.

This function is called to determine if the course has a view page, whether or not
it contains a listing of activities. It can be useful to set this to false when the course
format has only one activity and ignores the course page. Or if there are multiple
activities but no page to see the centralised information.

Initially this was created to know if forms should add a button to return to the course page.
So if 'Return to course' does not make sense in your format your should probably return false.

return: boolean

uses_sections()   X-Ref
Returns true if this course format uses sections

This function may be called without specifying the course id
i.e. in {@link course_format_uses_sections()}

Developers, note that if course format does use sections there should be defined a language
string with the name 'sectionname' defining what the section relates to in the format, i.e.
$string['sectionname'] = 'Topic';
or
$string['sectionname'] = 'Week';

return: bool

get_sections()   X-Ref
Returns a list of sections used in the course

This is a shortcut to get_fast_modinfo()->get_section_info_all()
return: array of section_info objects

get_section($section, $strictness = IGNORE_MISSING)   X-Ref
Returns information about section used in course

param: int|stdClass $section either section number (field course_section.section) or row from course_section table
param: int $strictness
return: section_info

get_section_name($section)   X-Ref
Returns the display name of the given section that the course prefers.

param: int|stdClass $section Section object from database or just field course_sections.section
return: Display name that the course format prefers, e.g. "Topic 2"

get_default_section_name($section)   X-Ref
Returns the default section using format_base's implementation of get_section_name.

param: int|stdClass $section Section object from database or just field course_sections section
return: string The default value for the section name based on the given course format.

supports_ajax()   X-Ref
Returns the information about the ajax support in the given source format

The returned object's property (boolean)capable indicates that
the course format supports Moodle course ajax features.

return: stdClass

ajax_section_move()   X-Ref
Custom action after section has been moved in AJAX mode

Used in course/rest.php

return: array This will be passed in ajax respose

get_view_url($section, $options = array()   X-Ref
The URL to use for the specified course (with section)

Please note that course view page /course/view.php?id=COURSEID is hardcoded in many
places in core and contributed modules. If course format wants to change the location
of the view script, it is not enough to change just this function. Do not forget
to add proper redirection.

param: int|stdClass $section Section object from database or just field course_sections.section
param: array $options options for view URL. At the moment core uses:
return: null|moodle_url

extend_course_navigation($navigation, navigation_node $node)   X-Ref
Loads all of the course sections into the navigation

This method is called from {@link global_navigation::load_course_sections()}

By default the method {@link global_navigation::load_generic_course_sections()} is called

When overwriting please note that navigationlib relies on using the correct values for
arguments $type and $key in {@link navigation_node::add()}

Example of code creating a section node:
$sectionnode = $node->add($sectionname, $url, navigation_node::TYPE_SECTION, null, $section->id);
$sectionnode->nodetype = navigation_node::NODETYPE_BRANCH;

Example of code creating an activity node:
$activitynode = $sectionnode->add($activityname, $action, navigation_node::TYPE_ACTIVITY, null, $activity->id, $icon);
if (global_navigation::module_extends_navigation($activity->modname)) {
$activitynode->nodetype = navigation_node::NODETYPE_BRANCH;
} else {
$activitynode->nodetype = navigation_node::NODETYPE_LEAF;
}

Also note that if $navigation->includesectionnum is not null, the section with this relative
number needs is expected to be loaded

param: global_navigation $navigation
param: navigation_node $node The course node within the navigation

get_default_blocks()   X-Ref
Returns the list of blocks to be automatically added for the newly created course

return: array of default blocks, must contain two keys BLOCK_POS_LEFT and BLOCK_POS_RIGHT

get_format_name()   X-Ref
Returns the localised name of this course format plugin

return: lang_string

course_format_options($foreditform = false)   X-Ref
Definitions of the additional options that this course format uses for course

This function may be called often, it should be as fast as possible.
Avoid using get_string() method, use "new lang_string()" instead
It is not recommended to use dynamic or course-dependant expressions here
This function may be also called when course does not exist yet.

Option names must be different from fields in the {course} talbe or any form elements on
course edit form, it may even make sence to use special prefix for them.

Each option must have the option name as a key and the array of properties as a value:
'default' - default value for this option (assumed null if not specified)
'type' - type of the option value (PARAM_INT, PARAM_RAW, etc.)

Additional properties used by default implementation of
{@link format_base::create_edit_form_elements()} (calls this method with $foreditform = true)
'label' - localised human-readable label for the edit form
'element_type' - type of the form element, default 'text'
'element_attributes' - additional attributes for the form element, these are 4th and further
arguments in the moodleform::addElement() method
'help' - string for help button. Note that if 'help' value is 'myoption' then the string with
the name 'myoption_help' must exist in the language file
'help_component' - language component to look for help string, by default this the component
for this course format

This is an interface for creating simple form elements. If format plugin wants to use other
methods such as disableIf, it can be done by overriding create_edit_form_elements().

Course format options can be accessed as:
$this->get_course()->OPTIONNAME (inside the format class)
course_get_format($course)->get_course()->OPTIONNAME (outside of format class)

All course options are returned by calling:
$this->get_format_options();

param: bool $foreditform
return: array of options

section_format_options($foreditform = false)   X-Ref
Definitions of the additional options that this course format uses for section

See {@link format_base::course_format_options()} for return array definition.

Additionally section format options may have property 'cache' set to true
if this option needs to be cached in {@link get_fast_modinfo()}. The 'cache' property
is recommended to be set only for fields used in {@link format_base::get_section_name()},
{@link format_base::extend_course_navigation()} and {@link format_base::get_view_url()}

For better performance cached options are recommended to have 'cachedefault' property
Unlike 'default', 'cachedefault' should be static and not access get_config().

Regardless of value of 'cache' all options are accessed in the code as
$sectioninfo->OPTIONNAME
where $sectioninfo is instance of section_info, returned by
get_fast_modinfo($course)->get_section_info($sectionnum)
or get_fast_modinfo($course)->get_section_info_all()

All format options for particular section are returned by calling:
$this->get_format_options($section);

param: bool $foreditform
return: array

get_format_options($section = null)   X-Ref
Returns the format options stored for this course or course section

When overriding please note that this function is called from rebuild_course_cache()
and section_info object, therefore using of get_fast_modinfo() and/or any function that
accesses it may lead to recursion.

param: null|int|stdClass|section_info $section if null the course format options will be returned
return: array

create_edit_form_elements(&$mform, $forsection = false)   X-Ref
Adds format options elements to the course/section edit form

This function is called from {@link course_edit_form::definition_after_data()}

param: MoodleQuickForm $mform form the elements are added to
param: bool $forsection 'true' if this is a section edit form, 'false' if this is course edit form
return: array array of references to the added form elements

edit_form_validation($data, $files, $errors)   X-Ref
Override if you need to perform some extra validation of the format options

param: array $data array of ("fieldname"=>value) of submitted data
param: array $files array of uploaded files "element_name"=>tmp_file_path
param: array $errors errors already discovered in edit form validation
return: array of "element_name"=>"error_description" if there are errors,

validate_format_options(array $rawdata, int $sectionid = null)   X-Ref
Prepares values of course or section format options before storing them in DB

If an option has invalid value it is not returned

param: array $rawdata associative array of the proposed course/section format options
param: int|null $sectionid null if it is course format option
return: array array of options that have valid values

validate_course_format_options(array $data)   X-Ref
Validates format options for the course

param: array $data data to insert/update
return: array array of options that have valid values

update_format_options($data, $sectionid = null)   X-Ref
Updates format options for a course or section

If $data does not contain property with the option name, the option will not be updated

param: stdClass|array $data return value from {@link moodleform::get_data()} or array with data
param: null|int null if these are options for course or section id (course_sections.id)
return: bool whether there were any changes to the options values

update_course_format_options($data, $oldcourse = null)   X-Ref
Updates format options for a course

If $data does not contain property with the option name, the option will not be updated

param: stdClass|array $data return value from {@link moodleform::get_data()} or array with data
param: stdClass $oldcourse if this function is called from {@link update_course()}
return: bool whether there were any changes to the options values

update_section_format_options($data)   X-Ref
Updates format options for a section

Section id is expected in $data->id (or $data['id'])
If $data does not contain property with the option name, the option will not be updated

param: stdClass|array $data return value from {@link moodleform::get_data()} or array with data
return: bool whether there were any changes to the options values

editsection_form($action, $customdata = array()   X-Ref
Return an instance of moodleform to edit a specified section

Default implementation returns instance of editsection_form that automatically adds
additional fields defined in {@link format_base::section_format_options()}

Format plugins may extend editsection_form if they want to have custom edit section form.

param: mixed $action the action attribute for the form. If empty defaults to auto detect the
param: array $customdata the array with custom data to be passed to the form
return: moodleform

page_set_course(moodle_page $page)   X-Ref
Allows course format to execute code on moodle_page::set_course()

param: moodle_page $page instance of page calling set_course

page_set_cm(moodle_page $page)   X-Ref
Allows course format to execute code on moodle_page::set_cm()

Current module can be accessed as $page->cm (returns instance of cm_info)

param: moodle_page $page instance of page calling set_cm

course_header()   X-Ref
Course-specific information to be output on any course page (usually above navigation bar)

Example of usage:
define
class format_FORMATNAME_XXX implements renderable {}

create format renderer in course/format/FORMATNAME/renderer.php, define rendering function:
class format_FORMATNAME_renderer extends plugin_renderer_base {
protected function render_format_FORMATNAME_XXX(format_FORMATNAME_XXX $xxx) {
return html_writer::tag('div', 'This is my header/footer');
}
}

Return instance of format_FORMATNAME_XXX in this function, the appropriate method from
plugin renderer will be called

return: null|renderable null for no output or object with data for plugin renderer

course_footer()   X-Ref
Course-specific information to be output on any course page (usually in the beginning of
standard footer)

See {@link format_base::course_header()} for usage

return: null|renderable null for no output or object with data for plugin renderer

course_content_header()   X-Ref
Course-specific information to be output immediately above content on any course page

See {@link format_base::course_header()} for usage

return: null|renderable null for no output or object with data for plugin renderer

course_content_footer()   X-Ref
Course-specific information to be output immediately below content on any course page

See {@link format_base::course_header()} for usage

return: null|renderable null for no output or object with data for plugin renderer

get_renderer(moodle_page $page)   X-Ref
Returns instance of page renderer used by this plugin

param: moodle_page $page
return: renderer_base

is_section_current($section)   X-Ref
Returns true if the specified section is current

By default we analyze $course->marker

param: int|stdClass|section_info $section
return: bool

section_get_available_hook(section_info $section, &$available, &$availableinfo)   X-Ref
Allows to specify for modinfo that section is not available even when it is visible and conditionally available.

Note: affected user can be retrieved as: $section->modinfo->userid

Course format plugins can override the method to change the properties $available and $availableinfo that were
calculated by conditional availability.
To make section unavailable set:
$available = false;
To make unavailable section completely hidden set:
$availableinfo = '';
To make unavailable section visible with availability message set:
$availableinfo = get_string('sectionhidden', 'format_xxx');

param: section_info $section
param: bool $available the 'available' propery of the section_info as it was evaluated by conditional availability.
param: string $availableinfo the 'availableinfo' propery of the section_info as it was evaluated by conditional availability.

can_delete_section($section)   X-Ref
Whether this format allows to delete sections

If format supports deleting sections it is also recommended to define language string
'deletesection' inside the format.

Do not call this function directly, instead use {@link course_can_delete_section()}

param: int|stdClass|section_info $section
return: bool

delete_section($section, $forcedeleteifnotempty = false)   X-Ref
Deletes a section

Do not call this function directly, instead call {@link course_delete_section()}

param: int|stdClass|section_info $section
param: bool $forcedeleteifnotempty if set to false section will not be deleted if it has modules in it.
return: bool whether section was deleted

inplace_editable_render_section_name($section, $linkifneeded = true,$editable = null, $edithint = null, $editlabel = null)   X-Ref
Prepares the templateable object to display section name

param: \section_info|\stdClass $section
param: bool $linkifneeded
param: bool $editable
param: null|lang_string|string $edithint
param: null|lang_string|string $editlabel
return: \core\output\inplace_editable

inplace_editable_update_section_name($section, $itemtype, $newvalue)   X-Ref
Updates the value in the database and modifies this object respectively.

ALWAYS check user permissions before performing an update! Throw exceptions if permissions are not sufficient
or value is not legit.

param: stdClass $section
param: string $itemtype
param: mixed $newvalue
return: \core\output\inplace_editable

get_default_course_enddate($mform, $fieldnames = array()   X-Ref
Returns the default end date value based on the start date.

This is the default implementation for course formats, it is based on
moodlecourse/courseduration setting. Course formats like format_weeks for
example can overwrite this method and return a value based on their internal options.

param: moodleform $mform
param: array $fieldnames The form - field names mapping.
return: int

supports_news()   X-Ref
Indicates whether the course format supports the creation of the Announcements forum.

For course format plugin developers, please override this to return true if you want the Announcements forum
to be created upon course creation.

return: bool

get_form_start_date($mform, $fieldnames)   X-Ref
Get the start date value from the course settings page form.

param: moodleform $mform
param: array $fieldnames The form - field names mapping.
return: int

allow_stealth_module_visibility($cm, $section)   X-Ref
Returns whether this course format allows the activity to
have "triple visibility state" - visible always, hidden on course page but available, hidden.

param: stdClass|cm_info $cm course module (may be null if we are displaying a form for adding a module)
param: stdClass|section_info $section section where this module is located or will be added to
return: bool

section_action($section, $action, $sr)   X-Ref
Callback used in WS core_course_edit_section when teacher performs an AJAX action on a section (show/hide)

Access to the course is already validated in the WS but the callback has to make sure
that particular action is allowed by checking capabilities

Course formats should register

param: stdClass|section_info $section
param: string $action
param: int $sr
return: null|array|stdClass any data for the Javascript post-processor (must be json-encodeable)

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: array the list of configs

Class: format_site  - X-Ref

Pseudo course format used for the site main page

get_section_name($section)   X-Ref
Returns the display name of the given section that the course prefers.

param: int|stdClass $section Section object from database or just field section.section
return: Display name that the course format prefers, e.g. "Topic 2"

get_view_url($section, $options = array()   X-Ref
For this fake course referring to the whole site, the site homepage is always returned
regardless of arguments

param: int|stdClass $section
param: array $options
return: null|moodle_url

get_default_blocks()   X-Ref
Returns the list of blocks to be automatically added on the site frontpage when moodle is installed

return: array of default blocks, must contain two keys BLOCK_POS_LEFT and BLOCK_POS_RIGHT

course_format_options($foreditform = false)   X-Ref
Definitions of the additional options that site uses

param: bool $foreditform
return: array of options

allow_stealth_module_visibility($cm, $section)   X-Ref
Returns whether this course format allows the activity to
have "triple visibility state" - visible always, hidden on course page but available, hidden.

param: stdClass|cm_info $cm course module (may be null if we are displaying a form for adding a module)
param: stdClass|section_info $section section where this module is located or will be added to
return: bool

contract_value(array &$dest, array $source, array $option, string $optionname)   X-Ref
'Converts' a value from what is stored in the database into what is used by edit forms.

author: Jason den Dulk
param: array $dest The destination array
param: array $source The source array
param: array $option The definition structure of the option.
param: string $optionname The name of the option, as provided in the definition.

clean_param_if_not_null($param, string $type = PARAM_RAW)   X-Ref
Cleans the given param, unless it is null.

author: Jason den Dulk
param: mixed $param The variable we are cleaning.
param: string $type Expected format of param after cleaning.
return: mixed Null if $param is null, otherwise the cleaned value.

expand_value(array &$dest, array $source, array $option, string $optionname)   X-Ref
'Converts' a value from what is used in edit forms into a value(s) to be stored in the database.

author: Jason den Dulk
param: array $dest The destination array
param: array $source The source array
param: array $option The definition structure of the option.
param: string $optionname The name of the option, as provided in the definition.

Functions that are not part of a class:

course_get_format($courseorid)   X-Ref
Returns an instance of format class (extending format_base) for given course

param: int|stdClass $courseorid either course id or
return: format_base