Navigation API

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.

1. The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
2. 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: if ($cm) {

   $PAGE->set_cm($cm, $course); // sets up global $COURSE

} else {

   $PAGE->set_course($course);// sets up global $COURSE

A page will only be required to explicitly set a context, course, or cm under one of these conditions:

1. require_login is NOT being called correctly
2. The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call $PAGE->set_context ).
3. 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:

1. Main navigation structure
2. Settings navigation
3. 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 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. $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(); 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. $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(); 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.

Settings navigation

Adding to the settings navigation is very similar to navigation $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();

Navbar

This is extending the settings navigation. $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')); 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.

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. function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm) function {modulename}_extend_settings_navigation($settings, ${modulename}node)

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.

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: navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));

See also

• Core APIs
• [Forum discussion - adding navigation to local plugins]