(->interceptor & {:as m :keys [id before after]})
Create an interceptor from named arguments
Create an interceptor from named arguments
(add-post-event-callback f)
(add-post-event-callback 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:
'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.
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.
returns an interceptor which runs a given function f
in the :after
position, presumably for side effects.
f
is called with two arguments: the :effects
value for :db
(or the coeffect
value of db if no db effect is returned) and the event.
Its return value is ignored, so f
can only side-effect.
Examples use can be seen in the /examples/todomvc:
f
runs schema validation (reporting any errors found).f
writes to localstorage.returns an interceptor which runs a given function `f` in the `:after` position, presumably for side effects. `f` is called with two arguments: the `:effects` value for `:db` (or the `coeffect` value of db if no db effect is returned) and the event. Its return value is ignored, so `f` can only side-effect. Examples use can be seen in the /examples/todomvc: - `f` runs schema validation (reporting any errors found). - `f` writes to localstorage.
(assoc-coeffect context key value)
Returns a new context
with a new coeffects map that contains key
mapped to the value
.
Returns a new `context` with a new coeffects map that contains `key` mapped to the `value`.
(assoc-effect context key value)
Returns a new context
with a new effects map that contains key
mapped to the value
.
Returns a new `context` with a new effects map that contains `key` mapped to the `value`.
(clear-cofx)
(clear-cofx id)
When called with no args, unregisters all coeffect handlers. When given one arg,
assumed to be the id
of a registered coeffect handler, unregisters the
associated handler.
When called with no args, unregisters all coeffect handlers. When given one arg, assumed to be the `id` of a registered coeffect handler, unregisters the associated handler.
(clear-event)
(clear-event id)
When called with no args, unregisters all event handlers. When given one arg,
assumed to be the id
of a registered event handler, unregisters the
associated handler.
When called with no args, unregisters all event handlers. When given one arg, assumed to be the `id` of a registered event handler, unregisters the associated handler.
(clear-fx)
(clear-fx id)
When called with no args, unregisters all effect handlers. When given one arg,
assumed to be the id
of a registered effect handler, unregisters the
associated handler.
When called with no args, unregisters all effect handlers. When given one arg, assumed to be the `id` of a registered effect handler, unregisters the associated handler.
(clear-global-interceptor)
(clear-global-interceptor id)
When called with no args, unregisters all global interceptors. When given
one arg, assumed to be the id
of a currently registered global
interceptor, it unregisters the associated interceptor.
When called with no args, unregisters all global interceptors. When given one arg, assumed to be the `id` of a currently registered global interceptor, it unregisters the associated interceptor.
(clear-sub)
(clear-sub query-id)
When called with no args, unregisters all subscription handlers. When given
one arg, assumed to be a query-id
of a registered subscription handler,
unregisters the associated handler.
NOTE: Depending on the usecase it may also be necessary to call
clear-subscription-cache!
.
When called with no args, unregisters all subscription handlers. When given one arg, assumed to be a `query-id` of a registered subscription handler, unregisters the associated handler. NOTE: Depending on the usecase it may also be necessary to call `clear-subscription-cache!`.
(clear-subscription-cache!)
Causes all subscriptions to be removed from the cache. Does this by:
on-dispose
on all cached subscriptionson-dispose
will perform the removal of themselves.This is for development time use. Useful when reloading Figwheel code after a React exception, because React components won't have been cleaned up properly. And this, in turn, means the subscriptions within those components won't have been cleaned up correctly. So this forces the issue.
Causes all subscriptions to be removed from the cache. Does this by: 1. running `on-dispose` on all cached subscriptions 2. Each `on-dispose` will perform the removal of themselves. This is for development time use. Useful when reloading Figwheel code after a React exception, because React components won't have been cleaned up properly. And this, in turn, means the subscriptions within those components won't have been cleaned up correctly. So this forces the issue.
(console level & args)
Logs args
to the console at level
.
Level can be one of :log
:error
:warn
:debug
:group
:groupEnd
.
If you are writing an extension to re-frame, like prehaps an effect handler,
you may want to use re-frame logging so that users can configure logging
from a central location.
usage: (console :error "Oh, dear God, it happened:" a-var "and" another) (console :warn "Possible breach of containment wall at:" dt)
Logs `args` to the console at `level`. Level can be one of `:log` `:error` `:warn` `:debug` `:group` `:groupEnd`. If you are writing an extension to re-frame, like prehaps an effect handler, you may want to use re-frame logging so that users can configure logging from a central location. usage: (console :error "Oh, dear God, it happened:" a-var "and" another) (console :warn "Possible breach of containment wall at:" dt)
An interceptor which logs/instruments an event handler's actions to
js/console.debug
. See examples/todomvc/src/events.cljs for use.
Output includes:
clojure.data/diff
of db, before vs after, which shows
the changes caused by the event handler. You will absolutely have
to understand https://clojuredocs.org/clojure.data/diff to
understand the output.You'd typically include this interceptor after (to the right of) any path interceptor.
Warning: calling clojure.data/diff on large, complex data structures can be slow. So, you won't want this interceptor present in production code. So condition it out like this :
(re-frame.core/reg-event-db
:evt-id
[(when ^boolean goog.DEBUG re-frame.core/debug)] ;; <-- conditional
(fn [db v]
...))
To make this code fragment work, you'll also have to set goog.DEBUG to
false in your production builds - look in project.clj
of /examples/todomvc.
An interceptor which logs/instruments an event handler's actions to `js/console.debug`. See examples/todomvc/src/events.cljs for use. Output includes: 1. the event vector 2. a `clojure.data/diff` of db, before vs after, which shows the changes caused by the event handler. You will absolutely have to understand https://clojuredocs.org/clojure.data/diff to understand the output. You'd typically include this interceptor after (to the right of) any path interceptor. Warning: calling clojure.data/diff on large, complex data structures can be slow. So, you won't want this interceptor present in production code. So condition it out like this : (re-frame.core/reg-event-db :evt-id [(when ^boolean goog.DEBUG re-frame.core/debug)] ;; <-- conditional (fn [db v] ...)) To make this code fragment work, you'll also have to set goog.DEBUG to false in your production builds - look in `project.clj` of /examples/todomvc.
(dispatch 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}])
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 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:
:on-change
handler of a text field where we are expecting fast typing.
2 when initialising your app - see 'main' in todomvc examplesUsage: (dispatch-sync [:sing :falsetto 634])
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 3. in a unit test where we don't want the action 'later' Usage: (dispatch-sync [:sing :falsetto 634])
(enqueue context interceptors)
Add a collection of interceptors
to the end of context's
execution :queue
.
Returns the updated context
.
In an advanced case, this function could allow an interceptor to add new
interceptors to the :queue
of a context.
Add a collection of `interceptors` to the end of `context's` execution `:queue`. Returns the updated `context`. In an advanced case, this function could allow an interceptor to add new interceptors to the `:queue` of a context.
Interceptor factory which runs the given function f
in the after handler
position. f
is called with two arguments: db
and v
, and is expected to
return a modified db
.
Unlike the after
interceptor which is only about side effects, enrich
expects f
to process and alter the given db
coeffect in some useful way,
contributing to the derived data, flowing vibe.
Imagine that todomvc needed to do duplicate detection - if any two todos had the same text, then highlight their background, and report them via a warning at the bottom of the panel.
Almost any user action (edit text, add new todo, remove a todo) requires a complete reassessment of duplication errors and warnings. Eg: that edit just made might have introduced a new duplicate, or removed one. Same with any todo removal. So we need to re-calculate warnings after any CRUD events associated with the todos list.
Unless we are careful, we might end up coding subtly different checks for each kind of CRUD operation. The duplicates check made after 'delete todo' event might be subtly different to that done after an editing operation. Nice and efficient, but fiddly. A bug generator approach.
So, instead, we create an f
which recalculates ALL warnings from scratch
every time there is ANY change. It will inspect all the todos, and
reset ALL FLAGS every time (overwriting what was there previously)
and fully recalculate the list of duplicates (displayed at the bottom?).
https://twitter.com/nathanmarz/status/879722740776939520
By applying f
in an :enrich
interceptor, after every CRUD event,
we keep the handlers simple and yet we ensure this important step
(of getting warnings right) is not missed on any change.
We can test f
easily - it is a pure function - independently of
any CRUD operation.
This brings huge simplicity at the expense of some re-computation each time. This may be a very satisfactory trade-off in many cases.
Interceptor factory which runs the given function `f` in the `after handler` position. `f` is called with two arguments: `db` and `v`, and is expected to return a modified `db`. Unlike the `after` interceptor which is only about side effects, `enrich` expects `f` to process and alter the given `db` coeffect in some useful way, contributing to the derived data, flowing vibe. Example Use: ------------ Imagine that todomvc needed to do duplicate detection - if any two todos had the same text, then highlight their background, and report them via a warning at the bottom of the panel. Almost any user action (edit text, add new todo, remove a todo) requires a complete reassessment of duplication errors and warnings. Eg: that edit just made might have introduced a new duplicate, or removed one. Same with any todo removal. So we need to re-calculate warnings after any CRUD events associated with the todos list. Unless we are careful, we might end up coding subtly different checks for each kind of CRUD operation. The duplicates check made after 'delete todo' event might be subtly different to that done after an editing operation. Nice and efficient, but fiddly. A bug generator approach. So, instead, we create an `f` which recalculates ALL warnings from scratch every time there is ANY change. It will inspect all the todos, and reset ALL FLAGS every time (overwriting what was there previously) and fully recalculate the list of duplicates (displayed at the bottom?). https://twitter.com/nathanmarz/status/879722740776939520 By applying `f` in an `:enrich` interceptor, after every CRUD event, we keep the handlers simple and yet we ensure this important step (of getting warnings right) is not missed on any change. We can test `f` easily - it is a pure function - independently of any CRUD operation. This brings huge simplicity at the expense of some re-computation each time. This may be a very satisfactory trade-off in many cases.
(get-coeffect context)
(get-coeffect context key)
(get-coeffect context key not-found)
When called with one arg, returns the coeffects map from the context
.
When called with two or three args, behaves like clojure.core/get
,
returns the value mapped to key
in the coeffects map, not-found
or
nil
if key
is not present.
When called with one arg, returns the coeffects map from the `context`. When called with two or three args, behaves like `clojure.core/get`, returns the value mapped to `key` in the coeffects map, `not-found` or `nil` if `key` is not present.
(get-effect context)
(get-effect context key)
(get-effect context key not-found)
When called with one arg, returns the effects map from the context
.
When called with two or three args, behaves like clojure.core/get
,
returns the value mapped to key
in the effects map, not-found
or
nil
if key
is not present.
When called with one arg, returns the effects map from the `context`. When called with two or three args, behaves like `clojure.core/get`, returns the value mapped to `key` in the effects map, `not-found` or `nil` if `key` is not present.
(inject-cofx id)
(inject-cofx id value)
Given an id
, and an optional, arbitrary value
, returns an interceptor
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 re-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:
:coeffects
value
This coeffect handler
is expected to modify and return its first, coeffects
argument.
inject-cofx
and reg-cofx
work togetherEarly in app startup, you register a coeffect handler
for :datetime
:
(re-frame.core/reg-cofx :datetime ;; usage (inject-cofx :datetime) (fn coeffect-handler [coeffect] (assoc coeffect :now (js/Date.)))) ;; modify and return first arg
Later, add an interceptor to an -fx event handler, using inject-cofx
:
(re-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 ... )))
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.
Given an `id`, and an optional, arbitrary `value`, returns an interceptor 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 `re-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`: (re-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`: (re-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.
(make-restore-fn)
Checkpoints the state of re-frame and returns a function which, when later called, will restore re-frame to that checkpointed state.
Checkpoint includes app-db, all registered handlers and all subscriptions.
Checkpoints the state of re-frame and returns a function which, when later called, will restore re-frame to that checkpointed state. Checkpoint includes app-db, all registered handlers and all subscriptions.
Interceptor factory which acts a bit like reaction
(but it flows into
db
, rather than out). It observes N paths within db
and if any of them
test not identical? to their previous value (as a result of a event handler
being run) then it runs f
to compute a new value, which is then assoc-ed
into the given out-path
within db
.
Usage:
(defn my-f
[a-val b-val]
... some computation on a and b in here)
(on-changes my-f [:c] [:a] [:b])
Put this Interceptor on the right handlers (ones which might change :a or :b). It will:
f
each time the value at path [:a] or [:b] changesf
with the values extracted from [:a] [:b]f
into the path [:c]Interceptor factory which acts a bit like `reaction` (but it flows into `db`, rather than out). It observes N paths within `db` and if any of them test not identical? to their previous value (as a result of a event handler being run) then it runs `f` to compute a new value, which is then assoc-ed into the given `out-path` within `db`. Usage: (defn my-f [a-val b-val] ... some computation on a and b in here) (on-changes my-f [:c] [:a] [:b]) Put this Interceptor on the right handlers (ones which might change :a or :b). It will: - call `f` each time the value at path [:a] or [:b] changes - call `f` with the values extracted from [:a] [:b] - assoc the return value from `f` into the path [:c]
returns an interceptor whose :before
substitutes the coeffects :db
with
a sub-path of :db
. Within :after
it grafts the handler's return value
back into db, at the right path.
So, its overall action is to make the event handler behave like the function
you might give to clojure's update-in
.
Examples:
(path :some :path)
(path [:some :path])
(path [:some :path] :to :here)
(path [:some :path] [:to] :here)
Example Use:
(reg-event-db
:event-id
(path [:a :b]) ;; used here, in interceptor chain
(fn [b v] ;; 1st arg is now not db. Is the value from path [:a :b] within db
... new-b)) ;; returns a new value for that path (not the entire db)
Notes:
path
may appear more than once in an interceptor chain. Progressive narrowing.:effects
contains no :db
effect, can't graft a value back in.returns an interceptor whose `:before` substitutes the coeffects `:db` with a sub-path of `:db`. Within `:after` it grafts the handler's return value back into db, at the right path. So, its overall action is to make the event handler behave like the function you might give to clojure's `update-in`. Examples: (path :some :path) (path [:some :path]) (path [:some :path] :to :here) (path [:some :path] [:to] :here) Example Use: (reg-event-db :event-id (path [:a :b]) ;; used here, in interceptor chain (fn [b v] ;; 1st arg is now not db. Is the value from path [:a :b] within db ... new-b)) ;; returns a new value for that path (not the entire db) Notes: 1. `path` may appear more than once in an interceptor chain. Progressive narrowing. 2. if `:effects` contains no `:db` effect, can't graft a value back in.
(purge-event-queue)
Remove all events queued for processing
Remove all events queued for processing
(reg-cofx 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.
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-ctx id handler)
(reg-event-ctx 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: (context-map event-vector) -> context-map
This form of registration is almost never used.
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: (context-map event-vector) -> context-map This form of registration is almost never used.
(reg-event-db id handler)
(reg-event-db 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: (db event) -> db
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 this
chain.
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: (db event) -> db `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 this chain.
(reg-event-fx id handler)
(reg-event-fx 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.
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 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.
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 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]`.
(reg-global-interceptor interceptor)
Registers interceptor
as a global interceptor. Global interceptors are
included in the processing of every event.
When you register an event handler you have the option of supplying an interceptor chain. Any global interceptors you register are effectively prepending to this chain in the order that they are registered.
Registers `interceptor` as a global interceptor. Global interceptors are included in the processing of every event. When you register an event handler you have the option of supplying an interceptor chain. Any global interceptors you register are effectively prepending to this chain in the order that they are registered.
(reg-sub query-id & args)
For a given query-id
, register two functions: a computation
function and an input signals
function.
During program execution, a call to subscribe
, such as (subscribe [:sub-id 3 "blue"])
,
will create a new :sub-id
node in the Signal Graph. And, at that time, re-frame
needs to know how to create the node. By calling reg-sub
, you are registering
'the template' or 'the mechanism' by which nodes in the Signal Graph can be created.
Repeating: calling reg-sub
does not create a node. It only creates the template
from which nodes can be created later.
reg-sub
arguments are:
query-id
(typically a namespaced keyword)The computation function
is always the last argument supplied and it is expected to have the signature:
(input-values, query-vector) -> a-value
When computation function
is called, the query-vector
argument will be the vector supplied to the
the subscribe
which caused the node to be created. So, if the call was (subscribe [:sub-id 3 "blue"])
,
then the query-vector
supplied to the computaton function will be [:sub-id 3 "blue"]
.
The arguments supplied between the query-id
and the computation-function
can vary in 3 ways,
but whatever is there defines the input signals
part of the template, controlling what input
values "flow into" the computation function
gets when it is called.
reg-sub
can be called in one of three ways, because there are three ways to define the input signals part.
But note, the 2nd method, in which a signal-fn
is explicitly supplied, is the most canonical and instructive. The other
two are really just sugary variations.
No input signals given:
(reg-sub
:query-id
a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value)
In the absence of an explicit input-fn
, the node's input signal defaults to app-db
and, as a result, the value within app-db
(a map) is
is given as the 1st argument when a-computation-fn
is called.
A signal function is explicitly supplied:
(reg-sub
:query-id
signal-fn ;; <-- here
computation-fn)
This is the most canonical and instructive of the three variations.
When a node is created from the template, the signal-fn
will be called and it
is expected to return the input signal(s) as either a singleton, if there is only
one, or a sequence if there are many, or a map with the signals as the values.
The values from returned nominated signals will be supplied as the 1st argument to
the a-computation-fn
when it is called - and subject to what this signal-fn
returns,
this value will be either a singleton, sequence or map of them (paralleling
the structure returned by the signal-fn
).
This example signal-fn
returns a vector of input signals.
(fn [query-vec dynamic-vec]
[(subscribe [:a-sub])
(subscribe [:b-sub])])
The associated computation function must be written to expect a vector of values for its first argument:
(fn [[a b] query-vec] ;; 1st argument is a seq of two values
....)
If, on the other hand, the signal function was simpler and returned a singleton, like this:
(fn [query-vec dynamic-vec]
(subscribe [:a-sub]))
then the associated computation function must be written to expect a single value as the 1st argument:
(fn [a query-vec] ;; 1st argument is a single value
...)
Further Note: variation #1 above, in which an input-fn
was not supplied, like this:
(reg-sub
:query-id
a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value)
is the equivalent of using this
2nd variation and explicitly suppling a signal-fn
which returns app-db
:
(reg-sub
:query-id
(fn [_ _] re-frame/app-db) ;; <--- explicit input-fn
a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value)
Syntax Sugar
(reg-sub
:a-b-sub
:<- [:a-sub]
:<- [:b-sub]
(fn [[a b] query-vec] ;; 1st argument is a seq of two values
{:a a :b b}))
This 3rd variation is just syntactic sugar for the 2nd. Instead of providing an
signals-fn
you provide one or more pairs of :<-
and a subscription vector.
If you supply only one pair a singleton will be supplied to the computation function,
as if you had supplied a signal-fn
returning only a single value:
(reg-sub
:a-sub
:<- [:a-sub]
(fn [a query-vec] ;; only one pair, so 1st argument is a single value
...))
For further understanding, read /docs
, and look at the detailed comments in
/examples/todomvc/src/subs.cljs
For a given `query-id`, register two functions: a `computation` function and an `input signals` function. During program execution, a call to `subscribe`, such as `(subscribe [:sub-id 3 "blue"])`, will create a new `:sub-id` node in the Signal Graph. And, at that time, re-frame needs to know how to create the node. By calling `reg-sub`, you are registering 'the template' or 'the mechanism' by which nodes in the Signal Graph can be created. Repeating: calling `reg-sub` does not create a node. It only creates the template from which nodes can be created later. `reg-sub` arguments are: - a `query-id` (typically a namespaced keyword) - a function which returns the inputs required by this kind of node (can be supplied in one of three ways) - a function which computes the value of this kind of node The `computation function` is always the last argument supplied and it is expected to have the signature: `(input-values, query-vector) -> a-value` When `computation function` is called, the `query-vector` argument will be the vector supplied to the the `subscribe` which caused the node to be created. So, if the call was `(subscribe [:sub-id 3 "blue"])`, then the `query-vector` supplied to the computaton function will be `[:sub-id 3 "blue"]`. The arguments supplied between the `query-id` and the `computation-function` can vary in 3 ways, but whatever is there defines the `input signals` part of the template, controlling what input values "flow into" the `computation function` gets when it is called. `reg-sub` can be called in one of three ways, because there are three ways to define the input signals part. But note, the 2nd method, in which a `signal-fn` is explicitly supplied, is the most canonical and instructive. The other two are really just sugary variations. 1. No input signals given: ```clj (reg-sub :query-id a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value) ``` In the absence of an explicit `input-fn`, the node's input signal defaults to `app-db` and, as a result, the value within `app-db` (a map) is is given as the 1st argument when `a-computation-fn` is called. 2. A signal function is explicitly supplied: ```clj (reg-sub :query-id signal-fn ;; <-- here computation-fn) ``` This is the most canonical and instructive of the three variations. When a node is created from the template, the `signal-fn` will be called and it is expected to return the input signal(s) as either a singleton, if there is only one, or a sequence if there are many, or a map with the signals as the values. The values from returned nominated signals will be supplied as the 1st argument to the `a-computation-fn` when it is called - and subject to what this `signal-fn` returns, this value will be either a singleton, sequence or map of them (paralleling the structure returned by the `signal-fn`). This example `signal-fn` returns a vector of input signals. ```clj (fn [query-vec dynamic-vec] [(subscribe [:a-sub]) (subscribe [:b-sub])]) ``` The associated computation function must be written to expect a vector of values for its first argument: ```clj (fn [[a b] query-vec] ;; 1st argument is a seq of two values ....) ``` If, on the other hand, the signal function was simpler and returned a singleton, like this: ```clj (fn [query-vec dynamic-vec] (subscribe [:a-sub])) ``` then the associated computation function must be written to expect a single value as the 1st argument: ```clj (fn [a query-vec] ;; 1st argument is a single value ...) ``` Further Note: variation #1 above, in which an `input-fn` was not supplied, like this: ```clj (reg-sub :query-id a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value) ``` is the equivalent of using this 2nd variation and explicitly suppling a `signal-fn` which returns `app-db`: ```clj (reg-sub :query-id (fn [_ _] re-frame/app-db) ;; <--- explicit input-fn a-computation-fn) ;; has signature: (fn [db query-vec] ... ret-value) ``` 3. Syntax Sugar ```clj (reg-sub :a-b-sub :<- [:a-sub] :<- [:b-sub] (fn [[a b] query-vec] ;; 1st argument is a seq of two values {:a a :b b})) ``` This 3rd variation is just syntactic sugar for the 2nd. Instead of providing an `signals-fn` you provide one or more pairs of `:<-` and a subscription vector. If you supply only one pair a singleton will be supplied to the computation function, as if you had supplied a `signal-fn` returning only a single value: ```clj (reg-sub :a-sub :<- [:a-sub] (fn [a query-vec] ;; only one pair, so 1st argument is a single value ...)) ``` For further understanding, read `/docs`, and look at the detailed comments in /examples/todomvc/src/subs.cljs
(reg-sub-raw query-id handler-fn)
This is a low level, advanced function. You should probably be using reg-sub instead. Docs in https://github.com/day8/re-frame/blob/master/docs/SubscriptionFlow.md
This is a low level, advanced function. You should probably be using reg-sub instead. Docs in https://github.com/day8/re-frame/blob/master/docs/SubscriptionFlow.md
(register-handler & args)
Deprecated. Use reg-event-db
instead.
Deprecated. Use `reg-event-db` instead.
(register-sub & args)
Deprecated. Use reg-sub-raw
instead.
Deprecated. Use `reg-sub-raw` instead.
(remove-post-event-callback id)
Unregisters the function identified by id
to be called after each event is
processed.
Unregisters the function identified by `id` to be called after each event is processed.
(set-loggers! new-loggers)
Change the set (or a subset) of logging functions used by re-frame.
new-loggers
should be a map with the same keys as loggers
(above)
Change the set (or a subset) of logging functions used by re-frame. `new-loggers` should be a map with the same keys as `loggers` (above)
(subscribe query)
(subscribe query dynv)
Given a query
vector, returns a Reagent reaction
which, over
time, reactively delivers a stream of values. So in FRP-ish terms,
it returns a Signal
.
To obtain the returned Signal/Stream's current value, it must be deref
ed.
query
is a vector of at least one element. The first element is the
query-id
, typically a namespaced keyword. The rest of the vector's
elements are optional, additional values which parameterise the query
performed.
dynv
is an optional 3rd argument, which is a vector of further input
signals (atoms, reactions, etc), NOT values. This argument exists for
historical reasons and is borderline deprecated these days.
(subscribe [:items]) (subscribe [:items "blue" :small]) (subscribe [:items {:colour "blue" :size :small}])
Note: for any given call to subscribe
there must have been a previous call
to reg-sub
, registering the query handler (function) for the query-id
given.
When used in a view function BE SURE to deref
the returned value.
In fact, to avoid any mistakes, some prefer to define:
(def <sub (comp deref re-frame.core/subscribe))
And then, within their views, they call (<sub [:items :small])
rather
than using subscribe
directly.
Two, or more, concurrent subscriptions for the same query will source reactive updates from the one executing handler.
Given a `query` vector, returns a Reagent `reaction` which, over time, reactively delivers a stream of values. So in FRP-ish terms, it returns a `Signal`. To obtain the returned Signal/Stream's current value, it must be `deref`ed. `query` is a vector of at least one element. The first element is the `query-id`, typically a namespaced keyword. The rest of the vector's elements are optional, additional values which parameterise the query performed. `dynv` is an optional 3rd argument, which is a vector of further input signals (atoms, reactions, etc), NOT values. This argument exists for historical reasons and is borderline deprecated these days. Example Usage: -------------- (subscribe [:items]) (subscribe [:items "blue" :small]) (subscribe [:items {:colour "blue" :size :small}]) Note: for any given call to `subscribe` there must have been a previous call to `reg-sub`, registering the query handler (function) for the `query-id` given. Hint ---- When used in a view function BE SURE to `deref` the returned value. In fact, to avoid any mistakes, some prefer to define: (def <sub (comp deref re-frame.core/subscribe)) And then, within their views, they call `(<sub [:items :small])` rather than using `subscribe` directly. De-duplication -------------- Two, or more, concurrent subscriptions for the same query will source reactive updates from the one executing handler.
An interceptor which removes the first element of the event vector, allowing you to write more aesthetically pleasing event handlers. No leading underscore on the event-v! Your event handlers will look like this:
(defn my-handler
[db [x y z]] ;; <-- instead of [_ x y z]
....)
An interceptor which removes the first element of the event vector, allowing you to write more aesthetically pleasing event handlers. No leading underscore on the event-v! Your event handlers will look like this: (defn my-handler [db [x y z]] ;; <-- instead of [_ x y z] ....)
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close