2016-08-25 04:27:48 +00:00
|
|
|
## Bootstrapping Your Application State
|
|
|
|
|
|
|
|
To bootstrap a re-frame application, you need to:
|
2016-08-25 09:24:00 +00:00
|
|
|
1. register handlers
|
|
|
|
- subscription (via `reg-sub`)
|
|
|
|
- events (via `reg-event-db` or `reg-event-fx`)
|
|
|
|
- effects (via `reg-fx`)
|
|
|
|
- coeffects (via `reg-cofx`)
|
2016-08-25 04:27:48 +00:00
|
|
|
2. kickstart reagent (views)
|
|
|
|
3. Load the right initial data into `app-db` which might be a `merge` of:
|
|
|
|
- Some default values
|
|
|
|
- Values stored in LocalStorage
|
|
|
|
- Values obtained via service calls to server
|
|
|
|
- etc, etc
|
|
|
|
|
|
|
|
Point 3 is the interesting bit and will be the main focus of this page, but let's work our way through them ...
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
## 1. Register Handlers
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
You declare and registered your handlers in the one step like this:
|
|
|
|
```clj
|
2016-08-25 04:27:48 +00:00
|
|
|
(re-frame/reg-event-db ;; event handler will be registered automatically
|
|
|
|
:some-id
|
|
|
|
(fn [db [_ value]]
|
2016-08-25 09:24:00 +00:00
|
|
|
... do some state change based on db and value ))
|
2016-08-25 04:27:48 +00:00
|
|
|
```
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
As a result, there's nothing further you need to do because, at script (js) load time, the
|
|
|
|
registration happens automatically.
|
|
|
|
|
|
|
|
## 2. Kick Start Reagent
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
Create a function `main` which does a `reagent/render` of your root reagent component `main-panel`:
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
```clj
|
2016-08-25 04:27:48 +00:00
|
|
|
(defn main-panel ;; my top level reagent component
|
|
|
|
[]
|
|
|
|
[:div "Hello DDATWD"])
|
|
|
|
|
|
|
|
(defn ^:export main ;; call this to bootstrap your app
|
|
|
|
[]
|
|
|
|
(reagent/render [main-panel]
|
|
|
|
(js/document.getElementById "app")))
|
|
|
|
```
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
Mounting the top level component `main-panel` will trigger a cascade of child
|
|
|
|
component creation. The full DOM tree will be rendered.
|
|
|
|
|
|
|
|
## 3. Loading Initial Data
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
Let's rewrite our `main-panel` component to use a subscription. In effect,
|
|
|
|
we want it to source and render some data held in `app-db`.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
First, we'll create the subscription handler:
|
2016-08-25 04:27:48 +00:00
|
|
|
```Clojure
|
|
|
|
(re-frame/reg-sub ;; a new subscription handler
|
|
|
|
:name ;; usage (subscribe [:name])
|
|
|
|
(fn [db _]
|
2016-08-25 09:24:00 +00:00
|
|
|
(:display-name db))) ;; extracts `:display-name` from app-db
|
|
|
|
```
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
And now we use that subscription:
|
|
|
|
```clj
|
2016-08-25 04:27:48 +00:00
|
|
|
(defn main-panel
|
|
|
|
[]
|
|
|
|
(let [name (re-frame/subscribe [:name])] ;; <--- a subscription <---
|
|
|
|
(fn []
|
|
|
|
[:div "Hello " @name])))) ;; <--- use the result of the subscription
|
|
|
|
```
|
|
|
|
|
|
|
|
The user of our app will see funny things
|
2016-08-25 09:24:00 +00:00
|
|
|
if that `(subscribe [:name])` doesn't deliver good data. But how do we ensure "good data"?
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
That will require:
|
|
|
|
1. getting data into `app-db`; and
|
2016-08-25 09:24:00 +00:00
|
|
|
2. not get into trouble if that data isn't yet in `app-db`. For example,
|
|
|
|
the data may have to come from a server and there's latency.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
**Note: `app-db` initially contains `{}`**
|
|
|
|
|
|
|
|
### Getting Data Into `app-db`
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
Only event handlers can change `app-db`. Those are the rules!! Even initial
|
|
|
|
values must be put in via an event handler.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
Here's an event handler for that purpose:
|
|
|
|
```Clojure
|
|
|
|
|
|
|
|
(re-frame/reg-event-db
|
2016-08-25 09:24:00 +00:00
|
|
|
:initialise-db ;; usage: (dispatch [:initialise-db])
|
2016-08-25 04:27:48 +00:00
|
|
|
(fn [_ _] ;; Ignore both params (db and event)
|
2016-08-25 09:24:00 +00:00
|
|
|
{:display-name "DDATWD" ;; return a new value for app-db
|
|
|
|
:items [1 2 3 4]}))
|
2016-08-25 04:27:48 +00:00
|
|
|
```
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
We'll need to dispatch an `:initialise-db` event to get it to execute. `main` seems like the natural place:
|
2016-08-25 04:27:48 +00:00
|
|
|
```Clojure
|
|
|
|
(defn ^:export main
|
|
|
|
[]
|
|
|
|
(re-frame/dispatch [:initialise-db]) ;; <--- this is new
|
|
|
|
(reagent/render [main-panel]
|
|
|
|
(js/document.getElementById "app")))
|
|
|
|
```
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
But remember, event handlers execute async. So although there's
|
|
|
|
a `dispatch` within `main`, the handler for `:initialise-db`
|
|
|
|
will not be run until sometime after `main` has finished.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
But how long after? And is there a race condition? The
|
|
|
|
component `main-panel` (which needs good data) might be
|
|
|
|
rendered before the `:initialise-db` event handler has
|
|
|
|
put good data into `app-db`.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
We don't want any rendering (of `main-panel`) until after `app-db` is right.
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
Okay, so that's enough of teasing-out the issues. Let's see a
|
|
|
|
quick sketch of the entire pattern. It is very straight-forward:
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
## The Pattern
|
|
|
|
|
|
|
|
```Clojure
|
|
|
|
(re-frame/reg-sub ;; the means by which main-panel gets data
|
|
|
|
:name ;; usage (subscribe [:name])
|
|
|
|
(fn [db _]
|
2016-08-25 09:24:00 +00:00
|
|
|
(:display-name db)))
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
(re-frame/reg-sub ;; we can check if there is data
|
|
|
|
:initialised? ;; usage (subscribe [:initialised?])
|
|
|
|
(fn [db _]
|
2016-08-25 09:24:00 +00:00
|
|
|
(not (empty? db)))) ;; do we have data
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
(defn main-panel ;; the top level of our app
|
|
|
|
[]
|
|
|
|
(let [name (re-frame/subscribe :name)] ;; we need there to be good data
|
|
|
|
(fn []
|
|
|
|
[:div "Hello " @name]))))
|
|
|
|
|
|
|
|
(defn top-panel ;; this is new
|
|
|
|
[]
|
|
|
|
(let [ready? (re-frame/subscribe [:initialised?])]
|
|
|
|
(fn []
|
|
|
|
(if-not @ready? ;; do we have good data?
|
|
|
|
[:div "Initialising ..."] ;; tell them we are working on it
|
|
|
|
[main-panel])))) ;; all good, render this component
|
|
|
|
|
|
|
|
(defn ^:export main ;; call this to bootstrap your app
|
|
|
|
[]
|
|
|
|
(re-frame/dispatch [:initialise-db])
|
|
|
|
(reagent/render [top-panel]
|
|
|
|
(js/document.getElementById "app")))
|
|
|
|
```
|
|
|
|
|
|
|
|
## Scales Up
|
|
|
|
|
|
|
|
This pattern scales up easily.
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
For example, imagine a more complicated scenario in which your app
|
|
|
|
is not fully initialised until 2 backend services supply data.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
|
|
|
Your `main` might look like this:
|
|
|
|
```Clojure
|
|
|
|
(defn ^:export main ;; call this to bootstrap your app
|
|
|
|
[]
|
|
|
|
(re-frame/dispatch [:initialise-db]) ;; basics
|
|
|
|
(re-frame/dispatch [:load-from-service-1]) ;; ask for data from service-1
|
|
|
|
(re-frame/dispatch [:load-from-service-2]) ;; ask for data from service-2
|
|
|
|
(reagent/render [top-panel]
|
|
|
|
(js/document.getElementById "app")))
|
|
|
|
```
|
|
|
|
|
|
|
|
Your `:initialised?` test then becomes more like this sketch:
|
|
|
|
|
|
|
|
```Clojure
|
|
|
|
(reg-sub
|
|
|
|
:initialised? ;; usage (subscribe [:initialised?])
|
|
|
|
(fn [db _]
|
2016-08-25 09:24:00 +00:00
|
|
|
(and (not (empty? db))
|
|
|
|
(:service1-answered? db)
|
|
|
|
(:service2-answered? db)))))
|
2016-08-25 04:27:48 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
This assumes boolean flags are set in `app-db` when data was loaded from these services.
|
|
|
|
|
|
|
|
## A Cheat - Synchronous Dispatch
|
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
In simple cases, you can simplify matters by using `(dispatch-sync [:initialise-db])` in
|
|
|
|
the main entry point function. The
|
|
|
|
[Simple Example](https://github.com/Day8/re-frame/blob/8cf42f57f50f3ee41e74de1754fdb75f80b31775/examples/simple/src/simpleexample/core.cljs#L110)
|
|
|
|
and [TodoMVC Example](https://github.com/Day8/re-frame/blob/8cf42f57f50f3ee41e74de1754fdb75f80b31775/examples/todomvc/src/todomvc/core.cljs#L35)
|
|
|
|
both use `dispatch-sync` to initialise the app-db.
|
|
|
|
|
|
|
|
`dispatch-sync` acts like a function call
|
|
|
|
and ensures the event is handled immediately, which is useful for initial data load in a
|
|
|
|
simple app - you don't need to guard against uninitialised data - you don't need
|
|
|
|
a `top-panel` (introduced above).
|
|
|
|
|
|
|
|
But don't get into the habit of using `dispatch-sync`. It is the right
|
|
|
|
tool in this context and, sometimes, when writing tests, but
|
|
|
|
`dispatch` is the staple to be used everywhere else.
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
## Loading Initial Data From Services
|
2016-08-25 04:27:48 +00:00
|
|
|
|
2016-08-25 09:24:00 +00:00
|
|
|
Above, in our example `main`, we used `dispatch` to request data
|
|
|
|
from a backend service. What would the event handlers look like
|
|
|
|
which initiate the GETs?
|
|
|
|
|
|
|
|
Let's go to [Talking to Servers](Talking-To-Servers.md) and find out!
|