API docs are now complete. Probably still some editing to do.
This commit is contained in:
parent
5a2bcac347
commit
b3c0c6d139
18
CHANGES.md
18
CHANGES.md
|
@ -1,28 +1,28 @@
|
|||
## Unreleased
|
||||
## Unreleased 0.10.0 (2017.07.NN)
|
||||
|
||||
#### New
|
||||
#### New Docs
|
||||
|
||||
- added [an API document](/docs/API.md)
|
||||
- added [API documentation](/docs/API.md)
|
||||
- added [testing docs](/docs/Testing.md)
|
||||
- added [a new mental model](/docs/MentalModelOmnibus.md#on-dsls-and-machines)
|
||||
- added [a new FAQ entry](docs/FAQs/When-Does-Dispatch-Happen.md) on dispatch processing
|
||||
- The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5)
|
||||
|
||||
#### Breaking
|
||||
|
||||
- [#357](https://github.com/Day8/re-frame/pull/357)
|
||||
I'd be amazed if this actually broke any apps. Shocked! But, better safe than sorry.
|
||||
The effect handler for `:db` has changed: if the value provided tests
|
||||
The effect handler for `:db` has changed: if the new value provided tests
|
||||
`identical?` to the existing value within `app-db`, then `app-db` is not `reset!`.
|
||||
Previously, `app-db` was always `reset!` when a `:db` effect was supplied,
|
||||
which caused Layer 2 subscriptions to run unnecessarily. So this is a tiny
|
||||
efficiency change in an edge case, which also results in behaviour that better matches
|
||||
Previously, `app-db` was always `reset!` irrespective,
|
||||
which potentially caused Layer 2 subscriptions to run unnecessarily. So this is a tiny
|
||||
efficiency change in this edge case, and it results in behaviour that better matches
|
||||
programmer intuitions.
|
||||
|
||||
#### Minor Fixes and Improvements
|
||||
|
||||
- The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5)
|
||||
- [#340](https://github.com/Day8/re-frame/pull/340)
|
||||
- [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.std-interceptors/on-changes` to work even if effect handler does not set `:db`.
|
||||
- [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.core/on-changes` to work even if event handler does not set `:db`.
|
||||
|
||||
|
||||
## 0.9.4 (2017.06.01)
|
||||
|
|
27
docs/API.md
27
docs/API.md
|
@ -1,12 +1,14 @@
|
|||
## The re-frame API
|
||||
|
||||
Orientation:
|
||||
1. The API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace
|
||||
2. The API is quite small - you'll use less than 10 API functions when writing an app.
|
||||
1. The API is provided by [re-frame.core](/src/re_frame/core.cljc) which means:
|
||||
- you should probably browse this namespace sometime
|
||||
- to use re-frame, you'll have to `require` it
|
||||
2. The API is small. Writing an app, you'll use 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)
|
||||
4. But below are helpful links to the doc strings of often-used API functions
|
||||
4. But below are links to the doc strings of often-used API functions.
|
||||
|
||||
## Links To API docs
|
||||
## Doc Strings For API Functions
|
||||
|
||||
The core API consists of:
|
||||
- [dispatch](/src/re_frame/router.cljc#L229-L239), [dispatch-sync](/src/re_frame/router.cljc#L247-L259). See also [this FAQ](/docs/FAQs/When-Does-Dispatch-Happen.md)
|
||||
|
@ -15,8 +17,8 @@ The core API consists of:
|
|||
- [subscribe](/src/re_frame/subs.cljc#L67-L83)
|
||||
|
||||
Occasionally, you'll need to use:
|
||||
- [reg-fx]() XXX
|
||||
- [reg-cofx]() XXX and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73)
|
||||
- [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#L22-L73)
|
||||
|
||||
And, finally, there are builtin Interceptors which are useful:
|
||||
- [path](/src/re_frame/std_interceptors.cljc#L149-L173)
|
||||
|
@ -25,11 +27,11 @@ And, finally, there are builtin Interceptors which are useful:
|
|||
- [and browse the others](/src/re_frame/std_interceptors.cljc)
|
||||
|
||||
|
||||
### Built-in Effect Handlers
|
||||
## Built-in Effect Handlers
|
||||
|
||||
The following built-in effects are effectively part of the API:
|
||||
The following built-in effects are part of the API:
|
||||
|
||||
#### :dispatch-later
|
||||
### :dispatch-later
|
||||
|
||||
`dispatch` one or more events after given delays. Expects a collection
|
||||
of maps with two keys: `:ms` and `:dispatch`
|
||||
|
@ -51,7 +53,7 @@ usage:
|
|||
{:dispatch [:event-id "param"] }
|
||||
```
|
||||
|
||||
#### :dispatch-n
|
||||
### :dispatch-n
|
||||
|
||||
`dispatch` more than one event. Expects a collection events.
|
||||
|
||||
|
@ -60,7 +62,7 @@ usage:
|
|||
{:dispatch-n (list [:do :all] [:three :of] [:these])}
|
||||
```
|
||||
|
||||
#### :deregister-event-handler
|
||||
### :deregister-event-handler
|
||||
|
||||
removes a previously registered event handler. Expects either a single id (
|
||||
typically a keyword), or a seq of ids.
|
||||
|
@ -74,7 +76,7 @@ or:
|
|||
{:deregister-event-handler [:one-id :another-id]}
|
||||
```
|
||||
|
||||
#### :db
|
||||
### :db
|
||||
|
||||
reset! app-db with a new value. Expects a map.
|
||||
|
||||
|
@ -83,6 +85,7 @@ usage:
|
|||
{:db {:key1 value1 :key2 value2}}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
Previous: [First Code Walk-Through](CodeWalkthrough.md)
|
||||
Up: [Index](README.md)
|
||||
|
|
|
@ -12,7 +12,13 @@
|
|||
(assert (re-frame.registrar/kinds kind))
|
||||
|
||||
(defn reg-cofx
|
||||
""
|
||||
"Register the given coeffect `handler` for the given coeffect `id`.
|
||||
|
||||
`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`.
|
||||
|
||||
Please see the docs for `inject-cofx` for example use."
|
||||
[id handler]
|
||||
(register-handler kind id handler))
|
||||
|
||||
|
|
|
@ -57,7 +57,7 @@
|
|||
|
||||
|
||||
;; -- effects -----------------------------------------------------------------
|
||||
(def reg-fx fx/register)
|
||||
(def reg-fx fx/reg-fx)
|
||||
(def clear-fx (partial registrar/clear-handlers fx/kind)) ;; think unreg-fx
|
||||
|
||||
;; -- coeffects ---------------------------------------------------------------
|
||||
|
|
|
@ -13,22 +13,51 @@
|
|||
|
||||
(def kind :fx)
|
||||
(assert (re-frame.registrar/kinds kind))
|
||||
(def register (partial register-handler kind))
|
||||
|
||||
(defn reg-fx
|
||||
"Register the given effect `handler` for the given effect `id`.
|
||||
|
||||
`id` is keyword, often namespaced.
|
||||
`handler` is a side-effecting function which takes a single value and returns nothing.
|
||||
|
||||
Example Use
|
||||
-----------
|
||||
|
||||
First registration ... associating `: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:
|
||||
|
||||
{: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]`."
|
||||
[id handler]
|
||||
(register-handler kind id handler))
|
||||
|
||||
;; -- Interceptor -------------------------------------------------------------
|
||||
|
||||
(def do-fx
|
||||
"An interceptor whose `:after` executes the instructions in `:effects`.
|
||||
"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-db 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 effects handlers).
|
||||
(see `reg-fx` for registration of effect handlers).
|
||||
|
||||
So, if `:effects` was:
|
||||
{:dispatch [:hello 42]
|
||||
:db {...}
|
||||
:undo \"set flag\"}
|
||||
|
||||
it will call the registered effects handlers for each of the map's keys:
|
||||
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]`.
|
||||
|
|
Loading…
Reference in New Issue