MoodleDocs - User contributions [en]

Moodle 4.0 developer update

2022-04-01T01:04:56Z

Peterd17: /* Theme updates: */

This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates =====
With the changes in boost to incorporate the primary and secondary navigation, 3rd party themes would need to account for the following in their templates:
* To leverage the activity_header, it's data needs to be exported and included into the base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
* It is recommended to transition towards the secondary/tertiary navigation hierarchy to reduce user cognitive load and with a logical separation of components
** Secondary navigation can be added to the templates by following the example https://github.com/moodle/moodle/blob/master/theme/boost/templates/columns2.mustache#L64-L68 This leverages the secondary navigation class to generate it's content.
* Flat navigation classes have been marked for deprecation. Themes that leverage the flat_navigation will need to make the following changes in their plugins in order to use it
** Account for the additional changes [[Moodle 4.0 developer update#Theme changes]]
** Indicate that they do not implement secondary navigation via the page's "set_secondary_navigation" function. It is recommended to set this within the root layout file e.g. columns2
** Initialise the flat navigation by introducing the following in the root layout file(if not existent)<syntaxhighlight lang="php">
$nav = $PAGE->flatnav;
$templatecontext['firstcollectionlabel'] = $nav->get_collectionlabel();
</syntaxhighlight>
* In order to reintroduce the settings cog in the templates, you can introduce the following: <syntaxhighlight>
<div id="region-main-settings-menu" class="d-print-none {{#hasblocks}}has-blocks{{/hasblocks}}">
<div> {{{ output.region_main_settings_menu }}} </div>
</div>
</syntaxhighlight>
===== Accessibility notes =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All course format output classes implements the new named_templatable interface, which allows the class to define its own template path using the "get_template_name" method. This new interface in combination with [[Templates#Blocks|mustache blocks]] allows the format plugins to provide alternative templates to render the course.

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Core blocks cleanup ===
In the "Add a block" menu, the list of blocks was really long. A few changes have been done to reduce this list.

More information about this project can be found in the [[Add a block cleanup]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-23T01:21:50Z

Peterd17: /* Theme updates: */

{{Moodle 4.0}}This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates: =====
With the changes in boost to incorporate the primary and secondary navigation, 3rd party themes would need to account for the following in their templates:
* To leverage the activity_header, it's data needs to be exported and included into the base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
* It is recommended to transition towards the secondary/tertiary navigation hierarchy to reduce user cognitive load and with a logical separation of components
** Secondary navigation can be added to the templates by following the example https://github.com/moodle/moodle/blob/master/theme/boost/templates/columns2.mustache#L64-L68 This leverages the secondary navigation class to generate it's content.
* Flat navigation classes have been marked for deprecation. Themes that leverage the flat_navigation will need to make the following changes in their plugins in order to use it
** Account for the additional changes [[Moodle 4.0 developer update#Theme changes]]
** Indicate that they do not implement secondary navigation via the page's "set_secondary_navigation" function. It is recommended to set this within the root layout file e.g. columns2
** Initialise the flat navigation by introducing the following in the root layout file(if not existent)<syntaxhighlight lang="php">
$nav = $PAGE->flatnav;
$templatecontext['firstcollectionlabel'] = $nav->get_collectionlabel();
</syntaxhighlight>
* In order to reintroduce the settings cog in the templates, you can introduce the following: <syntaxhighlight>
<div id="region-main-settings-menu" class="d-print-none {{#hasblocks}}has-blocks{{/hasblocks}}">
<div> {{{ output.region_main_settings_menu }}} </div>
</div>
</syntaxhighlight>

===== Accessibility notes: =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Core blocks cleanup ===
In the "Add a block" menu, the list of blocks was really long. A few changes have been done to reduce this list.

More information about this project can be found in the [[Add a block cleanup]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-21T23:41:41Z

Peterd17: /* Theme updates: */

{{Moodle 4.0}}This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates: =====
With the changes in boost to incorporate the primary and secondary navigation, 3rd party themes would need to account for the following in their templates:
* To leverage the activity_header, it's data needs to be exported and included into the base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
* It is recommended to transition towards the secondary/tertiary navigation hierarchy to reduce user cognitive load and with a logical separation of components
** Secondary navigation can be added to the templates by following the example https://github.com/moodle/moodle/blob/master/theme/boost/templates/columns2.mustache#L64-L68 This leverages the secondary navigation class to generate it's content.
* Themes that leverage the flat_navigation will still function with the additional caveat of the additional [[Moodle 4.0 developer update#Theme changes]]
** The themes should indicate that they do not implement secondary navigation via the page's "set_secondary_navigation" function. It is recommended to set this within the root layout file e.g. columns2
* In order to reintroduce the settings cog in the templates, you can introduce the following: <syntaxhighlight>
<div id="region-main-settings-menu" class="d-print-none {{#hasblocks}}has-blocks{{/hasblocks}}">
<div> {{{ output.region_main_settings_menu }}} </div>
</div>
</syntaxhighlight>
*
===== Accessibility notes: =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-21T07:08:42Z

Peterd17: /* Theme updates: */

{{Moodle 4.0}}This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates: =====
* In order for 3rd party themes to use the class they need to export the activity_header and include the following into their base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
* It is recommended for 3rd party themes to transition towards the secondary/tertiary navigation hierarchy to reduce user cognitive load and with a logical separation of components
** Secondary navigation can be added to the templates by following the example https://github.com/moodle/moodle/blob/master/theme/boost/templates/columns2.mustache#L64-L68 This leverages the secondary navigation class to generate it's content.
* Existing 3rd party themes that leverage the flat_navigation will still function with the additional caveat of the additional [[Moodle 4.0 developer update#Theme changes]]
** 3rd party themes should indicate that they do not implement secondary navigation via the page's "set_secondary_navigation" function. It is recommended to set this within the root layout file e.g. columns2
* In order to reintroduce the settings cog in 3rd party templates, you can introduce the following: <syntaxhighlight>
<div id="region-main-settings-menu" class="d-print-none {{#hasblocks}}has-blocks{{/hasblocks}}">
<div> {{{ output.region_main_settings_menu }}} </div>
</div>
</syntaxhighlight>
*
===== Accessibility notes: =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-18T07:05:55Z

Peterd17: /* Theme updates: */

{{Moodle 4.0}}This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates: =====

* In order for 3rd party themes to use the class they need to export the activity_header and include the following into their base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
* It is recommended for 3rd party themes to transition towards the secondary/tertiary navigation hierarchy to reduce user cognitive load and with a logical separation of components
** Secondary navigation can be added to the templates by following the example https://github.com/moodle/moodle/blob/master/theme/boost/templates/columns2.mustache#L64-L68 This leverages the secondary navigation class to generate it's content.
* Existing 3rd party themes that leverage the flat_navigation will still function with the additional caveat of the additional [[Moodle 4.0 developer update#Theme changes]]
* In order to reintroduce the settings cog in 3rd party templates, you can introduce the following: <syntaxhighlight>
<div id="region-main-settings-menu" class="d-print-none {{#hasblocks}}has-blocks{{/hasblocks}}">
<div> {{{ output.region_main_settings_menu }}} </div>
</div>
</syntaxhighlight>
*

===== Accessibility notes: =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-17T02:28:39Z

Peterd17: /* Page API */

{{Moodle 4.0}}This page highlights the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== Navigation changes ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.
=== Primary navigation ===
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.
==== Customising the primary navigation ====
Not yet implemented but we are looking at allowing the full addition and removal of any of the primary navigation tabs in the boost theme config file.
=== Secondary navigation ===
The main content area shows tabs for secondary navigation with a maximum of 5 items being rendered in this ‘more’ menu. A new UI component has been created to render menus like this. Files:
/lib/templates/moremenu.mustache
==== Adding items to the navigation ====
The secondary navigation pulls information mainly from the settings navigation node from each context. Any plugin that implements the existing navigation hooks will have their items added to the secondary navigation.
Existing navigation hooks:
* {module}_extend_navigation
* {local}_extend_navigation
* {report}_report_extend_navigation
* {plugin}_extend_navigation_course
* {plugin}_extend_navigation_category_settings
==== Changing the order of tabs ====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.
=== Tertiary navigation ===
We've moved action buttons to the top of the page. We would encourage you to do the same.
If you have any buttons on an activity page that go to another page, or open a form (or similar), then we encourage you to move them from the body of your activity page to the top. All of the core activities have been updated to follow this pattern. Please take a look to see how you can format your activity in a similar fashion. There is no API here. You are welcome to create the buttons and display them as you wish in this top area.
=== New API functions ===
==== Page API ====
* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondarynav - Force override the secondary navigation class

* set_secondary_navigation - Sets the ‘_hassecondarynavigation’ and optionally the ‘_hastablistsecondarynavigation’ to indicate whether a page should render the secondary navigation, and if the secondary navigation should be rendered and behave with a tablist ARIA role (as opposed to its default which is being rendered with a menubar ARIA role).
==== Navigationlib ====
* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument
==== The activity header class ====
There is a new activity header class that handles the display of information common to activities. 3rd party activities are not required to explicitly output this information as part of rendering individual pages.

The common information that are currently handled by the class are:
* title
* description
* completion information

As part of the update it was required that the initial information to be displayed by the class be toggable at a theme and layout level. Taking this into account the following theme level configurable exists:
* activityheaderconfig => An array that currently only enforces 'notitle' but can be expanded in the future NOTE: Boost has this set as true by default 'options'
The following layout level options that can be defined:
* noactivityheader - to remove the header in this specific layout.
* activityheader - An array that enforces the following options:
** notitle
** nocompletion
** nodescription
The class has a page level getter which you can use to fetch the current version of the class. The base state is initialised within the constructor with the completion information only fetched when data is exported for the template.

The class has setters for the following variables which can be leveraged to modify the header for a particular page in the format set_{variable_name}:
* hidecompletion
* description
* title
Alternately, bulk operations can also be done by passing the above variables in an array to 'set_attrs' which in turn calls the setters.<blockquote>'''Note: Any updates to the activityheader needs to be performed before the call to $OUTPUT->header'''</blockquote>
===== Theme updates: =====
In order for 3rd party themes to use the class they need to export the activity_header and include the following into their base template :<syntaxhighlight lang="html">
{{#headercontent}}
{{> core/activity_header}}
{{#headercontent}}
</syntaxhighlight>** headercontent being the array element that contains the exported activity_header data
===== Accessibility notes: =====
The jump to ‘maincontent’ div is now rendered within the activity header when within an activity context
== Component library ==
Each Moodle installation now ships with a Moodle User Interface (UI) Component library, a documentation system used to describe all the Bootstrap components and the custom Moodle components. The component Library is a helper tool for developers when creating user interfaces, a testing tool for theme developers and a documentation tool for core developers. The ultimate goal of having a component library is to encourage developers to create consistent user interfaces to improve Moodle’s overall user experience.

The library contains pages with documentation about User Interface components. It contains details on how to use the component, what variations are available and the JavaScript events / options are associated with the component.

When writing on these pages it is possible to render core mustache templates using some custom syntax like this:
<nowiki>{{< mustache template="core/notification_error" >}}</nowiki>
<nowiki>{{< /mustache >}}</nowiki>
You can also call core JavaScript or use HTML examples where the html code and the rendered result are visible in the Component Library. For more info visit the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-templates/ Moodle templates] page or the [http://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/library/moodle-javascript/ Moodle JavaScript] page.

Each page in the library uses the current css from the default theme in your Moodle installation, if you have multiple themes installed and enabled the setting "Allow theme changes on url", the component library will have a theme selector option.

A hosted version of the Component Library can be found here. http://componentlibrary.moodle.com
=== Enabling the Component Library ===
Component library pages are written in the markdown language. These pages need to be compiled to HTML pages before the Component Library is visible. To compile the pages the server running Moodle needs to have the [[Javascript Modules#Install%20NVM%20and%20Node|JavaScript developer tools installed]] (nodeJs and Grunt)

If your server meets all requirements you can enable the library running
$ npm install
$ grunt componentlibrary
Further installation instructions can be found in the Component Library itself.
=== Documenting new UI Components ===
There are no set rules for adding new pages in the component library yet. These rules will need to be written and adopted in the integration process for Moodle code.

As a guideline for making this rules consideration are:

The component library is not about single use components, for example the Moodle grade book (a huge component with many custom features). Or about very common components like buttons, these are already covered by the Bootstrap section of the component library.

New features should be build keeping in mind the UI part needs to be customisable and if possible (and making sense) reusable. And example would be the new page drawers that we are introducing for the Navigation project. Or the custom primary navigation menus where overflowing items are pushed into a More section.
== Theme changes ==
=== Edit switch ===
On theme boost the “Turn editing on” and “Customise this page” buttons have been replaced by an edit switch in the top navbar. Theme Classic will keep using the old buttons. Child themes can choose to use the edit switch if the theme config.php is using this variable
$THEME->haseditswitch = true;
The languague menu, which used to be rendered in place of the custom menu has moved to the user dropdown when the user is logged in. If not logged in it will be placed next to the search / notification / messaging icon in the top navbar.
=== Login page ===
The login page has been redesigned and allows the admin to configure a background image for the login page only in the theme settings page. This change is available in both Boost and Classic. The login page still has all the features with an improved layout.
=== The page footer ===
In large screens, the page footer button is only visible when clicking a help button at the bottom right of the screen.
=== User initials as profile picture placeholder ===
If users do not upload a profile picture the user initials are displayed on a rounded gray background as a placeholder picture in the top navbar or any other page using a placeholder image. This change will be available in both Boost and Classic.

With the introduction of this placeholder image the full username will no longer be displayed in the top navbar.
=== Removal of back to top link ===
The "back to top" link will be removed for theme boost since the new course index reduced the dependence on page scrolling. Also, the new footer is positioned where this component used to be.
=== Styling changes ===
By default rounded edges will be used for UI components, for the page header and main content area the borders will be removed.
=== New layout page ===
Theme boost now uses the drawers.php layout for the course index and blocks.
== Question bank changes ==
There was a big project to deliver [[Question bank improvements for Moodle 4.0]] which added a new plugin type for adding features to the question banks, tracking the version history for each question as it is edited (question table has been split into <code>question</code>, <code>question_versions</code> and <code>question_bank_entries</code>), and tracking where each question is going to be used, with new tables <code>question_references</code> and <code>question_set_references</code>. This work was done in Epic MDL-70329 if you want to track down the details of any of the core changes.
=== Question type plugins ===
Amazingly, we (Safat and colleagues at Catalyst AU) managed to implement this without breaking most question type plugins.

However, the changes to the question bank, and the other Moodle 4.0 changes, probably broke the Behat tests for your plugin. To help with fixing that, MDL-74130 adds navigation to key question type pages (Preview and Edit for a question, and standard question bank pages like the bank itself, import and export) which should let you fix your test efficiently, and in a way that will work in all Moodle versions since 3.9.

The 'most' in the first paragraph here is becuase more advance question types may require more effort to fix. (For example qtype_combined which creates multi-part qusetions like the core qtype_multianswer; or qtype_pmatch or qtype_stack, which store additional data - questions tests - alongside the question itseld. How should that work with versionning?) But, if you have not done weird things like that, you are probably safe. If you find anything else that causes problems, please list it here.

The same thing should apply to question behaviour and question import/export format plugings: no significant changes required (probably just fixing the Behat tests because of the navigation changes).
=== New plugin type: qbank plugins ===
This is not something that will cause problems for people upgrading from 3.x. Rather, it is an exciting possibility you can explore once you have survived process of upgrading to 4.0. There is a whole new plugin type which you can create to add new features to the question bank. For example extra columns, new actions and bulk actions, and so on. See [[Question_bank_plugins]].
=== Activities that use questions ===
The probable bad news is if you have an activity module which uses questions. So far, the only activity which has been fixed is mod_quiz in Moodle core, so we don't yet have a good picture of what fixes will be necessary in other activities. Work is about to start fixing [https://github.com/studentquiz/moodle-mod_studentquiz mod_studentquiz], so watching that should give more clues. As we do that, we will try to update this section of this page. Other help writing the information required here would also be greatly appreciated.
== The course format system ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
=== Mandatory renderer in course formats ===
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
=== New format base class ===
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
=== New course output classes and mustache files ===
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
=== Course editor javascript modules and frontend components ===
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some Moodle 4.0 new features are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation
The new course editor uses a component-based reactive pattern to keep track of the course changes. The pattern highlights are:
* The main AMD module "core_crouseformat\courseeditor" maintains a data structure called state.
* Each UI element is implemented as a Component that observes the course state data and reacts to any data change
* When any reactive component needs to modify the course, it asks the course editor to execute a mutation. Mutations encapsulate all web services calls and alter the course state data.

The reactive library documentation, as well as the format plugin migration guide, will be available soon.
=== Other course related 4.0 changes ===
Two new web services have been added:
* core_courseformat_get_state: user by the new javascript course editor to get the current course state data (containing the list of sections, activities, and other course-related data)
* core_courseformat_update_course: to alter the current course content. Each call returns the parts of the course state altered by the action
== Behat changes ==
=== New steps ===
Moodle 4.0 introduces some new behat steps.

Sometimes you want to create a bulk number of activities. In that case you can use:<syntaxhighlight lang="gherkin">
:count :entitytype exist with the following data:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
Given 100 "mod_lti > tool types" exist with the following data:
|name |Test tool [count] |
|description |Example description [count] |
|baseurl |https://www.example.com/tool[count]|
</syntaxhighlight>

Dynamic (AJAX) tabs is a new feature contributed to Moodle 4.0 by the Workplace team (MDL-71943). You can use the following step to navigate between the tabs.<syntaxhighlight lang="gherkin">
And I click on the "tab title" dynamic tab
</syntaxhighlight>

To make sure that edit mode is (or is not) available on the current page, the following steps can be used.<syntaxhighlight lang="gherkin">
And edit mode should be available on the current page
And edit mode should not be available on the current page
</syntaxhighlight>

There are new aliases for the existing steps <code>I turn editing mode on</code> and <code>I turn editing mode off</code>.<syntaxhighlight lang="gherkin">
And I switch editing mode on
And I switch editing mode off
</syntaxhighlight>

In addition to the existing step to go to a course with editing mode on, we now have the following step to do the same but with editing mode being off.<syntaxhighlight lang="gherkin">
And I am on "course full name" course homepage with editing mode off
</syntaxhighlight>

The following step is similar to the old <code>following "link string" should download between "min bytes" and "max bytes" bytes</code> step, with more flexibility.<syntaxhighlight lang="gherkin">
And following "element string" "element type" in the "container string" "container type" should download between "min bytes" and "max bytes" bytes
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And following "Download" "link" in the "Starter" "table_row" should download between "0" and "5000" bytes
</syntaxhighlight>

The following step can be used to hover the mouse over the trigger area.<syntaxhighlight lang="gherkin">
And I hover over the "element string" "element type" in the "container string" "container type"
</syntaxhighlight>

The following step enables an installed plugin.<syntaxhighlight lang="gherkin">
And I enable "plugin name" "plugin type" plugin
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I enable "course_summary" "block" plugin
</syntaxhighlight>

The following is a special variation of 'I click on "<page name>" "link" in the "page" "region"'. It first checks to see if we are on the given page via the breadcrumb. If not we then attempt to follow the link name given.<syntaxhighlight lang="gherkin">
And I follow the breadcrumb "page name"
</syntaxhighlight>

You can use the following step to ensure a node is active in the navbar.<syntaxhighlight lang="gherkin">
And I should see "Node" is active in navigation
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I should see "My courses" is active in navigation
</syntaxhighlight>

The following step can be used to navigate to a given node in the primary navigation.<syntaxhighlight lang="gherkin">
And I select "Node" from primary navigation
</syntaxhighlight>

The following steps are to check whether an item exists in the user menu or not.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the user menu
And "item text" "selector type" should not exist in the user menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "Language" "link" should exist in the user menu
</syntaxhighlight>

The following steps are to check if a submenu of the user menu is shown, and if an item exists or does not exist in a given user submenu.<syntaxhighlight lang="gherkin">
And I should see "submenu name" user submenu
And "item text" "selector type" should exist in the "submenu name" user submenu
And "item text" "selector type" should not exist in the "submenu name" user submenu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I follow "Language" in the user menu
Then I should see "Language selector" user submenu
And "English &lrm;(en)&lrm;" "link" should exist in the "Language selector" user submenu
And "English (pirate) &lrm;(en_ar)&lrm;" "link" should not exist in the "Language selector" user submenu
</syntaxhighlight>

To add enrolment methods to courses you can use the following new step. The data that you provide in the next lines are used to fill the enrolment method form.<syntaxhighlight lang="gherkin">
And I add "enrolment method" in "course identifier" with:
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
When I add "Self enrolment" enrolment method in "Course 1" with:
| Custom instance name | Test student enrolment |
| Enrolment key | moodle_rules |
| Use group enrolment keys | Yes |
</syntaxhighlight>

There are 3 new steps specific to the calendar component. These steps can be used to hover over a day in the mini-calendar or the full calendar.<syntaxhighlight lang="gherkin">
And I hover over day "day of month" of this month in the full calendar page
And I hover over day "day of month" of this month in the mini-calendar block
And I hover over today in the mini-calendar block
</syntaxhighlight>

Some new steps are added to question bank to be able to add comment to questions, verify the existence of a comment, and deleting comments form questions. Please note that the steps for adding comments only write the comment text in the comment field. You still need to click on the "Add comment" button to save the comment.<syntaxhighlight lang="gherkin">
And I add "comment text" comment to question
And I add "comment text" comment to question preview
And I delete "comment text" comment from question
And I delete "comment text" comment from question preview
And I should see "number of comments" on the comments column
And I click "number of comments" on the row on the comments column

</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "Question bank" in current page administration
And I should see "0" on the comments column
And I click "0" on the row on the comments column
And I add "test comment 01" comment to question
And I click on "Add comment" "button" in the ".modal-dialog" "css_element"
And I click on "Close" "button" in the ".modal-dialog" "css_element"
And I should see "1" on the comments column
And I click "1" on the row on the comments column
And I delete "test comment 01" comment from question
</syntaxhighlight>

Similar to the steps for comments, the following steps are to verify the number of a question's usage and to click on it in order to open the question usage modal.<syntaxhighlight lang="gherkin">
And I should see "usage count" on the usage column
And I click "usage count" on the usage column
</syntaxhighlight>

The following new steps are related to bulk actions in the question bank UI.<syntaxhighlight lang="gherkin">
And I click on question bulk action "action"
And I should see question bulk action "action"
And I should not see question bulk action "action"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I click on "First question" "checkbox"
And I click on "Second question" "checkbox"
And I click on "With selected" "button"
And I should see question bulk action "deleteselected"
And I click on question bulk action "deleteselected"
And I click on "Delete" "button" in the "Confirm" "dialogue"
</syntaxhighlight>

[https://docs.moodle.org/en/Report_builder Report builder] is a new feature contributed to Moodle 4.0 by the Workplace team. The following new step is added to Moodle 4.0 to select an action from the action menu in the list of custom reports table.<syntaxhighlight lang="gherkin">
And I press "action" action in the "report name" report row
</syntaxhighlight>

There's another step related to the report builder to set a column's aggregation in the report editor.<syntaxhighlight lang="gherkin">
And I set the "column title" column aggregation to "aggregation method"
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I set the "First name" column aggregation to "Comma separated values"
</syntaxhighlight>

The following step needs to be used in scenarios that involve testing BigBlueButton. For this to work, you need to have a [https://github.com/moodlehq/bigbluebutton_mock BigBlueButton Mock API Server] and set <code>TEST_MOD_BIGBLUEBUTTONBN_MOCK_SERVER</code> to point to that in config.php.<syntaxhighlight lang="gherkin">
And a BigBlueButton mock server is configured
</syntaxhighlight>

The following step replicates receiving a callback from the BigBlueButton server indicating the recordings for meetings are ready for viewing.<syntaxhighlight lang="gherkin">
And the BigBlueButtonBN server has sent recording ready notifications
</syntaxhighlight>

The following steps are specific to the lesson activity. Note that in 4.0, some links (such as the "edit" and the "grade essays" links) are replaced by buttons, so you need to update your old steps with the new ones.<syntaxhighlight lang="gherkin">
And I edit the lesson
</syntaxhighlight>A new step is added to be used in lesson activities to edit them. This step navigates the user to the lesson edit page.
<syntaxhighlight lang="gherkin">
And I grade lesson essays
</syntaxhighlight>It's a new step to go to the "Grade essays" page of the lesson we are currently in.
<syntaxhighlight lang="gherkin">
And I select edit type "edit type"
</syntaxhighlight>Select the lesson edit type when we are in the the lesson's edit page. "edit type" can either be "Collapsed" or "Expanded".

The following new step can be used to navigate to the exports page in the course gradebook and select the specified export type from the grade exports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "export option" export page in the course gradebook
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And I navigate to "XML file" export page in the course gradebook
</syntaxhighlight>

Similarly, there's a new step to navigate to the imports page in the course gradebook and select the specified import type from the grade imports navigation selector.<syntaxhighlight lang="gherkin">
And I navigate to "import option" import page in the course gradebook
</syntaxhighlight>
=== Boost steps ===
In addition to the steps listed in the previous section, there are also some Boost specific steps coming with Moodle 4.0. These steps only work in Boost or Boost child themes, so you need to make sure they are not used in scenarios that may be run by non-Boost themes.

The following step checks whether a node is active in the secondary navigation.<syntaxhighlight lang="gherkin">
And I should see :name is active in secondary navigation
</syntaxhighlight>

The Boost theme shows the language selector menu in the primary navigation when not logged in, and within the user menu when logged in. The following steps are to check if the primary navigation includes the language selector menu.<syntaxhighlight lang="gherkin">
And language selector menu should exist in the navbar
And language selector menu should not exist in the navbar
</syntaxhighlight>

And the following steps can be used to check whether an item exists in the language selector menu in the Boost theme.<syntaxhighlight lang="gherkin">
And "item text" "selector type" should exist in the language selector menu
And "item text" "selector type" should not exist in the language selector menu
</syntaxhighlight>For example:<syntaxhighlight lang="gherkin">
And "English &lrm;(en)&lrm;" "link" should exist in the language selector menu
</syntaxhighlight>
=== Modified steps ===
The step <code>I change the (window|viewport) size to "size"</code> now supports 2 new values for the size argument. The size argument now accepts <code>mobile</code> and <code>tablet</code> values in addition to <code>small</code>, <code>medium</code> and <code>large</code>.
=== Removed steps ===
Some behat steps are removed or replaced with new steps.

As a result of some design changes, hidden or restricted activities are no longer dimmed. Therefore the step<syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be dimmed
</syntaxhighlight>is now removed.
Depending on what you were using that step for, you may be able to use these steps:<syntaxhighlight lang="gherkin">
And "Label name" label should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And "Activity or resource name" activity should be hidden
</syntaxhighlight><syntaxhighlight lang="gherkin">
And I should see "Activity or resource name"
And "Activity or resource name" "link" should not exist in the "region-main" "region"
</syntaxhighlight>
=== Other things to consider ===
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. It is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] is integrated these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
Old behat steps that may now fail can be updated to the new steps.
For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
Or for settings, instead of:
<syntaxhighlight lang="gherkin">And I follow "Test choice name"
And I navigate to "Edit settings" in current page administration</syntaxhighlight>
Use:
<syntaxhighlight lang="gherkin">And I am on the "Test choice name" "choice activity editing" page</syntaxhighlight>

There are also similar stream-lined navigation steps for accessing question bank pages. See MDL-74130.
== Other ==
=== Core plugins review ===
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.
=== Site admin presets plugin ===
The third-party plugin [https://moodle.org/plugins/block_admin_presets Admin presets], created by David Monllaó and maintained by developers from [https://pimenko.com/ Pimenko] has been adapted and integrated into Moodle 4.0. It stores settings and plugins status (enabled/disabled) in what's called "presets" to let admins quickly switch between different configurations.

More information about this project can be found in the [[Site admin presets|Site admin presets plugin]] page.
=== JavaScript browser support changes ===
From Moodle 4.0, Internet Explorer is no longer supported. See MDL-73915 and MDLSITE-6109 for further information on this change.

This change means that changes built on 4.0 onwards (including the master branch) will be different to older versions of Moodle.

For plugin developers supporting multiple versions of Moodle using a single plugin version, the compiled javascript files are backwards compatible and will _work_ on all supported versions, however if you run the `grunt` command on multiple versions you will see unbuilt changes. Running grunt on all versions of Moodle is not necessary and this check can be safely disabled for Moodle versions 3.9 - 4.0, as long as only at least you run `grunt` against at least one version of Moodle.

If you need to support Internet Explorer and do not wish to fork your plugin for Moodle 4.0 onwards, then it is recommended that you run `grunt` on an older version of Moodle.
=== The course index element ===
The new course index feature can be themed using a set of scss variables. Use them to change the look and feel instead of adding custom css
/theme/boost/scss/moodle/courseindex.scss
With the introduction of the course index component, the previous and next links shown underneath each activity are no longer needed and they will be removed.
=== Activity icons ===
The icons used for activities have been redesigned and updated for all core moodle activities.

When viewing the new icons in a file manager, for example for the quiz activity, you will see a simple black monochrome icon with a transparent background.

On the course page, or in the activity chooser, the icon will display as a white icon on a coloured background. Styling of the icons on the coursepage is controlled by the css in theme/boost/scss/moodle/icons.scss.

The background colour for activity icons is set using a new variable in function [modname]_supports(). The quiz activity is of type assessment, so in function quiz_supports() there is a new line defining the purpose:
case FEATURE_MOD_PURPOSE: return MOD_PURPOSE_ASSESSMENT;
Available purposes are:
* MOD_PURPOSE_COMMUNICATION
* MOD_PURPOSE_ASSESSMENT
* MOD_PURPOSE_COLLABORATION
* MOD_PURPOSE_CONTENT
* MOD_PURPOSE_ADMINISTRATION
* MOD_PURPOSE_INTERFACE
The background colours linked to these purposes are set in theme/boost/scss/moodle/variables.scss
$activity-icon-colors: map-merge(
(
"administration": #5d63f6,
"assessment": #eb66a2,
"collaboration": #f7634d,
"communication": #11a676,
"content": #399be2,
"interface": #a378ff
),
$activity-icon-colors
);
If activity plugins do not define FEATURE_MOD_PURPOSE the activity icon will be rendered against a light grey background. There is no requirement to define the purpose of activity plugins, it will only affect the icon styling.

Plugins implementing the variable FEATURE_MOD_PURPOSE are only supported on Moodle 4.0 and newer.

Customising the activity icon can be done in an alternative way. For example using the styles.css in mod/[pluginname/styles.css

In the example below the activity plugin developer chooses to keep the coloured icon for the activity and render it as large as the coloured background on the core activities
.modicon_subcourse.activityiconcontainer {
background-color: transparent;
padding: 0;
}

.modicon_subcourse.activityiconcontainer img {
width: 50px;
height: 50px;
}
To customize all icon colours use this scss array and add it to the ‘Raw initial SCSS’ in the theme Boost advanced settings page. The complete array of icon background colours can be overridden using the ‘Raw initial SCSS’ in the theme settings page. The example below changes the colours of each activity type.
$activity-icon-colors: (
"administration": #5D63F6,
"assessment": #11A676,
"collaboration": #EB66A2,
"communication": #F7634D,
"content": #399BE2,
"interface": #A378FF
)
== I'm a developer, what do I need to know? ==
This section is a quick checklist of the areas in this document that you should consult when updating your plugin.
=== Modules ===
If you are a module developer (activity / resources) then you need to review the following updates and changes:
* If using settings, reformat to work with the secondary navigation. We have significantly changed the way that settings are shown. Settings added to the course and activity administration branch of the navigation are now by default shown in the secondary navigation. You will most likely find them in the more section of the secondary navigation. Please avoid creating settings in containers (a parent navigation node with children). These settings will still be shown, but this goes against the pattern that we are trying to establish for navigation around the site. If you have a lot of settings, consider creating a specific page to handle your additional settings.
** The order of the items in the secondary navigation may not be to your liking. This can be changed. See [[Moodle_4.0_developer_update#Changing_the_order_of_tabs|changing the order of tabs]]
* Update my behat tests to use new steps for site navigation. See [[Moodle_4.0_developer_update#Behat_changes|new behat steps]].
* Update my module to use the new activity_header API. See [[Moodle_4.0_developer_update#The_activity_header_class|the activity header]].
* Update my pages to make it work with the general format of the tertiary navigation. See [[Moodle_4.0_developer_update#Tertiary_navigation|the tertiary navigation]].
* Update my activity icon to use the API and set a purpose. See [[Moodle_4.0_developer_update#Activity_icons|activity icons]].
=== Themes ===
If you are a theme developer then you may want to consider the following:
* Take a look at the [[Moodle_4.0_developer_update#Navigation_changes|new navigation]] and decide if you want to incorporate this into your theme.
** A new layout ([[Moodle_4.0_developer_update#New_layout_page|drawers]])
** An [[Moodle_4.0_developer_update#Edit_switch|edit switch]]
** The [[Moodle_4.0_developer_update#The_course_index_element|course index]]
* Use of the flat nav
* New Site administration page and layout
* Course settings and how they are displayed
=== Course format ===
There have been a lot of changes made to the course format. Most in the process of moving the course format away from using the old rendering system and towards templates.
We recommend the following sections be read carefully:
# [[Moodle_4.0_developer_update#The_course_format_system|The course format]]. There have been a lot of deprecations and reading this section is critical in understanding the changes made.
# Consider moving the rendering of your content over to the [[Templates|template system]].
=== Other plugins ===
# Are you adding settings? See the [[Moodle_4.0_developer_update#Adding_items_to_the_navigation|secondary nav]] for adding items to this navigation bar.
# Have a look at [[Moodle_4.0_developer_update#Secondary_navigation|secondary]] and [[Moodle_4.0_developer_update#Tertiary_navigation|tertiary]] navigation changes in general if you have a plugin that has multiple pages to navigate around.
# Do you have behat tests? Check the new [[Moodle_4.0_developer_update#Behat_changes|behat changes]].

Moodle 4.0 developer update

2022-03-04T06:27:23Z

Peterd17: /* The activity header class */

Moodle 4.0 developer update

2021-09-02T13:17:54Z

Peterd17: /* Navigation */

{{Moodle 4.0}}This page will highlight the important changes that are coming in Moodle 4.0 for developers. Including how the UX improvements impact custom themes, relevant API changes, and what you can do as developer to prepare for the 4.0 release.
== UX and theme changes ==
== Component library ==
== Navigation ==
The core Navigation API has been left mostly untouched. The callbacks to all navigation callbacks remains unchanged and will be called as part of the regular 'navigation' and 'settingsnav' initialisation. Some new core classes have been created and exist within a new namespace 'core/navigation' and serves as conduit to rearrange, cherry-pick existing navigation nodes from the navigation/settingsnav trees and display within the respective navigation type. As such, it is highly recommended to provide unique keys for custom navigation nodes as this helps in the cherry-picking / rearranging process within the new classes.

===== Primary navigation / Primary Output =====
The primary navigation(the navbar) apart from the existing content will now display links to the Dashboard, My Courses, Site Admin and Course search, by default. You can still add items to the navbar via the 'custom menu' option. This will be displayed within the 'More' menu. We have transitioned the menus to be rendered via templates - refer user_menu.mustache. The lang menu has been moved to reside within the user menu.

===== New view =====
All settings for courses/modules will now be displayed as tabs within the module. A predefined set of tabs will be shown with any remaining / newly added ones residing within the 'Course Admin' page. The settings cog will not be shown anymore. It is recommended to review any settings as some might be displayed as tabs and possibly move them to the tertiary navigation as is done in the core activity modules<sup>1</sup>. At most 5 tabs will be displayed to a user with all the overflow nodes now residing within the 'More' menu. Some of the nodes can be hidden by using the new functions defined.

===== New API functions =====

====== Page API ======

* Magic getters to fetch the primary and secondary navs and the primary output.
* The secondarynav magic getter also checks whether a custom secondary class has been defined within the module's local\views directory. Use this if you want to deviate from the standard secondary nav structure/order.

* set_secondary_nav - Force override the secondary navigation class

* has_secondary_navigation_setter - Sets the ‘_hassecondarynavigation’ to indicate whether a page should render the secondary navigation

====== Navigationlib ======

* set_show_in_secondary_navigation - whether or not a node should be displayed in the secondary nav. Accepts a single boolean argument
* set_force_into_more_menu- whether or not to force a node into the 'More' menu. Accepts a single boolean argument

===== Changing order of tabs in secondary navigation nodes =====
Apart from the previously mentioned functions, you can also create a custom secondary class as mentioned earlier. This will automatically be picked by getter and used to render the secondary nav within the activity. E.g. mod_assign/local/views/secondary. Note: This is currently only possible on an activity and block level.

===== Upcoming changes: =====

# <sup>1 -</sup> Complete tertiary nav overhaul for core’s modules - [https://tracker.moodle.org/browse/MDL-71912 MDL-71912]. [https://tracker.moodle.org/browse/MDL-71913 MDL-71913],[https://tracker.moodle.org/browse/MDL-71914 MDL-71914],[https://tracker.moodle.org/browse/MDL-71915 MDL-71915]
# Backwards compatibility for complex deep nested custom navigation. Any custom navigation added by 3rd party devs will now be displayed as flatter structure within a URL select - [https://tracker.moodle.org/browse/MDL-72352 MDL-72352]
# New module API to inject common content at the top of a module page. The common content would be the title, description and activity information. This solves 2 issues:
## A centralised location where we can handle #2 and inject it into the relevant page
## A centralised location where we can inject items particularly activity_information without the need to be replicated in each module.

== The core_courseformat subsystem ==
Most of the logic for rendering and editing a course has been moved to a new subsystem called courseformat. The subsystem is located in "course/format" folder so it includes all the format plugins inside. The methods and modules which are distributed between the course and the course/format folders are now rearranged or refactored to be aligned with the current Moodle coding style.
==== Mandatory renderer in course formats ====
Now format plugins renderer is not optional anymore. Legacy formats without a renderer will get a deprecation message but it will continue working however, they should create a new renderer as soon as possible. The section-based format can do it by extending the provided core_courseformat\output\section_renderer class which includes all the necessary methods.
==== New format base class ====
The old base_format class (which all plugins extend) is now renamed as core_courseformat\base. The new class provides all the functionally of the previous base_format but it has been refactored to be used as a centralized source of truth for the course rendering. Legacy formats should extend the new class to avoid the deprecation message.

Now, the plugin format class provides information such as:
* If the page is displaying a single or multiple section
* Give access to other related format objects like the modinfo, the course record, maximum number of sections...
* If the format is compatible with features like course index, reactive components, ajax...
* Other format specifics like the page title, the default section name, default blocks...

The format instance is now the main object output components will use to render a course (see next section for more information).
==== New course output classes and mustache files ====
Traditionally, section-based course formats uses print_single_section_page and print_multiple_section_page to render the course content. In Moodle 4.0 most of the course rendering methods are migrated to output components and mustache templates. The old methods will get deprecation messages if they use the old renderer methods.

This is an example of a format rendering a course:<syntaxhighlight lang="php-brief">
// Get the course format instance.
$format = course_get_format($course);

// Get the specific format renderer.
$renderer = $format->get_renderer($PAGE);

if (!empty($displaysection)) {
// Setup the format instance to display a single section.
$format->set_section_number($displaysection);
}

// Create the ouptut instance and render it.
$outputclass = $format->get_output_classname('content');
$widget = new $outputclass($format);

echo $renderer->render($widget);
</syntaxhighlight>Format plugins are free to use its own output classes to render a course, or they could override the existing output classes by providing their own implementation. For example, the default output for "content" (as in the previous example) is "core_courseformat\output\local\|content", however, if the plugin has a "format_XXX\output\courseformat\content" class, the $format->class the get_output_class will return the overridden one.
Another important update on course rendering is that now all course structure is rendered using mustache templates instead of the original html_writer methods. Now themes are able to override the course format by providing alternative versions of the mustache files. All core course templates are located in "course/format/templates".

All the new output classes and a guide on how to migrate the current third-party plugins will be available soon.
==== Course editor javascript modules and frontend components ====
The majority of the javascript logic related to the course editing is replaced by AMD modules. Because this is a major change in the way courses are edited and rendered, by default format plugins will continue using the previous YUI modules for now. However, formats can start using the new libraries overriding the "$format->supports_components()" method.

Some new feature of Moodle 4.0 are only available for courses using the new editor library:
* Edit the course via the course index
* Creating sections without reloading the course page
* The new move section/activity modal
* Native browser drag&drop implementation

The new course editor uses a component-based reactive pattern to keep track of the course changes.
==== Other course related 4.0 changes ====
* New web services
== API changes ==
== Behat changes ==
To make behat tests more readable and easy to maintain, it is recommended to use the most direct steps to get what the test needs. So since MDL-66335 was integrated, and the step was improved in MDL-72179 is highly recommended to use
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
instead of navigating to the activity via
I am on "Course" course homepage
I follow "Activity name"
Now that [https://docs.moodle.org/dev/Prototypes#Course_creation_improvements Course index] (MDL-71209) is integrated but the project is not stable, these behat steps
I am on "Course" course homepage
I follow "Activity name"
will fail using Boost theme.

The reason for it is that the drawer used in Boost is hiding the course index. So when the test is trying to follow an "Activity name" link, it finds two different links:
* one in the course index
* another one in the course main content.
But the first one, the one in the course index, is hidden by the drawer, and the test fails.

However the recommended behat steps
I am on the "Activity name" "[modname] activity" page
or
I am on the "Activity name" "[modname] activity" page logged in as "user"
work '''fine'''.

Some of the failing behats are fixed in https://github.com/ferranrecio/moodle/commit/c79d58a50b48aa6891ff1d3ba92a7b0ab2393c88#diff-fdf8b0b1eade3b69eaad038de0ddd7c8dec2be7afa32dc693fb929739a49fa9dR32 - MDL-71209

For example:
And I am on the "Test assignment name" "assign activity" page logged in as teacher1
instead of:
When I log in as "teacher1"
And I am on "Course" course homepage
And I follow "Test assignment name"
== Core plugins review ==
A few plugins from core Moodle LMS which are no longer or hardly used have been removed and, if appropriate, added to the Moodle plugins directory.

More information about this project, the list of plugins to be removed and the process to follow for keeping them before upgrading to 4.0 can be found in the [[Core plugins review]] page.

Moodle 4.0 navigation improvements

2021-08-06T06:52:53Z

Peterd17: /* Technical design of *_navigation */

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Template:Moodle 4.0}}
== Introduction ==
With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==
=== Primary navigation ===
Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.
==== Desktop primary navigation ====
[[File:Primary.png]]
==== Mobile primary navigation ====
Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]
=== Secondary navigation ===
Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area. At most 5 tabs will be shown excluding the 'More' menu/tab. Any extra tabs will now reside within the 'More' menu.

The secondary navigation will appear in most cases and specifically in System, Course, Module and Category contexts. However in other situations and other contexts it does not make sense to show the secondary navigation either from a UX perspective OR because of multiple entry points into the respective page. e.g. user profile page and blocks.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.
==== Desktop secondary navigation ====
[[File:Secondary.png]]

=== Page header (Context header) ===
Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.
==== Mobile view page header ====
[[File:Mobile_context.png]]
==== Breadcrumbs ====
Breadcrumbs are being changed to follow the guidelines set in [https://www.nngroup.com/articles/breadcrumbs/ Nielsen Norman Group - Breadcrumbs: 11 Design Guidelines]

A few of the changes being implemented:
# Remove entries without any links
# Remove the link from the last item in the list as this defines the page a user is already on
# Remove breadcrumbs from the course index page as this can be accessed via the primary navigation links as a new root page.
# Remove breadcrumbs from site admin pages as navigation can be done via the secondary navigation

== User stories ==
These are the user stories that this project aims to address.
=== For the student ===
{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily move between courses and activities so that I can focus on learning.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another or one activity to another at speed.
|-
| As a learner, I want to view my grades within a course so that I know how I am doing.
| Within the course context I should be able to click straight through to my grade overview.
|-
| As a learner, I want to view my grades for a forum activity, so that I can receive feedback on my participation.
| Within a forum activity I should be able to view my grades using the existing forum grading functionality.
|}
=== For the course creator / teacher ===
{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily move between courses and activities so that I can focus on course creation or facilitation.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a teacher, I want to easily access the course settings so that I can make changes as necessary.
| Within a course, the course settings should be easily available.
|-
| As a teacher, I want to easily access activity settings so that I can make changes as necessary.
| Within a course activity or resource, the settings should be easily available.
|-
| As a teacher, I want to easily access course reports so that I can review my students' activity.
| Within a course, the reports should be easily available.
|-
| As a teacher, I want to easily access the course gradebook so that I can check my students' grades.
| Within a course, the gradebook should be easily available.
|-
| As a teacher, I want to easily grade a student's forum posts, so that I can provide them with feedback on their participation.
| Within a forum activity, I can open the forum grading functionality and give each students a grade.
|-
| As a teacher, I want to be able to easily add new content or modify existing content in a course so that I can update the course as necessary.
| Within a course, I can easily turn on course editing to add or edit activities and resources.
|}
=== For the administrator ===
{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site administrator, I want to be able to easily access site administration settings so that I can make changes as necessary.
| Links to the site administration settings still appear in easily findable locations for site administrators.
|}
=== Common user stories ===
{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I want to see other participants within a course so that I can contact them.
| Within the course I can easily find a navigation item for participants.
|-
| As any user, I want to be able to navigate around the site using assistive technologies.
| The new navigation meets WCAG 2.1 AA and can be used with screen readers and other assistive technologies.
|-
| As any user, I want to see an overview of all of my courses so that I can easily access a particular course.
| I can navigate to a page that contains the courses I am currently enrolled in or have access to.
|-
| As any user, I want to easily navigate to a course I am enrolled in so that I can continue my learning.
| I can easily find my desired course to review its content.
|-
| As any user, I want to quickly navigate to the site home page so that I can find other relevant content.
| I am able to navigate to the site home page easily and quickly.
|-
| As any user, I want to be able to go from one activity back to the course page so that I can easily find another activity.
| As any user, I should be able to use the context header bar within an activity or resource to navigate back to the course page.
|-
| As any user, I want to navigate back to the section the activity is in so that I can find other activities in the same section.
| As any user, I should be able to use the context header bar within an activity to navigate back to the section of the course that the current activity is placed in.
|-
| As any user, I can search a forum so that I can find relevant posts or discussions before making a new post.
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0).
|}
== Code architecture ==
Global and settings navigation are a true source of the internal navigation system. The new structure will be grouped into 2 broad components - primary and secondary navigation. The structure are for display purposes and can be interpreted by the different themes as they please.

The 2 components cover the following:
* 'primary' navigation items across the top of the page with the site header. This has 2 sub-components:
** views/primary - Contains the base nodes for a vanilla moodle install. Based on current designs these are - Home, Dashboard, My Courses, Site Admin
** output/primary - An amalgamation of everything that can appear on the top of the page which includes the base nodes within view/primary as well as user, lang and custom menu items.
* 'secondary' navigation items across the top of the page content within the context header

Based on user testing and UX research, it was decided that an ordered set of nodes be defined and shown within the secondary navigation at a site/course/module level. This was based on most used items, common items between modules as well as existing functionality.

The current idea is to provide mapping constructs within the secondary nav class which would cherry-pick navigation nodes based on their keys, from the global and settings navigation trees. This way, we avoid creating any additional callbacks and CRUD statements.

The current idea is to create a view based class system where views/*_navigation classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.
=== Technical design of *_navigation ===
The primary & secondary navigation classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

Assuming a label 'Custom label' has been added. This can only be done via the custommenuitems in site admin by an authorised user. This is picked up output/primary.php and is still displayed at the top of the page.

Any additional tabs to be added in the secondary navigation must be added to the settings navigation via the existing callbacks. The location of additional nodes/tabs depends on the following:

# The order defined in the mapping construct in the secondary navigation class
# The number of items displayed
# The width of the viewport
# Whether the new tab is forced to reside within the more menu.

=== Consideration given to third party plugins ===
The new navigation classes will leverage the existing global and setting navigation and nodes defined in them. This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

As previously mentioned the secondary navigation is context based
If a core OR third party Moodle plugin require a custom view/order for the nodes it is recommended to ship the plugin with a secondary class within the namespace and is only applicable to course modules<syntaxhighlight lang="php">
mod_{pluginname}\local\views
</syntaxhighlight>

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigation & secondarynavigation. These properties will be used in conjunction with magic_get_*nav() to create a new primary_navigation or secondary_navigation and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.
=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

Moodle 4.0 navigation improvements

2021-08-06T05:12:22Z

Peterd17: /* Code architecture */

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Template:Moodle 4.0}}
== Introduction ==
With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==
=== Primary navigation ===
Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.
==== Desktop primary navigation ====
[[File:Primary.png]]
==== Mobile primary navigation ====
Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]
=== Secondary navigation ===
Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area. At most 5 tabs will be shown excluding the 'More' menu/tab. Any extra tabs will now reside within the 'More' menu.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.
==== Desktop secondary navigation ====
[[File:Secondary.png]]

=== Page header (Context header) ===
Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.
==== Mobile view page header ====
[[File:Mobile_context.png]]
==== Breadcrumbs ====
Breadcrumbs are being changed to follow the guidelines set in [https://www.nngroup.com/articles/breadcrumbs/ Nielsen Norman Group - Breadcrumbs: 11 Design Guidelines]

A few of the changes being implemented:
# Remove entries without any links
# Remove the link from the last item in the list as this defines the page a user is already on
# Remove breadcrumbs from the course index page as this can be accessed via the primary navigation links as a new root page.
# Remove breadcrumbs from site admin pages as navigation can be done via the secondary navigation

== User stories ==
These are the user stories that this project aims to address.
=== For the student ===
{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily move between courses and activities so that I can focus on learning.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another or one activity to another at speed.
|-
| As a learner, I want to view my grades within a course so that I know how I am doing.
| Within the course context I should be able to click straight through to my grade overview.
|-
| As a learner, I want to view my grades for a forum activity, so that I can receive feedback on my participation.
| Within a forum activity I should be able to view my grades using the existing forum grading functionality.
|}
=== For the course creator / teacher ===
{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily move between courses and activities so that I can focus on course creation or facilitation.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a teacher, I want to easily access the course settings so that I can make changes as necessary.
| Within a course, the course settings should be easily available.
|-
| As a teacher, I want to easily access activity settings so that I can make changes as necessary.
| Within a course activity or resource, the settings should be easily available.
|-
| As a teacher, I want to easily access course reports so that I can review my students' activity.
| Within a course, the reports should be easily available.
|-
| As a teacher, I want to easily access the course gradebook so that I can check my students' grades.
| Within a course, the gradebook should be easily available.
|-
| As a teacher, I want to easily grade a student's forum posts, so that I can provide them with feedback on their participation.
| Within a forum activity, I can open the forum grading functionality and give each students a grade.
|-
| As a teacher, I want to be able to easily add new content or modify existing content in a course so that I can update the course as necessary.
| Within a course, I can easily turn on course editing to add or edit activities and resources.
|}
=== For the administrator ===
{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site administrator, I want to be able to easily access site administration settings so that I can make changes as necessary.
| Links to the site administration settings still appear in easily findable locations for site administrators.
|}
=== Common user stories ===
{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I want to see other participants within a course so that I can contact them.
| Within the course I can easily find a navigation item for participants.
|-
| As any user, I want to be able to navigate around the site using assistive technologies.
| The new navigation meets WCAG 2.1 AA and can be used with screen readers and other assistive technologies.
|-
| As any user, I want to see an overview of all of my courses so that I can easily access a particular course.
| I can navigate to a page that contains the courses I am currently enrolled in or have access to.
|-
| As any user, I want to easily navigate to a course I am enrolled in so that I can continue my learning.
| I can easily find my desired course to review its content.
|-
| As any user, I want to quickly navigate to the site home page so that I can find other relevant content.
| I am able to navigate to the site home page easily and quickly.
|-
| As any user, I want to be able to go from one activity back to the course page so that I can easily find another activity.
| As any user, I should be able to use the context header bar within an activity or resource to navigate back to the course page.
|-
| As any user, I want to navigate back to the section the activity is in so that I can find other activities in the same section.
| As any user, I should be able to use the context header bar within an activity to navigate back to the section of the course that the current activity is placed in.
|-
| As any user, I can search a forum so that I can find relevant posts or discussions before making a new post.
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0).
|}
== Code architecture ==
Global and settings navigation are a true source of the internal navigation system. The new structure will be grouped into 2 broad components - primary and secondary navigation. The structure are for display purposes and can be interpreted by the different themes as they please.

The 2 components cover the following:
* 'primary' navigation items across the top of the page with the site header. This has 2 sub-components:
** views/primary - Contains the base nodes for a vanilla moodle install. Based on current designs these are - Home, Dashboard, My Courses, Site Admin
** output/primary - An amalgamation of everything that can appear on the top of the page which includes the base nodes within view/primary as well as user, lang and custom menu items.
* 'secondary' navigation items across the top of the page content within the context header

Based on user testing and UX research, it was decided that an ordered set of nodes be defined and shown within the secondary navigation at a site/course/module level. This was based on most used items, common items between modules as well as existing functionality.

The current idea is to provide mapping constructs within the secondary nav class which would cherry-pick navigation nodes based on their keys, from the global and settings navigation trees. This way, we avoid creating any additional callbacks and CRUD statements.

The current idea is to create a view based class system where views/*_navigation classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.

=== Technical design of *_navigation ===
The primary & secondary navigation classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

An example of the above would be the following where "Custom label" has been added by an arbitrary plugin to the primary navigation of a Moodle instance:

Note: In this example we will be using simple strings, During implementation the navigation_node class should be used.

$primarynav = $PAGE->secondarynavigationview
$customlabel = $secondnav->register('Custom label')

To add further navigation items underneath the "Custom label" navigation item you could then do the following:

$customlabel->register_child('Secondary label')
$doclabels = $customlabel->register_child('Docs')
$doclabels->register('Indepth docs')

After the following the following would be represented within the primary navigation after the default navigation items:
* Custom label
** Secondary label
** Docs
*** Indepth docs
=== Consideration given to third party plugins ===
It is highly likely that the new navigation classes will be using functions from settings_navigation such as load_module_settings(). This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigationview & secondarynavigationview. These properties will be used in conjunction with magic_get_*navview() to create a new primary_navigation_view or secondary_navigation_view and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.
=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

Moodle 4.0 navigation improvements

2021-08-06T04:14:47Z

Peterd17: /* Breadcrumbs */

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Template:Moodle 4.0}}
== Introduction ==
With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==
=== Primary navigation ===
Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.
==== Desktop primary navigation ====
[[File:Primary.png]]
==== Mobile primary navigation ====
Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]
=== Secondary navigation ===
Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area. At most 5 tabs will be shown excluding the 'More' menu/tab. Any extra tabs will now reside within the 'More' menu.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.
==== Desktop secondary navigation ====
[[File:Secondary.png]]

=== Page header (Context header) ===
Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.
==== Mobile view page header ====
[[File:Mobile_context.png]]
==== Breadcrumbs ====
Breadcrumbs are being changed to follow the guidelines set in [https://www.nngroup.com/articles/breadcrumbs/ Nielsen Norman Group - Breadcrumbs: 11 Design Guidelines]

A few of the changes being implemented:
# Remove entries without any links
# Remove the link from the last item in the list as this defines the page a user is already on
# Remove breadcrumbs from the course index page as this can be accessed via the primary navigation links as a new root page.
# Remove breadcrumbs from site admin pages as navigation can be done via the secondary navigation

== User stories ==
These are the user stories that this project aims to address.
=== For the student ===
{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily move between courses and activities so that I can focus on learning.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another or one activity to another at speed.
|-
| As a learner, I want to view my grades within a course so that I know how I am doing.
| Within the course context I should be able to click straight through to my grade overview.
|-
| As a learner, I want to view my grades for a forum activity, so that I can receive feedback on my participation.
| Within a forum activity I should be able to view my grades using the existing forum grading functionality.
|}
=== For the course creator / teacher ===
{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily move between courses and activities so that I can focus on course creation or facilitation.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a teacher, I want to easily access the course settings so that I can make changes as necessary.
| Within a course, the course settings should be easily available.
|-
| As a teacher, I want to easily access activity settings so that I can make changes as necessary.
| Within a course activity or resource, the settings should be easily available.
|-
| As a teacher, I want to easily access course reports so that I can review my students' activity.
| Within a course, the reports should be easily available.
|-
| As a teacher, I want to easily access the course gradebook so that I can check my students' grades.
| Within a course, the gradebook should be easily available.
|-
| As a teacher, I want to easily grade a student's forum posts, so that I can provide them with feedback on their participation.
| Within a forum activity, I can open the forum grading functionality and give each students a grade.
|-
| As a teacher, I want to be able to easily add new content or modify existing content in a course so that I can update the course as necessary.
| Within a course, I can easily turn on course editing to add or edit activities and resources.
|}
=== For the administrator ===
{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site administrator, I want to be able to easily access site administration settings so that I can make changes as necessary.
| Links to the site administration settings still appear in easily findable locations for site administrators.
|}
=== Common user stories ===
{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I want to see other participants within a course so that I can contact them.
| Within the course I can easily find a navigation item for participants.
|-
| As any user, I want to be able to navigate around the site using assistive technologies.
| The new navigation meets WCAG 2.1 AA and can be used with screen readers and other assistive technologies.
|-
| As any user, I want to see an overview of all of my courses so that I can easily access a particular course.
| I can navigate to a page that contains the courses I am currently enrolled in or have access to.
|-
| As any user, I want to easily navigate to a course I am enrolled in so that I can continue my learning.
| I can easily find my desired course to review its content.
|-
| As any user, I want to quickly navigate to the site home page so that I can find other relevant content.
| I am able to navigate to the site home page easily and quickly.
|-
| As any user, I want to be able to go from one activity back to the course page so that I can easily find another activity.
| As any user, I should be able to use the context header bar within an activity or resource to navigate back to the course page.
|-
| As any user, I want to navigate back to the section the activity is in so that I can find other activities in the same section.
| As any user, I should be able to use the context header bar within an activity to navigate back to the section of the course that the current activity is placed in.
|-
| As any user, I can search a forum so that I can find relevant posts or discussions before making a new post.
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0).
|}
== Code architecture ==
Navigation views are a way to distinguish from the actual navigation of the system. Global and settings navigation are a true source of the internal navigation system. The views are for display purposes and can be interpreted by the different themes as they please.

As a developer you can register your new navigation item against different views for example
* 'primary' navigation items across the top of the page with the site header
* 'secondary' navigation items across the top of the page content within the context header
As seen in the diagram below, the current idea is to create a view based class system where *_navigation_view classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.

New classes that extend existing classes
[[File:view_diagram.jpg
=== Technical design of *_navigation_view ===
The primary & secondary navigation view classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

An example of the above would be the following where "Custom label" has been added by an arbitrary plugin to the primary navigation of a Moodle instance:

Note: In this example we will be using simple strings, During implementation the navigation_node class should be used.

$primarynav = $PAGE->secondarynavigationview
$customlabel = $secondnav->register('Custom label')

To add further navigation items underneath the "Custom label" navigation item you could then do the following:

$customlabel->register_child('Secondary label')
$doclabels = $customlabel->register_child('Docs')
$doclabels->register('Indepth docs')

After the following the following would be represented within the primary navigation after the default navigation items:
* Custom label
** Secondary label
** Docs
*** Indepth docs
=== Consideration given to third party plugins ===
It is highly likely that the new navigation classes will be using functions from settings_navigation such as load_module_settings(). This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigationview & secondarynavigationview. These properties will be used in conjunction with magic_get_*navview() to create a new primary_navigation_view or secondary_navigation_view and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.
=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

Moodle 4.0 navigation improvements

2021-08-06T04:12:28Z

Peterd17: /* Page header (Context header) */

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Template:Moodle 4.0}}
== Introduction ==
With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==
=== Primary navigation ===
Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.
==== Desktop primary navigation ====
[[File:Primary.png]]
==== Mobile primary navigation ====
Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]
=== Secondary navigation ===
Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area. At most 5 tabs will be shown excluding the 'More' menu/tab. Any extra tabs will now reside within the 'More' menu.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.
==== Desktop secondary navigation ====
[[File:Secondary.png]]

=== Page header (Context header) ===
Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.
==== Mobile view page header ====
[[File:Mobile_context.png]]

==== Breadcrumbs ====
Breadcrumbs are being changed to follow the guidelines set in [https://www.nngroup.com/articles/breadcrumbs/ Nielsen Norman Group - Breadcrumbs: 11 Design Guidelines]

A few of the changes being implemented:
# Remove entries without any links
# Remove the link from the last item in the list as this defines the page a user is already on
# Remove breadcrumbs from the course index page as this can be accessed via the primary navigation links as a new root page.

== User stories ==
These are the user stories that this project aims to address.
=== For the student ===
{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily move between courses and activities so that I can focus on learning.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another or one activity to another at speed.
|-
| As a learner, I want to view my grades within a course so that I know how I am doing.
| Within the course context I should be able to click straight through to my grade overview.
|-
| As a learner, I want to view my grades for a forum activity, so that I can receive feedback on my participation.
| Within a forum activity I should be able to view my grades using the existing forum grading functionality.
|}
=== For the course creator / teacher ===
{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily move between courses and activities so that I can focus on course creation or facilitation.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a teacher, I want to easily access the course settings so that I can make changes as necessary.
| Within a course, the course settings should be easily available.
|-
| As a teacher, I want to easily access activity settings so that I can make changes as necessary.
| Within a course activity or resource, the settings should be easily available.
|-
| As a teacher, I want to easily access course reports so that I can review my students' activity.
| Within a course, the reports should be easily available.
|-
| As a teacher, I want to easily access the course gradebook so that I can check my students' grades.
| Within a course, the gradebook should be easily available.
|-
| As a teacher, I want to easily grade a student's forum posts, so that I can provide them with feedback on their participation.
| Within a forum activity, I can open the forum grading functionality and give each students a grade.
|-
| As a teacher, I want to be able to easily add new content or modify existing content in a course so that I can update the course as necessary.
| Within a course, I can easily turn on course editing to add or edit activities and resources.
|}
=== For the administrator ===
{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site administrator, I want to be able to easily access site administration settings so that I can make changes as necessary.
| Links to the site administration settings still appear in easily findable locations for site administrators.
|}
=== Common user stories ===
{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I want to see other participants within a course so that I can contact them.
| Within the course I can easily find a navigation item for participants.
|-
| As any user, I want to be able to navigate around the site using assistive technologies.
| The new navigation meets WCAG 2.1 AA and can be used with screen readers and other assistive technologies.
|-
| As any user, I want to see an overview of all of my courses so that I can easily access a particular course.
| I can navigate to a page that contains the courses I am currently enrolled in or have access to.
|-
| As any user, I want to easily navigate to a course I am enrolled in so that I can continue my learning.
| I can easily find my desired course to review its content.
|-
| As any user, I want to quickly navigate to the site home page so that I can find other relevant content.
| I am able to navigate to the site home page easily and quickly.
|-
| As any user, I want to be able to go from one activity back to the course page so that I can easily find another activity.
| As any user, I should be able to use the context header bar within an activity or resource to navigate back to the course page.
|-
| As any user, I want to navigate back to the section the activity is in so that I can find other activities in the same section.
| As any user, I should be able to use the context header bar within an activity to navigate back to the section of the course that the current activity is placed in.
|-
| As any user, I can search a forum so that I can find relevant posts or discussions before making a new post.
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0).
|}
== Code architecture ==
Navigation views are a way to distinguish from the actual navigation of the system. Global and settings navigation are a true source of the internal navigation system. The views are for display purposes and can be interpreted by the different themes as they please.

As a developer you can register your new navigation item against different views for example
* 'primary' navigation items across the top of the page with the site header
* 'secondary' navigation items across the top of the page content within the context header
As seen in the diagram below, the current idea is to create a view based class system where *_navigation_view classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.

New classes that extend existing classes
[[File:view_diagram.jpg
=== Technical design of *_navigation_view ===
The primary & secondary navigation view classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

An example of the above would be the following where "Custom label" has been added by an arbitrary plugin to the primary navigation of a Moodle instance:

Note: In this example we will be using simple strings, During implementation the navigation_node class should be used.

$primarynav = $PAGE->secondarynavigationview
$customlabel = $secondnav->register('Custom label')

To add further navigation items underneath the "Custom label" navigation item you could then do the following:

$customlabel->register_child('Secondary label')
$doclabels = $customlabel->register_child('Docs')
$doclabels->register('Indepth docs')

After the following the following would be represented within the primary navigation after the default navigation items:
* Custom label
** Secondary label
** Docs
*** Indepth docs
=== Consideration given to third party plugins ===
It is highly likely that the new navigation classes will be using functions from settings_navigation such as load_module_settings(). This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigationview & secondarynavigationview. These properties will be used in conjunction with magic_get_*navview() to create a new primary_navigation_view or secondary_navigation_view and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.
=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

Moodle 4.0 navigation improvements

2021-08-06T04:00:59Z

Peterd17: /* Secondary navigation */

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Template:Moodle 4.0}}
== Introduction ==
With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==
=== Primary navigation ===
Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.
==== Desktop primary navigation ====
[[File:Primary.png]]
==== Mobile primary navigation ====
Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]
=== Secondary navigation ===
Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area. At most 5 tabs will be shown excluding the 'More' menu/tab. Any extra tabs will now reside within the 'More' menu.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.
==== Desktop secondary navigation ====
[[File:Secondary.png]]

=== Page header (Context header) ===
Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.
==== Mobile view page header ====
[[File:Mobile_context.png]]
== User stories ==
These are the user stories that this project aims to address.
=== For the student ===
{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily move between courses and activities so that I can focus on learning.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another or one activity to another at speed.
|-
| As a learner, I want to view my grades within a course so that I know how I am doing.
| Within the course context I should be able to click straight through to my grade overview.
|-
| As a learner, I want to view my grades for a forum activity, so that I can receive feedback on my participation.
| Within a forum activity I should be able to view my grades using the existing forum grading functionality.
|}
=== For the course creator / teacher ===
{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily move between courses and activities so that I can focus on course creation or facilitation.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a teacher, I want to easily access the course settings so that I can make changes as necessary.
| Within a course, the course settings should be easily available.
|-
| As a teacher, I want to easily access activity settings so that I can make changes as necessary.
| Within a course activity or resource, the settings should be easily available.
|-
| As a teacher, I want to easily access course reports so that I can review my students' activity.
| Within a course, the reports should be easily available.
|-
| As a teacher, I want to easily access the course gradebook so that I can check my students' grades.
| Within a course, the gradebook should be easily available.
|-
| As a teacher, I want to easily grade a student's forum posts, so that I can provide them with feedback on their participation.
| Within a forum activity, I can open the forum grading functionality and give each students a grade.
|-
| As a teacher, I want to be able to easily add new content or modify existing content in a course so that I can update the course as necessary.
| Within a course, I can easily turn on course editing to add or edit activities and resources.
|}
=== For the administrator ===
{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site administrator, I want to be able to easily access site administration settings so that I can make changes as necessary.
| Links to the site administration settings still appear in easily findable locations for site administrators.
|}
=== Common user stories ===
{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I want to see other participants within a course so that I can contact them.
| Within the course I can easily find a navigation item for participants.
|-
| As any user, I want to be able to navigate around the site using assistive technologies.
| The new navigation meets WCAG 2.1 AA and can be used with screen readers and other assistive technologies.
|-
| As any user, I want to see an overview of all of my courses so that I can easily access a particular course.
| I can navigate to a page that contains the courses I am currently enrolled in or have access to.
|-
| As any user, I want to easily navigate to a course I am enrolled in so that I can continue my learning.
| I can easily find my desired course to review its content.
|-
| As any user, I want to quickly navigate to the site home page so that I can find other relevant content.
| I am able to navigate to the site home page easily and quickly.
|-
| As any user, I want to be able to go from one activity back to the course page so that I can easily find another activity.
| As any user, I should be able to use the context header bar within an activity or resource to navigate back to the course page.
|-
| As any user, I want to navigate back to the section the activity is in so that I can find other activities in the same section.
| As any user, I should be able to use the context header bar within an activity to navigate back to the section of the course that the current activity is placed in.
|-
| As any user, I can search a forum so that I can find relevant posts or discussions before making a new post.
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0).
|}
== Code architecture ==
Navigation views are a way to distinguish from the actual navigation of the system. Global and settings navigation are a true source of the internal navigation system. The views are for display purposes and can be interpreted by the different themes as they please.

As a developer you can register your new navigation item against different views for example
* 'primary' navigation items across the top of the page with the site header
* 'secondary' navigation items across the top of the page content within the context header
As seen in the diagram below, the current idea is to create a view based class system where *_navigation_view classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.

New classes that extend existing classes
[[File:view_diagram.jpg
=== Technical design of *_navigation_view ===
The primary & secondary navigation view classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

An example of the above would be the following where "Custom label" has been added by an arbitrary plugin to the primary navigation of a Moodle instance:

Note: In this example we will be using simple strings, During implementation the navigation_node class should be used.

$primarynav = $PAGE->secondarynavigationview
$customlabel = $secondnav->register('Custom label')

To add further navigation items underneath the "Custom label" navigation item you could then do the following:

$customlabel->register_child('Secondary label')
$doclabels = $customlabel->register_child('Docs')
$doclabels->register('Indepth docs')

After the following the following would be represented within the primary navigation after the default navigation items:
* Custom label
** Secondary label
** Docs
*** Indepth docs
=== Consideration given to third party plugins ===
It is highly likely that the new navigation classes will be using functions from settings_navigation such as load_module_settings(). This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigationview & secondarynavigationview. These properties will be used in conjunction with magic_get_*navview() to create a new primary_navigation_view or secondary_navigation_view and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.
=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

File:linkedin scopes defined.png

2021-07-05T07:41:38Z

Peterd17:

File:linkedin auth page.png

2021-07-05T07:40:52Z

Peterd17:

File:linkedin added products.png

2021-07-05T07:35:57Z

Peterd17:

File:linkedin products prior selection.png

2021-07-05T07:33:36Z

Peterd17: List of linkedin products prior to selection

List of linkedin products prior to selection

File:linkedin app creation.png

2021-07-05T07:20:42Z

Peterd17: Initial page of the linkedin app creation process

Initial page of the linkedin app creation process

Moodle libraries credits

2021-05-11T06:47:25Z

Peterd17: Existing thirdparty lib missing from list.

Some of Moodle's libraries were written by other people, and are being redistributed as part of Moodle under their respective open source licenses that thankfully allow us to do so. Thanks to the authors of all these excellent products - without them Moodle would be missing important functionality. Copyright information for each package is included below:

==ADOdb==

''lib/adodb''

Database abstraction library for MySQL, PostgreSQL, MSSQL, Oracle, Interbase, Foxpro, Access, ADO, Sybase, DB2 and ODBC.

Version: 5.20.14

@copyright (c) 2000-2013 John Lim (jlim#natsoft.com). All rights reserved.

@copyright (c) 2014 Damien Regad, Mark Newnham and the ADOdb community

License: Dual LGPL and BSD-style

http://adodb.sourceforge.net

==Bennu==

"lib/bennu"

Bennu is an object-oriented library written in PHP that implements the iCalendar standard (RFC 2445).

Version: 0.1 (customized since then)

Copyright (c) 2005, Jon Papaioannou

License: LGPL 2.1+

http://bennu.sourceforge.net/

==Amazon S3==

''repository/s3/S3.php''

A standalone Amazon S3 (REST) client for PHP 5.2.x using CURL that does not require PEAR.

Version: 0.5.1

Copyright (c) 2013, Donovan Schönknecht

License: BSD 2-Clause

https://github.com/tpyo/amazon-s3-php-class/releases

==CAS==

''auth/cas/CAS''

phpCAS library to support CAS authentication plugin

Version: 1.3.7

Copyright Jasig

License: Apache License 2.0

https://wiki.jasig.org/display/CASC/phpCAS

==Chart.js==

''lib/amd/src/chartjs-lazy.js''

Simple yet flexible JavaScript charting for designers & developers

Version: 2.9.4

Copyright 2016 Nick Downie

License: MIT

http://www.chartjs.org

==CodeMirror==

''lib/editor/atto/plugins/html/yui/src/codemirror''

CodeMirror is a versatile text editor implemented in JavaScript for the browser.

Version: 5.59.4

License: MIT

https://github.com/codemirror/CodeMirror

==Emoji-data==

''lib/emoji-data''

Library to parse easily data and spritesheets for emoji

License: MIT

https://github.com/iamcal/emoji-data/

==EvalMath==

''lib/evalmath''

Class to safely evaluate math expressions

Copyright Miles Kaufmann

License: BSD

http://www.twmagic.com/

==Flexitour==

"admin/tool/usertours/amd/src/tour.js"

A JS library for tours

© 2016 Andrew Nicols and contributors

License: GPLv3

https://github.com/andrewnicols/flexitour

==FLV player==

''filter/mediaplugin/flvplayer.swf''

Flash movie to play FLV files

Copyright Jeroen Wijering

License: GNU GPL

http://www.jeroenwijering.com

(This library is not currently used in Moodle)

== GeoIp2 ==

''lib/maxmind/GeoIp2''

Library for processing of GeoIP data files

Version: 2.10.0

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/GeoIP2-php

== GeoPattern==

''lib/geopattern-php''

Library for creating beautiful generative background images from a string

Version: 1.1.1

Copyright 2015 Leaf Corcoran

License: MIT

https://github.com/RedeyeGroup/geopattern-php

==Google APIs==

"lib/google"

Library Google APIs Client Library for PHP

Version: 1.1.7

License: Apache License Version 2.0

https://github.com/google/google-api-php-client

==Graph Class==

''lib/graphlib.php''

Class to draw line, point, bar, and area graphs, including numeric x-axis and double y-axis.

Version: 1.6.3 (with modifications)

Copyright © 2000 Herman Veluwenkamp (''hermanV AT mindless DOT com'')

License: LGPL

==H5P==

''lib/h5p''

The general H5P library

Version: 1.24

Copyright © Joubel

License: GPL-3.0

https://github.com/h5p/h5p-php-library/

==Horde==

''lib/horde''

Library used by the inbound e-mail handling system.

Version: 5.2.22

Copyright © Horde LLC

License: LGPL

http://www.horde.org/

==html2text==

''lib/html2text''

PHP script to convert HTML into an approximate text equivalent

Version: 4.2.1

Copyright (c) 2005-2007 Jon Abernathy <jon@chuggnutt.com>

License: GNU GPL

https://github.com/mtibben/html2text.git

==htmlArea==

''lib/editor''

Javascript/HTML script to put a GUI editor in textareas on Internet Explorer and Mozilla

Version: 3.0 beta (with modifications)

Copyright © 2002 interactivetools.com, inc.

License: htmlArea License (based on BSD license)

(This library is not currently used in Moodle)

==HTML Purifier==

"lib/htmlpurifier"

Filters HTML.

Version: 4.13.0

License: LGPL

==IP-Atlas==

''lib/ipatlas''

PHP scripts to show the location of an IP address on a map.

Version: 1.0 (with modifications)

Copyright © 2002 Ivan Kozik

License: GNU GPL

http://www.xpenguin.com/ip-atlas.php

(This library is not currently used in Moodle)

==Jabber - XMPPHP==

''lib/jabber''

PHP library for XMPP (aka Jabber, Google Talk, etc).

Version: 0.1rc2-r77

Copyright: 2008 Nathanael C. Fritz

License: GPL

http://code.google.com/p/xmpphp

==jQuery==

''lib/jquery''

jQuery is a fast, small, and feature-rich JavaScript library widely used on moodle.

Version: 3.4.1

Copyright: 2016 The jQuery Foundation

License: MIT

https://jquery.com

==jQuery migrate==

''lib/jquery/jquery-migrate-1.4.0.js''

Library used migrate older jQuery code to jQuery 3.0.

Version: 1.4.0

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

(This library is not currently used in Moodle)

==jQuery UI==

''lib/jquery/ui-1.12.1/''

jQuery UI is a set of user interface interactions, effects, widgets, and themes built on top of the jQuery library.

Version: 1.12.1

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

==Services_JSON==

''lib/json''

Allows PHP->JS communication via JSON

Version: 1.3.1

Copyright © 2005 Michal Migurski

License: Modified BSD (GPL-compatible)

http://pear.php.net/pepr/pepr-proposal-show.php?id=198

(This library is not currently used in Moodle)

==JWT==

''lib/php-jwt''

A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519

Version: 5.0.0

Copyright © 2011, Neuman Vong

License: BSD

https://github.com/firebase/php-jwt

==ENUM==

''lib/php-enum''

PHP Enum implementation inspired from SplEnum

Version: 1.7.6

Copyright (c) 2015 My C-Labs

License: MIT

https://github.com/myclabs/php-enum

==kses==

''lib/kses.php''

HTML/XHTML filter that only allows some elements and attributes

Version: 0.2.2

Copyright © 2002, 2003, 2005 Ulf Harnhammar

License: GNU GPL

http://sourceforge.net/projects/kses

(This library is not currently used in Moodle)

==less.php==

The less.php is a PHP port of the official LESS processor used by moodle themes.

''lib/lessphp''

Version: 1.7.0.10

License: Apache 2.0

http://lessphp.typesettercms.com/

Copyright: Matt Agar and Martin Jantošovič

(This library is not currently used in Moodle)

==loglevel.js==

Minimal lightweight simple logging for JavaScript.

Version 1.6.6

Copyright (c) 2019 Tim Perry

License: MIT

https://github.com/pimterry/loglevel/

==LTI Tool Provider Library for PHP==

"lib/ltiprovider/"

PHP library for communicating with learning tools as per the LTI specification.

Version: 3.0.2

© 2016 IMS Global Learning Consortium Inc. All Rights Reserved. Trademark Policy - (www.imsglobal.org/trademarks)

License: Apache 2

https://github.com/IMSGlobal/LTI-Tool-Provider-Library-PHP

==MathJax==

JavaScript filter library for displaying LaTeX, AsciiMath notation, and MathML.

Not actually included in Moodle. Instead, Moodle [[:en:MathJax filter|has a setting]] for where the library is located to be loaded from. It is currently pointing to the Cloudflare CDN by default.

© Copyright 2009 - 2017 The MathJax Consortium

* Default MathJax version: 2.7.2 (Moodle 3.4)
* License: Apache 2.0
* Homepage: https://www.mathjax.org/

==MatthiasMullie\Minify==
CSS & JavaScript minifier, in PHP

Version 1.3.61

License: MIT

https://github.com/matthiasmullie/minify

==MaxMind DB Reader==
lib/maxmind/MaxMind/

PHP API for reading MaxMind DB files

Version: 1.5.1

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/MaxMind-DB-Reader-php/

==mimeTeX==

''filter/tex''

Compiled C program to convert TeX into GIFs

Version: 1.74

Copyright © 2002-2004 John Forkosh Associates, Inc

License: GNU GPL

http://www.forkosh.com/mimetex.html

==Mustache.js==

"lib/amd/src/mustache.js"

JS library for displaying mustache templates.

Version: 3.0.1

Copyright (c) 2009 Chris Wanstrath (Ruby)

Copyright (c) 2010-2014 Jan Lehnardt (JavaScript)

Copyright (c) 2010-2015 The mustache.js community

License: MIT

https://github.com/janl/mustache.js/releases

==Mustache==

"lib/mustache"

PHP library for displaying mustache templates.

Version: 2.12.0

Copyright (c) 2010-2016 Justin Hileman

License: MIT

https://github.com/bobthecow/mustache.php/releases

==mp3player==

''lib/mp3player''

Flash movie to play streaming MP3s

Copyright © 2005 Andrew Walker

License: GNU GPL

(This library is not currently used in Moodle)

==overlibmws==

''lib/overlib.js''

Javascript library to enable DHTML popups, floating windows, events etc

Version: July 2004

Copyright © 2002-2004 Foteos Macrides

Copyright © 1998-2004 Erik Bosrup

License: Artistic Open Source License

http://www.macridesweb.com/oltest/

(This library is not currently used in Moodle)

==PclZip==

''lib/pclzip''

Class to create, manage and unpack zip files.

Version: 2.4 RC1

Copyright © 2004 Vincent Blavet (''vincent AT phpconcept DOT net'')

License: GNU GPL

http://www.phpconcept.net

(This library is not currently used in Moodle)

==PEAR OLE Classes==

''lib/pear''

Class to write Excel files

Version: 0.5

Copyright © 2004 Xavier Noguer

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/OLE

(This library is not currently used in Moodle)

==PEAR Spreadsheet_Excel_Writer==

''lib/pear''

Class to write Excel files

Version: 0.9.1

Copyright © 2004 Xavier Noguer and Mika Tuupola

License: LGPL

http://pear.php.net/package/Spreadsheet_Excel_Writer

(This library is not currently used in Moodle)

==PEAR HTML_Quickform==

''lib/pear''

Class to write forms

Version: 3.2.6

Copyright © 2004 Bertrand Mansion, Adam Daniel, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform

==PEAR HTML_Quickform_Renderer_Tableless==

''lib/pear''

Class to render forms without tables

Version: 0.3.4

Copyright © 2005 Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform_Renderer_Tableless

==PEAR HTML_QuickForm_DHTMLRulesTableless==

''lib/pear''

Class to render validation notices with dhtml

Version: 0.1.2

Copyright © 2005 Alexey Borzov, Adam Daniel, Bertrand Mansion, Justin Patrin, Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_QuickForm_DHTMLRulesTableless

==PEAR HTML_Common==

''lib/pear''

Class with many common HTML functions (used by HTML Quickform)

Version: 0.3.4

Copyright © 2004 Adam Daniel, Bertrand Mansion, Klaus Guenther, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Common

==PEAR XML_Parser==

''lib/pear''

Class implementing one handy (sax-expat) XML parser

Version: 1.3.2

Copyright © 2004-2008 The PHP Group & Stephan Schmidt

License: New BSD License

http://pear.php.net/package/XML_Parser

(This library is not currently used in Moodle)

==PHP-CSS-Parser==

''lib/php-css-parser''

A Parser for CSS Files written in PHP.

Version: 8.3.0

Copyright (c) 2011 Raphael Schweikert, http://sabberworm.com/

License: MIT

https://github.com/sabberworm/PHP-CSS-Parser

==PHPExcel==

''lib/phpexcel/PHPExcel.php''

Library to read, write and create spreadsheet documents in PHP.

Version 1.8.1

Copyright © 2006 - 2015 PHPExcel
License: LGPL

https://github.com/PHPOffice/PHPExcel

(This library is not currently used in Moodle)

==PhpSpreadsheet==

''lib/phpspreadsheet''

Library to read, write and create spreadsheet documents in PHP.

Version 1.7.0

License: LGPL

https://github.com/PHPOffice/PhpSpreadsheet

==PHP mailer==

''lib/class.phpmailer.php''

Class for sending email using either sendmail, PHP mail(), or SMTP. Methods are based upon the standard AspEmail(tm) classes.

Version 6.0.7

Copyright © 2003 Brent R. Matzelle (''bmatzelle AT yahoo DOT com'')
License: LGPL

http://phpmailer.sourceforge.net
https://github.com/PHPMailer/PHPMailer/releases

==PHP Markdown==

''lib/markdown.php''

Functions to convert from the Markdown text format into clean XHTML.

Version: 1.8.0 (with modifications)

* @copyright 2004-2016 Michel Fortin <https://michelf.com/projects/php-markdown/>

* @copyright (Original Markdown) 2004-2006 John Gruber <https://daringfireball.net/projects/markdown/>
All rights reserved.

License: BSD

http://www.michelf.com/projects/php-markdown/

==PHP-ML==

''lib/mlbackend/php/phpml''

Machine learning library used to generate data for the Analytics system.

Version: 0.8.0

* @copyright 2016-2018 Arkadiusz Kondas <arkadiusz.kondas[at]gmail>

License: MIT

https://php-ml.readthedocs.io/

==Popper.js==

"admin/tool/usertours/amd/src/popper.js"

A kickass library used to created Poppers in web applications

Version: 1.12.6

© 2016 Federico Zivolo and contributors

License: MIT

https://github.com/FezVrasta/popper.js

==RTLCSS for PHP==

"lib/rtlcss"

RTLCSS is a framework for converting Left-To-Right (LTR) Cascading Style Sheets(CSS) to Right-To-Left (RTL).

© 2016 Frédéric Massart

License: MIT

https://github.com/moodlehq/rtlcss-php

==RequireJS==

''/lib/requirejs/''

RequireJS is a JavaScript file and module loader.

Version 2.3.5

License: new BSD or MIT

http://requirejs.org/

==scssphp==

''/lib/scssphp/''

scssphp is a compiler for SCSS written in PHP.

Version: 1.0.2

Copyright (c) 2015 Leaf Corcoran

License: MIT

http://leafo.github.io/scssphp

==SimplePie==

"/lib/simplepie"

Simple Pie helps with blogs.

Version 1.5.2

License: BSD

https://github.com/simplepie/simplepie

==Snoopy==

''lib/snoopy''

A PHP net client

Version: 1.0

Copyright © 1999-2000 Monte Ohrt (''monte AT ispi DOT net'')
License: GNU LGPL

http://snoopy.sourceforge.com

(This library is not currently used in Moodle)

==SMTP class==

''lib/class.smtp.php''

Class that can be used to connect and communicate with any SMTP server. It implements all the SMTP functions defined in RFC821 except TURN.

Version: 03/26/2001

Copyright © 2001 Chris Ryan (''chris AT greatbridge DOT com'')

(This library is not currently used in Moodle)

==Spike PHPCoverage==

''lib/spikephpcoverage''

PHP code coverage reporting tool

Version: 0.8.2 (with modifications)

Copyright © 2004 SpikeSource Inc

License: LGPL

http://developer.spikesource.com/projects/phpcoverage

(This library is not currently used in Moodle)

==Spout==

"lib/spout"

Library for importing and exporting csv / excel / ODS files.

Version 3.0.1

License: Apache

https://github.com/box/spout/

==TCPDF Class==

''lib/tcpdf''

Class to generate PDF files

Version: 6.2.26

Copyright Olivier PLATHEY

License: Freeware

http://www.setasign.com/products/fpdi/downloads

==Typo3 Character Set Class==

''lib/typo3''

Class for conversion between charsets and multibyte-savy operations with strings.

Version: 4.7.19

Copyright © 2003-2005 Kasper Skaarhoj

Licence: GNU GPL

http://typo3.org/

==Video.js==

''amd/src/video-lazy.js''

JavaScript library that makes it easier to work with and build on HTML5 video

Version: 7.7.6

Copyright Brightcove, Inc

Licence: Apache

http://videojs.com/

==XHProf==

''lib/xhprof''

A Hierarchical Profiler for PHP

Version: 0.9.4

Copyright © 2009 Phacility

Licence: Apache

https://github.com/phacility/xhprof

==Yahoo User Interface==

''lib/yui''

The Yahoo! User Interface Library is a set of utilities and controls, in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. The YUI Library also includes several core CSS resources.Set of user-interface components using AJAX, DHTML etc. We use it for all our AJAX-related stuff.

CVS version: 3.17.2

Copyright (c) 2006, Yahoo! Inc.

Licence: BSD

http://developer.yahoo.com/yui/

[[Category:Credits]]

Moodle libraries credits

2021-05-11T06:35:46Z

Peterd17: /* HTML Purifier */

Some of Moodle's libraries were written by other people, and are being redistributed as part of Moodle under their respective open source licenses that thankfully allow us to do so. Thanks to the authors of all these excellent products - without them Moodle would be missing important functionality. Copyright information for each package is included below:

==ADOdb==

''lib/adodb''

Database abstraction library for MySQL, PostgreSQL, MSSQL, Oracle, Interbase, Foxpro, Access, ADO, Sybase, DB2 and ODBC.

Version: 5.20.14

@copyright (c) 2000-2013 John Lim (jlim#natsoft.com). All rights reserved.

@copyright (c) 2014 Damien Regad, Mark Newnham and the ADOdb community

License: Dual LGPL and BSD-style

http://adodb.sourceforge.net

==Bennu==

"lib/bennu"

Bennu is an object-oriented library written in PHP that implements the iCalendar standard (RFC 2445).

Version: 0.1 (customized since then)

Copyright (c) 2005, Jon Papaioannou

License: LGPL 2.1+

http://bennu.sourceforge.net/

==Amazon S3==

''repository/s3/S3.php''

A standalone Amazon S3 (REST) client for PHP 5.2.x using CURL that does not require PEAR.

Version: 0.5.1

Copyright (c) 2013, Donovan Schönknecht

License: BSD 2-Clause

https://github.com/tpyo/amazon-s3-php-class/releases

==CAS==

''auth/cas/CAS''

phpCAS library to support CAS authentication plugin

Version: 1.3.7

Copyright Jasig

License: Apache License 2.0

https://wiki.jasig.org/display/CASC/phpCAS

==Chart.js==

''lib/amd/src/chartjs-lazy.js''

Simple yet flexible JavaScript charting for designers & developers

Version: 2.9.4

Copyright 2016 Nick Downie

License: MIT

http://www.chartjs.org

==Emoji-data==

''lib/emoji-data''

Library to parse easily data and spritesheets for emoji

License: MIT

https://github.com/iamcal/emoji-data/

==EvalMath==

''lib/evalmath''

Class to safely evaluate math expressions

Copyright Miles Kaufmann

License: BSD

http://www.twmagic.com/

==Flexitour==

"admin/tool/usertours/amd/src/tour.js"

A JS library for tours

© 2016 Andrew Nicols and contributors

License: GPLv3

https://github.com/andrewnicols/flexitour

==FLV player==

''filter/mediaplugin/flvplayer.swf''

Flash movie to play FLV files

Copyright Jeroen Wijering

License: GNU GPL

http://www.jeroenwijering.com

(This library is not currently used in Moodle)

== GeoIp2 ==

''lib/maxmind/GeoIp2''

Library for processing of GeoIP data files

Version: 2.10.0

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/GeoIP2-php

== GeoPattern==

''lib/geopattern-php''

Library for creating beautiful generative background images from a string

Version: 1.1.1

Copyright 2015 Leaf Corcoran

License: MIT

https://github.com/RedeyeGroup/geopattern-php

==Google APIs==

"lib/google"

Library Google APIs Client Library for PHP

Version: 1.1.7

License: Apache License Version 2.0

https://github.com/google/google-api-php-client

==Graph Class==

''lib/graphlib.php''

Class to draw line, point, bar, and area graphs, including numeric x-axis and double y-axis.

Version: 1.6.3 (with modifications)

Copyright © 2000 Herman Veluwenkamp (''hermanV AT mindless DOT com'')

License: LGPL

==H5P==

''lib/h5p''

The general H5P library

Version: 1.24

Copyright © Joubel

License: GPL-3.0

https://github.com/h5p/h5p-php-library/

==Horde==

''lib/horde''

Library used by the inbound e-mail handling system.

Version: 5.2.22

Copyright © Horde LLC

License: LGPL

http://www.horde.org/

==html2text==

''lib/html2text''

PHP script to convert HTML into an approximate text equivalent

Version: 4.2.1

Copyright (c) 2005-2007 Jon Abernathy <jon@chuggnutt.com>

License: GNU GPL

https://github.com/mtibben/html2text.git

==htmlArea==

''lib/editor''

Javascript/HTML script to put a GUI editor in textareas on Internet Explorer and Mozilla

Version: 3.0 beta (with modifications)

Copyright © 2002 interactivetools.com, inc.

License: htmlArea License (based on BSD license)

(This library is not currently used in Moodle)

==HTML Purifier==

"lib/htmlpurifier"

Filters HTML.

Version: 4.13.0

License: LGPL

==IP-Atlas==

''lib/ipatlas''

PHP scripts to show the location of an IP address on a map.

Version: 1.0 (with modifications)

Copyright © 2002 Ivan Kozik

License: GNU GPL

http://www.xpenguin.com/ip-atlas.php

(This library is not currently used in Moodle)

==Jabber - XMPPHP==

''lib/jabber''

PHP library for XMPP (aka Jabber, Google Talk, etc).

Version: 0.1rc2-r77

Copyright: 2008 Nathanael C. Fritz

License: GPL

http://code.google.com/p/xmpphp

==jQuery==

''lib/jquery''

jQuery is a fast, small, and feature-rich JavaScript library widely used on moodle.

Version: 3.4.1

Copyright: 2016 The jQuery Foundation

License: MIT

https://jquery.com

==jQuery migrate==

''lib/jquery/jquery-migrate-1.4.0.js''

Library used migrate older jQuery code to jQuery 3.0.

Version: 1.4.0

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

(This library is not currently used in Moodle)

==jQuery UI==

''lib/jquery/ui-1.12.1/''

jQuery UI is a set of user interface interactions, effects, widgets, and themes built on top of the jQuery library.

Version: 1.12.1

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

==Services_JSON==

''lib/json''

Allows PHP->JS communication via JSON

Version: 1.3.1

Copyright © 2005 Michal Migurski

License: Modified BSD (GPL-compatible)

http://pear.php.net/pepr/pepr-proposal-show.php?id=198

(This library is not currently used in Moodle)

==JWT==

''lib/php-jwt''

A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519

Version: 5.0.0

Copyright © 2011, Neuman Vong

License: BSD

https://github.com/firebase/php-jwt

==ENUM==

''lib/php-enum''

PHP Enum implementation inspired from SplEnum

Version: 1.7.6

Copyright (c) 2015 My C-Labs

License: MIT

https://github.com/myclabs/php-enum

==kses==

''lib/kses.php''

HTML/XHTML filter that only allows some elements and attributes

Version: 0.2.2

Copyright © 2002, 2003, 2005 Ulf Harnhammar

License: GNU GPL

http://sourceforge.net/projects/kses

(This library is not currently used in Moodle)

==less.php==

The less.php is a PHP port of the official LESS processor used by moodle themes.

''lib/lessphp''

Version: 1.7.0.10

License: Apache 2.0

http://lessphp.typesettercms.com/

Copyright: Matt Agar and Martin Jantošovič

(This library is not currently used in Moodle)

==loglevel.js==

Minimal lightweight simple logging for JavaScript.

Version 1.6.6

Copyright (c) 2019 Tim Perry

License: MIT

https://github.com/pimterry/loglevel/

==LTI Tool Provider Library for PHP==

"lib/ltiprovider/"

PHP library for communicating with learning tools as per the LTI specification.

Version: 3.0.2

© 2016 IMS Global Learning Consortium Inc. All Rights Reserved. Trademark Policy - (www.imsglobal.org/trademarks)

License: Apache 2

https://github.com/IMSGlobal/LTI-Tool-Provider-Library-PHP

==MathJax==

JavaScript filter library for displaying LaTeX, AsciiMath notation, and MathML.

Not actually included in Moodle. Instead, Moodle [[:en:MathJax filter|has a setting]] for where the library is located to be loaded from. It is currently pointing to the Cloudflare CDN by default.

© Copyright 2009 - 2017 The MathJax Consortium

* Default MathJax version: 2.7.2 (Moodle 3.4)
* License: Apache 2.0
* Homepage: https://www.mathjax.org/

==MatthiasMullie\Minify==
CSS & JavaScript minifier, in PHP

Version 1.3.61

License: MIT

https://github.com/matthiasmullie/minify

==MaxMind DB Reader==
lib/maxmind/MaxMind/

PHP API for reading MaxMind DB files

Version: 1.5.1

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/MaxMind-DB-Reader-php/

==mimeTeX==

''filter/tex''

Compiled C program to convert TeX into GIFs

Version: 1.74

Copyright © 2002-2004 John Forkosh Associates, Inc

License: GNU GPL

http://www.forkosh.com/mimetex.html

==Mustache.js==

"lib/amd/src/mustache.js"

JS library for displaying mustache templates.

Version: 3.0.1

Copyright (c) 2009 Chris Wanstrath (Ruby)

Copyright (c) 2010-2014 Jan Lehnardt (JavaScript)

Copyright (c) 2010-2015 The mustache.js community

License: MIT

https://github.com/janl/mustache.js/releases

==Mustache==

"lib/mustache"

PHP library for displaying mustache templates.

Version: 2.12.0

Copyright (c) 2010-2016 Justin Hileman

License: MIT

https://github.com/bobthecow/mustache.php/releases

==mp3player==

''lib/mp3player''

Flash movie to play streaming MP3s

Copyright © 2005 Andrew Walker

License: GNU GPL

(This library is not currently used in Moodle)

==overlibmws==

''lib/overlib.js''

Javascript library to enable DHTML popups, floating windows, events etc

Version: July 2004

Copyright © 2002-2004 Foteos Macrides

Copyright © 1998-2004 Erik Bosrup

License: Artistic Open Source License

http://www.macridesweb.com/oltest/

(This library is not currently used in Moodle)

==PclZip==

''lib/pclzip''

Class to create, manage and unpack zip files.

Version: 2.4 RC1

Copyright © 2004 Vincent Blavet (''vincent AT phpconcept DOT net'')

License: GNU GPL

http://www.phpconcept.net

(This library is not currently used in Moodle)

==PEAR OLE Classes==

''lib/pear''

Class to write Excel files

Version: 0.5

Copyright © 2004 Xavier Noguer

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/OLE

(This library is not currently used in Moodle)

==PEAR Spreadsheet_Excel_Writer==

''lib/pear''

Class to write Excel files

Version: 0.9.1

Copyright © 2004 Xavier Noguer and Mika Tuupola

License: LGPL

http://pear.php.net/package/Spreadsheet_Excel_Writer

(This library is not currently used in Moodle)

==PEAR HTML_Quickform==

''lib/pear''

Class to write forms

Version: 3.2.6

Copyright © 2004 Bertrand Mansion, Adam Daniel, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform

==PEAR HTML_Quickform_Renderer_Tableless==

''lib/pear''

Class to render forms without tables

Version: 0.3.4

Copyright © 2005 Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform_Renderer_Tableless

==PEAR HTML_QuickForm_DHTMLRulesTableless==

''lib/pear''

Class to render validation notices with dhtml

Version: 0.1.2

Copyright © 2005 Alexey Borzov, Adam Daniel, Bertrand Mansion, Justin Patrin, Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_QuickForm_DHTMLRulesTableless

==PEAR HTML_Common==

''lib/pear''

Class with many common HTML functions (used by HTML Quickform)

Version: 0.3.4

Copyright © 2004 Adam Daniel, Bertrand Mansion, Klaus Guenther, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Common

==PEAR XML_Parser==

''lib/pear''

Class implementing one handy (sax-expat) XML parser

Version: 1.3.2

Copyright © 2004-2008 The PHP Group & Stephan Schmidt

License: New BSD License

http://pear.php.net/package/XML_Parser

(This library is not currently used in Moodle)

==PHP-CSS-Parser==

''lib/php-css-parser''

A Parser for CSS Files written in PHP.

Version: 8.3.0

Copyright (c) 2011 Raphael Schweikert, http://sabberworm.com/

License: MIT

https://github.com/sabberworm/PHP-CSS-Parser

==PHPExcel==

''lib/phpexcel/PHPExcel.php''

Library to read, write and create spreadsheet documents in PHP.

Version 1.8.1

Copyright © 2006 - 2015 PHPExcel
License: LGPL

https://github.com/PHPOffice/PHPExcel

(This library is not currently used in Moodle)

==PhpSpreadsheet==

''lib/phpspreadsheet''

Library to read, write and create spreadsheet documents in PHP.

Version 1.7.0

License: LGPL

https://github.com/PHPOffice/PhpSpreadsheet

==PHP mailer==

''lib/class.phpmailer.php''

Class for sending email using either sendmail, PHP mail(), or SMTP. Methods are based upon the standard AspEmail(tm) classes.

Version 6.0.7

Copyright © 2003 Brent R. Matzelle (''bmatzelle AT yahoo DOT com'')
License: LGPL

http://phpmailer.sourceforge.net
https://github.com/PHPMailer/PHPMailer/releases

==PHP Markdown==

''lib/markdown.php''

Functions to convert from the Markdown text format into clean XHTML.

Version: 1.8.0 (with modifications)

* @copyright 2004-2016 Michel Fortin <https://michelf.com/projects/php-markdown/>

* @copyright (Original Markdown) 2004-2006 John Gruber <https://daringfireball.net/projects/markdown/>
All rights reserved.

License: BSD

http://www.michelf.com/projects/php-markdown/

==PHP-ML==

''lib/mlbackend/php/phpml''

Machine learning library used to generate data for the Analytics system.

Version: 0.8.0

* @copyright 2016-2018 Arkadiusz Kondas <arkadiusz.kondas[at]gmail>

License: MIT

https://php-ml.readthedocs.io/

==Popper.js==

"admin/tool/usertours/amd/src/popper.js"

A kickass library used to created Poppers in web applications

Version: 1.12.6

© 2016 Federico Zivolo and contributors

License: MIT

https://github.com/FezVrasta/popper.js

==RTLCSS for PHP==

"lib/rtlcss"

RTLCSS is a framework for converting Left-To-Right (LTR) Cascading Style Sheets(CSS) to Right-To-Left (RTL).

© 2016 Frédéric Massart

License: MIT

https://github.com/moodlehq/rtlcss-php

==RequireJS==

''/lib/requirejs/''

RequireJS is a JavaScript file and module loader.

Version 2.3.5

License: new BSD or MIT

http://requirejs.org/

==scssphp==

''/lib/scssphp/''

scssphp is a compiler for SCSS written in PHP.

Version: 1.0.2

Copyright (c) 2015 Leaf Corcoran

License: MIT

http://leafo.github.io/scssphp

==SimplePie==

"/lib/simplepie"

Simple Pie helps with blogs.

Version 1.5.2

License: BSD

https://github.com/simplepie/simplepie

==Snoopy==

''lib/snoopy''

A PHP net client

Version: 1.0

Copyright © 1999-2000 Monte Ohrt (''monte AT ispi DOT net'')
License: GNU LGPL

http://snoopy.sourceforge.com

(This library is not currently used in Moodle)

==SMTP class==

''lib/class.smtp.php''

Class that can be used to connect and communicate with any SMTP server. It implements all the SMTP functions defined in RFC821 except TURN.

Version: 03/26/2001

Copyright © 2001 Chris Ryan (''chris AT greatbridge DOT com'')

(This library is not currently used in Moodle)

==Spike PHPCoverage==

''lib/spikephpcoverage''

PHP code coverage reporting tool

Version: 0.8.2 (with modifications)

Copyright © 2004 SpikeSource Inc

License: LGPL

http://developer.spikesource.com/projects/phpcoverage

(This library is not currently used in Moodle)

==Spout==

"lib/spout"

Library for importing and exporting csv / excel / ODS files.

Version 3.0.1

License: Apache

https://github.com/box/spout/

==TCPDF Class==

''lib/tcpdf''

Class to generate PDF files

Version: 6.2.26

Copyright Olivier PLATHEY

License: Freeware

http://www.setasign.com/products/fpdi/downloads

==Typo3 Character Set Class==

''lib/typo3''

Class for conversion between charsets and multibyte-savy operations with strings.

Version: 4.7.19

Copyright © 2003-2005 Kasper Skaarhoj

Licence: GNU GPL

http://typo3.org/

==Video.js==

''amd/src/video-lazy.js''

JavaScript library that makes it easier to work with and build on HTML5 video

Version: 7.7.6

Copyright Brightcove, Inc

Licence: Apache

http://videojs.com/

==XHProf==

''lib/xhprof''

A Hierarchical Profiler for PHP

Version: 0.9.4

Copyright © 2009 Phacility

Licence: Apache

https://github.com/phacility/xhprof

==Yahoo User Interface==

''lib/yui''

The Yahoo! User Interface Library is a set of utilities and controls, in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. The YUI Library also includes several core CSS resources.Set of user-interface components using AJAX, DHTML etc. We use it for all our AJAX-related stuff.

CVS version: 3.17.2

Copyright (c) 2006, Yahoo! Inc.

Licence: BSD

http://developer.yahoo.com/yui/

[[Category:Credits]]

Moodle libraries credits

2021-05-11T06:33:42Z

Peterd17: /* Chart.js */

Some of Moodle's libraries were written by other people, and are being redistributed as part of Moodle under their respective open source licenses that thankfully allow us to do so. Thanks to the authors of all these excellent products - without them Moodle would be missing important functionality. Copyright information for each package is included below:

==ADOdb==

''lib/adodb''

Database abstraction library for MySQL, PostgreSQL, MSSQL, Oracle, Interbase, Foxpro, Access, ADO, Sybase, DB2 and ODBC.

Version: 5.20.14

@copyright (c) 2000-2013 John Lim (jlim#natsoft.com). All rights reserved.

@copyright (c) 2014 Damien Regad, Mark Newnham and the ADOdb community

License: Dual LGPL and BSD-style

http://adodb.sourceforge.net

==Bennu==

"lib/bennu"

Bennu is an object-oriented library written in PHP that implements the iCalendar standard (RFC 2445).

Version: 0.1 (customized since then)

Copyright (c) 2005, Jon Papaioannou

License: LGPL 2.1+

http://bennu.sourceforge.net/

==Amazon S3==

''repository/s3/S3.php''

A standalone Amazon S3 (REST) client for PHP 5.2.x using CURL that does not require PEAR.

Version: 0.5.1

Copyright (c) 2013, Donovan Schönknecht

License: BSD 2-Clause

https://github.com/tpyo/amazon-s3-php-class/releases

==CAS==

''auth/cas/CAS''

phpCAS library to support CAS authentication plugin

Version: 1.3.7

Copyright Jasig

License: Apache License 2.0

https://wiki.jasig.org/display/CASC/phpCAS

==Chart.js==

''lib/amd/src/chartjs-lazy.js''

Simple yet flexible JavaScript charting for designers & developers

Version: 2.9.4

Copyright 2016 Nick Downie

License: MIT

http://www.chartjs.org

==Emoji-data==

''lib/emoji-data''

Library to parse easily data and spritesheets for emoji

License: MIT

https://github.com/iamcal/emoji-data/

==EvalMath==

''lib/evalmath''

Class to safely evaluate math expressions

Copyright Miles Kaufmann

License: BSD

http://www.twmagic.com/

==Flexitour==

"admin/tool/usertours/amd/src/tour.js"

A JS library for tours

© 2016 Andrew Nicols and contributors

License: GPLv3

https://github.com/andrewnicols/flexitour

==FLV player==

''filter/mediaplugin/flvplayer.swf''

Flash movie to play FLV files

Copyright Jeroen Wijering

License: GNU GPL

http://www.jeroenwijering.com

(This library is not currently used in Moodle)

== GeoIp2 ==

''lib/maxmind/GeoIp2''

Library for processing of GeoIP data files

Version: 2.10.0

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/GeoIP2-php

== GeoPattern==

''lib/geopattern-php''

Library for creating beautiful generative background images from a string

Version: 1.1.1

Copyright 2015 Leaf Corcoran

License: MIT

https://github.com/RedeyeGroup/geopattern-php

==Google APIs==

"lib/google"

Library Google APIs Client Library for PHP

Version: 1.1.7

License: Apache License Version 2.0

https://github.com/google/google-api-php-client

==Graph Class==

''lib/graphlib.php''

Class to draw line, point, bar, and area graphs, including numeric x-axis and double y-axis.

Version: 1.6.3 (with modifications)

Copyright © 2000 Herman Veluwenkamp (''hermanV AT mindless DOT com'')

License: LGPL

==H5P==

''lib/h5p''

The general H5P library

Version: 1.24

Copyright © Joubel

License: GPL-3.0

https://github.com/h5p/h5p-php-library/

==Horde==

''lib/horde''

Library used by the inbound e-mail handling system.

Version: 5.2.22

Copyright © Horde LLC

License: LGPL

http://www.horde.org/

==html2text==

''lib/html2text''

PHP script to convert HTML into an approximate text equivalent

Version: 4.2.1

Copyright (c) 2005-2007 Jon Abernathy <jon@chuggnutt.com>

License: GNU GPL

https://github.com/mtibben/html2text.git

==htmlArea==

''lib/editor''

Javascript/HTML script to put a GUI editor in textareas on Internet Explorer and Mozilla

Version: 3.0 beta (with modifications)

Copyright © 2002 interactivetools.com, inc.

License: htmlArea License (based on BSD license)

(This library is not currently used in Moodle)

==HTML Purifier==

"lib/htmlpurifier"

Filters HTML.

Version: 4.10.0

License: LGPL

==IP-Atlas==

''lib/ipatlas''

PHP scripts to show the location of an IP address on a map.

Version: 1.0 (with modifications)

Copyright © 2002 Ivan Kozik

License: GNU GPL

http://www.xpenguin.com/ip-atlas.php

(This library is not currently used in Moodle)

==Jabber - XMPPHP==

''lib/jabber''

PHP library for XMPP (aka Jabber, Google Talk, etc).

Version: 0.1rc2-r77

Copyright: 2008 Nathanael C. Fritz

License: GPL

http://code.google.com/p/xmpphp

==jQuery==

''lib/jquery''

jQuery is a fast, small, and feature-rich JavaScript library widely used on moodle.

Version: 3.4.1

Copyright: 2016 The jQuery Foundation

License: MIT

https://jquery.com

==jQuery migrate==

''lib/jquery/jquery-migrate-1.4.0.js''

Library used migrate older jQuery code to jQuery 3.0.

Version: 1.4.0

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

(This library is not currently used in Moodle)

==jQuery UI==

''lib/jquery/ui-1.12.1/''

jQuery UI is a set of user interface interactions, effects, widgets, and themes built on top of the jQuery library.

Version: 1.12.1

Copyright: 2016 The jQuery Foundation and other contributors

License: MIT

https://github.com/jquery/jquery-migrate

==Services_JSON==

''lib/json''

Allows PHP->JS communication via JSON

Version: 1.3.1

Copyright © 2005 Michal Migurski

License: Modified BSD (GPL-compatible)

http://pear.php.net/pepr/pepr-proposal-show.php?id=198

(This library is not currently used in Moodle)

==JWT==

''lib/php-jwt''

A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519

Version: 5.0.0

Copyright © 2011, Neuman Vong

License: BSD

https://github.com/firebase/php-jwt

==ENUM==

''lib/php-enum''

PHP Enum implementation inspired from SplEnum

Version: 1.7.6

Copyright (c) 2015 My C-Labs

License: MIT

https://github.com/myclabs/php-enum

==kses==

''lib/kses.php''

HTML/XHTML filter that only allows some elements and attributes

Version: 0.2.2

Copyright © 2002, 2003, 2005 Ulf Harnhammar

License: GNU GPL

http://sourceforge.net/projects/kses

(This library is not currently used in Moodle)

==less.php==

The less.php is a PHP port of the official LESS processor used by moodle themes.

''lib/lessphp''

Version: 1.7.0.10

License: Apache 2.0

http://lessphp.typesettercms.com/

Copyright: Matt Agar and Martin Jantošovič

(This library is not currently used in Moodle)

==loglevel.js==

Minimal lightweight simple logging for JavaScript.

Version 1.6.6

Copyright (c) 2019 Tim Perry

License: MIT

https://github.com/pimterry/loglevel/

==LTI Tool Provider Library for PHP==

"lib/ltiprovider/"

PHP library for communicating with learning tools as per the LTI specification.

Version: 3.0.2

© 2016 IMS Global Learning Consortium Inc. All Rights Reserved. Trademark Policy - (www.imsglobal.org/trademarks)

License: Apache 2

https://github.com/IMSGlobal/LTI-Tool-Provider-Library-PHP

==MathJax==

JavaScript filter library for displaying LaTeX, AsciiMath notation, and MathML.

Not actually included in Moodle. Instead, Moodle [[:en:MathJax filter|has a setting]] for where the library is located to be loaded from. It is currently pointing to the Cloudflare CDN by default.

© Copyright 2009 - 2017 The MathJax Consortium

* Default MathJax version: 2.7.2 (Moodle 3.4)
* License: Apache 2.0
* Homepage: https://www.mathjax.org/

==MatthiasMullie\Minify==
CSS & JavaScript minifier, in PHP

Version 1.3.61

License: MIT

https://github.com/matthiasmullie/minify

==MaxMind DB Reader==
lib/maxmind/MaxMind/

PHP API for reading MaxMind DB files

Version: 1.5.1

Copyright MaxMind

License: Apache 2.0

https://github.com/maxmind/MaxMind-DB-Reader-php/

==mimeTeX==

''filter/tex''

Compiled C program to convert TeX into GIFs

Version: 1.74

Copyright © 2002-2004 John Forkosh Associates, Inc

License: GNU GPL

http://www.forkosh.com/mimetex.html

==Mustache.js==

"lib/amd/src/mustache.js"

JS library for displaying mustache templates.

Version: 3.0.1

Copyright (c) 2009 Chris Wanstrath (Ruby)

Copyright (c) 2010-2014 Jan Lehnardt (JavaScript)

Copyright (c) 2010-2015 The mustache.js community

License: MIT

https://github.com/janl/mustache.js/releases

==Mustache==

"lib/mustache"

PHP library for displaying mustache templates.

Version: 2.12.0

Copyright (c) 2010-2016 Justin Hileman

License: MIT

https://github.com/bobthecow/mustache.php/releases

==mp3player==

''lib/mp3player''

Flash movie to play streaming MP3s

Copyright © 2005 Andrew Walker

License: GNU GPL

(This library is not currently used in Moodle)

==overlibmws==

''lib/overlib.js''

Javascript library to enable DHTML popups, floating windows, events etc

Version: July 2004

Copyright © 2002-2004 Foteos Macrides

Copyright © 1998-2004 Erik Bosrup

License: Artistic Open Source License

http://www.macridesweb.com/oltest/

(This library is not currently used in Moodle)

==PclZip==

''lib/pclzip''

Class to create, manage and unpack zip files.

Version: 2.4 RC1

Copyright © 2004 Vincent Blavet (''vincent AT phpconcept DOT net'')

License: GNU GPL

http://www.phpconcept.net

(This library is not currently used in Moodle)

==PEAR OLE Classes==

''lib/pear''

Class to write Excel files

Version: 0.5

Copyright © 2004 Xavier Noguer

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/OLE

(This library is not currently used in Moodle)

==PEAR Spreadsheet_Excel_Writer==

''lib/pear''

Class to write Excel files

Version: 0.9.1

Copyright © 2004 Xavier Noguer and Mika Tuupola

License: LGPL

http://pear.php.net/package/Spreadsheet_Excel_Writer

(This library is not currently used in Moodle)

==PEAR HTML_Quickform==

''lib/pear''

Class to write forms

Version: 3.2.6

Copyright © 2004 Bertrand Mansion, Adam Daniel, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform

==PEAR HTML_Quickform_Renderer_Tableless==

''lib/pear''

Class to render forms without tables

Version: 0.3.4

Copyright © 2005 Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Quickform_Renderer_Tableless

==PEAR HTML_QuickForm_DHTMLRulesTableless==

''lib/pear''

Class to render validation notices with dhtml

Version: 0.1.2

Copyright © 2005 Alexey Borzov, Adam Daniel, Bertrand Mansion, Justin Patrin, Mark Wiesemann

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_QuickForm_DHTMLRulesTableless

==PEAR HTML_Common==

''lib/pear''

Class with many common HTML functions (used by HTML Quickform)

Version: 0.3.4

Copyright © 2004 Adam Daniel, Bertrand Mansion, Klaus Guenther, Alexey Borzov

License: PHP (plus special exemption for Moodle to make it compatible)

http://pear.php.net/package/HTML_Common

==PEAR XML_Parser==

''lib/pear''

Class implementing one handy (sax-expat) XML parser

Version: 1.3.2

Copyright © 2004-2008 The PHP Group & Stephan Schmidt

License: New BSD License

http://pear.php.net/package/XML_Parser

(This library is not currently used in Moodle)

==PHP-CSS-Parser==

''lib/php-css-parser''

A Parser for CSS Files written in PHP.

Version: 8.3.0

Copyright (c) 2011 Raphael Schweikert, http://sabberworm.com/

License: MIT

https://github.com/sabberworm/PHP-CSS-Parser

==PHPExcel==

''lib/phpexcel/PHPExcel.php''

Library to read, write and create spreadsheet documents in PHP.

Version 1.8.1

Copyright © 2006 - 2015 PHPExcel
License: LGPL

https://github.com/PHPOffice/PHPExcel

(This library is not currently used in Moodle)

==PhpSpreadsheet==

''lib/phpspreadsheet''

Library to read, write and create spreadsheet documents in PHP.

Version 1.7.0

License: LGPL

https://github.com/PHPOffice/PhpSpreadsheet

==PHP mailer==

''lib/class.phpmailer.php''

Class for sending email using either sendmail, PHP mail(), or SMTP. Methods are based upon the standard AspEmail(tm) classes.

Version 6.0.7

Copyright © 2003 Brent R. Matzelle (''bmatzelle AT yahoo DOT com'')
License: LGPL

http://phpmailer.sourceforge.net
https://github.com/PHPMailer/PHPMailer/releases

==PHP Markdown==

''lib/markdown.php''

Functions to convert from the Markdown text format into clean XHTML.

Version: 1.8.0 (with modifications)

* @copyright 2004-2016 Michel Fortin <https://michelf.com/projects/php-markdown/>

* @copyright (Original Markdown) 2004-2006 John Gruber <https://daringfireball.net/projects/markdown/>
All rights reserved.

License: BSD

http://www.michelf.com/projects/php-markdown/

==PHP-ML==

''lib/mlbackend/php/phpml''

Machine learning library used to generate data for the Analytics system.

Version: 0.8.0

* @copyright 2016-2018 Arkadiusz Kondas <arkadiusz.kondas[at]gmail>

License: MIT

https://php-ml.readthedocs.io/

==Popper.js==

"admin/tool/usertours/amd/src/popper.js"

A kickass library used to created Poppers in web applications

Version: 1.12.6

© 2016 Federico Zivolo and contributors

License: MIT

https://github.com/FezVrasta/popper.js

==RTLCSS for PHP==

"lib/rtlcss"

RTLCSS is a framework for converting Left-To-Right (LTR) Cascading Style Sheets(CSS) to Right-To-Left (RTL).

© 2016 Frédéric Massart

License: MIT

https://github.com/moodlehq/rtlcss-php

==RequireJS==

''/lib/requirejs/''

RequireJS is a JavaScript file and module loader.

Version 2.3.5

License: new BSD or MIT

http://requirejs.org/

==scssphp==

''/lib/scssphp/''

scssphp is a compiler for SCSS written in PHP.

Version: 1.0.2

Copyright (c) 2015 Leaf Corcoran

License: MIT

http://leafo.github.io/scssphp

==SimplePie==

"/lib/simplepie"

Simple Pie helps with blogs.

Version 1.5.2

License: BSD

https://github.com/simplepie/simplepie

==Snoopy==

''lib/snoopy''

A PHP net client

Version: 1.0

Copyright © 1999-2000 Monte Ohrt (''monte AT ispi DOT net'')
License: GNU LGPL

http://snoopy.sourceforge.com

(This library is not currently used in Moodle)

==SMTP class==

''lib/class.smtp.php''

Class that can be used to connect and communicate with any SMTP server. It implements all the SMTP functions defined in RFC821 except TURN.

Version: 03/26/2001

Copyright © 2001 Chris Ryan (''chris AT greatbridge DOT com'')

(This library is not currently used in Moodle)

==Spike PHPCoverage==

''lib/spikephpcoverage''

PHP code coverage reporting tool

Version: 0.8.2 (with modifications)

Copyright © 2004 SpikeSource Inc

License: LGPL

http://developer.spikesource.com/projects/phpcoverage

(This library is not currently used in Moodle)

==Spout==

"lib/spout"

Library for importing and exporting csv / excel / ODS files.

Version 3.0.1

License: Apache

https://github.com/box/spout/

==TCPDF Class==

''lib/tcpdf''

Class to generate PDF files

Version: 6.2.26

Copyright Olivier PLATHEY

License: Freeware

http://www.setasign.com/products/fpdi/downloads

==Typo3 Character Set Class==

''lib/typo3''

Class for conversion between charsets and multibyte-savy operations with strings.

Version: 4.7.19

Copyright © 2003-2005 Kasper Skaarhoj

Licence: GNU GPL

http://typo3.org/

==Video.js==

''amd/src/video-lazy.js''

JavaScript library that makes it easier to work with and build on HTML5 video

Version: 7.7.6

Copyright Brightcove, Inc

Licence: Apache

http://videojs.com/

==XHProf==

''lib/xhprof''

A Hierarchical Profiler for PHP

Version: 0.9.4

Copyright © 2009 Phacility

Licence: Apache

https://github.com/phacility/xhprof

==Yahoo User Interface==

''lib/yui''

The Yahoo! User Interface Library is a set of utilities and controls, in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. The YUI Library also includes several core CSS resources.Set of user-interface components using AJAX, DHTML etc. We use it for all our AJAX-related stuff.

CVS version: 3.17.2

Copyright (c) 2006, Yahoo! Inc.

Licence: BSD

http://developer.yahoo.com/yui/

[[Category:Credits]]

lib/formslib.php Form Definition

2019-04-16T04:03:42Z

Peterd17: Spelling mistake

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will cause the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

{{Moodle 2.5}}
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:
<code php>
$mform->setExpanded('foo')
</code>

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== autocomplete ===
{{Moodle 3.1}}
Available since Moodle 3.1

<code php>
$searchareas = \core_search\manager::get_search_areas_list(true);
$areanames = array();
foreach ($searchareas as $areaid => $searcharea) {
$areanames[$areaid] = $searcharea->get_visible_name();
}
$options = array(
'multiple' => true,
'noselectionstring' => get_string('allareas', 'search'),
);
$mform->addElement('autocomplete', 'areaids', get_string('searcharea', 'search'), $areanames, $options);
</code>

The autocomplete element is an advanced form element that supports server-side searching - or simple filtering of a predefined list of options. Some benefits of using this form element are that it handles very large datasets extremely well - it has great accessibility built in - and it gives a good user experience. If you have so much data you need to build pagination into a page - you could probably come up with a better design using this. The simplest way to use it is compatible with the standard 'select' form element. You give it a list of options and some parameters to configure how it behaves. The valid parameters for this simple mode of operation are:
* multiple (boolean - default false) - Allow more than one selected item. The data coming from the form will be an array in this case.
* noselectionstring (string - default <nowiki>''</nowiki>) - The text to display when nothing is selected.
* showsuggestions (boolean - default true) - Do not show the list of suggestions when the user starts typing.
* placeholder (string - default <nowiki>''</nowiki>) - The text to show in the search box when it is empty.
* casesensitive (boolean - default false) - Is the search case sensitive ?
* tags (boolean - default false) - This changes the behaviour so that the user can create new valid entries in the list by typing them and pressing enter.
* ajax (string - default <nowiki>''</nowiki>) - This string is the name of an AMD module that can fetch and format results.

More explanation on the 'ajax' option. This should be the name of an AMD module that implements 2 functions:
<code javascript>
/**
* Source of data for Ajax element.
*
* @param {String} selector The selector of the auto complete element.
* @param {String} query The query string.
* @param {Function} callback A callback function receiving an array of results.
* @return {Void}
*/
transport: function(selector, query, callback) ...

/**
* Process the results for auto complete elements.
*
* @param {String} selector The selector of the auto complete element.
* @param {Array} results An array or results.
* @return {Array} New array of results.
*/
processResults: function(selector, results)...

</code>
A good example is here: [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/amd/src/frameworks_datasource.js admin/tool/lp/amd/src/frameworks_datasource.js]

When using the ajax option in an mform with validation etc - it is recommended to sub-class the php class "MoodleQuickForm_autocomplete" so that you can provide a list of name and
values to populate the form element if the form is re-displayed due to a validation error. An example is [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/classes/form/framework_autocomplete.php admin/tool/lp/classes/form/framework_autocomplete.php].

We have provided several useful subclasses of this form element already that are simple to use (course and tags).

<code php>
// Course example.
// Valid options are:
// 'multiple' - boolean multi select
// 'exclude' - array or int, list of course ids to never show
// 'requiredcapabilities' - array of capabilities. Uses ANY to combine them.
// 'limittoenrolled' - boolean Limits to enrolled courses.
// 'includefrontpage' - boolean Enables the frontpage to be selected.
$options = array('multiple' => true, 'includefrontpage' => true);
$mform->addElement('course', 'mappedcourses', get_string('courses'), $options);

// Tags
// Valid options are:
// 'showstandard' - boolean One of the core_tag_tag constants to say which tags to display
// 'component' - string The component name and itemtype define the tag area
// 'itemtype' - string The component name and itemtype define the tag area
$mform->addElement('tags', 'interests', get_string('interestslist'), array('itemtype' => 'user', 'component' => 'core'));
</code>

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

NOTE: It won't work properly without the setType() as shown.

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0,
'enable_filemanagement' => true);
</code>

The option 'enable_filemanagement' will display the file management button on true and remove it on false.

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

Note: Because the text editor might be "Atto" (depending on user preferences) and Atto has an "autosave" feature - it requires that the combination of $PAGE->url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

You can set an 'onchange' attribute when adding or creating the select element:

$form->addElement('select', 'iselTest', 'Test Select:', $arrayOfOptions, array('onchange' => 'javascript:myFunctionToDoSomething();'));

====multi-select====
<pre>
$select = $mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you can use the 'setSelected' method. The 'setSelected' can either get a value or an array of values.

<pre>
$options = array(
'ff0000' => 'Red',
'00ff00' => 'Green',
'0000ff' => 'Blue'
);
$select = $mform->addElement('select', 'colors', get_string('colors'), $options);
// This will select the colour blue.
$select->setSelected('0000ff');
</pre>

Or for multiple-selection:
<pre>
$skillsarray = array(
'val1' => 'Skill A',
'val2' => 'Skill B',
'val3' => 'Skill C'
);
$mform->addElement('select', 'md_skills', get_string('skills', 'metadata'), $skillsarray);
$mform->getElement('md_skills')->setMultiple(true);
// This will select the skills A and B.
$mform->getElement('md_skills')->setSelected(array('val1', 'val2'));
</pre>

However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = $mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = $mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', ' ', false);
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text input element. (For text labels, use the 'static' element.) Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

=== filetypes ===
{{Moodle 3.4}}
Available since Moodle 3.4

<code php>
$mform->addElement('filetypes', 'allowedfiletypes', get_string('allowedfiletypes', 'tool_myplugin'));
</code>

Creates an input element allowing the user to specify file types for the given purpose. The typical scenario is a setting that allows the teacher define a list of allowed file types submitted by students.

The element allows the user to either type the list of filetypes manually, or select the types from the list. Also supported is selecting the whole group of file types - such as "image". The element integrates with the [[Core filetypes]] system so all default types and groups are presented, as well as those [[:en:Working with files#Site administration settings|defined locally by the admin]].

As the list can be types in manually, the form processing code should always normalize it first via the provided utility methods:

<code php>
$formdata = $mform->get_data();
$filetypesutil = new \core_form\filetypes_util();
$allowedfiletypes = $filetypesutil->normalize_file_types($formdata->allowedfiletypes);
</code>

This always returns an array of recognized valid values. The original list can be separated by whitespace, end of lines, commas, colons and semicolons. During the normalization, values are converted to lowercase, empty valies and duplicates are removed. Glob evaluation is not supported.

The normalization should also happen if the previously defined list had been saved to the database and re-read for actual usage. The normalization output value can be directly used as the accepted_types option for the filepicker.

<code php>
$filetypesutil = new \core_form\filetypes_util();
$options['accepted_types'] = $filetypesutil->normalize_file_types($allowedfiletypes);
</code>

By default, user input is validated against the list of known file types and groups. This validation can be disabled via options.

'''Supported options'''

; onlytypes : Allow selection from these file types only; for example ['onlytypes' => ['web_image']].
; allowall : Allow to select 'All file types', defaults to true. Does not apply with onlytypes are set.
; allowunknown : Skip implicit validation against the list of known file types.

Example:

<code php>
$mform->addElement('filetypes', 'doctypes', get_string('doctypes', 'tool_myplugin'), ['onlytypes' => ['document'], 'allowunknown' => true]);
</code>

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
</pre>

* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems);
</pre>

* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems, null, false);
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

<pre>
$mform->addElement('editor', 'desc', get_string('description'));
$mform->setDefault('desc', array('text'=>$defaulttext));
</pre>

Note that when setting the default for an editor element you must use an array to define the default "text" value as shown above.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1')

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq', 'in' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'in' then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.
===A tricky case===

You need to take care with disabledIf if you plan to use it with groups of checkboxes.

Let's say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.

To fix ideas:

If the selection in the checkboxes group is:

mycheck_01 == 1
mycheck_02 == 0
mycheck_03 == 0
mycheck_04 == 0
mycheck_05 == 1

the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.

The following code will, apparently, fail:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'neq', '1');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'neq', '1');
</code>

In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element "mycheck_01" and will not apply the corresponding rule.

A working solution for this kind of issue seems to be:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'notchecked');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'notchecked');
</code>
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.

==hideIf==
{{Moodle 3.4}}
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
This uses the same syntax as disabledIf just with hideIf instead.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==disable_form_change_checker==

By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call

$mform->disable_form_change_checker()

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]

Favourites API

2019-03-19T01:14:13Z

Peterd17: The alias in the sql should match up with the argument passed in the preceding function

==Overview==
===What is a favourite?===
The favourites API allows you to mark items as favourites for a given user. Marking an item as a favourite is akin to adding a web page to your browser favourites (or bookmarks), or marking someone in your contacts as a favourite. The API provides a means to create, read and delete favourite items, allowing any component to favourite arbitrary items as they see fit.

===What can be marked as a favourite?===
Almost any 'item' can be marked as a favourite, provided it is something which can be identified by a unique integer id.
===Identifying items===
In order to store a favourite, and be able to uniquely identify it for later retrieval, 4 fields are required. These are: '''component''', '''itemtype''', '''itemid''' and '''contextid'''. You will see these in a range of API calls.

The '''itemid''' is a unique integer identifier of the item itself. This might be a course id, or conversation id, or the id of any entity in Moodle. In fact, it does not have to be the id of a record from the database either; it can be any arbitrary id, so long as the component storing the item knows what it represents.

The two fields '''component''' and '''itemtype''' make up a pairing representing the ''type'' of each favourite. Within this pair, the '''component''' must be a valid [[Frankenstyle|frankenstyle]] component name and is the name of the component wishing to set/unset the item as a favourite. The '''itemtype''' can be any identifying string, provided it is unique within the respective component. The type pairing allows us to distinguish between favourites of different types (from different areas of Moodle), which may have identical itemid values.

The '''contextid''' is the id of the context in which the item is being marked as a favourite. For example, a user's course might be marked as a favourite at the course context, whereas a user's conversation with another user might be marked as a favourite at the user context. It's also possible that items of a certain ''type'' (remember, this is the {component, itemtype} pairing) will be marked as favourites in different contexts, based on the context of the item itself. For example, consider the case in messaging, in which we have a group conversation (one which is linked to a course group), and an individual conversation between two users. Setting the group conversation as a favourite would require the course context to be used, whereas doing the same for the individual conversation would require a user context. Which contextid to use is a decision that must be made by the component creating the favourite.

==Using the API==
===Getting a service object===
Favourites relies on a service layer to provide functionality to consumers. Getting a service object is as simple as using the service factory methods.

Assuming you have a user context, you can get a service scoped to a single user with:
<code php>
$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
</code>
The returned $ufservice is an object of type \core_favourites\local\service\user_favourite_service.

===Creating a favourite===
Let's say we want to set a course as a favourite. Note: In core, this is done by using the favourite ''type'' {'core_course', 'courses'}.

The service provides the method:
<code php>
public function create_favourite(string $component, string $itemtype, int $itemid, \context $context, int $ordering = null) : favourite;
</code>
So, assuming we have the courseid and course context, we can create our favourite with:
<code php>
$favourite = $ufservice->create_favourite('core_course', 'courses', $course->id, $coursecontext);
</code>
The returned $favourite is an object of type \core_favourites\local\entity\favourite.

===Reading favourites===
There are several read actions supported by the service object.
<code php>
public function count_favourites_by_type(string $component, string $itemtype, \context $context = null) : int;
public function find_favourites_by_type(string $component, string $itemtype, int $limitfrom = 0, int $limitnum = 0) : array;
public function favourite_exists(string $component, string $itemtype, int $itemid, \context $context) : bool;
public function get_favourite(string $component, string $itemtype, int $itemid, \context $context) : favourite;
</code>

===Deleting a favourite===
The service provides the method:
<code php>
public function delete_favourite(string $component, string $itemtype, int $itemid, \context $context);
</code>
So, assuming we have the courseid and course context, we can remove the favourite with:
<code php>
$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
$ufservice->delete_favourite('core_course', 'courses', $course->id, $coursecontext);
</code>

===Including favourites in external queries===
Most of the time, you should ask the service to find favourite items for you. Sometimes, however, rather than fetching the favourites from the service, you'll just want to include the relevant information in those records from an existing query. You might want to do this if dealing with performance sensitive code where additional queries are undesirable.

The service lets you do this too, by providing the method:
<code php>
public function get_join_sql_by_type(string $component, string $itemtype, string $tablealias, string $joinitemid) : array;
</code>
which can be used in such cases.

For example, and for simplicity, let's say we have a query returning the ids and names of all courses within a given course category:
<code php>
$sql = "SELECT c.id, c.name
FROM {course} c
WHERE c.category = :category";
$params = ['category' => 3];

$courses = $DB->get_records_sql($sql, $params);
</code>
we can then modify this using the get_join_sql_by_type() result to include favourite information.
<code php>
$ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);
list($favsql, $favparams) = $ufservice->get_join_sql_by_type('core_course', 'courses', 'favalias', 'c.id');

$sql = "SELECT c.id, c.name, favalias.id as favouriteid
FROM {course} c
$favsql
WHERE c.category = :category";
$params = ['category' => 3] + $favparams;

$courses = $DB->get_records_sql($sql, $params);
</code>
We've now included id of the favourite in the results via a LEFT JOIN, so as to preserve the original set of records.

If you wish to select ONLY favourites, adding "AND favouriteid IS NOT NULL" to the query will achieve this.