Calendar API - Revision history

Devdocsbot: Protected "Calendar API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-09-22T14:00:55Z

Protected "Calendar API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 14:00, 22 September 2022
(No difference)

Devdocsbot: Update migration status and path

2022-09-22T13:58:29Z

Update migration status and path

← Older revision		Revision as of 13:58, 22 September 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/core/calendar/}}
	{{ Moodle 3.3 }}		{{ Moodle 3.3 }}

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:32:58Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"
Show changes



Mudrd8mz: Text replacement - "" to ""

2021-07-14T13:03:04Z
Text replacement - "<code>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:03, 14 July 2021
				
Line 218:
Line 218:
} }
</syntaxhighlight><br /> </syntaxhighlight><br />
The variables to pass to <code>create_instance()</syntaxhighlight> are - The variables to pass to <syntaxhighlight lang="php">create_instance()</syntaxhighlight> are -



# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz'). # $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').



Mudrd8mz: Text replacement - "" to ""
2021-07-14T13:02:25Z
Text replacement - "</code>" to "</syntaxhighlight>"

				
				
				
				
				
				← Older revision
				Revision as of 13:02, 14 July 2021
				
Line 33:
Line 33:



calendar_event::create($event); calendar_event::create($event);
</code> </syntaxhighlight>



==Updating an event== ==Updating an event==
Line 44:
Line 44:
$data = $mform->get_data(); $data = $mform->get_data();
$event->update($data); $event->update($data);
</code> </syntaxhighlight>



==Deleting an event== ==Deleting an event==
Line 53:
Line 53:
$event = calendar_event::load($eventid); $event = calendar_event::load($eventid);
$event->delete($repeats); $event->delete($repeats);
</code> </syntaxhighlight>



==Event priority== ==Event priority==
Line 62:
Line 62:
<code php> <code php>
$event->priority = null; $event->priority = null;
</code> </syntaxhighlight>
* 0 for user override events. * 0 for user override events.
<code php> <code php>
$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY; $event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;
</code> </syntaxhighlight>
* A positive integer for group events. * A positive integer for group events.



Line 79:
Line 79:
     ...      ...
] ]
</code> </syntaxhighlight>
where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below: where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below:
<code php> <code php>
Line 133:
Line 133:
     ];      ];
} }
</code> </syntaxhighlight>



==Action events== ==Action events==
Line 144:
Line 144:
$event->type = CALENDAR_EVENT_TYPE_ACTION; $event->type = CALENDAR_EVENT_TYPE_ACTION;
$event->timesort = $scorm->timeclose; $event->timesort = $scorm->timeclose;
</code> </syntaxhighlight>



[[File:my overview sam student.png]] [[File:my overview sam student.png]]
Line 182:
Line 182:
     }      }
} }
</code> </syntaxhighlight>



====mod_xyz_core_calendar_provide_event_action()==== ====mod_xyz_core_calendar_provide_event_action()====
Line 217:
Line 217:
     );      );
} }
</code><br /> </syntaxhighlight><br />
The variables to pass to <code>create_instance()</code> are - The variables to pass to <code>create_instance()</syntaxhighlight> are -



# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz'). # $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').
Line 247:
Line 247:
     return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;      return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;
} }
</code> </syntaxhighlight>



==Refreshing calendar events of activity modules== ==Refreshing calendar events of activity modules==
Line 265:
Line 265:
// Queue it. // Queue it.
\core\task\manager::queue_adhoc_task($refreshtask); \core\task\manager::queue_adhoc_task($refreshtask);
</code> </syntaxhighlight>



==calendar_get_legacy_events()== ==calendar_get_legacy_events()==
Line 348:
Line 348:
     }      }
} }
</code> </syntaxhighlight>



====core_calendar_get_valid_event_timestart_range==== ====core_calendar_get_valid_event_timestart_range====
Line 363:
Line 363:
      [1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.       [1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.
] ]
</code> </syntaxhighlight>



If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example: If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example:
<code php> <code php>
[null, null] // No limits. [null, null] // No limits.
</code><br /> </syntaxhighlight><br />
  <code php>   <code php>
[null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff. [null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff.
</code><br /> </syntaxhighlight><br />
<code php> <code php>
[[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff. [[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff.
</code> </syntaxhighlight>



If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz). If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz).
Line 406:
Line 406:
     return [$mindate, $maxdate];      return [$mindate, $maxdate];
} }
</code> </syntaxhighlight>



==Component events== ==Component events==
Line 438:
Line 438:
$event->categoryid = 0; $event->categoryid = 0;
$event->userid = $userid; $event->userid = $userid;
</code> </syntaxhighlight>



If this is an action event, see the "Action events" section above for supported callbacks. Note that currently category-level action events are not displayed on the timeline (but they will be displayed in the calendar). Timeline only displays the site-wide events, user events and events in the courses where user is enrolled. If this is an action event, see the "Action events" section above for supported callbacks. Note that currently category-level action events are not displayed on the timeline (but they will be displayed in the calendar). Timeline only displays the site-wide events, user events and events in the courses where user is enrolled.
Line 450:
Line 450:
<code php> <code php>
$string['myeventtype'] = 'My event type'; $string['myeventtype'] = 'My event type';
</code> </syntaxhighlight>



Mudrd8mz: /* Component events */ MDL-58866 Copied the initial docs from Marina's comment
2020-06-18T09:14:53Z
Component events:  MDL-58866 Copied the initial docs from Marina's comment

				
				
				
				
				
				← Older revision
				Revision as of 09:14, 18 June 2020
				
Line 410:
Line 410:
==Component events== ==Component events==



From Moodle 3.9 plugins other than activity modules can create calendar events.   Starting from Moodle 3.9 plugins other than activity modules can create calendar events, too.  These can be site-level, course category-level, course-level or user events. Events can be standard or action events.



TBC Example of creating an event:
 
<code php>
$event->component = 'tool_yourtool';
$event->modulename = '';
$event->eventtype = 'myeventtype';
$event->instance = $instanceid; // Whatever instance you want.
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // Or: $event->type = CALENDAR_EVENT_TYPE_ACTION;
// ... Other properties, see section "Create event" above.
 
// For site events:
$event->courseid = SITEID;
$event->categoryid = 0;
 
// For category events:
$event->categoryid = $categoryid;
$event->courseid = 0;
 
// For course events:
$event->courseid = $courseid;
$event->categoryid = 0;
 
// For user events:
$event->courseid = 0;
$event->categoryid = 0;
$event->userid = $userid;
</code>
 
If this is an action event, see the "Action events" section above for supported callbacks. Note that currently category-level action events are not displayed on the timeline (but they will be displayed in the calendar). Timeline only displays the site-wide events, user events and events in the courses where user is enrolled.
 
Events created by the plugins can not be edited or deleted by users in the calendar. Drag&drop is currently not supported for component events.
 
To change the icon of the event, add the file pix/myeventtype.svg to your plugin. You can add font-awesome mapping in <pluginname>_get_fontawesome_icon_map() callback.
 
To change the alt text for the icon add to the language file:
 
<code php>
$string['myeventtype'] = 'My event type';
</code>



Mudrd8mz: /* Creating an event */ MDL-68645 Do not apply filters when passing the module description as the new calendar event's description
2020-05-19T21:54:39Z
Creating an event:  MDL-68645 Do not apply filters when passing the module description as the new calendar event's description

				
				
				
				
				
				← Older revision
				Revision as of 21:54, 19 May 2020
				
Line 21:
Line 21:
$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->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->name = get_string('calendarstart', 'scorm', $scorm->name);
$event->description = format_module_intro('scorm', $scorm, $cmid); $event->description = format_module_intro('scorm', $scorm, $cmid, false);
$event->format = FORMAT_HTML;
$event->courseid = $scorm->course; $event->courseid = $scorm->course;
$event->groupid = 0; $event->groupid = 0;



Marina.glancy at 07:44, 4 May 2020
2020-05-04T07:44:11Z


				
				
				
				
				
				← Older revision
				Revision as of 07:44, 4 May 2020
				
Line 406:
Line 406:
} }
</code> </code>

==Component events==

From Moodle 3.9 plugins other than activity modules can create calendar events. 

TBC



Nmagill: Clarify the use of $checkcapability parameter in event creation and updating
2018-08-24T08:55:57Z
Clarify the use of $checkcapability parameter in event creation and updating

				
				
				
				
				
				← Older revision
				Revision as of 08:55, 24 August 2018
				
Line 12:
Line 12:



==Creating an event== ==Creating an event==
Creating a new calendar event.   Creating a new calendar event. The optional parameter $checkcapability is used to check user's capability to add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be created, for example when an activity is creating an event based on a deadline.



<code php> <code php>
Line 35:
Line 35:



==Updating an 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.  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 yet. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be updated, for example when an activity is updating an event based on a change to it's settings.



<code php> <code php>



Ryanwyllie at 02:34, 14 November 2017
2017-11-14T02:34:13Z

Show changes

← Older revision		Revision as of 13:03, 14 July 2021
Line 218:		Line 218:
	}		}
	</syntaxhighlight><br />		</syntaxhighlight><br />
	The variables to pass to <~~code~~>create_instance()</syntaxhighlight> are -		The variables to pass to <syntaxhighlight lang="php">create_instance()</syntaxhighlight> are -

	# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').		# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').

← Older revision		Revision as of 13:02, 14 July 2021
Line 33:		Line 33:

	calendar_event::create($event);		calendar_event::create($event);
	</~~code~~>		</syntaxhighlight>

	==Updating an event==		==Updating an event==
Line 44:		Line 44:
	$data = $mform->get_data();		$data = $mform->get_data();
	$event->update($data);		$event->update($data);
	</~~code~~>		</syntaxhighlight>

	==Deleting an event==		==Deleting an event==
Line 53:		Line 53:
	$event = calendar_event::load($eventid);		$event = calendar_event::load($eventid);
	$event->delete($repeats);		$event->delete($repeats);
	</~~code~~>		</syntaxhighlight>

	==Event priority==		==Event priority==
Line 62:		Line 62:
	<code php>		<code php>
	$event->priority = null;		$event->priority = null;
	</~~code~~>		</syntaxhighlight>
	* 0 for user override events.		* 0 for user override events.
	<code php>		<code php>
	$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;		$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;
	</~~code~~>		</syntaxhighlight>
	* A positive integer for group events.		* A positive integer for group events.

Line 79:		Line 79:
	...		...
	]		]
	</~~code~~>		</syntaxhighlight>
	where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below:		where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below:
	<code php>		<code php>
Line 133:		Line 133:
	];		];
	}		}
	</~~code~~>		</syntaxhighlight>

	==Action events==		==Action events==
Line 144:		Line 144:
	$event->type = CALENDAR_EVENT_TYPE_ACTION;		$event->type = CALENDAR_EVENT_TYPE_ACTION;
	$event->timesort = $scorm->timeclose;		$event->timesort = $scorm->timeclose;
	</~~code~~>		</syntaxhighlight>

	[[File:my overview sam student.png]]		[[File:my overview sam student.png]]
Line 182:		Line 182:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	====mod_xyz_core_calendar_provide_event_action()====		====mod_xyz_core_calendar_provide_event_action()====
Line 217:		Line 217:
	);		);
	}		}
	</~~code~~><br />		</syntaxhighlight><br />
	The variables to pass to <code>create_instance()</~~code~~> are -		The variables to pass to <code>create_instance()</syntaxhighlight> are -

	# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').		# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').
Line 247:		Line 247:
	return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;		return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;
	}		}
	</~~code~~>		</syntaxhighlight>

	==Refreshing calendar events of activity modules==		==Refreshing calendar events of activity modules==
Line 265:		Line 265:
	// Queue it.		// Queue it.
	\core\task\manager::queue_adhoc_task($refreshtask);		\core\task\manager::queue_adhoc_task($refreshtask);
	</~~code~~>		</syntaxhighlight>

	==calendar_get_legacy_events()==		==calendar_get_legacy_events()==
Line 348:		Line 348:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	====core_calendar_get_valid_event_timestart_range====		====core_calendar_get_valid_event_timestart_range====
Line 363:		Line 363:
	[1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.		[1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.
	]		]
	</~~code~~>		</syntaxhighlight>

	If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example:		If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example:
	<code php>		<code php>
	[null, null] // No limits.		[null, null] // No limits.
	</~~code~~><br />		</syntaxhighlight><br />
	<code php>		<code php>
	[null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff.		[null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff.
	</~~code~~><br />		</syntaxhighlight><br />
	<code php>		<code php>
	[[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff.		[[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff.
	</~~code~~>		</syntaxhighlight>

	If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz).		If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz).
Line 406:		Line 406:
	return [$mindate, $maxdate];		return [$mindate, $maxdate];
	}		}
	</~~code~~>		</syntaxhighlight>

	==Component events==		==Component events==
Line 438:		Line 438:
	$event->categoryid = 0;		$event->categoryid = 0;
	$event->userid = $userid;		$event->userid = $userid;
	</~~code~~>		</syntaxhighlight>

	If this is an action event, see the "Action events" section above for supported callbacks. Note that currently category-level action events are not displayed on the timeline (but they will be displayed in the calendar). Timeline only displays the site-wide events, user events and events in the courses where user is enrolled.		If this is an action event, see the "Action events" section above for supported callbacks. Note that currently category-level action events are not displayed on the timeline (but they will be displayed in the calendar). Timeline only displays the site-wide events, user events and events in the courses where user is enrolled.
Line 450:		Line 450:
	<code php>		<code php>
	$string['myeventtype'] = 'My event type';		$string['myeventtype'] = 'My event type';
	</~~code~~>		</syntaxhighlight>

← Older revision		Revision as of 21:54, 19 May 2020
Line 21:		Line 21:
	$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->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->name = get_string('calendarstart', 'scorm', $scorm->name);
	$event->description = format_module_intro('scorm', $scorm, $cmid);		$event->description = format_module_intro('scorm', $scorm, $cmid, false);
			$event->format = FORMAT_HTML;
	$event->courseid = $scorm->course;		$event->courseid = $scorm->course;
	$event->groupid = 0;		$event->groupid = 0;

← Older revision		Revision as of 07:44, 4 May 2020
Line 406:		Line 406:
	}		}
	</code>		</code>

			==Component events==

			From Moodle 3.9 plugins other than activity modules can create calendar events.

			TBC

← Older revision		Revision as of 08:55, 24 August 2018
Line 12:		Line 12:

	==Creating an event==		==Creating an event==
	Creating a new calendar event.		Creating a new calendar event. The optional parameter $checkcapability is used to check user's capability to add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be created, for example when an activity is creating an event based on a deadline.

	<code php>		<code php>
Line 35:		Line 35:

	==Updating an 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.		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 yet. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true. You should set it to false if you have already checked that the user has the capabilities required for the event to be updated, for example when an activity is updating an event based on a change to it's settings.

	<code php>		<code php>