Sign up Sign in Samples Blog contact support
add events API

Ticket

 
+issue

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)

  1. captcha
  2. √ notifications
  3. √ geocoding
  4. √ emailing (flexmail)

old (non-core)

  1. √ creating watermarked version of images
  2. √ special permissions warning

new (completion of these items is not hinged to this ticket)

  1. required "fields" (subcards) -- this is requested very often.
  2. customizing page to which we are directed after login (eg by role)
  3. integrating with remote services
  4. 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:

Packs+api
  +events  

Blessed vs. Possible

 
The initial API release will be somewhat limited in scope, because many aspects of Wagn's
...

 

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)

  1. approve #before store, check permissions and validate data (no db changes)
  2. store #record attributes, cascade changes, update references, set read rules, etc
  3. 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.

 

 

+discussion

Very curious what is meant by 'before, after, or "around"' ?

--John Abbe.....2013-05-20 17:05:55 +0000

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.

--Ethan McCutchen.....2013-05-20 17:12:21 +0000

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.

--John Abbe.....2013-05-21 00:29:40 +0000

hmm, don't think that's related. this is about api.

--Ethan McCutchen.....2013-05-21 02:13:51 +0000

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)".

--Ethan McCutchen.....2013-05-31 17:22:29 +0000

'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.

--Gerry Gleason.....2013-06-17 15:43:12 +0000

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.

--Gerry Gleason.....2013-06-17 15:46:59 +0000

yes, I need to update this ticket to address the issues that you mentioned. Will do today.

--Ethan McCutchen.....2013-06-17 15:52:35 +0000

Before closing this we need to document current capabilities and ticket remaining todos.

--Ethan McCutchen.....2013-09-10 19:53:22 +0000

Will be adding more tickets for other todos, but I'm less concerned now that they'll be lost. closing.

--Ethan McCutchen.....2015-07-28 22:00:35 +0000

 

+Relevant user stories