If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Navigation 2.0

From MoodleDocs

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

Moodle 2.0

State of play September 2009

It is mostly done. Just needs testing and refinement.


Improving navigation in a complex web application like Moodle touches on a lot of areas, but in particular we must aim to hit these goals:


It should be clearer what settings affect only yourself, and what settings affect what others see.

It should be clear what is global navigation (whole site), and what is local navigation (within a course or module).


All parts of the interface should be consistent. We need to have a set of guidelines and core frameworks to better restrict what developers are allowed to do, while also reworking the core code to implement things like blocks and tabs in consistent ways.


Users should be able to easily learn what is there for them.

Users should be able to move around "their world" within Moodle with a minimum of effort.


Processing blocks and building up a page with navigation must be very efficient.

Backward compatibility

If possible, plugins should not have to change.

Users should also not find the new interface too different (just better!)


What parts of Moodle might be affected by this work?

Navigation bar

Since Moodle 1.9, we construct the navigation bar from an array using the build_navigation function. However, that converts all the data to a string, which is then passed to the theme. Instead, we should keep the information about the navigation bar links as structured data, and let the theme choose how to render it.

Local navigation

In different places we have the global administration tree, the Course admin block, the Jump to menu, tabs like in the user profile, various activities, in the roles UI, and the 'Update this forum' button. These are all ways of getting around nearby, related pages. It would be good to make these concepts more consistent. (There is also $homelink in the footer. Currently the HTML for this is generated in print_header.)

This is an area we need to think about a lot more

Please discuss here:


Blocks themselves should not change. What is currently inconsistent is how blocks get associated with particular pages. At the moment this is done through the (pageid, pagetype) columns of block_instance, and the pagetype column of block_pinned. Does it work if we change this to (contextid, pagetype)?

The other thought is, can we make sticky blocks more flexible? What if we let them be configured in any context, not just globally? This would let people do things like add a block to every course in a particular category.

Perhaps let themes control where on the page blocks can appear.

Some more thought required here.

Please discuss here:

Course view

What do we need on top of the existing course formats?

--Mike Churchward 13:04, 14 April 2009 (UTC):

The biggest issues we have with creating custom course formats are:

  1. Controlling the display flow. Currently, course formats can only write out the main section of the page (right, centre and left). The header and start of the page are all written by '/course/view.php' before the course format gains control. The biggest gain course format creators could have would be the ability to control all aspects of the course page. ( Martin Dougiamas 14:14, 14 April 2009 (UTC): Although I can see some very big conflict problems here between the course format and the theme, this should be possible using some sort of course format variable (or file being present) that course/view.php could detect to work out when to pass control to the course format).
  2. The course object is loaded by a database call. This might be better served by an API call, that can be overloaded or 'pluggable'. This would allow course formats to load data from their own tables into the course object. ( Martin Dougiamas 14:14, 14 April 2009 (UTC): Putting this into a function that again, detected something in the current course format, should be pretty easy).
  3. The edit course function is not controllable by the course format, making it difficult to provide custom settings screens for a specific format. ( Martin Dougiamas 14:14, 14 April 2009 (UTC): As above)


Give themers as much flexibility as possible, without having to do major changes throughout Moodle.

Let them change the HTML output by the print_XXX functions in weblib.php.

Should we allow themes to have their own lang files and settings.php page in the admin tree?

Theme engines for Moodle?

Solution 1

This section is intended to be a short summary of a possible solution for Moodle 2.0. It's heavily based on Tim Hunt's ideas and discussions I've had with him, but I wanted to paraphrase it to help me think about it. Martin Dougiamas 06:52, 13 March 2009 (UTC)

The one-line summary is: make blocks more consistent and themes more powerful, and then let people build their "perfect" interfaces from those.

A key point to all this is backward compatibility. All of this will only affect pages that are coded for it. Older code will work as before, using deprecated functions.

1. Improve HTML generation

Our aim is to give interface designers ultimate control over the presentation of Moodle.

Key points:

  • refactor all weblib-type functions into a class of renderers
  • implement similar renderers for all modules
  • allow any current theme to subclass and override these renderers
  • allow themes to define named regions on the page where blocks will go (eg left, right, top, bottom, center)

This gives us great flexibility within a common and easy to understand framework. For example, it allows templates, but doesn't depend on them.

See Tim's explanation of theme engines for a lot more details.

2. Improve Blocks and Pages

Our aim is to make blocks work everywhere with a lot of control where they go.

Key points:

  • change the implementation of "pages" to be based on contexts
  • develop the idea of sticky blocks to support inheritance in the tree of contexts (eg sticky block at course level would appear in all subcontexts unless they chose to "override" this block).
  • add more controls to blocks to hide/show them in certain types of pages
  • use the theme regions when placing blocks

See Tim's very flexible block system proposal for details.

3. Use blocks for most navigation

Even though we plan the default configuration to provide the best navigation we can, by having most navigation in blocks we give admins and teachers the most flexibility to customise their navigation.

Key points:

  • Navigation block: with a hierarchical tree that adapts to show "things around you" within Moodle. eg at site level it could show courses, at course level it could show the same thing as well as activities within the current course. Such a block would normally be made sticky so that it appears in the same place on all pages. Depending on the theme it could be a block on the side or a drop-down menu in the header!
  • Admin block: would contain all the settings for the current thing you are looking at. Forum settings in the forum, Course settings in the course.
  • Menu block: would allow the custom definition of top-level pages and links to other systems (eg like the menus on

Some mockups:

Example Front page, showing site blocks, menu block (rendered as menu at top) and admin block

Note that the menu at the top is actually a sticky block. It could also have been rendered as a normal block, or a menu on the side, or a simple list of links somewhere. It's just an unsorted list on every page being rendered with CSS.

Example Course page, showing site blocks and course blocks

This shows a block in the "middle" region for this theme, just above the main content for the course page. Blocks can be put into any region. On the right are some course blocks. Note the site blocks still being shown on the left side in this example, although the content is changing to be more relevant to this context.

Example Activity page, showing site blocks, course blocks and local admin block

This activity shows site blocks and course blocks being inherited and shown. An activity could also specify (in the settings for that activity) that it doesn't want any blocks shown.

Implementation plan

Please see Navigation 2.0 implementation plan.

Relevant tracker issues

Tracking bugs

  • MDL-12212 META: Complete review and rewrite of Pagelib (and blocks)

Theme related

These come from a review of all the 'Theme' tracker issues.

  • MDL-3625 $menu in header does too many things
  • MDL-3626 header.html and footer.html $variable inconsistency
  • MDL-8369 Folder-like presentation of the courses at the main page
  • MDL-9306 Main course formats need to have tables removed but keep AJAX working - there seem to be some regressions from this work ;-)
    • MDL-12164 Hiding Course Topics and Switching Roles creates Problem in other Topics
    • MDL-13410 Course view misaligned
    • MDL-17450 Display of blocks and topic section not correct in 2.0
  • MDL-10522 Hard-coded <br /> used for spacing.
    • MDL-14058 Code includes
      tags in many places, which breaks theming, or makes it more difficult
  • MDL-10681 Popup windows need uniform body class
  • MDL-12093 It is not possible to change the page layout in popup windows
  • MDL-12183 Improve block HTML structure
  • MDL-12191 Let themes know whether this page has blocks.
  • MDL-14061 Add category short names, and an option for categories in the navigation bar.
  • MDL-14305 Class on body to identify the page as Moodle, and a specific site. (Enables sharing of stylesheets, but with a few specific customisations.)
  • MDL-14306 The course category hierarchy should be reflected in CSS classes on the body tag (actually, contextids would let this be done more efficiently).
  • MDL-14539 Replace table layout with div - parhaps a duplicate of MDL-9306.
  • MDL-14632 Increase use of tabs on all mod activities.
  • MDL-14901 Themes can no longer control the separater used in the nav bar.
  • MDL-15400 Sideblocks on "My Moodle" page not conforming to global width
  • MDL-15817 Part course them and part site theme is used when displayng Outline and Complete reports
  • MDL-15959 patch any theme to have a personal visual style (CSS file) for each course - not sure this is a good solution, but it is an interesting requirement.
  • MDL-16244 Support for a drop-down menu bar - Like on now.

Block related

And the following are the relevant 'Blocks' issues.

  • MDL-12240 Add the $CFG->defaultblocks functions to adminmenu
  • MDL-15946 Add ability to add blocks to Category page
  • MDL-11960 Cannot configure rss block on tag page
  • MDL-11131 Moving blocks causes some blocks to disappear (pinned blocks trouble)
  • MDL-14542 Modification to improve javascript and css header insertion for blocks, modules and filters
  • MDL-5320 Under some circumstances some block_instances aren't deleted...
  • MDL-6692 blocks on forum pages
  • MDL-13582 "Course Sticky Blocks" don't get displayed when the "Show the course blocks" option is chosen when using "Add a resource" > "Compose a web page"
  • MDL-13606 Sticky blocks on tag pages
  • MDL-13627 Blocks - Default Closed View
  • MDL-13708 The instances column, in the blocks management screen, links only to courses, but counts everything
  • MDL-13888 Allow RSS block on MyMoodle pages only for users who can configure it
  • MDL-13891 admin tree block disply in myMoodle controlled by capabilities
  • MDL-15379 No way to exclude core blocks from specific modules if Blocks in Modules is enabled without changing core block code
  • MDL-17447 LOCAL: stickyblocks targets
  • MDL-6024 make hidden blocks visible to teacher
  • MDL-6748 Patch to allow a center position for Moodle blocks
  • MDL-5898 customizable blogs blocks


  • MDL-17730 More flexibility when creating skip links.
  • MDL-7336 Allow filters to be enabled/disabled per course or activity
  • MDL-6981 Allow text filters to add stuff to page footer
  • MDL-18765 Maximum and minimum block widths are currently hard-coded in some view pages

See also

Using Moodle forum discussions: