status-im
/
re-frame
mirror of https://github.com/status-im/re-frame.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge remote-tracking branch 'refs/remotes/Day8/master'

This commit is contained in:
Shaun Mahood 2016-08-25 14:40:48 -06:00
parent ebf0d874d0 f22e1def08
commit 6bd664404f
8 changed files with 142 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/Basic-App-Structure.md
View File

@ -34,19 +34,19 @@ Assuming your larger apps has multiple "panels" (or "views") which are relativel
```
src
├── panel1
├── panel-1
│ ├── db.cljs <--- schema, validation, etc (data layer)
│ ├── subs.cljs <--- subscription handlers (query layer)
│ ├── views.cljs <--- reagent components (view layer)
│ └── events.cljs <--- event handlers (control/update layer)
├── panel2
├── panel-2
│ ├── db.cljs <--- schema, validation. etc (data layer)
│ ├── subs.cljs <--- subscription handlers (query layer)
│ ├── views.cljs <--- reagent components (view layer)
│ └── events.cljs <--- event handlers (control/update layer)
.
.
└── panelN
└── panel-n
```
Continue to [Navigation](Navigation.md) to learn how to switch between panels of a larger app.

4
docs/Interceptors.md
View File

@ -119,7 +119,7 @@ and inserts its own interceptors
so ACTUALLY, there's about 5 interceptors in the chain.
So, ultimately, that event registration associates the event id `:some-id`
with a chain of interceptors.
with __just__ a chain of interceptors. Nothing more.
Later, when a `(dispatch [:some-id ...])` happens, that 5-chain of
interceptors will be "executed". And that's how events get handled.
@ -216,7 +216,7 @@ designed by the talented
Dunno about you, but I'm easily offended by underscores.
If our components did this:
If we had a component which did this:
```clj
(dispatch [:delete-item 42])
```

127
docs/Loading-Initial-Data.md
View File

@ -1,7 +1,11 @@
## Bootstrapping Your Application State
## Bootstrapping Application State
To bootstrap a re-frame application, you need to:
1. register handlers (subscription and event handlers)
1. register handlers
- subscription (via `reg-sub`)
- events (via `reg-event-db` or `reg-event-fx`)
- effects (via `reg-fx`)
- coeffects (via `reg-cofx`)
2. kickstart reagent (views)
3. Load the right initial data into `app-db` which might be a `merge` of:
- Some default values
@ -11,23 +15,27 @@ To bootstrap a re-frame application, you need to:
Point 3 is the interesting bit and will be the main focus of this page, but let's work our way through them ...
## Register Event Handlers
## 1. Register Handlers
Generally, there's nothing to do because this happens automatically at (js) script load time, because you declared and registered your event handlers like this:
```Clojure
re-frame's multifarious handlers all work in the same way. You declare
and registered your handlers in the one step, like this "event handler" example:
```clj
(re-frame/reg-event-db ;; event handler will be registered automatically
:some-id
(fn [db [_ value]]
... do some state change based on db and value
... do some state change based on db and value ))
```
## Kick Start Reagent
As a result, there's nothing further you need to do because
handler registration happens as a direct result of loading the code
code (presumably via a `<script>`).
## 2. Kick Start Reagent
Create a function `main` which does a `reagent/render` of your root reagent component `main-panel`:
```Clojure
```clj
(defn main-panel ;; my top level reagent component
[]
[:div "Hello DDATWD"])
@ -38,17 +46,24 @@ Create a function `main` which does a `reagent/render` of your root reagent comp
(js/document.getElementById "app")))
```
## Loading Initial Data
Mounting the top level component `main-panel` will trigger a cascade of child
component creation. The full DOM tree will be rendered.
Let's rewrite our `main-panel` component to use a subscription:
## 3. Loading Initial Data
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`.
First, we'll create the subscription handler:
```Clojure
(re-frame/reg-sub ;; a new subscription handler
:name ;; usage (subscribe [:name])
(fn [db _]
(:name db))) ;; pulls out :name
(:display-name db))) ;; extracts `:display-name` from app-db
```
And now we use that subscription:
```clj
(defn main-panel
[]
(let [name (re-frame/subscribe [:name])] ;; <--- a subscription <---
@ -57,31 +72,33 @@ Let's rewrite our `main-panel` component to use a subscription:
```
The user of our app will see funny things
if that `(subscribe [:name])` doesn't deliver good data. We must ensure there's good data in `app-db`.
if that `(subscribe [:name])` doesn't deliver good data. But how do we ensure "good data"?
That will require:
1. getting data into `app-db`; and
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.
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.
**Note: `app-db` initially contains `{}`**
### Getting Data Into `app-db`
Only event handlers can change `app-db`. Those are the rules!! Even initial values must be put in via an event handler.
Only event handlers can change `app-db`. Those are the rules!! Indeed, even initial
values must be put in `app-db` via an event handler.
Here's an event handler for that purpose:
```Clojure
(re-frame/reg-event-db
:initialise-db ;; usage: (re-frame/dispatch [:initialise-db])
:initialise-db ;; usage: (dispatch [:initialise-db])
(fn [_ _] ;; Ignore both params (db and event)
{:display-name "DDATWD" ;; return a new value for app-db
:items [1 2 3 4]}))
{:display-name "DDATWD" ;; return a new value for app-db
:items [1 2 3 4]}))
```
We'll need to dispatch the `:initialise-db` event to get it to execute. `main` seems like the natural place:
You'll notice that this handler does nothing other than to return a ` map`. That map
will become the new value within `app-db`.
We'll need to dispatch an `:initialise-db` event to get it to execute. `main` seems like the natural place:
```Clojure
(defn ^:export main
[]
@ -90,13 +107,21 @@ We'll need to dispatch the `:initialise-db` event to get it to execute. `main` s
(js/document.getElementById "app")))
```
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.
But remember, event handlers execute async. So although there's
a `dispatch` within `main`, the event is simply queued, and the
handler for `:initialise-db`
will not be run until sometime after `main` has finished.
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`.
But how long after? And is there a race condition? The
component `main-panel` (which assumes good data) might be
rendered before the `:initialise-db` event handler has
put good data into `app-db`.
We don't want any rendering (of `main-panel`) until after `app-db` is right.
We don't want any rendering (of `main-panel`) until after `app-db`
has been correctly initialised.
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:
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.
## The Pattern
@ -104,12 +129,12 @@ Okay, so that's enough of teasing-out the issues. Let's see a quick sketch of th
(re-frame/reg-sub ;; the means by which main-panel gets data
:name ;; usage (subscribe [:name])
(fn [db _]
(:name db)))
(:display-name db)))
(re-frame/reg-sub ;; we can check if there is data
:initialised? ;; usage (subscribe [:initialised?])
(fn [db _]
(not (empty? @db)))) ;; do we have data
(not (empty? db)))) ;; do we have data
(defn main-panel ;; the top level of our app
[]
@ -136,10 +161,10 @@ Okay, so that's enough of teasing-out the issues. Let's see a quick sketch of th
This pattern scales up easily.
For example, imagine a more complicated scenario in which your app is not fully initialised until 2 backend services supply data.
For example, imagine a more complicated scenario in which your app
is not fully initialised until 2 backend services supply data.
Your `main` might look like this:
```Clojure
(defn ^:export main ;; call this to bootstrap your app
[]
@ -156,17 +181,43 @@ Your `:initialised?` test then becomes more like this sketch:
(reg-sub
:initialised? ;; usage (subscribe [:initialised?])
(fn [db _]
(and (not (empty? @db))
(:service1-answered? @db)
(:service2-answered? @db)))))
(and (not (empty? db))
(:service1-answered? db)
(:service2-answered? db)))))
```
This assumes boolean flags are set in `app-db` when data was loaded from these services.
## A Cheat - Synchronous Dispatch
## Cheating - Synchronous Dispatch
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](https://github.com/Day8/re-frame/blob/8cf42f57f50f3ee41e74de1754fdb75f80b31775/examples/todomvc/src/todomvc/core.cljs#L35) example both use `dispatch-sync` to initialise the app-db. This causes the event to jump to the front of the line and causes it to execute immediately, which is fine for the initial data load in a simple app but can lead to problems elsewhere. As your app gets more complicated, it is strongly suggested that you use the regular `dispatch` function where possible. If you are using `dispatch-sync` and run into weird errors, there's a pretty high chance that it's the culprit.
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.
## Services
`dispatch` queues an event for later processing, but `dispatch-sync` acts
like a function call and handles an event immediately. That's useful for initial data
load we are considering, particularly for simple apps. Using `dispatch-sync` guarantees
that initial state will be in place before any views are mounted, so we know they'll
subscribe to sensible values. We don't need a guard like `top-panel` (introduced above).
Remember when we used `dispatch` to request the data in our `main` function? What would those event handlers looks like? Let's go to [Talking to Servers](Talking-To-Servers.md) and find out!
But don't get into the habit of using `dispatch-sync` everywhere. It is the right
tool in this context and, sometimes, when writing tests, but
`dispatch` is the staple you should use everywhere else.
## Loading Initial Data From Services
Above, in our example `main`, we imagined using `(re-frame/dispatch [:load-from-service-1])` to request data
from a backend services. How would we write the handler for this event?
The next Tutorial will show you how.
---
Previous: [Interceptors](Interceptors.md)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Up: [Index](Readme.md)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Next: [Talking To Servers](Talking-To-Servers.md)

24
docs/Namespaced-Keywords.md
View File

@ -1,13 +1,21 @@
## Namespaced Ids
## What About Event Ids?
As an app gets bigger, you'll tend to get clashes on ids - event-ids, or query-ids (subscriptions), etc.
One panel will need to `dispatch` an `:edit` event and so will
another, but the two panels will have different handlers.
So how then to not have a clash? How then to distinguish between
one `:edit` event and another?
As an app gets bigger, you'll tend to get clashes on event ids. One panel will need to `dispatch` an `:edit` event and so will another, but the two panels will have different handlers.
So how then to not have a clash? How then to distinguish between one edit event and another?
Your goal should be to use event-ids which encode both the event
itself (`:edit` ?) and the context (`:panel1` or `:panel2` ?).
Your goal should be to use event-ids which encode both the event itself (`:edit` ?) and the context (`:panel1` or `:panel2` ?).
Luckily, ClojureScript provides a nice easy solution: use keywords
with a __synthetic namespace__. Perhaps something like `:panel1/edit` and `:panel2/edit`.
Luckily, ClojureScript provides a nice easy solution: use keywords with a synthetic namespace. Perhaps something like `:panel1/edit` and `:panel2/edit`.
You see, ClojureScript allows the namespace in a keyword to be a total
fiction. I can have the keyword `:panel1/edit` even though
`panel1.cljs` doesn't exist.
You see ClojureScript allows the namespace in a keyword to be a fiction. I can have the keyword `:panel1/edit` even though `panel1.cljs` doesn't exist.
Naturally, you'll take advantage of this by using keyword namespaces which are both unique and descriptive.
Naturally, you'll take advantage of this by using keyword namespaces
which are both unique and descriptive.

2
docs/Navigation.md
View File

@ -46,4 +46,4 @@ A high level reagent view has a subscription to :active-panel and will switch to
```
Continue to [Namespaced Keywords](Namespaced-Keywords.md) to reduce clashes on event ids.
Continue to [Namespaced Keywords](Namespaced-Keywords.md) to reduce clashes on ids.

BIN
images/logo/Genesis.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 208 KiB

BIN
images/logo/Guggenheim.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

33
images/logo/README.md
View File

@ -1,5 +1,34 @@
**re-frame logo**
## The re-frame Logo
Created by the mysterious @martinklepsch
Some say he appears on high value stamps in Germany and that he once
punched a horse to the ground. Others say that he loves recursion so much
that in his wallet he keeps a photograph of his wallet.
All we know for certain is that he wields [Sketch.app](https://www.sketchapp.com/) like
Bruce Lee wielded nunchucks.
## Genesis Theories
While we wouldn't presume to fathom the cavernous depths of Martin's creativity, some have
speculated the re-frame logo was created as a bifarious rainbow omage to Frank Lloyd Wright's Guggenheim.
![](Guggenheim.jpg)
<br><br>
Others scoff and insist he smeared the cljs logo across re-frame's official
architecture diagram to form a flowing poststructuralist rebuttal of the tyrannical
"OO" adjacency.
![](Genesis.png)
You be the judge.
Are we better off never knowing? Does art require an answer?
### Instructions
Use [Sketch.app](https://www.sketchapp.com/) to update the `re-frame-logo.sketch` file.
Unfortunately the gradients are not exported properly so we can't provide an SVG here for now.
Unfortunately the gradients are not exported properly so we can't provide an SVG here for now.