Calendar API

Moodle 3.3

This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see Calendar_API_old.

The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.

Overview

The Moodle Calendar collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.

The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.

Creating an event

Creating a new calendar event.

require_once($CFG->dirroot.'/calendar/lib.php');

$event = new stdClass(); $event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event. $event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview. $event->name = get_string('calendarstart', 'scorm', $scorm->name); $event->description = format_module_intro('scorm', $scorm, $cmid); $event->courseid = $scorm->course; $event->groupid = 0; $event->userid = 0; $event->modulename = 'scorm'; $event->instance = $scorm->id; $event->timestart = $scorm->timeopen; $event->timesort = $scorm->timeopen; $event->visible = instance_is_visible('scorm', $scorm); $event->timeduration = 0;

calendar_event::create($event);

Updating an event

You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true.

$eventid = required_param('id', PARAM_INT); $event = calendar_event::load($eventid);

$data = $mform->get_data(); $event->update($data);

Deleting an event

You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.

$eventid = required_param('id', PARAM_INT); $event = calendar_event::load($eventid); $event->delete($repeats);

Action events

Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION.

The callbacks

mod_xyz_core_calendar_is_event_visible(calendar_event $event)

This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.

mod_xyz_core_calendar_core_calendar_provide_event_action(calendar_event $event, \core_calendar\action_factory $factory)

This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown. This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.

Eg. function mod_scorm_core_calendar_provide_event_action(calendar_event $event,

       \core_calendar\action_factory $factory) {
   global $CFG;

   require_once($CFG->dirroot . '/mod/scorm/locallib.php');

   $cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];

   if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {
       // The scorm has closed so the user can no longer submit anything.
       return null;
   }

   // Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.
   $customdata = $cm->customdata ?: [];
   $customdata['id'] = $cm->instance;
   $scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);

   // Check that the SCORM activity is open.
   list($actionable, $warnings) = scorm_get_availability_status($scorm);

   return $factory->create_instance(
       get_string('enter', 'scorm'),
       new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),
       1,
       $actionable
   );

}

The variables to pass to create_instance() are -

1. $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').
2. $url \moodle_url The URL the user visits in order to perform this action.
3. $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.
4. $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.

mod_xyz_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0)

This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.