Ferreteria/v2/usage/events

About

All types of events are (or soon will be) tied to a central table. The idea is that we should be able to arbitrarily add new types of events with their own specialized data by having "sub-tables" which store the additional fields and point back to the base event table for all the basic stuff, instead of having one massive table with every possible field in it (most of which would be empty most of the time).

The base (central) event table and all of the subsidiary tables (see modules/FerretLog) are called the EventPlex.

Event Codes

Rather than try to create a comprehensive index of all existing event code constants, we're going to rigidly follow a format in naming them so they can be easily found:

• All event codes should begin with KS_EVENT_.
• All Ferreteria-defined event codes will begin with KS_EVENT_FERRETERIA_.
• All application-defined event codes should begin with KS_EVENT_<YOUR_APP_PREFIX>_, where <YOUR_APP_PREFIX> uniquely identifies your application or extension.

Creating Events

All events start with a base event record, which you create like this:

$idEvent = fcApp::Me()->CreateEvent($sCode,$sText,$arData);

• $sCode is a Ferreteria-defined or application-defined event-type code
• $sText is a human-readable of what happened
• $sData (optional) is an array of any event-related values you want to store; it will be serialized

Using $idEvent as an argument, you can then tag sub-events onto that base event (as many types as you like, but only one event per type).

Event Done

These are used to record that an event which was initiated has now completed. You create the base event (see above) before starting, then do this on completion:

fcApp::Me()->EventTable_Done()->CreateRecord($idEvent,$sState,$sText)

• $idEvent is the return value from the base CreateEvent() method
• $sState is an application-defined status code. These are named the same as the codes used in the base event, i.e. the constants begin with "KS_EVENT_"

Event in Table

to be documented