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 Packs+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:
Blessed vs. Possible
That doesn't mean we'll prevent you from using unblessed API; it means we're not going to break our backs to support anything unblessed. So if you use unblessed code, we celebrate your bravery, but know that future releases may break your modules without much warning or apology.
+best practices
An area to record helpful habits for private modules as well as conventions to facilitate adoption and compatibility of public modules.
We need more examples of what this might be, for example use of * in rightnames. In general managing the Wagn namespace, etc. What else is in here that we have already identified?
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.
Very curious what is meant by 'before, after, or "around"' ?
around is sort of before and after. A simple example might be some sort of measurement of how long a process takes. You could wrap the measurement action "around" the saving action.
Ah, so the same pattern as with dates - you often want to be able to specify a period of time, with a beginning and an ending.
hmm, don't think that's related. this is about api.
I think the original name for this (Event) was better. Imo here are just four actions: create, read, update, and delete. (We might make a case for "save" as also being an action that means create or update). But there are tons and tons of events (saving subcards, calling flexmail, etc). And, in fact, in the api, I think it makes most sense to be able to specify both, eg "after saving subcards (event) when creating (action)".
'commit' is what is now called 'store' in the code, right?
These are developer issues/use cases, Wagneers won't see this kind of thing. For developers, it may be useful to lay out what the actual 'core' events are that will be 'within' the commit (store) event. In principle, developers can hook onto any of these 'sub-events' with the same keywords, but I think they are probably outside the 'approved' developer APIs. At that level, some small number of exposed events (as listed in the solution) are the official interface, and the other events are completely inside these.
We also need to spec how/which of the main events can interrupt the flow of events to a success. We are mainly throwing exceptions? Some way to return a 'failure' indication? For sure we can add errors to the card object for detail on what failed.
yes, I need to update this ticket to address the issues that you mentioned. Will do today.
Before closing this we need to document current capabilities and ticket remaining todos.
Will be adding more tickets for other todos, but I'm less concerned now that they'll be lost. closing.