Activity completion API

Moodle 2.0

Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

If you make no changes to a module whatsoever, it can only support 'manual' completion (where the user ticks a box).

Feature support

To support the completion system, your module must include a modulename_supports function in its lib.php. Here is an example:

/**
 * Indicates API features that the forum supports.
 *
 * @param string $feature
 * @return mixed True if yes (some features may use other values)
 */
function forum_supports($feature) {
    switch($feature) {
        case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
        case FEATURE_COMPLETION_HAS_RULES: return true;
        default: return null;
    }
}

The relevant features for completion are:

• FEATURE_COMPLETION_TRACKS_VIEWS - the module can support completion 'on view', meaning that an activity becomes marked complete as soon as a user clicks on it.

• FEATURE_GRADE_HAS_GRADE - the module provides (or may provide, depending on settings) a grade for students. When a module supports grades, it can support completion 'on grade', meaning that an activity becomes marked complete as soon as a user is assigned a grade.

• FEATURE_COMPLETION_HAS_RULES - the module has custom completion rules.

Completion on view

Completion on view means that, if selected, an activity is marked complete as soon as the user views it. 'View' is usually defined as seeing the module's main page; if you click on the activity, and there isn't an error, you have probably viewed it. However it is up to each module precisely how they define 'view'.

How to implement

In your module's _supports function, return true for FEATURE_COMPLETION_TRACKS_VIEWS.

Then add this code to run whenever a user successfully views the activity (for example, near the print_footer() call in view.php):

$completion=new completion_info($course);
$completion->set_module_viewed($cm);

Performance issues

Calling this method has no significant performance cost if 'on view' completion is not enabled for the activity. If it is enabled, then the performance cost is kept low because the 'viewed' state is cached; it doesn't add a database query to every request.

Completion on grade

Completion on grade means that, if selected, an activity is marked complete as soon as the user receives a grade from that activity.

How to implement

In your module's _supports function, return true for FEATURE_GRADE_HAS_GRADE. No other action is necessary.

Performance issues

When 'on grade' completion is enabled, there will be some additional database queries after a grade is assigned or changed. Unless your activity changes grades very frequently, this is unlikely to be an issue.

Custom completion rules

Custom completion rules allow for module-specific conditions. For example, the forum has custom rules so that you can make it mark a user completed when they make a certain number of posts to the forum.

It is a lot harder to implement custom completion rules than it is to use the system-provided 'view' or 'grade' conditions, but the instructions below should help make it clear.

How to implement

To implement custom completion rules, you need to:

1. Return true for FEATURE_COMPLETION_HAS_RULES in your module's _supports function.
2. Add database fields to your module's main table to store the custom completion settings.
3. Add controls to your module's settings form so that users can select the custom rules, altering these database settings.
4. Add a function that checks the value of these rules (if set).
5. Add code so that whenever the value affecting a rule might change, you inform the completion system.