Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/course/format/classes/ -> base.php (source)
Differences Between: [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
Contains the base definition class for any course format plugin.
| Copyright: | 2020 Ferran Recio <ferran@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1719 lines (68 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 1 class
base:: (72 methods):
__construct()
get_format_or_default()
get_class_name()
instance()
reset_course_cache()
session_cache_reset_all()
session_cache_reset()
session_cache()
get_format()
get_courseid()
get_course()
get_course_display()
get_modinfo()
get_last_section_number()
get_max_sections()
has_view_page()
page_title()
uses_sections()
uses_course_index()
uses_indentation()
get_sections()
get_section()
get_section_name()
get_default_section_name()
get_section_highlighted_name()
set_section_number()
get_section_number()
get_sections_preferences()
get_sections_preferences_by_preference()
set_sections_preference()
supports_ajax()
supports_components()
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()
get_output_classname()
is_section_current()
is_section_visible()
show_editor()
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_section_modules_updated()
get_config_for_external()
delete_format_data()
Base class for course formats
Each course format must declare class
class format_FORMATNAME extends core_courseformat\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
course_format::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.
Each course format must declare class
class format_FORMATNAME extends core_courseformat\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
course_format::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 course_get_format($courseorid) to get an instance of the format class return: course_format param: string $format param: int $courseid |
| get_format_or_default($format) X-Ref |
| Validates that course format exists and enabled and returns either itself or default format return: string param: string $format |
| 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 return: string param: string $format |
| instance($courseorid) X-Ref |
| Returns an instance of the class return: course_format param: int|stdClass $courseorid either course id or |
| reset_course_cache($courseid = 0) X-Ref |
| Resets cache for the course (or all caches) To be called from rebuild_course_cache() param: int $courseid |
| session_cache_reset_all() X-Ref |
| Reset the current user for all courses. The course format cache resets every time the course cache resets but also when the user changes their language, all course editors return: void |
| session_cache_reset(stdClass $course) X-Ref |
| Reset the current user course format cache. The course format cache resets every time the course cache resets but also when the user changes their course format preference, complete an activity... return: string the new statekey param: stdClass $course the course object |
| session_cache(stdClass $course) X-Ref |
| Return the current user course format cache key. The course format session cache can be used to cache the user course representation. The statekey will be reset when the the course state changes. For example when the course is edited, the user completes an activity or simply some course preference like collapsing a section happens. return: string the current statekey param: stdClass $course the course object |
| 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_course_display() X-Ref |
| Get the course display value for the current course. Formats extending topics or weeks will use coursedisplay as this setting name so they don't need to override the method. However, if the format uses a different display logic it must override this method to ensure the core renderers know if a COURSE_DISPLAY_MULTIPAGE or COURSE_DISPLAY_SINGLEPAGE is being used. return: int The current value (COURSE_DISPLAY_MULTIPAGE or COURSE_DISPLAY_SINGLEPAGE) |
| get_modinfo() X-Ref |
| Return the current course modinfo. This method is used mainly by the output components to avoid unnecesary get_fast_modinfo calls. return: course_modinfo |
| 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 |
| page_title() X-Ref |
| Generate the title for this section page. return: string the page title |
| 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 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 |
| uses_course_index() X-Ref |
| Returns true if this course format uses course index This function may be called without specifying the course id i.e. in course_index_drawer() return: bool |
| uses_indentation() X-Ref |
| Returns true if this course format uses activity indentation. return: bool if the course format uses indentation. |
| 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 return: section_info param: int|stdClass $section either section number (field course_section.section) or row from course_section table param: int $strictness |
| get_section_name($section) X-Ref |
| Returns the display name of the given section that the course prefers. return: Display name that the course format prefers, e.g. "Topic 2" param: int|stdClass $section Section object from database or just field course_sections.section |
| get_default_section_name($section) X-Ref |
| Returns the default section using course_format's implementation of get_section_name. return: string The default value for the section name based on the given course format. param: int|stdClass $section Section object from database or just field course_sections section |
| get_section_highlighted_name() X-Ref |
| Returns the name for the highlighted section. return: string The name for the highlighted section based on the given course format. |
| set_section_number(int $singlesection) X-Ref |
| Set if the current format instance will show multiple sections or an individual one. Some formats has the hability to swith from one section to multiple sections per page, this method replaces the old print_multiple_section_page and print_single_section_page. param: int $singlesection zero for all sections or a section number |
| get_section_number() X-Ref |
| Set if the current format instance will show multiple sections or an individual one. Some formats has the hability to swith from one section to multiple sections per page, output components will use this method to know if the current display is a single or multiple sections. return: int zero for all sections or the sectin number |
| get_sections_preferences() X-Ref |
| Return the format section preferences. return: array of preferences indexed by sectionid |
| get_sections_preferences_by_preference() X-Ref |
| Return the format section preferences. return: array of preferences indexed by preference name |
| set_sections_preference(string $preferencename, array $sectionids) X-Ref |
| Return the format section preferences. param: string $preferencename preference name param: int[] $sectionids affected section ids |
| 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 |
| supports_components() X-Ref |
| Returns true if this course format is compatible with content components. Using components means the content elements can watch the frontend course state and react to the changes. Formats with component compatibility can have more interactions without refreshing the page, like having drag and drop from the course index to reorder sections and activities. return: bool if the format is compatible with components. |
| 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. return: null|moodle_url 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: |
| extend_course_navigation($navigation, navigation_node $node) X-Ref |
| Loads all of the course sections into the navigation This method is called from global_navigation::load_course_sections() By default the method 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 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 course_format::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(); return: array of options param: bool $foreditform |
| section_format_options($foreditform = false) X-Ref |
| Definitions of the additional options that this course format uses for section See course_format::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 get_fast_modinfo(). The 'cache' property is recommended to be set only for fields used in course_format::get_section_name(), course_format::extend_course_navigation() and course_format::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); return: array param: bool $foreditform |
| 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. return: array param: null|int|stdClass|section_info $section if null the course format options will be returned |
| create_edit_form_elements(&$mform, $forsection = false) X-Ref |
| Adds format options elements to the course/section edit form This function is called from course_edit_form::definition_after_data() return: array array of references to the added form elements 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 |
| edit_form_validation($data, $files, $errors) X-Ref |
| Override if you need to perform some extra validation of the format options return: array of "element_name"=>"error_description" if there are errors, 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 |
| 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 return: array array of options that have valid values param: array $rawdata associative array of the proposed course/section format options param: int|null $sectionid null if it is course format option |
| validate_course_format_options(array $data) X-Ref |
| Validates format options for the course return: array array of options that have valid values param: array $data data to insert/update |
| 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 return: bool whether there were any changes to the options values param: stdClass|array $data return value from moodleform::get_data() or array with data param: null|int $sectionid null if these are options for course or section id (course_sections.id) |
| 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 return: bool whether there were any changes to the options values param: stdClass|array $data return value from moodleform::get_data() or array with data param: stdClass $oldcourse if this function is called from update_course() |
| 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 return: bool whether there were any changes to the options values param: stdClass|array $data return value from moodleform::get_data() or array with data |
| 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 course_format::section_format_options() Format plugins may extend editsection_form if they want to have custom edit section form. return: moodleform 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 |
| 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 course_format::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 course_format::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 course_format::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 return: renderer_base param: moodle_page $page |
| get_output_classname(string $outputname) X-Ref |
| Returns instance of output component used by this plugin return: string the output component classname param: string $outputname the element to render (section, activity...) |
| is_section_current($section) X-Ref |
| Returns true if the specified section is current By default we analyze $course->marker return: bool param: int|stdClass|section_info $section |
| is_section_visible(section_info $section) X-Ref |
| Returns if an specific section is visible to the current user. Formats can overrride this method to implement any special section logic. return: bool; param: section_info $section the section modinfo |
| show_editor(?array $capabilities = ['moodle/course:manageactivities']) X-Ref |
| return true if the course editor must be displayed. return: bool true if edit controls must be displayed param: array|null $capabilities array of capabilities a user needs to have to see edit controls in general. |
| 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 course_can_delete_section() return: bool param: int|stdClass|section_info $section |
| delete_section($section, $forcedeleteifnotempty = false) X-Ref |
| Deletes a section Do not call this function directly, instead call course_delete_section() return: bool whether section was deleted param: int|stdClass|section_info $section param: bool $forcedeleteifnotempty if set to false section will not be deleted if it has modules in it. |
| inplace_editable_render_section_name($section, $linkifneeded = true,$editable = null, $edithint = null, $editlabel = null) X-Ref |
| Prepares the templateable object to display section name return: \core\output\inplace_editable param: \section_info|\stdClass $section param: bool $linkifneeded param: bool $editable param: null|lang_string|string $edithint param: null|lang_string|string $editlabel |
| 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. return: \core\output\inplace_editable param: stdClass $section param: string $itemtype param: mixed $newvalue |
| 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. return: int param: moodleform $mform param: array $fieldnames The form - field names mapping. |
| 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. return: int param: moodleform $mform param: array $fieldnames The form - field names mapping. |
| 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. return: bool 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 |
| 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 return: null|array|stdClass any data for the Javascript post-processor (must be json-encodeable) param: stdClass|section_info $section param: string $action param: int $sr the section return |
| get_section_modules_updated(section_info $section) X-Ref |
| Return an array with all section modules content. This method is used in section_action method to generate the updated modules content after a modinfo change. return: string[] the full modules content. param: section_info $section the section |
| 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 |
| delete_format_data() X-Ref |
| Course deletion hook. Format plugins can override this method to clean any format specific data and dependencies. |
