|
|
| (53 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| (This document is a draft proposal.)
| | {{Template:Migrated|newDocId=/docs/apis/plugintypes/mod/visibility}} |
| | |
| == 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.
| |
| * Change the 'restriction information' code so that it adds restriction information (this is things like 'Not available until 30 December 2010') into a ->restrictions member of modinfo
| |
| * 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).
| |
| | |
| NOTE: Maybe this function also needs access to the rest of $modinfo? But it hasn't all been completely filled in because this function obviously hasn't run... still we could provide it if required...
| |
