diff --git a/docs/apis/plugintypes/format/index.md b/docs/apis/plugintypes/format/index.md index 3778531ea..37dbd3c82 100644 --- a/docs/apis/plugintypes/format/index.md +++ b/docs/apis/plugintypes/format/index.md @@ -197,6 +197,7 @@ You must define `$string['sectionname']` if your language file even if the forma | `core_courseformat\base` Overridable method | Description | |---|---| | `uses_sections()` | returns true or false if the format uses sections or not. There is a global function
`course_format_uses_sections()` that invokes it. It affects default navigation tree building. Various modules and reports may call this function to know whether to display the section name for the particular module or not. | +| `uses_linear_navigation()` | Returns true if the course format explicitly supports the sequential linear navigation footer. If it returns false, linear navigation is completely deactivated for the format. | | `get_default_section_name()` | This method gets the default section name if the user has not provided a value for the section name. In format_base, it basically calls `get_section_name()`, which returns the `$string['sectionname']` + the section number of the current section, if available, or blank, otherwise. It can be used in conjunction with your course format's `get_section_name()` implementation. For reference, please refer to the implementations in format_topics and format_weeks classes. | | `get_section_name()` | Returns the name for a particular section. This function may be called often so it should use only fields cached in section_info object (field course_sections.name is always cached)
In 3.0+, it checks if the `$string['sectionname']` is available in the lang file. If the section name string is not available, it returns an empty string. | | `get_view_url()` | Returns the URL for a particular section, it can be either anchored on course view page or separate page. See parent function PHPdocs for more details | @@ -236,7 +237,7 @@ Webservices expect course format options to be passed in additional entities but | `core_courseformat\base` Overridable method | Description | |---|---| -| `course_format_options()` | By overriding this method course format specifies which additional options it has for course | +| `course_format_options()` | By overriding this method course format specifies which additional options it has for course. It can also be used to inject linear navigation defaults using `\core_courseformat\local\linearnavigationsettings::get_course_format_options_default()`. | | `section_format_options()` | By overriding this method course format specifies which additional options it has for course section. Note that since section information is cached you may want to cache some additional options as well. See PHPdocs for more information | | `get_format_options()` | (usually no need to override) low level function to retrieve course format options values. It is more convenient to use methods get_course() and get_section() | | `create_edit_form_elements()` | This function is called to alter course edit form and standard section edit form. The default implementation creates simple form elements for each option defined in either `course_format_options()` or `section_format_options()`. Overwrite it if you want to have more comprehensive form elements or if you do not want options to appear in edit forms, etc. | @@ -263,6 +264,10 @@ The format base class is used for all the core_courseformat integrations, from s | `is_section_current()` | Returns if a specific section is marked as current (highlighted) or not. | | `show_editor()` | Do all the user and page validations to know if the current course display has to include editor options or not. This includes both page editing mode and user capabilities. You can pass an array of capabilities which should be checked. If none specified, will default to `moodle/course:manageactivities`. | +:::tip[Linear navigation feature integration] +For a comprehensive integration guide, structural configuration examples, and admin `settings.php` file entry setups, see the [Linear navigation support guide](./linear_navigation.md). +::: + ## Rendering a course {/* #rendering-a-course */} Each format plugin is responsible for rendering the course in the format.php file, this means each plugin can choose how to render the course content. However, there are some conventions on how a course should be rendered to integrate the plugin with the existing components. diff --git a/docs/apis/plugintypes/format/linear_navigation.md b/docs/apis/plugintypes/format/linear_navigation.md new file mode 100644 index 000000000..5e1674a5c --- /dev/null +++ b/docs/apis/plugintypes/format/linear_navigation.md @@ -0,0 +1,136 @@ +--- +title: Linear navigation support +tags: + - Plugins + - Format + - Linear navigation +--- + + + +The linear course navigation feature provides an intuitive, forward-and-backward navigation footer within courses. It allows users to cycle through sections or activities sequentially without returning to the main page. + +By default, third-party course formats do not display the linear navigation elements. To enable and support this feature within a custom course format, your plugin's format class must explicitly opt in. + +## Opting into linear navigation + +To support linear navigation, your course format must override the `uses_linear_navigation()` method in its format class (extending `\core_courseformat\base`). + +```php title="course/format/mycustomformat/lib.php" +/** + * Custom course format class. + */ +class format_mycustomformat extends \core_courseformat\base { + /** + * Determines whether the course format supports linear navigation. + * + * @return bool True if linear navigation is supported, false otherwise. + */ + public static function uses_linear_navigation(): bool { + // Return true to unconditionally enable it. + return true; + } +} +``` + +## Adding format-level configuration + +If your course format requires configuration at the course settings level (similar to how `format_topics` and `format_weeks` handle it), you should integrate it into your format's native settings framework (`course_format_options`). + +```php title="course/format/mycustomformat/lib.php" + /** + * Define the format options for a course. + * + * @param bool $foreditform True if it's being requested for the course edit form. + * @return array Array of options. + */ + public function course_format_options($foreditform = false) { + static $courseformatoptions = false; + // Initialise the course format options array if it hasn't been done yet with the default values. + if ($courseformatoptions === false) { + // Get course format's settings. + $courseformatoptions = []; + + // Add linear navigation settings if enabled for the format. + $courseformatoptions = array_merge( + \core_courseformat\local\linearnavigationsettings::get_course_format_options_default(self::get_format()), + $courseformatoptions, + ); + + } + + if ($foreditform) { + // Get the edit form options for the format. + $courseformatoptionsedit = []; + + // Add course format settings. + + // Append your format's explicit linear navigation setting override if desired, + // or rely on the core 'enablelinearnav' setting configuration. + $courseformatoptions = array_merge_recursive( + $courseformatoptionsedit, + \core_courseformat\local\linearnavigationsettings::get_course_format_options_edit_form(self::get_format()), + ); + } + return $courseformatoptions; + } +``` + +:::info[Adding site-wide administration settings] + +To allow administrators to enable, disable, or define the default state for linear navigation within your custom format, add the configuration option to your plugin's settings.php file. + +```php title="course/format/mycustomformat/settings.php" + $options = [ + 1 => get_string('yes'), + 0 => get_string('no'), + ]; + + $settings->add(new admin_setting_configselect( + 'format_mycustomformat/enablelinearnav', + new lang_string('linearnavigationsettings', 'core_courseformat'), + new lang_string('linearnavigationsettings_help', 'core_courseformat'), + 1, + $options + )); +``` + +::: + +## Controlling the page state rendering + +The core output requirements verify format capabilities during execution. If you need to programmatically suppress or alter the navigation footer layout from specific views or custom renderers inside your format, utilise the page output control methods: + +```php title="course/format/mycustomformat/mypluginpage.php" +// Explicitly suppress the navigation footer on a specific layout template +$PAGE->set_show_navigation_footer(false); +``` + +The following methods can be used to check the state of linear navigation and control the rendering of the navigation footer on a per-page basis: + +```php title="course/format/mycustomformat/mypluginpage.php" + +// Query if the navigation footer should be shown on the page. +if (\core_courseformat\local\linearnavigationsettings::show_navigation_footer($PAGE)) { + // Custom structural adjustments +} + +// Check if linear navigation is enabled for the course. +// It only checks the course format and the linear navigation format option, regardless of any +// page-level state. It is useful for activities that need to adapt their output (for example, +// hiding navigation controls of their own) when linear navigation is enabled. +$linearnavigationenabled = \core_courseformat\local\linearnavigationsettings::is_linear_navigation_enabled($course); +if ($linearnavigationenabled) { + // Custom structural adjustments +} +``` + +## Behat integration + +The navigation feature includes dedicated steps to validate the execution layer within your functional test suites: + +```gherkin +And the course linear navigation should be visible +# Or to verify the disabled state: +And the course linear navigation should not be visible +``` diff --git a/docs/devupdate.md b/docs/devupdate.md index 7938fe89f..beceeafa2 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -8,3 +8,11 @@ tags: {/* */} This page highlights the important changes that are coming in Moodle 5.3 for developers. + +## Linear navigation support + + + +Moodle 5.3 introduces support for sequential linear navigation controls within course views. By default, third-party course formats do not display linear navigation elements. To explicitly opt in and declare support for this feature, course formats must override the `uses_linear_navigation()` method. + +For a comprehensive integration guide, structural configuration examples, and page-state API controls, see the [Linear navigation support guide](./apis/plugintypes/format/linear_navigation.md).