add events API
Ticket
+issues
The broadest issue is that Wagn is still an app and trying to become a platform. The events API will give the Wagn pack API a completeness analogous to an MVC framework, though, as described in pack+api, there are significant differences.
With the views API, we are able to arrange existing data very flexibly, but we are not enabled to customize the process of generating and modifying data. This will be the role of the events API.
The new events API should unify a lot of existing functionality and make many more things possible. For example, all of the following should be implementable via events:
old (core)
- captcha
- √ notifications
- √ geocoding
- √ emailing (flexmail)
old (non-core)
- √ creating watermarked version of images
- √ special permissions warning
new (completion of these items is not hinged to this ticket)
- required "fields" (subcards) -- this is requested very often.
- customizing page to which we are directed after login (eg by role)
- integrating with remote services
- complex transactions (eg, editing one card triggers edit of another. one case might be a ticketing system where a comment on +discussion automatically reopens the ticket by changing content of
+solution
An "event", like a view, is going to be very fractal. The act of defining an event will almost always involve attaching it to another event. Most of the basic components of saving a card (permissions checks, validations, etc) should be events and therefore extendable via the api.
roughly outlined here:
event definition syntax (in a set file):
event :eventname [, :preposition=>:eventname, :on=>:action ] &block
Prepositions: before, after, around. When
Actions: create, update, and delete. also
In the future there may also be read events (based in the renderer) and an init event (supporting only the "after" prefix). Both are out of scope here.
A high level view of event phases (order is significant)
- approve #before store, check permissions and validate data (no db changes)
- store #record attributes, cascade changes, update references, set read rules, etc
- extend #after store, send emails, trigger further transactions, etc.
In principle, no db transaction should be committed if any event returns false or adds card errors in the approve or store phases. In the extend phase, neither failure nor errors should trigger a rollback or impact other events. Note: not yet tested.
Also we need to recurse through subcards in each phase. For example, when required fields are supported, missing subcards should be caught in the "approve" process before any db changes are made. Note: not yet working.