Events

Event objects are the part of the Hooks API that arrange sets of actions into coordinated groups that can be presented to the user. Events are an abstract, primarily user-facing feature, as can be seen on the Points Types administration screen.

Each event is represented by a class that extends WordPoints_Hook_Event. Let’s use the class for the user_register event that is included with WordPoints as an example:

As you can see, the event object itself is mainly just responsible for providing human-readable information about the event. Every event has to have a title and description. The title is the human-readable name for an event, while the description can provide additional information about the event.

In the case above, our event can also be reversed, if the user that registered is later deleted. So we also implement the WordPoints_Hook_Event_ReversingI interface, and provide a description of the action that reverses this event via the get_reversal_text() method. This is used by the points reactor to explain to the user why a particular points transaction was reversed (since it reverses points transactions when an event is reversed).

Once you have created your event class, you need to register it with WordPoints:

As you can see, we just hook into the initialization of the events class registry and register our event class with a unique slug. The most interesting part of this is the third parameter that we pass to $events->register() after the event slug and class name. This parameter is an associative array with the keys 'actions' and 'args'.

The actions array is used to set up WordPoints’s action router to trigger reactions that are tied to this even when those actions occur. Note that the action slugs here are the names of actions in the Action object registry, not the raw action names that are called with do_action(). (Learn more about Action objects here.) The keys in the action array depend upon what kind of event we are registering. In this case, it is an event that can be reversed (users can be deleted after they are registered), so we register 'toggle_on' and 'toggle_off' actions. This tells the Hooks API that this event occurs when the 'user_register' action fires, and is reversed when the 'user_delete' action fires. If we needed to hook into multiple actions for either of these, we could also use an array of action slugs instead of just a single string. For non-reversing events (like when a user visits the site—that’s an action that can’t really be reversed), we’d use 'fire' instead of 'toggle_on' or 'toggle_off' as the key for the action slug(s).

The args array informs the Hooks API as to what kind of entities this event relates to. In this case, the event occurs when a user registers, so we specify that there is a 'user' arg. The value of each event arg has be retrieved by a hook Arg object when that event occurs. In this case, the user ID is made available as an arg of the actions that the event hooks to, so we can use the WordPoints_Hook_Arg class that is included with WordPoints to retrieve the ID of the user when our event is fired.