Still working on API docs - move "built-in effects docs"
This commit is contained in:
parent
f0079345e0
commit
e6d87cf7a8
75
docs/API.md
75
docs/API.md
|
@ -1,13 +1,14 @@
|
|||
## The re-frame API
|
||||
|
||||
Orientation:
|
||||
1. The re-frame API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace
|
||||
2. Typically, you'll only use 4 to 10 of the API functions (small surface)
|
||||
3. Oft-used API functions have doc strings, linked-to below (no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36))
|
||||
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.
|
||||
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
|
||||
|
||||
## Links To API docs
|
||||
|
||||
The core API is:
|
||||
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)
|
||||
- [reg-event-db](/src/re_frame/core.cljc#L71-L80), [reg-event-fx](/src/re_frame/core.cljc#L87-L97)
|
||||
- [reg-sub](/src/re_frame/subs.cljc#L151-L237)
|
||||
|
@ -17,17 +18,71 @@ Occasionally, you'll need to use:
|
|||
- [reg-fx]() XXX
|
||||
- [reg-cofx]() XXX and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73)
|
||||
|
||||
And, finally, there are builtin Interceptors which are used a bit:
|
||||
And, finally, there are builtin Interceptors which are useful:
|
||||
- [path](/src/re_frame/std_interceptors.cljc#L149-L173)
|
||||
- [after](/src/re_frame/std_interceptors.cljc#L260-L281)
|
||||
- [debug](/src/re_frame/std_interceptors.cljc#L13-L36)
|
||||
- [and browse the others](/src/re_frame/std_interceptors.cljc)
|
||||
|
||||
Builtin effects:
|
||||
XXX
|
||||
|
||||
Builtin coeffects:
|
||||
XXX
|
||||
|
||||
### Built-in Effect Handlers
|
||||
|
||||
The following built-in effects are effectively part of the API:
|
||||
|
||||
#### :dispatch-later
|
||||
|
||||
`dispatch` one or more events after given delays. Expects a collection
|
||||
of maps with two keys: `:ms` and `:dispatch`
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}
|
||||
{:ms 100 :dispatch [:also :this :in :100ms]}]}
|
||||
```
|
||||
|
||||
Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
|
||||
|
||||
#### :dispatch
|
||||
|
||||
`dispatch` one event. Expects a single vector.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch [:event-id "param"] }
|
||||
```
|
||||
|
||||
#### :dispatch-n
|
||||
|
||||
`dispatch` more than one event. Expects a collection events.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch-n (list [:do :all] [:three :of] [:these])}
|
||||
```
|
||||
|
||||
#### :deregister-event-handler
|
||||
|
||||
removes a previously registered event handler. Expects either a single id (
|
||||
typically a keyword), or a seq of ids.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:deregister-event-handler :my-id)}
|
||||
```
|
||||
or:
|
||||
```clj
|
||||
{:deregister-event-handler [:one-id :another-id]}
|
||||
```
|
||||
|
||||
#### :db
|
||||
|
||||
reset! app-db with a new value. Expects a map.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:db {:key1 value1 :key2 value2}}
|
||||
```
|
||||
|
||||
|
||||
Previous: [First Code Walk-Through](CodeWalkthrough.md)
|
||||
Up: [Index](README.md)
|
||||
|
|
|
@ -21,12 +21,6 @@ make side effects a noop in event replays.
|
|||
- [Effects With No Data](#effects-with-no-data)
|
||||
- [Testing And Noops](#testing-and-noops)
|
||||
- [Summary](#summary)
|
||||
- [Builtin Effect Handlers](#builtin-effect-handlers)
|
||||
- [:dispatch-later](#dispatch-later)
|
||||
- [:dispatch](#dispatch)
|
||||
- [:dispatch-n](#dispatch-n)
|
||||
- [:deregister-event-handler](#deregister-event-handler)
|
||||
- [:db](#db)
|
||||
- [External Effects](#external-effects)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
@ -280,76 +274,21 @@ then you can use a `fixture` to restore all effect handlers at the end of your t
|
|||
`re-frame.core/make-restore-fn` creates a checkpoint for re-frame state (including
|
||||
registered handlers) to which you can return.
|
||||
|
||||
### Existing Effect Handlers
|
||||
|
||||
Built-in effect handlers are detailed [the API](/docs/API.md) document.
|
||||
|
||||
And please review the [External-Resources document](External-Resources.md) for a list of 3rd party Effect Handlers.
|
||||
|
||||
|
||||
### Summary
|
||||
|
||||
The 4 Point Summary
|
||||
|
||||
In note form:
|
||||
The 4 Point Summary in note form:
|
||||
|
||||
1. Event handlers should only return effect declaratively
|
||||
2. They return a map like `{:effect1 value1 :effect2 value2}`
|
||||
3. Keys of this map can refer to builtin effects handlers (see below) or custom ones
|
||||
4. We use `reg-fx` to register our own effects handlers, builtin ones are already registered
|
||||
|
||||
### Builtin Effect Handlers
|
||||
|
||||
#### :dispatch-later
|
||||
|
||||
`dispatch` one or more events after given delays. Expects a collection
|
||||
of maps with two keys: `:ms` and `:dispatch`
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}
|
||||
{:ms 100 :dispatch [:also :this :in :100ms]}]}
|
||||
```
|
||||
|
||||
Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
|
||||
|
||||
#### :dispatch
|
||||
|
||||
`dispatch` one event. Expects a single vector.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch [:event-id "param"] }
|
||||
```
|
||||
|
||||
#### :dispatch-n
|
||||
|
||||
`dispatch` more than one event. Expects a collection events.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:dispatch-n (list [:do :all] [:three :of] [:these])}
|
||||
```
|
||||
|
||||
#### :deregister-event-handler
|
||||
|
||||
removes a previously registered event handler. Expects either a single id (
|
||||
typically a keyword), or a seq of ids.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:deregister-event-handler :my-id)}
|
||||
```
|
||||
or:
|
||||
```clj
|
||||
{:deregister-event-handler [:one-id :another-id]}
|
||||
```
|
||||
|
||||
#### :db
|
||||
|
||||
reset! app-db with a new value. Expects a map.
|
||||
|
||||
usage:
|
||||
```clj
|
||||
{:db {:key1 value1 :key2 value2}}
|
||||
```
|
||||
|
||||
### External Effects
|
||||
|
||||
Please see the [External-Resources document](External-Resources.md) for a list of 3rd part Effect Handlers.
|
||||
4. We use `reg-fx` to register our own effects handlers, built-in ones are already registered
|
||||
|
||||
|
||||
***
|
||||
|
|
Loading…
Reference in New Issue