diff --git a/docs/API.md b/docs/API.md index 279f687..f9a3b5b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,11 +1,19 @@ ## The re-frame API Orientation: - 1. The API is provided by [re-frame.core](/src/re_frame/core.cljc) which means: - - it will be worth your while to browse this namespace sometime - - to use re-frame, you'll need to `require` it + 1. The API is provided by [re-frame.core](/src/re_frame/core.cljc): + - at some point, it will be worth your time to browse it + - to use re-frame, you'll need to `require` it, perhaps this way ... + ``` + (ns my.namespace + (:require [re-frame.core :as rf])) + + ... now use rf/reg-event-fx or rf/subscribe + ``` + 2. The API is small. Writing an app, you'll be using less than 10 API functions. Maybe just 5. - 3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36) but + 3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36) + but, as a substitute, the links below take you to the doc strings of often-used API functions. ## Doc Strings For API Functions @@ -17,8 +25,8 @@ The core API consists of: - [subscribe](/src/re_frame/subs.cljc#L67-L83) Occasionally, you'll need to use: - - [reg-fx](/src/re_frame/fx.cljc#L17-L39) - - [reg-cofx](/src/re_frame/cofx.cljc#L14-L21) and [inject-cofx](/src/re_frame/cofx.cljc#L28-L79) + - [reg-fx](/src/re_frame/fx.cljc#L17-L40) + - [reg-cofx](/src/re_frame/cofx.cljc#L14-L22) and [inject-cofx](/src/re_frame/cofx.cljc#L29-L80) And, finally, there are builtin Interceptors which are useful: - [path](/src/re_frame/std_interceptors.cljc#L149-L173) diff --git a/src/re_frame/cofx.cljc b/src/re_frame/cofx.cljc index 2869436..9b1ecab 100644 --- a/src/re_frame/cofx.cljc +++ b/src/re_frame/cofx.cljc @@ -12,13 +12,14 @@ (assert (re-frame.registrar/kinds kind)) (defn reg-cofx - "Register the given coeffect `handler` for the given coeffect `id`. + "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 values, the first of which is - always `context` and which returns an updated `context`. + `handler` is a function which takes either one or two arguements, the first of which is + always `coeffects` and which returns an updated `coeffects`. - Please see the docs for `inject-cofx` for example use." + See the docs for `inject-cofx` for example use." [id handler] (register-handler kind id handler)) @@ -30,18 +31,18 @@ whose `:before` adds to the `:coeffects` (map) by calling a pre-registered 'coeffect handler' identified by the `id`. - It is expected that a `coeffect handler` will previously have been registered - for the given `id`, via a call to `re-frame.core/reg-cofx`. + 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. - The `coeffect handler` (identified by `id`) will be called (at `:before` time) - with two arguments: + 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 argument. + This `coeffect handler` is expected to modify and return its first, `coeffects` argument. - Example Use - ----------- + Example Of how `inject-cofx` and `reg-cofx` work together + --------------------------------------------------------- 1. Early in app startup, you register a `coeffect handler` for `:datetime`: @@ -53,12 +54,12 @@ 2. Later, add an interceptor to an -fx event handler, using `inject-cofx`: - (re-frame.reg-event-fx + (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] - ... can access (:now coeffect) to obtain current datetime ... ))) + ... in here can access (:now coeffect) to obtain current datetime ... ))) Background ---------- diff --git a/src/re_frame/fx.cljc b/src/re_frame/fx.cljc index 1918dab..ee8012f 100644 --- a/src/re_frame/fx.cljc +++ b/src/re_frame/fx.cljc @@ -15,28 +15,29 @@ (assert (re-frame.registrar/kinds kind)) (defn reg-fx - "Register the given effect `handler` for the given effect `id`. + "Register the given effect `handler` for the given `id`. `id` is keyword, often namespaced. - `handler` is a side-effecting function which takes a single value and returns nothing. + `handler` is a side-effecting function which takes a single argument and whose return + value is ignored. Example Use ----------- - First registration ... associating `:effect2` with a handler. + 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: + Then, later, if an event handler were to return this effects map ... - {:effect1 42 + {... :effect2 [1 2]} - Then the `handler` `fn` we registered previously, using reg-fx, will be - called with a `value` argument of `[1 2]`." + ... then the `handler` `fn` we registered previously, using `reg-fx`, will be + called with an argument of `[1 2]`." [id handler] (register-handler kind id handler))