Callbacks: Difference between revisions

Revision as of 06:58, 19 May 2017

Moodle does not have well-defined Hooks API but still allows plugins to hook into different processes by implementing callbacks.

Some old APIs that were created before object-oriented programming use only callbacks. One of them is [Activity modules].

Types of callbacks in Moodle

Callback functions one-to-many

Core or specific plugin has a "hook point" where it allows plugins to execute some code, modify variables or return a result. Sometimes only plugins of a specific plugin type are allowed. If plugins want to implement the function for this callback they normally must place it in lib.php with the name pluginfullname_callbackname(). Here pluginname should be a full plugin name with a prefix, however activity modules can often omit the "mod_" prefix for historical reasons. Implementing this type of callback is optional and the "hook point" does not care how many and which plugins implement callback. Also "hook point" does not check if the plugin is enabled on this site, inside the calback plugins must check it themselves if it is important. Methods get_plugin_list_with_function() and get_plugins_with_function() are normally used in the "hook points" to find all plugins implementing a callback.

This document aims to cover ALL callbacks of this type that are present in Moodle core APIs or in standard Moodle plugins.

Callback functions one-to-one

Core API (or plugins such as blocks or reports) looks for and executes a method from the plugin/component that "owns" some entity, usually for checking permissions, pre-processing or providing the human-readable representation of this entity. Similar to one-to-many callbacks, the component/plugin must define a function with the name pluginfullname_callbackname() in lib.php . In some cases the function must be present or otherwise an exception is thrown or debugging message is displayed. Methods component_callback() and component_callback_exists() are normally used to find an implementation of a callback. Unlike one-to-many callbacks the implementing functions can exist not only in plugins but also in core components.

Other

Files in the specific location. Core APIs may look for plugins that have a file with a specific file name, for example version.php, settings.php, styles.css, module.js, files in db/ folder, etc. See Plugin files
Event observers. Each plugin can implement event observers that execute code when event is triggered. See Events API about how to listen to events. Event observers can not always substitute callbacks because they do not return any value and can only happen in case of event. Many "hook points" are necessary before something has happened or when nothing is happening at all, for example a report/summary is gathered. However if it is possible to achieve the desired outcome with event observer, Moodle will not accept requests for adding a "hook point".
Callbacks that are specified in the db/* file, for example in db/service.php developers must specify callback responsible for implementing web service, in db/tags.php developers specify callback for finding tagged items, etc. These types of callbacks are not covered on this page, information about them can be found in the respective APIs.

List of Moodle callbacks

List of one-to-many callbacks

To implement one of these callbacks plugins must add a function pluginfullname_callbackname() in lib.php unless stated otherwise. The pluginfullname is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the mod_ prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

Callback	Plugin type	Version	Comments
Navigation, see Navigation API
extend_navigation_course	*	3.0+	before Moodle 3.0 was only supported by report and tool plugin types
extend_settings_navigation	local, booktool		Note, modules have a one-to-one callback with the same name, see below
extend_navigation	local		Note, modules have a one-to-one callback with the same name, see below
extend_navigation_user_settings	*	3.0+	before Moodle 3.0 was only supported by tool plugin types
extend_navigation_category_settings	*	3.0+
extend_navigation_frontpage	*	3.1+
extend_navigation_user	*	3.1+
Before-actions hooks
course_module_background_deletion_recommended	*	3.2+	see upgrade.txt
pre_block_delete	*	3.1+
pre_course_category_delete	*	3.1+
pre_course_delete	*	3.1+
pre_course_module_delete	*	3.1+
pre_user_delete	*	3.1+
Page rendering
add_htmlattributes	*	3.3+
before_footer	*	3.3+
before_http_headers	*	3.3+
before_standard_html_head	*	3.3+
before_standard_top_of_body_html	*	3.3+
render_navbar_output	*	3.2+
Course module edit form
coursemodule_edit_post_actions	*	3.1+
coursemodule_standard_elements	*	3.1+
coursemodule_validation	*	3.1+
LTI source
messagetype	ltisource		Callback name is the type of the message
get_shortcuts	ltisource	3.1+
Modules
check_updates_since	mod	3.2+
dndupload_register	mod
Other
get_fontawesome_icon_map	*	3.3+
get_question_bank_search_conditions	local
oauth2_system_scopes	*	3.3+
rss_get_feed	*
supports_logstore	report
Deprecated
cron	*		See Task API
delete_course	mod,report,coursereport,format		Replace with observer to course_contents_deleted event
print_overview	mod	up to 3.2	New dashboard uses Calendar API to populate events on the timeline
report_extend_navigation	coursereport		Plugin type coursereport is deprecated, plugin type report should be used instead

Notes:

if Moodle version is not specified, this means that callback existed for a long time and can be found in all currently supported Moodle versions

List of one-to-one callbacks