MoodleDocs - User contributions [en]

New feature ideas

2011-06-17T21:01:00Z

Neogic: /* What happens next? */ Roadmap link doesn't exist - removed link.

==Where to begin==

Have you any ideas for new features or improvements you'd like included in Moodle? If so, please

# Start by [http://moodle.org/public/search/ searching moodle.org] to check whether someone else has had the same idea. The Moodle community is very large, so it's quite likely you'll find someone else with the same idea as you ;-)
# Either join an existing discussion about your idea or start a new discussion in an appropriate [http://moodle.org/course/view.php?id=5 Using Moodle forum].
# Assuming others agree with your idea, [http://tracker.moodle.org/secure/CreateIssue!default.jspa create a new issue in the Moodle tracker], selecting 'New feature' or 'Improvement' as the issue type. (You'll need to create a tracker account to be able to create a new issue.) Include a link to the discussion thread in the tracker issue.
# Post the tracker issue number in the discussion thread, so that others can watch / comment / vote for it to be implemented.

==What happens next?==

# The [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10512 list of most voted-for new features] is regularly reviewed by Moodle HQ and other core developers.
# Promising ideas are added to the Roadmap (depending on funding availability) and/or to the list of [[Projects for new developers]].
# Small feature ideas and improvements may be added to core by the component maintainer (see [[Credits]] for the list of component maintainers).

==How to maximize the chance of your idea being implemented==

Ideas with lots of votes are more likely to be implemented, however votes are not the only deciding factor.

The M in Moodle stands for modular, and so the easiest ideas for new developers to implement are new modules and plugins, such as course formats (e.g. GSOC 2006 project [[Student projects/AJAX course format|AJAX course format]]), question types (e.g. GSOC 2007 project [[Student projects/New question types|New question types]]) or gradebook reports (e.g. GSOC 2008 project [[Student projects/Animated grade statistics report|Animated grade statistics report]]).

If you're able to provide funding for your idea to be implemented, please submit a ticket at the [http://moodle.com/helpdesk/ Moodle.com helpdesk] or contact a [http://moodle.com/custom/ Moodle Partner specializing in custom development].

If you're a developer and can [[How to create a patch|create a patch]] for your feature idea or improvement, please attach it to the tracker issue for review by the component maintainer.

==See also==

* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program, including a list of GSOC projects from 2006, 2007 and 2008

[[Category:Project]]

Old Events API

2011-06-07T00:58:46Z

Neogic: /* Groups */ more compact and readable params lists

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===Roles===
* role_assigned
** full new record from 'role_assignments' table
* role_unassigned
** record from 'role_assignments', course context only

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record

===Groups===
* groups_member_added
** groupid, userid
* groups_member_removed
** groupid, userid
* groups_group_created
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_updated
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_deleted
** id, courseid, name, description, timecreated, timemodified, picture
* groups_grouping_created
** id, courseid, name, timecreated, timemodified
* groups_grouping_updated
** id, courseid, name, timecreated, timemodified
* groups_grouping_deleted
** id, courseid, name, timecreated, timemodified
* groups_members_removed ''(user deleted from all groups in a course)''
** courseid, userid
* groups_groupings_groups_removed ''(remove all groups from all groupings in a course)''
** courseid (as plain integer, not object)
* groups_groups_deleted ''(delete all groups in a course)''
** courseid (as plain integer, not object)
* groups_groupings_deleted ''(delete all groupings in a course)''
** courseid (as plain integer, not object)

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_processed
* quiz_attempt_started

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2011-06-07T00:51:15Z

Neogic: /* Events wishlist */ note events which may already be available

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===Roles===
* role_assigned
** full new record from 'role_assignments' table
* role_unassigned
** record from 'role_assignments', course context only

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_processed
* quiz_attempt_started

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2011-06-07T00:44:16Z

Neogic: /* Events which exist */ added missing events (found in v2.0.2 code)

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===Roles===
* role_assigned
** full new record from 'role_assignments' table
* role_unassigned
** record from 'role_assignments', course context only

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_processed
* quiz_attempt_started

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed
* module_removed
* grade_update
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2011-06-07T00:31:16Z

Neogic: /* Courses */ add missing event

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled - ''params TBC''
* user_logout - ''params TBC''
* user_unenrol_modified - ''params TBC''
* user_unenrolled - ''params TBC''

===Roles===
* role_assigned (full new record from 'role_assignments' table)
* role_unassigned (record from 'role_assignments', course context only)

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed
* module_removed
* grade_update
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2011-06-07T00:28:20Z

Neogic: /* Users */

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled - ''params TBC''
* user_logout - ''params TBC''
* user_unenrol_modified - ''params TBC''
* user_unenrolled - ''params TBC''

===Roles===
* role_assigned (full new record from 'role_assignments' table)
* role_unassigned (record from 'role_assignments', course context only)

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed
* module_removed
* grade_update
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Old Events API

2011-06-07T00:24:58Z

Neogic: /* Users */ add missing v2 events

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

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

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

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

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

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.

function message_send_handler($eventdata) {
// handle event
// ...
return true;
}

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

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

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled (new in v2 - params TBC)
* user_logout (new in v2 - params TBC)
* user_unenrol_modified (new in v2 - params TBC)
* user_unenrolled (new in v2 - params TBC)

===Roles===
* role_assigned (full new record from 'role_assignments' table)
* role_unassigned (record from 'role_assignments', course context only)

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed
* module_removed
* grade_update
* assignment_submitted
* course completed
* course module completion state changed (completed / not completed)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]

Talk:Old Events API

2011-06-07T00:19:08Z

Neogic: Created page with "* Gah! Already updated the "Events which exist" list a few weeks ago, but my changes appear to have been lost (and don't appear in the history). Was the page reset during the Moo..."

* Gah! Already updated the "Events which exist" list a few weeks ago, but my changes appear to have been lost (and don't appear in the history). Was the page reset during the MoodleDocs maintenance?
* Any how .. here's complete list of events (with raw-ish params used in code) triggered by v2.0.2, according to a code search for "trigger_event": 
** assessable_file_uploaded - $eventdata
** assessable_files_done - $eventdata
** cohort_added - $cohort
** cohort_deleted - $cohort
** cohort_member_added - {$cohortid, $userid}
** cohort_member_removed - {$cohortid, $userid}
** cohort_updated - $cohort
** course_category_deleted - $category
** course_content_removed - $course
** course_created - $course
** course_deleted - $course
** course_updated - $course
** groups_group_created - $group
** groups_group_deleted - $group
** groups_group_updated - $group
** groups_grouping_created - $data
** groups_grouping_deleted - $grouping
** groups_grouping_updated - $data
** groups_groupings_deleted - $courseid
** groups_groupings_groups_removed - $courseid
** groups_groups_deleted - $courseid
** groups_member_added - $eventdata
** groups_member_removed - $eventdata
** groups_members_removed - $eventdata
** mod_created - $eventdata
** mod_deleted - $eventdata
** mod_updated - $eventdata
** portfolio_send - $this->id
** quiz_attempt_processed - $eventdata
** quiz_attempt_started - $eventdata
** role_assigned - $ra
** role_unassigned - $ra
** user_created - $user
** user_deleted - $user
** user_enrolled - $ue
** user_logout - $params
** user_unenrol_modified - $ue
** user_unenrolled - $ue
** user_updated - $user

--[[User:B Johnson|B Johnson]] 08:19, 7 June 2011 (WST)