API tweaks

This commit is contained in:
Mike Thompson 2017-07-24 22:50:55 +10:00
parent b02846aec2
commit 66ff98ca77
2 changed files with 27 additions and 17 deletions

View File

@ -1,20 +1,19 @@
## The re-frame API ## The re-frame API
Orientation: Orientation:
1. The API is provided by [re-frame.core](/src/re_frame/core.cljc): 1. The API is provided by `re-frame.core`:
- at some point, it will be worth your time to browse it - at some point, it would be worth your time [to browse it](/src/re_frame/core.cljc)
- to use re-frame, you'll need to `require` it, perhaps this way ... - to use re-frame, you'll need to `require` it, perhaps like this ...
``` ```clj
(ns my.namespace (ns my.namespace
(:require [re-frame.core :as rf])) (:require [re-frame.core :as rf]))
... now use rf/reg-event-fx or rf/subscribe ... now use rf/reg-event-fx or rf/subscribe
``` ```
2. The API is small. Writing an app, you use less than 10 API functions. Maybe just 5.
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) 3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36)
but, as a substitute, but, as a substitute,
the links below take you to the doc strings of often-used API functions. the links below take you to the doc-strings of often-used API functions.
## Doc Strings For API Functions ## Doc Strings For API Functions
@ -36,9 +35,9 @@ And, finally, there are the builtin Interceptors:
## Built-in Effect Handlers ## Built-in Effect Handlers
The following built-in effects are also part of the API: The following built-in effects are also a part of the API:
### :dispatch-later #### :dispatch-later
`dispatch` one or more events after given delays. Expects a collection `dispatch` one or more events after given delays. Expects a collection
of maps with two keys: `:ms` and `:dispatch` of maps with two keys: `:ms` and `:dispatch`
@ -51,6 +50,8 @@ usage:
Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ... Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
***
#### :dispatch #### :dispatch
`dispatch` one event. Expects a single vector. `dispatch` one event. Expects a single vector.
@ -60,7 +61,9 @@ usage:
{:dispatch [:event-id "param"] } {:dispatch [:event-id "param"] }
``` ```
### :dispatch-n ***
#### :dispatch-n
`dispatch` more than one event. Expects a collection events. `dispatch` more than one event. Expects a collection events.
@ -69,7 +72,14 @@ usage:
{:dispatch-n (list [:do :all] [:three :of] [:these])} {:dispatch-n (list [:do :all] [:three :of] [:these])}
``` ```
### :deregister-event-handler Note: nil events are ignored which means events can be added
conditionally:
```clj
{:dispatch-n (list (when (> 3 5) [:conditioned-out])
[:another-one])}
```
***
#### :deregister-event-handler
removes a previously registered event handler. Expects either a single id ( removes a previously registered event handler. Expects either a single id (
typically a keyword), or a seq of ids. typically a keyword), or a seq of ids.
@ -82,8 +92,8 @@ or:
```clj ```clj
{:deregister-event-handler [:one-id :another-id]} {:deregister-event-handler [:one-id :another-id]}
``` ```
***
### :db #### :db
reset! app-db with a new value. Expects a map. reset! app-db with a new value. Expects a map.

View File

@ -10,7 +10,7 @@
(def kinds #{:event :fx :cofx :sub}) (def kinds #{:event :fx :cofx :sub})
;; This atom contains a register of all handlers. ;; This atom contains a register of all handlers.
;; Contains a map keyed first by `kind` (of handler), and then `id`. ;; Contains a two layer map, keyed first by `kind` (of handler), and then `id` of handler.
;; Leaf nodes are handlers. ;; Leaf nodes are handlers.
(def kind->id->handler (atom {})) (def kind->id->handler (atom {}))
@ -26,8 +26,8 @@
([kind id required?] ([kind id required?]
(let [handler (get-handler kind id)] (let [handler (get-handler kind id)]
(when debug-enabled? ;; This is in a separate when so Closure DCE can run ... (when debug-enabled? ;; This is in a separate `when` so Closure DCE can run ...
(when (and required? (nil? handler)) ;; ...otherwise you'd need to type hint the `and` with a ^boolean for DCE. (when (and required? (nil? handler)) ;; ...otherwise you'd need to type-hint the `and` with a ^boolean for DCE.
(console :error "re-frame: no " (str kind) " handler registered for: " id))) (console :error "re-frame: no " (str kind) " handler registered for: " id)))
handler))) handler)))