Conditional activities API
Overview
Conditional Apis allow you to specify , if to show or hide an activity when the conditions associated with it are met/not met.
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:-
- Fetching information related to conditions
- Adding/Updating conditional clauses to activities
- Deleting conditions attached to activities
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 avaialabilty 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