-

Note: You are currently viewing documentation for Moodle 3.10. Up-to-date documentation for the latest stable version of Moodle may be available here: Events API.

Development:Events API: Difference between revisions

From MoodleDocs
No edit summary
No edit summary
Line 51: Line 51:
==Standards for naming events==
==Standards for naming events==


All event names should follow a consistent naming pattern, such as ...
All event names should follow a consistent naming pattern, such as modulename_noun_verb
 


==Database structure==
==Database structure==


There are 2 core tables for events
There are 2 core tables for events.
 
===events_handlers===


===event table===
This table is for storing which components requests what type of event, and the location of the responsible handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called event time an 'grade_added' event is triggered by a module.
This table is for storing which components requests what type of event, and the location of the responsible handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called event time an 'grade_added' event is triggered by a module.


Line 64: Line 66:
  component - e.g. moodle, mod/forum, block/rss_client
  component - e.g. moodle, mod/forum, block/rss_client
  file - path to the file of the function, eg /grade/export/lib.php
  file - path to the file of the function, eg /grade/export/lib.php
  function - serialized object of the function name, could be a string or an array
  function - serialized string or array describing function, suitable to be passed to '''call_user_func()'''


===event queue===
===events_queue===


The event queue table should put all responding events into the queue. For example, an event triggered by grade book 'grade_updated' can result in the response of all modules. Each response should be either queued or processed instantly. If an "instant" event is not processed successfully it is then queued. So a 'grade_updated' event would insert multiple records into the event_queue table.
The event queue table should put all responding events into the queue. For example, an event triggered by grade book 'grade_updated' can result in the response of all modules. Each response should be either queued or processed instantly. If an "instant" event is not processed successfully it is then queued. So a 'grade_updated' event could insert multiple records into the event_queue table.  The status field counts failures - if the failures reach some high number then some action should be taken (alert the admin etc).


  id - auto increment identifier
  id - auto increment identifier
  updated - time stamp of thelast attempt to run this from the queue
  eventid - foreign key id corresponding to the id of the event table
event - foreign key id corresponding to the id of the event table
  eventdata - serialized version of the data object passed to the event handler.
  eventdata - serialized object of the data passed into the event handlers.
  schedule - 'cron' or 'instant'.  
  type - 'cron' or 'instant'.  
  status - number of failed attempts to process this handler
  status - number of failed attempts
timeupdated - time stamp of the last attempt to run this from the queue


== See also ==
== See also ==

Revision as of 13:11, 12 April 2007

The Events API is a new core system in Moodle to allow better communication between modules. It's based on modules triggering new events with attached data, and the other modules handling those events with custom functions.

Overview

We'll be using the example of a grade being posted from a module into the new gradebook in Moodle 1.9, but there are obviously all kinds of events possible.

Triggering an event

Whenever a grade is created or changed by a module, it should “tell” the system about it (in addition to any local working storage it uses). So, using the quiz as an example, we first define an object as follows:

$eventdata = new object;
$eventdata->courseid = $course->id;
$eventdata->itemname = $quiz->name;
$eventdata->itemtype = 'mod';
$eventdata->itemmodule = 'quiz';
$eventdata->iteminstance = $quiz->id;
$eventdata->itemnumber = 1;
$eventdata->iteminfo = $quiz->info;
$eventdata->idnumber = $cm->idnumber;   // new field in 1.9
$eventdata->grademax = $quiz->grade;
$eventdata->grademin = 0;
$eventdata->userid = $USER->id;
$eventdata->gradevalue = $currentvalue;

Then we post the object as an event and forget about it:

trigger_event('grade_added', $eventdata);


Handling an event

Modules can define an events.php in their db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For example, an export plugin could register something like:

$events = array (
   'grade_added' => array (
        'file'        => '/grade/export/banner/lib.php',
        'function'  => 'banner_handle_grade',    // argument to call_user_func(), could be an array
        'timing'    => 'cron'
    );
);

These are parsed during install / upgrade and stored in a simple database table.

Then, when a grade_added event happens, all the registered functions for that event will be called something like this (but with more error handling):

         include_once($CFG->dirroot.$events['grade_added']['file'];
         call_user_func($events['grade_added']['function'], $eventdata);

All plugins in Moodle have access to this and can this easily “hook in” to 'grade_added' events (and of course any other events).

Standards for naming events

All event names should follow a consistent naming pattern, such as modulename_noun_verb


Database structure

There are 2 core tables for events.

events_handlers

This table is for storing which components requests what type of event, and the location of the responsible handlers. For example, the grade book can register 'grade_added' event with a function add_grade() that should be called event time an 'grade_added' event is triggered by a module.

id - auto increment identifier
event - name of the event, e.g. 'grade_added'
component - e.g. moodle, mod/forum, block/rss_client
file - path to the file of the function, eg /grade/export/lib.php
function - serialized string or array describing function, suitable to be passed to call_user_func()

events_queue

The event queue table should put all responding events into the queue. For example, an event triggered by grade book 'grade_updated' can result in the response of all modules. Each response should be either queued or processed instantly. If an "instant" event is not processed successfully it is then queued. So a 'grade_updated' event could insert multiple records into the event_queue table. The status field counts failures - if the failures reach some high number then some action should be taken (alert the admin etc).

id - auto increment identifier
eventid - foreign key id corresponding to the id of the event table
eventdata - serialized version of the data object passed to the event handler.
schedule - 'cron' or 'instant'. 
status - number of failed attempts to process this handler
timeupdated - time stamp of the last attempt to run this from the queue

See also