MoodleDocs - User contributions [en]

Moodle 3.1 release notes

2016-05-24T19:19:02Z

Gaudreaj: /* Smaller new things */

[[Releases]] > {{FULLPAGENAME}}

Release date: 23 May 2016

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.1%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.1].

See our [https://docs.moodle.org/31/en/New_features New Features page] for a more user-friendly introduction to Moodle 3.1 with screenshots.

If you are upgrading from previous version, make sure you read the [https://docs.moodle.org/31/en/Upgrading Upgrading] documentation.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software up-to-date.

* Moodle upgrade: Moodle 2.7 or later (if upgrading from earlier versions, you must upgrade to 2.7.14 as a first step)
* PHP version: minimum PHP 5.4.4 (always use latest PHP 5.4.x , 5.5.x or 5.6.x on Windows - http://windows.php.net/download/). PHP 7 is supported but has some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations].
* Ghostscript should be installed for pdf annotation.
* Unoconv should be installed for file conversion used by pdf annotations (new in Moodle 3.1)
* '''New requirement for Moodle 3.1 comparing to 3.0''': PHP extension <tt>xmlreader</tt>

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.1
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

=== Browser support ===

{| class="nicetable"
|-
! Browser
! Minimum version
! Recommended version
! Notes
|-
| [https://www.google.com/intl/en_au/chrome/browser/ Google Chrome]
| 30.0
| Latest
|
|-
| [http://www.mozilla.org/en-US/ Mozilla Firefox]
| 25.0
| Latest
|
|-
| [http://www.apple.com/safari/ Apple Safari]
| 6
| Latest
|
|-
| [http://windows.microsoft.com/en-AU/internet-explorer/download-ie Microsoft Internet Explorer]
| 9
| Latest
| Version 10 is required for drag-and-drop upload of content from outside the browser into Moodle
|}

==Major features==

===Highlights===

* MDL-53451 - Competencies support in Moodle
* MDL-52954 - Improvements to the Assignment grading user interface
* MDL-31989 - [https://docs.moodle.org/31/en/Global_search Global Search] API allows to search forums, wikis and other content throughout the whole site. [https://docs.moodle.org/31/en/Global_search Installation and setup] of SOLR server is required,
* MDL-52002 - Significant performance improvements in gradebook calculations
* MDL-48012 - [https://docs.moodle.org/31/en/Recycle_bin Recycle bin] plugin is now part of standard Moodle distribution: allow instructors to "undo" deletions of course modules and courses. [https://moodleassociation.org/ Moodle Users Association] project
* MDL-49279 - Add support in moodle plugins for exporting "[[Moodle Mobile Remote add-ons|Mobile app addons]]"

===Forum===

* MDL-372 - Allow to [https://docs.moodle.org/31/en/Using_Forum#Pinned_posts "pin" discussions] to keep them always on the top of the list
* MDL-34160 - Allow forum email subject to be customised
* MDL-47365 - Add [https://docs.moodle.org/31/en/Using_Forum#Permalinks permalink] option to forum posts
* MDL-51214 - Rename the News forum to [https://docs.moodle.org/31/en/Announcements "Announcements"]
* MDL-44087 - Forum does not observe message notification settings for digest emails
* MDL-53050 - Highlight the selected forum post when deep linking with a #anchor

===Assignment===

* MDL-52397 - Feedback for Assignments is not sent if the assignment grade timemodified setting was set to two days ago
* MDL-52596 - Add a 'maxperpage' site wide setting for grading table size (to mitigate broken grading pages in large courses)
* MDL-52269 - Not obvious to tell if an assignment is in blind marking if user holds the "mod/assign:viewblinddetails" capabilty
* MDL-52270 - Difficult to cross reference users with their blind identities
* MDL-44598 - List student names on 'grant extension' screen
* MDL-52490 - Download selected assign submissions as a zip file
* MDL-52290 - EditPDF - Also show the total page number in the pagination
* MDL-52489 - "Download all submissions as a zip" should maintain the folder structure in students submissions

===External tool (LTI)===

* MDL-52154 - Rework LTI admin screens
* MDL-45064 - Option to add Preconfigured LTI Tool to Activity Chooser
* MDL-52035 - Integrate LTI Provider support in Moodle as the [https://docs.moodle.org/31/en/Publish_as_LTI_tool Publish as LTI tool]
* MDL-52821 - Compliance: Send tool_consumer_instance_description in LTI launch request

===Feedback===

* MDL-53738 - Feedback activity module will be enabled by default in new 3.1 installations. If you are upgrading to 3.1 we recommend you to enable it manually.
* MDL-52094 - Various improvements to UI and bug fixes, including:
** Performance improvement to download responses as raw data in multiple formats (CSV, Excel, etc.) - now available on "Show responses" page instead of "Analysis"
** Allow any characters in labels, do not display empty labels
** Do not display empty pages
** Map frontpage feedback to multiple courses without leaving the form
** Improved display of automatic question numbers
** Disable "Response time" for anonymous feedbacks
** Use moodleforms to display feedback

===SCORM===

* MDL-45712 - Add Result field to the SCORM Interactions Report
* MDL-48680 - Add score and status submission events to SCORM activity
* MDL-42473 - Add group support to SCORM activity

===Quiz===

* MDL-52738 - Quiz attempt/review page should have a previous button to match next
* MDL-46092 - Add the OU styling of the Quiz navigation into Moodle core as the default
* MDL-46091 - Rationalise confirmations when you start a quiz
* MDL-52806 - Show right answers when manually grading automatically marked questions
* MDL-53304 - Immediate feedback behaviours should not show a disabled check button when you can't use it

===Other activity modules===

* MDL-42190 - Workshop: Possibility to delete a submission
* MDL-51306 - Folder: [https://docs.moodle.org/31/en/Folder_resource Bulk download all files within a folder activity as ZIP file]
* MDL-52414 - Lesson: Allow Default Settings for [https://docs.moodle.org/31/en/Lesson_settings Lesson Module Settings]
* MDL-51267 - URL/File: Make setting up a [https://docs.moodle.org/31/en/URL_resource_settings#General URL]/[https://docs.moodle.org/31/en/File_resource_settings#Uploading_files File] resource more obvious
* MDL-50794 - Workshop: [https://docs.moodle.org/31/en/Workshop_settings Restricting file types as attachments] to a workshop

===Gradebook===

* MDL-48634 - Option to rescale existing grades when changing max points
* MDL-52522 - grade_minmaxtouse should be respected for overridden categories
* MDL-51900 - Tab Down Grade Column in Single View of Gradebook
* MDL-52309 - Make Grade History report require user to submit parameters before the report starts running

===Performance===

* MDL-51374 - Do not purge entire databasemeta cache when there are structure changes (esp temp tables).
* MDL-51603 - Refactor downloading of csv, ods, excel etc files in reports and exports across moodle to stream progressively
* MDL-34925 - Improve bulk user export performance
* MDL-50385 - Performance improvement to the grade history report

===Tagging===

* MDL-50851 - Introduce tag collections - ability to separate independent tag areas
* MDL-52252 - Add tags to modules (Resources and Activities)
* MDL-25742 - Allow to search wiki pages by tags
* MDL-51283 - Rename "official" tags to "standard", allow admin to set for each tag area how to use standard tags
* MDL-16855 - Add tag filtering to "Manage tags" page
* MDL-52707 - Allow tags to be combined

===Usability===

* MDL-27628 - [https://docs.moodle.org/31/en/Course_meta_link Enrol meta:] Possible to add multiple courses without leaving the form
* MDL-51818 - Move the profile 'Message' button to be next to the user picture
* MDL-52258 - Calendar now shows duration in calendar block
* MDL-53043 - Move user search box above the students list in the manual enrolments popup
* MDL-35590 - Navigation block redesign to meet ARIA specification
* MDL-49963 - Allow to message all participants when there are more than one page in participants list
* MDL-51354 - Help popup and improved name for events dropdown menu on the course and site logs pages
* MDL-53026 - Use inplace editable for editing cohort names
* MDL-51706 - Move plagiarism links to the top of the summary and full text outputs
* MDL-53382 - "Show all" link on participants page should be moved beneath the page switcher

===Other improvements===

* MDL-53057 - Add [https://docs.moodle.org/31/en/File_system_repository#Using_a_File_System_repository_file search feature to the File system repository]
* MDL-48506 - Improve memcached cache store so that it is multi-site safe
* MDL-50661 - Restyle "Clean" theme to use Logo and Header in Frontpage with smaller logo option in other pages.
* MDL-36652 - When downloading an Excel spreadsheet of student logs, have the course short name included in the file name.
* MDL-53207 - Display stock avatar instead of own user picture from messages from fake users
* MDL-51698 - Markup the crumb trail so search engines understand it and leverage it
* MDL-53072 - Option to choose whether we include suspended users when auto-creating groups
* MDL-52869 - Convert inline activity name edit to use the inplace editable element

===For administrators===

* MDL-26935 - New capability to control role renaming
* MDL-28030 - Add config.php settings to allow plugins to rewrite output moodle_urls (eg clean / semantic urls)
* MDL-52752 - Administrators can specify an alternate URL to use for MathJax
* MDL-52219 - Completion tracking & availability should default to on for new installs
* MDL-52990 - Enable all emails to be themed, ie add 4 wrapper mustache templates
* MDL-53260 - Option to display CLI upgrade messages in English
* MDL-52386 - Allow to control field for flagging enabled/disabled users in LDAP authentication (useful for Active Directory)
* MDL-52383 - Calendar "Days to look ahead" should allow intervals up to 1 year
* MDL-49934 - Admins or managers should be able to retrieve assignments info via get_assignments web service

==Security issues==

There are no security issues included in this release, please refer to [https://docs.moodle.org/dev/Moodle_3.0.4_release_notes Moodle 3.0.4 release notes]

==For developers==

===Significant new areas===

* MDL-31989 - [https://docs.moodle.org/dev/Search_API Global Search] API allows to index and search forums, wikis and other content throughout the whole site.
* MDL-49279, MDL-50032 - Add support in moodle plugins for exporting "[[Moodle Mobile Remote add-ons|Mobile app addons]]"
* MDL-53451 - Competencies support in Moodle ([https://docs.moodle.org/dev/Competency_API documentation])
* MDL-50887 - Implement plugins infrastructure for antivirus and create ClamAV plugin ([https://docs.moodle.org/dev/Antivirus_plugins documentation]).
* MDL-51603 - New [https://docs.moodle.org/dev/Data_formats Dataformat] plugin type for downloading data as csv, ods, excel etc (eg from table_sql export)
* MDL-50851 - Significant changes to Tags API, tag areas can now implement callbacks to display tagged items ([https://docs.moodle.org/dev/Tag_API documentation])
* MDL-46891 - Upgrade to behat 3.x ([https://docs.moodle.org/dev/Acceptance_testing/Migrating_from_Behat_2.5_to_3.x_in_Moodle documentation])

===Smaller new things===

* MDL-51802 - Reusable element for inplace editing ([https://docs.moodle.org/dev/Inplace_editable documentation])
* MDL-30811 - Introduce notification stack to moodle sessions ([https://docs.moodle.org/dev/Notifications documentation])
* MDL-52237 - Add a callback to inject nodes in the user profile navigation ([https://docs.moodle.org/dev/Navigation_API#User_profile documentation])
* MDL-51324 - New course chooser element for moodleforms ([https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete documentation])
* MDL-53311 - Reusable element for displaying tree similar to navigation tree ([https://docs.moodle.org/dev/Tree documentation])

===Smaller changes in core APIs===

* MDL-52954 - file_storage class can now convert between office documents ([https://docs.moodle.org/dev/File_API#Convert_between_file_formats_.28office_documents.29 documentation])
* MDL-53274 - Throw exception (in developer mode) if page context is not set, otherwise it is easily missed in AJAX calls
* MDL-52826, MDL-52715 - Allow to use moodleforms in AJAX requests ([https://docs.moodle.org/dev/Fragment documentation])
* MDL-51718 - Allow to specify scheme in moodle_url
* MDL-51700 - Ajax service should clean the return values of the external functions
* MDL-53962 - '''Changes to webservices XML-RPC API''' - it is now '''critical''' to specify parameters for XML-RPC calls in the correct order. Previously Zend may have been able to work out the order, our new implementation, at this stage, cannot.

===Themeability improvements===

* MDL-50464 - New renderer for RSS Client Block allows themes to customise its look

===Changes related to particular plugins===

* MDL-52013 - Allow mod_assign plugins to add calendar events
* MDL-48362 - Improve the enrol API to prevent logic in the UI ([https://docs.moodle.org/dev/Enrolment_plugins#Standard_Editing_UI documentation])
* MDL-52996 - Allow Atto customisation for special-purpose plugins
* MDL-52781 - Improved validation on user fields when creating users from external datasources
* MDL-53304 - Changes to interactive question behaviour may cause the unit tests for your question type to break if you have followed the common patter. You will need to make changes like [https://github.com/moodle/moodle/commit/81e47a35e8bb98a94ea88e45eee63dcda1b46f74#diff-d16a78021131604bb14ae59ebe6eeebbL235 this].

===Deprecations===

For full list of deprecations refer to lib/upgrade.txt and upgrade.txt files in the folder where the particular plugin is located. Here are the most major deprecations:

* MDL-49414 - Remove deprecated web services
* MDL-48621 - Deprecate the old events system
* MDL-52207 - Delete Zend framework

==See also==
*[[Moodle 3.0 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.1]]

[[fr:Notes de mise à jour de Moodle 3.1]]
[[es:Notas de Moodle 3.1]]

Navigation API

2016-05-24T19:18:00Z

Gaudreaj: /* User profile */

==Overview==
The Navigation API allows for the manipulation of the navigation system used in Moodle.

==What the navigation is==
It's very important to understand what the navigation is exactly within Moodle. One of the goals for Moodle 2.0 was to standardise navigation throughout Moodle and try to bring order to the structure of a Moodle site. Navigation is available through the page object '''$PAGE''', against which you set the heading for the page, the title, any JavaScript requirements, etc. The navigation structure uses the information $PAGE contains to generate a navigation structure for the site. The navigation or settings [[blocks]] are interpretations of the navigation structure Moodle creates.

This navigation structure is available through three variables:

; $PAGE->navigation : This is the main navigation structure, it will contain items that will allow the user to browse to the other available pages.
; $PAGE->settingsnav : This is the settings navigation structure contains items that will allow the user to edit settings.
; $PAGE->navbar : The navbar is a special structure for page breadcrumbs.

==What the navigation is not==
The navigation is '''NOT''' the navigation block or the settings block! These two blocks were created to display the navigation structure. The navigation block looks at ''$PAGE->navigation'', and the settings block looks at ''$PAGE->settingsnav''. Both blocks interpret their data into an HTML structure and render it.

# The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
# The navigation and settings blocks display the back-end navigation structure but add nothing to it at all.
::In the [[model-view-controller pattern]], $PAGE->navigation, $PAGE->settingsnav, and $PAGE->navbar are the models, and the blocks are views.

The navbar is just the path to the active navigation or settings item. The navbar is not displayed by a block; instead it is added into the theme's layout files and displayed by the core renderer.

==How the navigation works==

The main navigation structure can be accessed through '''$PAGE->navigation'''. The navigation and settings are contextual in that they will relate to the page that the user is viewing. This is determined by other $PAGE object properties:
* '''$PAGE->context''' is a Moodle context that immediately outlines the nature of the page the user is viewing.
* '''$PAGE->course''' is the course the user is viewing. This is essential if the context is CONTEXT_COURSE or greater. However, it is also useful in other contexts such as CONTEXT_USER.
* '''$PAGE->cm''' is the course module instance. This is essential if the context is CONTEXT_MODULE or greater.
* '''$PAGE->url''' is used to match the active navigation item.

Nearly every page sets $PAGE->url through a call to '''$PAGE->set_url''' however not many explicitly set the context, course, or cm. When you call '''require_login''' with a course or cm it automatically calls the following:
<code php>
if ($cm) {
$PAGE->set_cm($cm, $course); // sets up global $COURSE
} else {
$PAGE->set_course($course);// sets up global $COURSE
</code>

A page will only be required to explicitly set a context, course, or cm under one of these conditions:
# '''require_login''' is NOT being called correctly
# The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call '''$PAGE->set_context''' ).
# The page is using a course or cm but it is also using one of the above contexts (call '''$PAGE->set_course''' or '''$PAGE->set_cm''' ).

The navigation structure cannot be generated before the $PAGE object is configured. It is only generated when it is first used, either when something tries to access the structure or when code tries to add to it. The navigation is initialised in a specific order:
# Main navigation structure
# Settings navigation
# Navbar (does not need to be generated because of its simple contents and rendering)

==Extending the navigation==

===Code extension===
This method of extending is when the code arbitrarily extends the navigation during its execution. Extending the navigation through this means allows you to extend the navigation anywhere easily, however it will only be shown on pages where your extending code gets called (you should probably put it in a function within lib.php).

These examples are taken from the [http://moodle.org/mod/forum/discuss.php?d=152391 General Developer Forum: Moodle 2 - how to set up breadcrumbs for a module page]. It has further information that is well worth reading.
====Navigation====
This is extending the main navigation structure.
<code php>
$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The above lines of code adds a preview node to the bottom of the navigation and then adds a thingnode to the previewnode (adding a leaf to our tree).
The final line of code makes the thingnode active so that the navbar finds it however if the URL you give it is the same as the url you set for the page it will automatically be marked active and you won't need this call.

Next extending the navigation for the course.
For this you will need to know the course id and have called require_login($courseorid); so that the navigation is loaded for the course.
<code php>
$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The new bit of code here really is the first line which simply finds the course node, to do this we give it the course id and the node type in this case TYPE_COURSE.
What we are doing here is relying on the navigation to generate the navigation up to the course and then just adding to the course.

Note that Moodle loads plugins in alphabetical order. Therefore plugin_b can find a node added by plugin_a but not the other way around.
====Settings navigation====
Adding to the settings navigation is very similar to navigation
<code php>
$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>

====Add Settings folder to navigation====

An example of a settings folder in a module can be see by navigating to Site administration / Plugins / Activity modules / Assignment.

[[File:assignmentmenu.png]]

An example of adding a navigation folder to a settings.php for a block with a link to the settings page and a external page is bellow.

<code php>
<?php

defined('MOODLE_INTERNAL') || die;

// Create folder / submenu in block menu, modsettings for activity modules, localplugins for Local plugins.
// The default folders are defined in admin/settings/plugins.php.
$ADMIN->add('blocksettings', new admin_category('blocksamplefolder',
get_string('pluginname', 'mod_sample')));

// Create settings block.
$settings = new admin_settingpage($section, get_string('settings', 'block_sample'));
if ($ADMIN->fulltree) {
$settings->add(new admin_setting_configcheckbox('block_sample_checkbox', get_string('checkbox', 'block_sample'),
get_string('checkboxdescription', 'block_kronoshtml'), 0));
}

// This adds the settings link to the folder/submenu.
$ADMIN->add('blocksamplefolder', $settings);
// This adds a link to an external page.
$ADMIN->add('blocksamplefolder', new admin_externalpage('block_sample_page', get_string('externalpage', 'block_sample'),
$CFG->wwwroot.'/blocks/sample/sample.php'));
// Prevent Moodle from adding settings block in standard location.
$settings = null;
</code>

====Navbar====
This is extending the settings navigation.
<code php>
$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
</code>
The above code tells the navbar to ignore what ever the active page was and just use what you add, at which point we add two items as shown.
===Plugin Callbacks===
These are specific functions that the navigation looks for and calls if they exist for the plugin, presently only three plugin types can extend the navigation through these call-backs.

Ideally all entries in "Administration / Site administration" tree should be done via settings.php files but sometimes it may be easier to directly modify the navigation structure created from the admin settings tree (such as when adding links to external pages).

====Module====
Modules have two call-back methods, first to extend the navigation, and second to extend the settings. These call-backs get called when ever the user is viewing a page within the module and should only extend the navigation for the module.
<code php>
function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)
</code>

====Course Formats====
Course formats are able to completely redefine the way in which navigation is generated for a course, as well as this they also have several methods to ensure the navigation is generated correctly.

====Course Reports====
By default reports don't add themselves or anything else to the navigation however there is a call-back that can be implemented to allow them to do so.

====Local Plugins====
{{Moodle 2.9}}Local plugins have two call-back methods, first to extend the navigation, and second to extend the settings.
<code php>
function local_{pluginname}_extend_navigation(global_navigation $nav)
function local_{pluginname}_extend_settings_navigation(settings_navigation $nav, context $context)
</code>

In versions before Moodle 2.9, the supported callbacks have <tt>_extends_</tt> (not imperative mood) in their names. This was a consistency bug fixed in MDL-49643.

<code php>
function local_{pluginname}_extends_navigation(global_navigation $nav)
function local_{pluginname}_extends_settings_navigation(settings_navigation $nav, context $context)
</code>

====Course settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the course settings navigation. Prior to 3.0 only ''reports'' and ''admin tools'' could extend the course settings navigation.

<code php>
function <component>_extend_navigation_course(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the user settings navigation. Prior to 3.0 only ''admin tools'' could extend the user settings navigation.

<code php>
function <component>_extend_navigation_user_settings(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

====Category settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the category settings navigation.

<code php>
function <component>_extend_navigation_category_settings(navigation_node $parentnode, context_coursecat $context);
</code>

====Frontpage settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the frontpage settings navigation. Prior to 3.0 only ''admin tools'' could extend the frontpage settings navigation.

<code php>
function <component>_extend_navigation_frontpage(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User profile====
{{Moodle 3.1}}
Any plugin implementing the following callback in lib.php can extend the user profile navigation.
<code php>
function <component>_extend_navigation_user(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

==FAQ's and troubleshooting==
'''Q.''' My page is on the navigation but it doesn't find it?

The first thing to do here is check the URL you are setting for the page. It should match the URL your page has within the navigation. If it doesn't you have two options, first change your '''$PAGE->set_url''' call, or second override the URL the navigation is using to find the active node as shown below:
<code php>
navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));
</code>

==See also==

* [[Core APIs]]
* [https://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Forum discussion - adding navigation to local plugins]

[[Category:API]]

Navigation API

2016-05-24T19:16:46Z

Gaudreaj: /* User Profile */

==Overview==
The Navigation API allows for the manipulation of the navigation system used in Moodle.

==What the navigation is==
It's very important to understand what the navigation is exactly within Moodle. One of the goals for Moodle 2.0 was to standardise navigation throughout Moodle and try to bring order to the structure of a Moodle site. Navigation is available through the page object '''$PAGE''', against which you set the heading for the page, the title, any JavaScript requirements, etc. The navigation structure uses the information $PAGE contains to generate a navigation structure for the site. The navigation or settings [[blocks]] are interpretations of the navigation structure Moodle creates.

This navigation structure is available through three variables:

; $PAGE->navigation : This is the main navigation structure, it will contain items that will allow the user to browse to the other available pages.
; $PAGE->settingsnav : This is the settings navigation structure contains items that will allow the user to edit settings.
; $PAGE->navbar : The navbar is a special structure for page breadcrumbs.

==What the navigation is not==
The navigation is '''NOT''' the navigation block or the settings block! These two blocks were created to display the navigation structure. The navigation block looks at ''$PAGE->navigation'', and the settings block looks at ''$PAGE->settingsnav''. Both blocks interpret their data into an HTML structure and render it.

# The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
# The navigation and settings blocks display the back-end navigation structure but add nothing to it at all.
::In the [[model-view-controller pattern]], $PAGE->navigation, $PAGE->settingsnav, and $PAGE->navbar are the models, and the blocks are views.

The navbar is just the path to the active navigation or settings item. The navbar is not displayed by a block; instead it is added into the theme's layout files and displayed by the core renderer.

==How the navigation works==

The main navigation structure can be accessed through '''$PAGE->navigation'''. The navigation and settings are contextual in that they will relate to the page that the user is viewing. This is determined by other $PAGE object properties:
* '''$PAGE->context''' is a Moodle context that immediately outlines the nature of the page the user is viewing.
* '''$PAGE->course''' is the course the user is viewing. This is essential if the context is CONTEXT_COURSE or greater. However, it is also useful in other contexts such as CONTEXT_USER.
* '''$PAGE->cm''' is the course module instance. This is essential if the context is CONTEXT_MODULE or greater.
* '''$PAGE->url''' is used to match the active navigation item.

Nearly every page sets $PAGE->url through a call to '''$PAGE->set_url''' however not many explicitly set the context, course, or cm. When you call '''require_login''' with a course or cm it automatically calls the following:
<code php>
if ($cm) {
$PAGE->set_cm($cm, $course); // sets up global $COURSE
} else {
$PAGE->set_course($course);// sets up global $COURSE
</code>

A page will only be required to explicitly set a context, course, or cm under one of these conditions:
# '''require_login''' is NOT being called correctly
# The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call '''$PAGE->set_context''' ).
# The page is using a course or cm but it is also using one of the above contexts (call '''$PAGE->set_course''' or '''$PAGE->set_cm''' ).

The navigation structure cannot be generated before the $PAGE object is configured. It is only generated when it is first used, either when something tries to access the structure or when code tries to add to it. The navigation is initialised in a specific order:
# Main navigation structure
# Settings navigation
# Navbar (does not need to be generated because of its simple contents and rendering)

==Extending the navigation==

===Code extension===
This method of extending is when the code arbitrarily extends the navigation during its execution. Extending the navigation through this means allows you to extend the navigation anywhere easily, however it will only be shown on pages where your extending code gets called (you should probably put it in a function within lib.php).

These examples are taken from the [http://moodle.org/mod/forum/discuss.php?d=152391 General Developer Forum: Moodle 2 - how to set up breadcrumbs for a module page]. It has further information that is well worth reading.
====Navigation====
This is extending the main navigation structure.
<code php>
$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The above lines of code adds a preview node to the bottom of the navigation and then adds a thingnode to the previewnode (adding a leaf to our tree).
The final line of code makes the thingnode active so that the navbar finds it however if the URL you give it is the same as the url you set for the page it will automatically be marked active and you won't need this call.

Next extending the navigation for the course.
For this you will need to know the course id and have called require_login($courseorid); so that the navigation is loaded for the course.
<code php>
$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The new bit of code here really is the first line which simply finds the course node, to do this we give it the course id and the node type in this case TYPE_COURSE.
What we are doing here is relying on the navigation to generate the navigation up to the course and then just adding to the course.

Note that Moodle loads plugins in alphabetical order. Therefore plugin_b can find a node added by plugin_a but not the other way around.
====Settings navigation====
Adding to the settings navigation is very similar to navigation
<code php>
$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>

====Add Settings folder to navigation====

An example of a settings folder in a module can be see by navigating to Site administration / Plugins / Activity modules / Assignment.

[[File:assignmentmenu.png]]

An example of adding a navigation folder to a settings.php for a block with a link to the settings page and a external page is bellow.

<code php>
<?php

defined('MOODLE_INTERNAL') || die;

// Create folder / submenu in block menu, modsettings for activity modules, localplugins for Local plugins.
// The default folders are defined in admin/settings/plugins.php.
$ADMIN->add('blocksettings', new admin_category('blocksamplefolder',
get_string('pluginname', 'mod_sample')));

// Create settings block.
$settings = new admin_settingpage($section, get_string('settings', 'block_sample'));
if ($ADMIN->fulltree) {
$settings->add(new admin_setting_configcheckbox('block_sample_checkbox', get_string('checkbox', 'block_sample'),
get_string('checkboxdescription', 'block_kronoshtml'), 0));
}

// This adds the settings link to the folder/submenu.
$ADMIN->add('blocksamplefolder', $settings);
// This adds a link to an external page.
$ADMIN->add('blocksamplefolder', new admin_externalpage('block_sample_page', get_string('externalpage', 'block_sample'),
$CFG->wwwroot.'/blocks/sample/sample.php'));
// Prevent Moodle from adding settings block in standard location.
$settings = null;
</code>

====Navbar====
This is extending the settings navigation.
<code php>
$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
</code>
The above code tells the navbar to ignore what ever the active page was and just use what you add, at which point we add two items as shown.
===Plugin Callbacks===
These are specific functions that the navigation looks for and calls if they exist for the plugin, presently only three plugin types can extend the navigation through these call-backs.

Ideally all entries in "Administration / Site administration" tree should be done via settings.php files but sometimes it may be easier to directly modify the navigation structure created from the admin settings tree (such as when adding links to external pages).

====Module====
Modules have two call-back methods, first to extend the navigation, and second to extend the settings. These call-backs get called when ever the user is viewing a page within the module and should only extend the navigation for the module.
<code php>
function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)
</code>

====Course Formats====
Course formats are able to completely redefine the way in which navigation is generated for a course, as well as this they also have several methods to ensure the navigation is generated correctly.

====Course Reports====
By default reports don't add themselves or anything else to the navigation however there is a call-back that can be implemented to allow them to do so.

====Local Plugins====
{{Moodle 2.9}}Local plugins have two call-back methods, first to extend the navigation, and second to extend the settings.
<code php>
function local_{pluginname}_extend_navigation(global_navigation $nav)
function local_{pluginname}_extend_settings_navigation(settings_navigation $nav, context $context)
</code>

In versions before Moodle 2.9, the supported callbacks have <tt>_extends_</tt> (not imperative mood) in their names. This was a consistency bug fixed in MDL-49643.

<code php>
function local_{pluginname}_extends_navigation(global_navigation $nav)
function local_{pluginname}_extends_settings_navigation(settings_navigation $nav, context $context)
</code>

====Course settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the course settings navigation. Prior to 3.0 only ''reports'' and ''admin tools'' could extend the course settings navigation.

<code php>
function <component>_extend_navigation_course(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the user settings navigation. Prior to 3.0 only ''admin tools'' could extend the user settings navigation.

<code php>
function <component>_extend_navigation_user_settings(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

====Category settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the category settings navigation.

<code php>
function <component>_extend_navigation_category_settings(navigation_node $parentnode, context_coursecat $context);
</code>

====Frontpage settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the frontpage settings navigation. Prior to 3.0 only ''admin tools'' could extend the frontpage settings navigation.

<code php>
function <component>_extend_navigation_frontpage(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User profile====
{{Moodle 3.1}}
Any plugin implementing the following callback in lib.php can extend the user profile navigation.

<code php>
function <component>_extend_navigation_user(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

==FAQ's and troubleshooting==
'''Q.''' My page is on the navigation but it doesn't find it?

The first thing to do here is check the URL you are setting for the page. It should match the URL your page has within the navigation. If it doesn't you have two options, first change your '''$PAGE->set_url''' call, or second override the URL the navigation is using to find the active node as shown below:
<code php>
navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));
</code>

==See also==

* [[Core APIs]]
* [https://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Forum discussion - adding navigation to local plugins]

[[Category:API]]

Navigation API

2016-05-24T19:16:24Z

Gaudreaj:

==Overview==
The Navigation API allows for the manipulation of the navigation system used in Moodle.

==What the navigation is==
It's very important to understand what the navigation is exactly within Moodle. One of the goals for Moodle 2.0 was to standardise navigation throughout Moodle and try to bring order to the structure of a Moodle site. Navigation is available through the page object '''$PAGE''', against which you set the heading for the page, the title, any JavaScript requirements, etc. The navigation structure uses the information $PAGE contains to generate a navigation structure for the site. The navigation or settings [[blocks]] are interpretations of the navigation structure Moodle creates.

This navigation structure is available through three variables:

; $PAGE->navigation : This is the main navigation structure, it will contain items that will allow the user to browse to the other available pages.
; $PAGE->settingsnav : This is the settings navigation structure contains items that will allow the user to edit settings.
; $PAGE->navbar : The navbar is a special structure for page breadcrumbs.

==What the navigation is not==
The navigation is '''NOT''' the navigation block or the settings block! These two blocks were created to display the navigation structure. The navigation block looks at ''$PAGE->navigation'', and the settings block looks at ''$PAGE->settingsnav''. Both blocks interpret their data into an HTML structure and render it.

# The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
# The navigation and settings blocks display the back-end navigation structure but add nothing to it at all.
::In the [[model-view-controller pattern]], $PAGE->navigation, $PAGE->settingsnav, and $PAGE->navbar are the models, and the blocks are views.

The navbar is just the path to the active navigation or settings item. The navbar is not displayed by a block; instead it is added into the theme's layout files and displayed by the core renderer.

==How the navigation works==

The main navigation structure can be accessed through '''$PAGE->navigation'''. The navigation and settings are contextual in that they will relate to the page that the user is viewing. This is determined by other $PAGE object properties:
* '''$PAGE->context''' is a Moodle context that immediately outlines the nature of the page the user is viewing.
* '''$PAGE->course''' is the course the user is viewing. This is essential if the context is CONTEXT_COURSE or greater. However, it is also useful in other contexts such as CONTEXT_USER.
* '''$PAGE->cm''' is the course module instance. This is essential if the context is CONTEXT_MODULE or greater.
* '''$PAGE->url''' is used to match the active navigation item.

Nearly every page sets $PAGE->url through a call to '''$PAGE->set_url''' however not many explicitly set the context, course, or cm. When you call '''require_login''' with a course or cm it automatically calls the following:
<code php>
if ($cm) {
$PAGE->set_cm($cm, $course); // sets up global $COURSE
} else {
$PAGE->set_course($course);// sets up global $COURSE
</code>

A page will only be required to explicitly set a context, course, or cm under one of these conditions:
# '''require_login''' is NOT being called correctly
# The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call '''$PAGE->set_context''' ).
# The page is using a course or cm but it is also using one of the above contexts (call '''$PAGE->set_course''' or '''$PAGE->set_cm''' ).

The navigation structure cannot be generated before the $PAGE object is configured. It is only generated when it is first used, either when something tries to access the structure or when code tries to add to it. The navigation is initialised in a specific order:
# Main navigation structure
# Settings navigation
# Navbar (does not need to be generated because of its simple contents and rendering)

==Extending the navigation==

===Code extension===
This method of extending is when the code arbitrarily extends the navigation during its execution. Extending the navigation through this means allows you to extend the navigation anywhere easily, however it will only be shown on pages where your extending code gets called (you should probably put it in a function within lib.php).

These examples are taken from the [http://moodle.org/mod/forum/discuss.php?d=152391 General Developer Forum: Moodle 2 - how to set up breadcrumbs for a module page]. It has further information that is well worth reading.
====Navigation====
This is extending the main navigation structure.
<code php>
$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The above lines of code adds a preview node to the bottom of the navigation and then adds a thingnode to the previewnode (adding a leaf to our tree).
The final line of code makes the thingnode active so that the navbar finds it however if the URL you give it is the same as the url you set for the page it will automatically be marked active and you won't need this call.

Next extending the navigation for the course.
For this you will need to know the course id and have called require_login($courseorid); so that the navigation is loaded for the course.
<code php>
$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The new bit of code here really is the first line which simply finds the course node, to do this we give it the course id and the node type in this case TYPE_COURSE.
What we are doing here is relying on the navigation to generate the navigation up to the course and then just adding to the course.

Note that Moodle loads plugins in alphabetical order. Therefore plugin_b can find a node added by plugin_a but not the other way around.
====Settings navigation====
Adding to the settings navigation is very similar to navigation
<code php>
$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>

====Add Settings folder to navigation====

An example of a settings folder in a module can be see by navigating to Site administration / Plugins / Activity modules / Assignment.

[[File:assignmentmenu.png]]

An example of adding a navigation folder to a settings.php for a block with a link to the settings page and a external page is bellow.

<code php>
<?php

defined('MOODLE_INTERNAL') || die;

// Create folder / submenu in block menu, modsettings for activity modules, localplugins for Local plugins.
// The default folders are defined in admin/settings/plugins.php.
$ADMIN->add('blocksettings', new admin_category('blocksamplefolder',
get_string('pluginname', 'mod_sample')));

// Create settings block.
$settings = new admin_settingpage($section, get_string('settings', 'block_sample'));
if ($ADMIN->fulltree) {
$settings->add(new admin_setting_configcheckbox('block_sample_checkbox', get_string('checkbox', 'block_sample'),
get_string('checkboxdescription', 'block_kronoshtml'), 0));
}

// This adds the settings link to the folder/submenu.
$ADMIN->add('blocksamplefolder', $settings);
// This adds a link to an external page.
$ADMIN->add('blocksamplefolder', new admin_externalpage('block_sample_page', get_string('externalpage', 'block_sample'),
$CFG->wwwroot.'/blocks/sample/sample.php'));
// Prevent Moodle from adding settings block in standard location.
$settings = null;
</code>

====Navbar====
This is extending the settings navigation.
<code php>
$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
</code>
The above code tells the navbar to ignore what ever the active page was and just use what you add, at which point we add two items as shown.
===Plugin Callbacks===
These are specific functions that the navigation looks for and calls if they exist for the plugin, presently only three plugin types can extend the navigation through these call-backs.

Ideally all entries in "Administration / Site administration" tree should be done via settings.php files but sometimes it may be easier to directly modify the navigation structure created from the admin settings tree (such as when adding links to external pages).

====Module====
Modules have two call-back methods, first to extend the navigation, and second to extend the settings. These call-backs get called when ever the user is viewing a page within the module and should only extend the navigation for the module.
<code php>
function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)
</code>

====Course Formats====
Course formats are able to completely redefine the way in which navigation is generated for a course, as well as this they also have several methods to ensure the navigation is generated correctly.

====Course Reports====
By default reports don't add themselves or anything else to the navigation however there is a call-back that can be implemented to allow them to do so.

====Local Plugins====
{{Moodle 2.9}}Local plugins have two call-back methods, first to extend the navigation, and second to extend the settings.
<code php>
function local_{pluginname}_extend_navigation(global_navigation $nav)
function local_{pluginname}_extend_settings_navigation(settings_navigation $nav, context $context)
</code>

In versions before Moodle 2.9, the supported callbacks have <tt>_extends_</tt> (not imperative mood) in their names. This was a consistency bug fixed in MDL-49643.

<code php>
function local_{pluginname}_extends_navigation(global_navigation $nav)
function local_{pluginname}_extends_settings_navigation(settings_navigation $nav, context $context)
</code>

====Course settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the course settings navigation. Prior to 3.0 only ''reports'' and ''admin tools'' could extend the course settings navigation.

<code php>
function <component>_extend_navigation_course(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the user settings navigation. Prior to 3.0 only ''admin tools'' could extend the user settings navigation.

<code php>
function <component>_extend_navigation_user_settings(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

====Category settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the category settings navigation.

<code php>
function <component>_extend_navigation_category_settings(navigation_node $parentnode, context_coursecat $context);
</code>

====Frontpage settings====
{{Moodle 3.0}}
Any plugin implementing the following callback in lib.php can extend the frontpage settings navigation. Prior to 3.0 only ''admin tools'' could extend the frontpage settings navigation.

<code php>
function <component>_extend_navigation_frontpage(navigation_node $parentnode, stdClass $course, context_course $context);
</code>

====User Profile====
{{Moodle 3.1}}
Any plugin implementing the following callback in lib.php can extend the user profile navigation.

<code php>
function <component>_extend_navigation_user(navigation_node $parentnode, stdClass $user, context_user $context, stdClass $course, context_course $coursecontext);
</code>

==FAQ's and troubleshooting==
'''Q.''' My page is on the navigation but it doesn't find it?

The first thing to do here is check the URL you are setting for the page. It should match the URL your page has within the navigation. If it doesn't you have two options, first change your '''$PAGE->set_url''' call, or second override the URL the navigation is using to find the active node as shown below:
<code php>
navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));
</code>

==See also==

* [[Core APIs]]
* [https://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Forum discussion - adding navigation to local plugins]

[[Category:API]]