Conditional activities API

Important: This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date. Why not view this page on the new site and help us to migrate more content to the new site!

This page requires updating. Please do so and remove this template when finished.

Overview

Conditional Apis allow you to specify , if to show or hide an activity when the conditions associated with it are met/not met. This should not be confused with completion API which is used to mark if an activity is completed or not. That is conditional API is used to handle the availability of an activity where as completion helps to track the progress of student in an activity.

Files

The main file containing all important conditional stuff is located at lib/conditionlib.php

Functions and Examples

The class condition_info defined in lib/conditionlib.php is the main conditional API in Moodle. Following are some important methods of the above mentioned class.

fill_availability_conditions(&$cm)
get_full_course_module()
add_completion_condition($cmid, $requiredcompletion)
add_grade_condition($gradeitemid, $min, $max, $updateinmemory=false)
wipe_conditions()
get_full_information($modinfo=null)
is_available(&$information, $grabthelot=false, $userid=0, $modinfo=null)
show_availability()
update_cm_from_form($cm, $fromform, $wipefirst=true)

The basic functionality of these methods can be classified as:-

1. Fetching information related to conditions
2. Adding/Updating conditional clauses to activities
3. Deleting conditions attached to activities

Fetching information related to conditions

Following functions are normally used to fetch information regarding conditions associated with activities:-

get_full_course_module();
get_full_information($modinfo=null);
is_available(&$information, $grabthelot=false, $userid=0, $modinfo=null);
show_availability();

get_full_course_module()

This method can fetches and returns all necessary information as a course module object which are required to determine the availability conditions.

Example:-

$cm->id = $id;
$test = new condition_info($cm,CONDITION_MISSING_EVERYTHING);
$fullcm = $test->get_full_course_module();

get_full_information()

This function returns a string which describes the various conditions in place for the activity in the given context.Some possible outputs can be:-

 a) From 13:05 on 14 Oct until 12:10 on 17 Oct (exact, exact)
 b) From 14 Oct until 12:11 on 17 Oct (midnight, exact)
 c) From 13:05 on 14 Oct until 17 Oct (exact, midnight 18 Oct)

Please refer the inline documentation in the code for detailed explanation of the logic and all possible cases.

Example:-

$ci = new condition_info($mod);
$fullinfo = $ci->get_full_information();

is_available()

This function is used to check if a given course module is currently available or not. A thing worth noting is that this doesn't take "visibility settings" and "viewhiddenactivities" capability into account. That is these settings should be properly checked after the result of is_available(), before dumping any data to the user.

Example:-

$ci = new condition_info((object)array('id'=>$cmid),CONDITION_MISSING_EVERYTHING);
$bool = $ci->is_available($text,false,0);

show_availability()

This function is used to check if information regarding availability of the current module should be shown to the user or not.

Example:-

$ci = new condition_info((object)array('id'=>$cmid),CONDITION_MISSING_EVERYTHING);
$bool = $ci->show_availability();

Adding/Updating conditional clauses to activities

fill_availability_conditions(&$cm);
add_completion_condition($cmid, $requiredcompletion);
add_grade_condition($gradeitemid, $min, $max, $updateinmemory=false);
update_cm_from_form($cm, $fromform, $wipefirst=true)

fill_availability_conditions()

This function adds any extra availability conditions to given course module object.

$rawmods = get_course_mods($courseid);
if (empty($rawmods)) {
    die;
}
if ($sections = $DB->get_records("course_sections", array("course"=>$courseid), "section ASC")) {
    foreach ($sections as $section) {
        if (!empty($section->sequence)) {
            $sequence = explode(",", $section->sequence);
                foreach ($sequence as $seq) {
                    if (empty($rawmods[$seq])) {
                        continue;
                    }
                    if (!empty($CFG->enableavailability)) {
                         condition_info::fill_availability_conditions($rawmods[$seq]);
                         //do something
                    }
                }
            }
        }
    }
}

add_completion_condition()

In Moodle availability condition of a Module or activity can depend on another activity. For example activity B will not be unlocked untill activity A is successfully completed. To add such inter-dependent condtions, this funtion is used.

Example:-

$test1=new condition_info((object)array('id'=>$cmid),CONDITION_MISSING_EVERYTHING);
$test1->add_completion_condition(13,3);

add_grade_condition()

This function is used to add a grade related restriction to an activity based on the grade secured in another activity. In the following example a minimum grade of 0.4 is required on gradeitem 666 to unlock the current activity in context.

Example:-

$test1=new condition_info((object)array('id'=>$cmid),CONDITION_MISSING_EVERYTHING);
$test1->add_grade_condition(666,0.4,null,true);

update_cm_from_form()

This function is used to update availability conditions from a user submitted form.

Example:-

$fromform = $mform->get_data();
if (!empty($fromform->update)) {

        if (!empty($course->groupmodeforce) or !isset($fromform->groupmode)) {
            $fromform->groupmode = $cm->groupmode; // keep original
        }

        // update course module first
        $cm->groupmode        = $fromform->groupmode;
        $cm->groupingid       = $fromform->groupingid;
        $cm->groupmembersonly = $fromform->groupmembersonly;

        $completion = new completion_info($course);
        if ($completion->is_enabled()) {
            // Update completion settings
            $cm->completion                = $fromform->completion;
            $cm->completiongradeitemnumber = $fromform->completiongradeitemnumber;
            $cm->completionview            = $fromform->completionview;
            $cm->completionexpected        = $fromform->completionexpected;
        }
        if (!empty($CFG->enableavailability)) {
            $cm->availablefrom             = $fromform->availablefrom;
            $cm->availableuntil            = $fromform->availableuntil;
            $cm->showavailability          = $fromform->showavailability;
            condition_info::update_cm_from_form($cm,$fromform,true);
        }
// Do something else with the data
}

Deleting conditions attached to activities

we have a simple function wipe_conditions() that can erase all conditions associated with the current activity. consider an example:-

$ci = new condition_info($cm, CONDITION_MISSING_EVERYTHING, false);
$ci->wipe_conditions();

See Also

• Conditional activities Adding module support
• Conditional activities - original specification for this feature.

User documentation

• How to make a new availability condition plugin.
• Conditional Activities
• Conditional Activities Settings
• Using Conditional Activities