Development:Module visibility and display

(This document is a draft proposal.)

Summary

We would like to create a generic API that allows the following:

• Module display on front page can be customised, for example making it possible to create another module that behaves like Label (displaying arbitrary html rather than a link to activity view.php) - currently this is hardcoded hack for Label. This change should apply to other areas such as navigation block as well as course page.

• Some modules can provide dynamic text, such as forum displaying unread messages. At present this is hardcoded so that only forum can do it.

• Modules can be hidden completely, or greyed out, from the view of particular students according to either custom module behaviour, or (if not specified by module) default behaviour regarding a new capability moodle/course:viewactivity and the existing option for whether a non-available module is greyed out or hidden entirely.

This should take advantage of the existing modinfo cache (maybe with slight changes) in order that performance is not adversely affected.

Removing existing hacks

• Existing hacks regarding label in all areas of code (e.g. navigation, etc) will be changed from the logic 'is this a label?' to the logic 'does this activity have a url?' (and label will be changed to work with this)
• Existing hacks regarding forum unread data will be removed and the forum unread code will be moved into the new API function. The code will be written in such a way as to have the same performance characteristics.

get_fast_modinfo change

The get_fast_modinfo function will be changed to:

• support new values in _get_coursemodule_info

• extend dynamic per-user calculation (that checks is something is visible to current user, ->uservisible) with additional checks

• call the new module API (if provided) after calculating modinfo, to get dynamic information

Modify _get_coursemodule_info

There will be a change to the existing module API function _get_coursemodule_info. This change will retain backward compatibility. I wrote documentation for the new function below; in that documentation, the # marker indicates a changed or new entry, other stuff is existing.

In get_fast_modinfo, the system can automatically turn the ->nolink option into a ->url which will either be a moodle_url or null (this avoids duplicate code working out the url mod/whatever/view.php?id=whatever in a zillion places). Possibly we could also allow ->url to be specified directly but this won't be supported everywhere, at least to start with.

PERFORMANCE CONCERNS: None. No changes would be made to existing modules except label, and that one doesn't add a database query. Anyway, this data is cached.

_get_coursemodule_info

This optional function returns additional information about an instance of your module, which can be accessed quickly when displaying the module.

You should return an object $info which may contain the following fields, all of which are optional:

• ->nolink #: set true if the module does not need a link.
• ->name: name of instance (text displayed in link on course page) - this will not be used if nolink is true.
• ->content #: HTML content to be displayed on the course page where this module is placed; appears below the link, if present (this is how Label displays content on course page)
• ->extraclasses #: Additional CSS classes to be added to the A or DIV tag(s) for this item on main course page.
• ->icon: specifies an icon to use for this instance instead of the normal module icon; you can either use the name of an icon which will be directly passed to the $OUTPUT->pix_icon function, or the special format mod/mymodule/iconname which will be passed to that function as two parameters iconname, mymodule.
• ->customdata #: A place to store a string or object containing custom data for this module, which needs to be available course-wide via the get_fast_modinfo function. If present, this data should be small in size.
• ->afterlink #: If specified, includes HTML code which displays after the link. This is normally not set by this function, but rather in _get_dynamic_coursemodule_info to display things like forum unread status.
• ->editicons #: If specified, includes HTML code which displays as part of the editing icons (hide, edit, delete, etc). This is normally not set by this function, but rather in _get_dynamic_coursemodule_info in case the module has a specific feature that is needed on home page.

• ->extra (deprecated in 2.1): puts content in a weird part of the A or DIV tag for the item; can be used to add attributes
• ->iconcomponent (deprecated in 2.1): doesn't appear to do anything?!

Extend dynamic calculation

Currently the modinfo code makes the following checks that apply dynamically per-request (and do not directly come from the cache) in order to create the ->uservisible member variable.

• If ->groupmembersonly is set, checks if the user belongs to group or has accessallgroups.
• If availability restrictions (date, grade, completion) are set, checks these.

My proposal is:

• Make this part of the code (that 'specialises' a single mod value for the current user/request) into a separate function, just to simplify it.
• Add a check for the moodle/course:viewactivity capability; if user doesn't have this capability, set ->uservisible to false. Also check the option about what to do with hidden activities; if this is set to the default 'grey it out', then set ->inactive to true.
  • Note: The default value for moodle/course:viewactivity should be true for all roles, even guest. This maintains existing behaviour. Sites that don't want guests to view activities can change the main role definition for guest.
• Call the _get_dynamic_coursemodule_info function (below) if the current module supplies one.

PERFORMANCE CONCERNS: Minimal. No new database queries are required.

New module API

A new module API function _get_dynamic_coursemodule_info will be defined. As parameters, this takes:

• the contents of modinfo for this module (which will include data from get_coursemodule_info).
• an optional userid (default 0 = current user).

When it returns, this returns a new version of modinfo that has been customised for the current user. This could include setting ->uservisible=false (to hide the activity entirely) or ->inactive to true (to grey it out) or ->afterlink = '16 unread' (to display dynamic data) or ->editicons (to add a custom editing icon for this module).

PERFORMANCE CONCERNS: None. Of standard modules, only the forum will implement this and it will use the same code as at present. Custom modules will need to be written carefully in a similar manner so that they also perform well (ie do any queries once for whole course and store in global cache, not once per module).