frame.core — lilactown/frame 0.0.2

*handling* clj/s

add-post-event-callback clj/s

(add-post-event-callback frame f)

(add-post-event-callback frame id f)

Registers a function f to be called after each event is processed f will be called with two arguments:

• event: a vector. The event just processed.
• queue: a PersistentQueue, possibly empty, of events yet to be processed. This is useful in advanced cases like:
• you are implementing a complex bootstrap pipeline
• you want to create your own handling infrastructure, with perhaps multiple handlers for the one event, etc. Hook in here.
• libraries providing 'isomorphic javascript' rendering on Nodejs or Nashorn. 'id' is typically a keyword. Supplied at "add time" so it can subsequently be used at "remove time" to get rid of the right callback.

create-frame clj/s

(create-frame & default-interceptor-factories)

dispatch clj/s

(dispatch {:keys [event-queue]} event)

Enqueue event for processing by event handling machinery. event is a vector of length >= 1. The 1st element identifies the kind of event. Note: the event handler is not run immediately - it is not run synchronously. It will likely be run 'very soon', although it may be added to the end of a FIFO queue which already contain events. Usage: (dispatch [:order-pizza {:supreme 2 :meatlovers 1 :veg 1})

dispatch-sync clj/s

(dispatch-sync {:keys [event-queue] :as frame} event-v)

Synchronously (immediately) process event. Do not queue. Generally, don't use this. Instead use dispatch. It is an error to use dispatch-sync within an event handler. Useful when any delay in processing is a problem:

1. the :on-change handler of a text field where we are expecting fast typing. 2 when initialising your app - see 'main' in todomvc examples
2. in a unit test where we don't want the action 'later' Usage: (dispatch-sync [:sing :falsetto 634])

do-fx clj/s

(do-fx frame)

An interceptor whose :after actions the contents of :effects. As a result, this interceptor is Domino 3. This interceptor is silently added (by reg-event-fx etc) to the front of interceptor chains for all events. For each key in :effects (a map), it calls the registered effects handler (see reg-fx for registration of effect handlers). So, if :effects was: {:dispatch [:hello 42] :db {...} :undo "set flag"} it will call the registered effect handlers for each of the map's keys: :dispatch, :undo and :db. When calling each handler, provides the map value for that key - so in the example above the effect handler for :dispatch will be given one arg [:hello 42]. You cannot rely on the ordering in which effects are executed.

handler-kinds clj/s

inject-cofx clj/s

(inject-cofx id)

(inject-cofx id value)

Given an id, and an optional, arbitrary value, returns an interceptor FACTORY whose :before adds to the :coeffects (map) by calling a pre-registered 'coeffect handler' identified by the id. The previous association of a coeffect handler with an id will have happened via a call to frame.core/reg-cofx - generally on program startup. Within the created interceptor, this 'looked up' coeffect handler will be called (within the :before) with two arguments:

• the current value of :coeffects
• optionally, the originally supplied arbitrary value This coeffect handler is expected to modify and return its first, coeffects argument. Example Of how inject-cofx and reg-cofx work together

---

1. Early in app startup, you register a coeffect handler for :datetime: (frame.core/reg-cofx :datetime ;; usage (inject-cofx :datetime) (fn coeffect-handler [coeffect] (assoc coeffect :now (js/Date.)))) ;; modify and return first arg
2. Later, add an interceptor to an -fx event handler, using inject-cofx: (frame.core/reg-event-fx ;; we are registering an event handler :event-id [ ... (inject-cofx :datetime) ... ] ;; <-- create an injecting interceptor (fn event-handler [coeffect event] ... in here can access (:now coeffect) to obtain current datetime ... ))) Background

---

coeffects are the input resources required by an event handler to perform its job. The two most obvious ones are db and event. But sometimes an event handler might need other resources. Perhaps an event handler needs a random number or a GUID or the current datetime. Perhaps it needs access to a DataScript database connection. If an event handler directly accesses these resources, it stops being pure and, consequently, it becomes harder to test, etc. So we don't want that. Instead, the interceptor created by this function is a way to 'inject' 'necessary resources' into the :coeffects (map) subsequently given to the event handler at call time.

reg-cofx clj/s

(reg-cofx frame id handler)

Register the given coeffect handler for the given id, for later use within inject-cofx. id is keyword, often namespaced. handler is a function which takes either one or two arguements, the first of which is always coeffects and which returns an updated coeffects. See the docs for inject-cofx for example use.

reg-event-fx clj/s

(reg-event-fx frame id handler)

(reg-event-fx frame id interceptors handler)

Register the given event handler (function) for the given id. Optionally, provide an interceptors chain. id is typically a namespaced keyword (but can be anything) handler is a function: (coeffects-map event-vector) -> effects-map interceptors is a collection of interceptors. Will be flattened and nils removed. handler is wrapped in its own interceptor and added to the end of the interceptor chain, so that, in the end, only a chain is registered. Special effects and coeffects interceptors are added to the front of the interceptor chain. These interceptors inject the value of app-db into coeffects, and, later, action effects.

reg-fx clj/s

(reg-fx frame id handler)

Register the given effect handler for the given id. id is keyword, often namespaced. handler is a side-effecting function which takes a single argument and whose return value is ignored. Example Use

First, registration ... associate :effect2 with a handler. (reg-fx :effect2 (fn [value] ... do something side-effect-y)) Then, later, if an event handler were to return this effects map ... {... :effect2 [1 2]} ... then the handler fn we registered previously, using reg-fx, will be called with an argument of [1 2].

register-default-fx clj/s

(register-default-fx frame)

remove-post-event-callback clj/s

(remove-post-event-callback frame id)