Obsolete:Navigation/Pagelib/Blocks 2.0 design

This article is a design document which is no longer in use, the code it describes having been written and added to the Moodle codebase, or simply considered then abandoned. The information it contains is likely to be out of date, especially API and Database Schema specifications.

It has been replaced by Development:Navigation 2.0 implementation plan.

We don't yet have a complete picture of how we want all this to work. However, given the goals, recent discussions, what works well in the code at the moment, and some of the obvious things that can be made better, I feel confident enough to outline some components of a solution.

Please discuss this proposal in the General Developer Forum.

Outline

Clear global navigation framework: Conceptually, we will work out how ever page in a Moodle site fits into a big tree structure. This makes designing a clear navigation scheme easier, because we know what we are navigating around. The skeleton of this tree structure is the tree of contexts. Each page belongs to one main context, but a context may have more than one page.
More consistent local navigation: Needs to work out what the plan is here
Class for generating HTML: All the print_XXX methods in lib/weblib.php get moved into a moodle_renderer class which themes can subclass if they want. The existing function will be kept, just redirecting to the class. They will be deprecated.
Class for storing information about the current page: All the information that is currently passed in to print_header via its million arguments, plus some of the information currently in global variables, will instead be stored in a class.
Blocks: Need to work out what the plan is here.
More power to themes: Some of this has already been covered. Also let themes have admin settings pages and their own language packs.

Clear global navigation framework

We are close to having this already, because each page in Moodle should have a list of links in the navbar that shows where it fits in the scheme of things. (Although sometimes not all links are shown here, for example, Course categories are not included, and the 'Forums' type link is controlled by an admin option, however, that is a presentation issue, it does not affect the underlying layout.) We should ensure that this is carried through consistently.

The skeleton of this tree will be the tree of contexts. That is, every page will have a main context with which it is associated. For example, all the admin screens belong to the system context. course main page, course settings, gradebook, list of all forums ... are attached to the course. Forum view, discussion thread, list of subscribers ... are attached to a particular forum. A profile page may be attached to the user context or a course context, depending on how it is accessed.

More consistent local navigation

We need a more detailed plan for how this should work.

Class for generating HTML

As much as possible of the HTML generation will be channelled through a new moodle_renderer class.

There will be a single instance of this class accessible through global. I propose the name $HTML. (Other possibilities are $OUT, $OUTPUT, $RESULT.)

Themes will be able to control which subclass of the moodle_renderer class is used. There is an issue here that you don't know which theme to use until you know which user you are logged in as, and which course they are in, but that is just the same as the issue with initialising $COURSE, and we seem to cope.

moodle_renderer class methods

Almost all the print_XXX functions in lib/weblib.php will become methods of this class.

We will get rid of the $return argument that these methods have, and instead for each method there will be two variants, get_XXX and print_XXX with print_XXX defined as echo get_XXX;.

Where appropriate methods will come in sets like print_box, print_box_start, print_box_end.

We will try as much as possible to increase the consistency in the order and types of arguments to the methods.

The HTML class will track which tags are currently open (as is currently done with $THEME->open_containers[]) to facilitate always generating well-formed XHTML pages. This will include attempts to detect when tags are not closed, with DEVELOPER debug output to help developers.

Insert templates here

It would be possible to make a moodle_renderer subclass that generates the HTML based on template files in the theme. Some people might like this, but it can be added later, I don't think this needs to block the 2.0 release.

Class for storing information about the current page

All the information about where we are now in Moodle will be collected into a single page_information class.

There will be a single instance of this class accessible through global. I think $PAGE would be the best name, only it is already taken. Suggestions include $PG, $PAGE2, $HERE, $NAV. (How about $OUTPUT? Martin Dougiamas 01:25, 23 February 2009 (CST))

To emphasise, this class has nothing to do with output. It simply holds information. When you call $HTML->print_header(), that will call the theme, which will make extensive use of this information, but this information will also be useful in other places.

Information this class will track:

Basic information

The URL of this page, perhaps as a moodle_url. Deprecates me and full_me.
The type of this page. (e.g. course-view. Used as an id="" on the body tag.)
The current language
The current theme

Navigational information

The context associated with this page
The course we are in ($COURSE, although it is too soon to deprecate that.)
If we are in an activity, the $cm object.
The parents of this page in the navigation tree. This is the raw data used to build the navbar.
The page title - goes in the HTML header. Perhaps defaults to the text of the last link in the navbar.
List of nearby pages. This is where it gets a big vague, but I am thinking of the information that is currently in the jumpto menu, or the admin tree, or in the tabs in activity modules like the quiz or glossar. The aim is to make it easier to display consistent navigation on the screen.

Other

List of blocks that should be shown on this page.
Lists of JavaScript and CSS files required by this page. (Deprecates require_js).
Whether this page is cacheable.
The name of the form element to be focussed on page load.
The Moodle Docs link for this page.

Things for backwards compatibility with print_header

Any <meta> tags that should be added to the output.
HTML code for the top right of the navbar 'Update this forum' button, etc.
Old $menu print_header argument.
Old $usexml argument (do we still need this?)

As far as I can see, there is no need for different subclasses of this class.

This class will probably have very little code, it will just be information storage. We will probably hide all the data behind getters and setters. (That lets us do developer debug output if, for example, you try to request a CSS file after print_header).

As many as possible of these properties should be initialised automatically, just like $COURSE is now.

The backwards-compatible, deprecated print_header function, will work by setting lots of properties of this class, then calling $HTML->print_header().

Supporting legacy themes

Legacy themes expect lots of stuff in various variable, then to have their header.php included. We should be able to support that by having the default $HTML->print_header() implementation get the information from the page_information class into the right variables, and then include header.html.

However, header.html files in themes should be updated to get the information they need directly from the page_information class.

Replacing pagelib

Hopefully we can make a deprecated $PAGE class implementation that wraps wound this class for backwards compatibility. And if legacy code tries to initialise pagelib, we should be able to intercept that an initialise the new class instead.

Alternatively, this proposal could be seen as simply further enhancing the $PAGE class.

Blocks

Will have to wait until we have an outline plan.

Some ideas (stolen from this proposal)

The page to which a block is added will be identified by (contextid, pagetype). This replaces pageid, which was never well defined. Sometimes it was courseid, but at other times it wasn't.
Remove any hard coded references to block going on either the 'left' or 'right', perhaps let themes control the list of possible places. (Mark Nielsen has a counter proposal that instead course formats should control this.)

OK, here is a more fully fleshed out blocks proposal. I'm putting it on a separate page, because it is possibly over the top, and may need to be scaled back before it is made part of this more sensible plan.

More power to themes

Let themes have their own languages packs, as most other plugins can. So if you do get_string('somestring', 'theme_mytheme'), and if that string is not found in lang/en_utf8/theme_mytheme.php (or whichever lang you are using) then have Moodle look in theme/mytheme/lang/en_utf8/theme_mytheme.php.

Let themes have settings.php files to have settings in the admin tree. As part of this, we'll need to reorganise the Appearance part of the admin tree, but that is already overdue, in my opinion. I can never find anything there.

Documentation