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

WIP

This commit is contained in:
mike-thompson-day8 2015-01-11 23:09:17 +11:00
parent a6b3f86b97
commit f5e3750f7b
1 changed files with 141 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

260
README.md
View File

@ -2,57 +2,59 @@
Still Alpha. But getting closer.
Todo:
- allow for pure event handlers. I suspect a macro will be needed.
## re-frame
re-frame is a tiny [Reagent] framework for writing [SPAs] using ClojureScript.
re-frame is a tiny [Reagent] framework for writing [SPAs] using ClojureScript.
It proposes a pattern for structuring an app, and provides a small library
implementing one version of this pattern.
This document proposes a **pattern** for structuring an SPA using ClojureScript and Reagent, and the repo provides a **reference implementation** for one version of this pattern.
In another context, re-frame might be called an MVC framework, except
it is instead a functional RACES framework - Reactive-Atom Component Event Subscription
(I love the smell of acronym in the morning).
re-frame isn't an MVC framework. Instead, it is a functional RACES framework - Reactive-Atom Component Event Subscription (I love the smell of acronym in the morning).
### TL;DR
### Overview
The re-frme pattern is simple. To prove that, the reference implementaton in this repo is just a couple hundred lines of code.
The re-frme pattern is simple. So simple, in fact, that the reference implementaton in this repo is barely 100 lines of code.
Despite its simplicity, re-frame is fully buzzword compliant: it has FRP-nature, pristinely pure functions, conveyor belts, and hammocks.
To build an app using re-frame, you'll:
- design your app's data structure. Optionally, provide a schema.
To build an app using re-frame, you:
- design your app's data structure (data layer)
- write and register subscription functions (query layer)
- write component functions (view layer)
- write Reagent component functions (view layer)
- write and register event handler functions (control layer and/or state transition layer)
All the functions you write are pure. So the distinct pieces of your app can be
described, understood and tested independently. And yet they combine to build the whole.
All the functions you write are pure, so the distinct pieces of your app can be
described, understood and tested independently.
### Further
Despite its simplicity, re-frame is impressively buzzword compliant: it has FRP-nature, unidirectional data flow, pristinely pure functions, uses conveyor belts, statecharts and claims a hammock conception.
We write larger, more complicated SPAs which have limited interaction with a server. re-frame's design reflects our needs. So there's nothing in re-frame about, say, routing to server-side services etc, etc. Its just about writing the client side.
### Client Side Bias
Nothing about re-frame is the slightest bit original or clever. You'll find
no ingenious use of functional zippers, transducers or core.async.
This is a good thing (although, for the record, one day I'd love to develop
something original and clever).
We write larger, more complicated SPAs which have a Parisian's indifference for servers. re-frame's design reflects our needs. So there's nothing in re-frame about, say, routing to server-side services, etc. It is just about writing client side apps. That doesn't mean it wouldn't work well when a server is heavily involved, its just that we haven't tweaked it in that direction.
At small scale, any framework seems like pesky overhead. The
explanatory examples in here are necessarily small scale, so you'll need to
squint a little to see the benefit.
### Nothng New
Nothing about re-frame is the slightest bit original or clever. You'll find
no ingenious use of functional zippers, transducers or core.async.
This is a good thing (although, for the record, one day I'd love to develop
something original and clever).
### Guiding Philosophy
First, above all we believe in the one true [Dan Holmsand], the creator of Reagent,
and his divine instrument the `ratom`. We genuflect towards Sweden once a day.
First, above all we believe in the one true [Dan Holmsand], the creator of Reagent, and his divine instrument the `ratom`. We genuflect towards Sweden once a day.
Second, we believe that [FRP] is a honking great idea. You might be tempted to see
Reagent as simply another of the React wrappers (a sibling to [OM] and [quiescent](https://github.com/levand/quiescent)). But I think you only really "get"
Reagent as simply another of the React wrappers (a sibling to [OM] and [quiescent](https://github.com/levand/quiescent)). But you'll only really "get"
Reagent when you view it as an FRP library. To put that another way, we think
that Reagent, at its best, is closer in
nature to [Hoplon] or [Elm] than it is OM.
Finally, we believe in one-way data flow. We don't like read/write `cursors` which
Finally, we believe in one-way data flow. No cycles. We don't like read/write `cursors` which
promote two way flow of data. re-frame does implement two data way flow, but it
uses two, separate, one-way flows to achieve it, and those two flows
are different in nature.
@ -61,51 +63,51 @@ If you are curious about FRP, I'd recommend [this FRP backgrounder](https://gist
## The Parts
To teach re-frame, I'll now incrementally develop a diagram, explaining each part as it is added.
To explain re-frame, I'll incrementally develop a diagram, explaining each part as it is added.
Along the way, I'll be using [Reagent] at an intermediate to advanced level. So, this is not a Reagent tutorial and you will need to have done one of those before continuing here. Try
Along the way, I'll be using [reagent] at an intermediate to advanced level. But this is no introductory reagent tutorial and you will need to have done one of those before continuing here. Try
[the official intro](http://reagent-project.github.io/) or
[this](https://github.com/jonase/reagent-tutorial) or
[this](http://yogthos.net/posts/2014-07-15-Building-Single-Page-Apps-with-Reagent.html).
##### On Data
<blockquote class="twitter-tweet" lang="en"><p>Well-formed Data at rest is as close to perfection in programming as it gets. All the crap that had to happen to put it there however...</p>&mdash; Fogus (@fogus) <a href="https://twitter.com/fogus/status/454582953067438080">April 11, 2014</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
##### The Big Ratom
Our re-frame diagram starts with the "well-formed data at rest" bit:
Our re-frame diagram starts (very modestly) with the "well-formed data at rest" bit:
```
app-db
```
re-frame recommends that you put your data into one place which we'll call `app-db`. Structure the data in that place, of course. And [give it a schema](https://github.com/miner/herbert).
re-frame says that you put your data into one place which we'll call `app-db`. Structure the data in that place, of course. And [give it a schema](https://github.com/miner/herbert).
Now, this advice is not the slightest bit controversial for 'real' databases, right?
You'd happily put all your well-formed data into PostgreSQL or MySQL. But within a running application (in memory), it is different. If you have a background in OO, this data-in-one-place is a
hard one to swallow. You've
You'd happily put all your well-formed data into PostgreSQL or MySQL. But within a running application (in memory), it is different. If you have a background in OO, this data-in-one-place business is a hard one to swallow. You've
spent your life breaking systems into pieces, organised around behaviour and trying
to hide the data. I still wake up in a sweat some nights thinking about all
that Clojure data lying around exposed and passive.
But, as @fogus tells us, data is the easy bit.
But, as @fogus tells us, data at rest is the easy bit.
From here on, we'll assume `app-db` is one of these:
From here on in this document, we'll assume `app-db` is one of these:
```Clojure
(def app-db (reagent/atom {})) ;; a Reagent atom, containing a map
```
Although it is a Reagent atom (`ratom`), I'd encourage you to think of it as an in-memory database.
It will contain structured data (perhaps with a formal [Herbert Schema] spec).
You will need to query that data. You will perform CRUD
Although it is a `Reagent atom` (hereafter `ratom`), I'd encourage you to think of it as an in-memory database.
It will contain structured data. You will need to query that data. You will perform CRUD
and other transformations on it. You'll often want to transact on this
database atomically, etc. So "in-memory database"
seems a more useful paradigm than plain old atom.
Finally, a clarification: `app-db` doesn't actually have to be a reagent/atom containing
a map. In theory, re-frame
imposes no requirement here. It could be a [datascript] database (untested). But, as you'll see, it
imposes no requirement here. It could be a [datascript] database (approach untested). But, as you'll see, it
does have to be a "reactive datastore" (one that can tell you when it has changed). In fact, `app-db` doesn't have to be a single atom either -- the pattern allows for as many as you like, although our implementation assumes one.
##### Benefits Arising From This Approach
@ -116,24 +118,31 @@ I'm going to quote verbatim from Elm's website:
2. Save and Undo become quite easy. Many applications would benefit from the ability to save all application state and send it off to the server so it can be reloaded at some later date. This is extremely difficult when your application state is spread all over the place and potentially tied to objects that cannot be serialized. With a central store, this becomes very simple. Many applications would also benefit from the ability to easily undo user's actions. For example, a painting app is better with Undo. Since everything is immutable in Elm, this is also very easy. Saving past states is trivial, and you will automatically get pretty good sharing guarantees to keep the size of the snapshots down.
##### Background Magic
##### Some Background Magic
Reagent provides a `ratom` (reagent atom) and a `reaction`. These are **two key building blocks**.
Reagent provides a `ratom` and a `reaction`. These are **two key building blocks** for re-frame, so let's make sure we understand them.
Mechanically, `ratoms` are like normal ClojureScript atoms. You can `swap!` and `reset!` them, `watch` them, etc. Mechanically, it holds mutable data. **Conceptually**, though we'll tweak that paradigm ever so slightly. **We view a `ratom` as being a value that changes over time.** This means we'll view it as an FRP [Signal](http://elm-lang.org/learn/What-is-FRP.elm).
`ratoms` behave just like normal ClojureScript atoms. You can `swap!` and `reset!` them, `watch` them, etc.
From a ClojureScript perspective, the purpose of an atom is to hold mutable data. From a re-frame perspective, we'll tweak that paradigm ever so slightly and **view a `ratom` as being a value that changes over time.** Subtle distinction, I know. But the re-frame perspective means meanns we're viewing a `ratom` as an FRP Signal. [Pause and read this](http://elm-lang.org/learn/What-is-FRP.elm).
`reaction` acts a bit like a function. It's a macro which wraps some `computation` (some block of code) and returns a `ratom` containing the result of that `computation`.
The computation performed by a `reaction` may involve dereferencing one or more `ratoms`.
The magic thing about a `reaction` is that the `computation` it wraps will be re-run automatically whenever 'its inputs' change, producing a new output (return) value.
A `reaction` will automatically rerun its `computation` whenever any of these dereferenced `ratoms` change.
So, the `ratom` returned by a `reaction` is itself a Signal. Its value will change over time as its input Signals (the dereferenced `ratoms`) change.
Wait, what, how?
So values can 'flow' into computations and out again, and then into other computations, etc. The result is some sort of signal graph. But our graph will be without cycles, because cycles are bad!
Well, when a `computation` (block of code) dereferences one or more `ratoms`, it will be automatically re-run (recomputing a new retturn value) whenever any of these dereferenced `ratoms` change.
To put it another way, a `reaction` 'notices' what `ratoms` are involved in the `computation` and will watch these `ratoms` and perform a re-computation whenever one of them changes.
So, the `ratom` returned by a `reaction` is itself an FRP Signal. Its value will change over time as the input Signals (the dereferenced `ratoms` in the computation) change.
So, via `ratoms`, values can 'flow' into computations and out again, and then into other computations, etc. The result is the data flows through the Signal graph. But our graph will be without cycles, because cycles are bad! We want unidirectional dataflow.
While the mechanics are different, `reaction` has the intent of `lift` in [Elm] and `defc=` in [Hoplon].
Some code to clarify:
Right, so that was a lot of words. Some code to clarify:
```Clojure
(ns example1
@ -166,7 +175,7 @@ Some code to clarify:
So, in FRP terms, a `reaction` will produce a "stream" of values (it is a Signal), accessible via the `ratom` it returns.
Okay, so that was all important background information for what is to follow. Back to the diagram...
Okay, that was all important background information for what is to follow. Back to the diagram...
### The Components
@ -194,48 +203,50 @@ And if we call it:
;; ==> [:div "Hello ratoms and reactions"]
```
You'll notice that our component is a regular Clojure function, nothing special. In this case, it takes no parameters and it returns a ClojureScript vector (Hiccup).
You'll notice that our component is a regular Clojure function, nothing special. In this case, it takes no parameters and it returns a ClojureScript vector (formated as Hiccup).
Here is a slightly more interesting (parameterised) component (function):
```Clojure
(defn greet ;; greet now has a parameter
[name] ;; 'name' is a ratom containing a string
[:div "Hello " @name]) ;; dereference 'name' here to extract the value it contains
(defn greet ;; greet has a parameter now
[name] ;; 'name' is a ratom holding a string
[:div "Hello " @name]) ;; dereference 'name' to extract the contained value
;; create a ratom, containing a string
(def n (reagent/atom "re-frame"))
;; call our `component` function
;; call our `component` function, passing in a ratom
(greet n)
;; ==> [:div "Hello " "re-frame"] returns a vector
```
So components are easy - they are functions which turn data into Hiccup (which will later become DOM).
Now, we're now going to introduce `reaction` into this mix. On the one hand, I'm complicating things by doing this, because Reagent allows you to be ignorant of the mechanics I'm about to show you. It invisibly wraps your components in a `reaction` allowing you to be blissfully ignorant of how the magic happens.
Now, let's going to introduce `reaction` into this mix. On the one hand, I'm complicating things by doing this, because Reagent allows you to be ignorant of the mechanics I'm about to show you. (It invisibly wraps your components in a `reaction` allowing you to be blissfully ignorant of how the magic happens.)
On the other hand, it is useful to understand exactly how the Signal graph is wired. AND, in a minute, when we get to subscriptions, we ourselves will be actively using `reaction`, so we might as well bite the bullet here and now ... and, anyway, it is easy...
On the other hand, it is useful to understand exactly how the Reagent Signal graph is wired. AND, in a minute, when we get to subscriptions, we'll be directly using `reaction`, so we might as well bite the bullet here and now ... and, anyway, it is easy...
```Clojure
(defn greet
[name] ;; name is a ratom
[:div "Hello " @name]) ;; dereference name here, to extract the value within
(defn greet ;; a component - data in, Hiccup out.
[name] ;; name is a ratom
[:div "Hello " @name]) ;; dereference name here, to extract the value within
(def n (reagent/atom "re-frame"))
;; The computation '(greet n)' returns Hiccup which is stored into 'hiccup-ratom'
(def hiccup-ratom (reaction (greet n))) ;; <-- notice the use of reaction
(def hiccup-ratom (reaction (greet n))) ;; <-- use of reaction !!!
;; what is the result of the initial computation ?
(println @hiccup-ratom)
;; ==> [:div "Hello " "re-frame"] ;; returns hiccup (a plain old vector of stuff)
;; now change 'n'
;; 'n' is an input signal for the reaction above.
;; 'n' is an input Signal for the reaction above.
;; Warning: 'n' is not an input signal because it is a parameter. Rather, it is
;; because 'n' is dereferenced within the execution of the reaction's code.
(reset! n "blah") ;; change n to a new value
;; because 'n' is dereferenced within the execution of the reaction's computation.
;; reaction notices what ratoms are dereferenced in its computation, and watches
;; them for changes.
(reset! n "blah") ;; n gets a new value
;; The reaction will be rerun...
;; ... 'hiccup-ratom' will be reset! to the new value
@ -243,26 +254,25 @@ On the other hand, it is useful to understand exactly how the Signal graph is wi
;; ==> [:div "Hello " "blah"] ;; yep, there's the new value
```
So, as `n` changes value over time (it is a Signal), the output of the computation `(greet n)` changes, and so too the value in `hiccup-ratom` changes (it is a Signal).
So, as `n` changes value over time (via `reset!`), the output of the computation `(greet n)` changes, which in turn means that the value in `hiccup-ratom` changes. Both `n` and `hiccup-ratom` are FRP Signals.
This is one-way data flow, with FRP-nature.
### Truth Interlude
I haven't been entirely straight with you:
1. Reagent re-runs `reactions` (re-computations) via requestAnimationFrame. So a recomputation happens about 16ms after the need for it is detected, or after the current thread of processing finishes, whichever is the greater. So if you are in a bREPL and you run the lines of code above one after the other too quickly, you might not see the re-computation done immediately after `n` gets reset!, because the animationFrame hasn't run (yet). You could add a `(reagent.core/flush)` after the reset! to force re-computation to happen straight away.
1. Reagent re-runs `reactions` (re-computations) via requestAnimationFrame. So a recomputation happens about 16ms after the need for it is detected, or after the current thread of processing finishes, whichever is the greater. So if you are in a bREPL and you run the lines of code above one after the other too quickly, you might not see the re-computation done immediately after `n` gets reset!, because the next animationFrame hasn't run (yet). But you could add a `(reagent.core/flush)` after the reset! to force re-computation to happen straight away.
2. `reaction` doesn't actually return a `ratom`. But it returns something that has ratom-nature, so we'll happily continue believing it is a `ratom` and no harm will come to us.
On with the rest of my lies and distortions...
### Components Like Templates?
A `component` like `greet` is a bit like the templates you'd find in frameworks
like Django or Rails or Mustache -- it maps data to HTML -- except for two massive differences:
- you have the full power of ClojureScript available to you (generating a Clojure data structure). The downside is that these are not "designer friendly" HTML templates.
A `component` like `greet` is like the templates you'd find in
Django, Rails, Express or Mustache -- it maps data to HTML -- except for two massive differences:
- you have the full power of ClojureScript available to you (generating a Clojure data structure). The downside is that these are not "designer friendly" HTML templates.
- these components are reactive. When their input Signals change, they
are automatically rerun, producing new Hiccup (fresh DOM!). Reagent adroitly shields you from
the details, but `components` are wrapped by a `reaction`.
are automatically rerun, producing new Hiccup (fresh DOM!). Reagent adroitly shields you from the details, but `components` are wrapped by a `reaction`.
### React etc.
@ -279,8 +289,8 @@ app-db --> components --> Hiccup --> Reagent --> VDOM --> React --> D
Best to imagine this process as a pipeline of 3 functions. Each
function takes data from the
previous step, and produces data for the next step. In the next
diagram, the three functions are marked. The unmarked nodes are data,
produced by one step, which become input to the next step. Hiccup,
diagram, the three functions are marked (f1, f2, f3). The unmarked nodes are data,
produced by one step, to be input to the following step. Hiccup,
VDOM and DOM are all various forms of HTML markup (in our world that's data).
```
@ -288,7 +298,7 @@ app-db --> components --> Hiccup --> Reagent --> VDOM --> React -->
f1 f2 f3
```
In abstract, Clojure syntax terms, you could squint and imagine the process as:
In abstract ClojureScript syntax terms, you could squint and imagine the process as:
```Clojure
(-> app-db
@ -297,9 +307,9 @@ In abstract, Clojure syntax terms, you could squint and imagine the process as:
React) ;; produces HTML (which magically and efficiently appears on the page).
```
Via `ratom` and `reaction`, changes to `app-db` are pushed into the pipeline, causing new DOM to pop out the other end, and display on our page.
Via `ratom` and `reaction`, changes to `app-db` are pushed into the pipeline, causing new DOM to pop out the other end, and be displayed on our page.
But, just to be clear, we don't have to bother ourselves with most of the pipeline. We just write the `components` part (pure functions) and Reagent/React looks after the rest.
But we don't have to bother ourselves with most of the pipeline. We just write the `components` and Reagent/React will look after the rest.
### Subscribe
@ -310,30 +320,32 @@ app-db --> components
```
So let's pause to consider **our dream solution** for this part of the flow. `components` would:
* obtain data from `app-db` (their job is to turn this data into Hiccup).
* obtain data from `app-db` (their job is to turn this data into hiccup).
* obtain this data via a (possibly parameterised) query over `app-db`. Think database kinda query.
* automatically recompute their Hiccup output, as the data returned by the query changes, over time.
* automatically recompute their hiccup output, as the data returned by the query changes, over time.
* use declarative queries. Components should know as little as possible about the data structure in `app-db`. SQL? Datalog?
re-frame's `subscriptions` are an attempt to live this dream. As you'll see, they fall short on a couple of points, but they're not too bad.
As the app developer, your job is to write and register one or more "subscription handlers" (functions that do a query). Your subscription functions must return a value that changes over time (Signal). i.e. they'll be returning a reaction (`ratom`).
As a re-frame app developer, your job is to write and register one or more "subscription handlers" (functions that do a named query). Your subscription functions must return a value that changes over time (a Signal). I.e. they'll be returning a reaction (`ratom`).
Rules:
- `components` never source data directly from `app-db`, and instead, they use a subscription.
- subscriptions are only ever used by components (they are never used in event handlers).
- subscriptions are only ever used by components (they are never used in, say, event handlers).
Here's a component using a subscription:
```Clojure
(defn greet ;; outer, setup function, called once
[]
(let [name-ratom (subscribe [:name-query])] ;; <---- subscribe here
(let [name-ratom (subscribe [:name-query])] ;; <---- subscribing happens here
(fn [] ;; the inner, render function, potentially called many times.
[:div "Hello" @name-ratom])))
```
First, note this is a form-2 `component` (there are 3 forms). Previously above, we've used the simplest, form-1 components (no setup was required, just render). With form-2, there's a function returning a function:
First, note this is a [Form-2](https://github.com/reagent-project/reagent/wiki/Creating-Components#form-2--functions-returning-a-function) `component` ([there are 3 forms](https://github.com/reagent-project/reagent/wiki/Creating-Components)).
Above, we've used the simplest, Form-1 components (no setup was required, just render). With Form-2, there's a function returning a function:
- the returned function is the render function. Behind the scenes, Reagent will wrap this render function in a `reaction` to make it produce new Hiccup when its inputs change. In our case, that means it will rerun every time `name-ratom` changes.
- the outer function is a setup function, called once to initialise the component. Notice the use of 'subscribe' with the parameter `:name-query`. That creates a Signal through which new values are supplied over time.
@ -343,7 +355,7 @@ First, note this is a form-2 `component` (there are 3 forms). Previously above,
(subscribe [query-id some optional query parameters])
```
There is only one subscribe function. We must register our `handlers` with it.
There is only one `subscribe` function. We must register our `handlers` with it.
The first element in the vector (`query-id`) identifies the query and the other elements are optional, query parameters. With a traditional database a query might be:
@ -353,9 +365,9 @@ select * from customers where name="blah"
In re-frame land, that would be done as follows:
(subscribe [:customer-query "blah"])
which would return a `ratom` holding the customer state (might change over time!).
which would return a `ratom` holding the customer state (a value which might change over time!).
Of course, for this to work, we must write and register a handler for `:customer-query`
For this to work, we must write and register a subscription handler for `:customer-query`
```Clojure
(defn customer-query ;; a query over 'app-db' which returns a customer
@ -365,16 +377,16 @@ Of course, for this to work, we must write and register a handler for `:customer
;; register our query handler
(register
:customer-query ;; the id
customer-query) ;; the query function
:customer-query ;; the id (the name of the query()
customer-query) ;; the function which will perform the query
```
**Note**: `components` tend to be organised into a hierarchy, often with data flowing from parent to child via parameters. So not every component needs a subscription.
**Note**: `components` tend to be organised into a hierarchy, often with data flowing from parent to child via parameters. So not every component needs a subscription. Often the values passed in from a parent component are sufficient.
**Rule**: subscriptions can only be used in form-2 components and the subscription must be in the outer setup function and not in the inner render function. So the following is **wrong** (compare to the correct version above)
**Rule**: subscriptions can only be used in `Form-2` components and the subscription must be in the outer setup function and not in the inner render function. So the following is **wrong** (compare to the correct version above)
```Clojure
(defn greet ;; a form-1 component - no inner render function
(defn greet ;; a Form-1 component - no inner render function
[]
(let [name-ratom (subscribe [:name-query])] ;; Eek! subscription in render part
[:div "Hello" @name-ratom]))
@ -382,9 +394,9 @@ Of course, for this to work, we must write and register a handler for `:customer
### The Signal Graph
Getting more complicated...
A bigger example ...
Imagine our `app-db` contains some `items` (a vector of maps). And imagine that we must display these items sorted by one of their attributes. We could write this query-handler:
Imagine that our `app-db` contains some `items` - a vector of maps. And imagine that we must display these items sorted by one of their attributes. We could write this query-handler:
```Clojure
(register
@ -392,14 +404,14 @@ Imagine our `app-db` contains some `items` (a vector of maps). And imagine that
(fn [db [_ sort-kw]] ;; sort-kw is a ratom, contains a keyword.
(assert (keyword? @sort-kw))
(reaction
(let [items (get-in @db [:some :path :items])] ;; get the items
(sort-by @sort-kw items))))) ;; return them sorted
(let [items (get-in @db [:some :path :items])] ;; exrtact items from db
(sort-by @sort-kw items))))) ;; return them sorted
```
First, notice that this reaction involves 2 input Signals: db and sort-kw.
If either changes, the query is re-run. That means it will be re-run if the items change OR the sort attribute changes.
First, notice that this reaction involves 2 input Signals: `db` and `sort-kw`.
If either changes, the query is re-run.
We'd use it like this:
In a component, we could use this query via `subscribe`:
```Clojure
(defn items-list ;; outer, setup function, called once
@ -415,9 +427,11 @@ We'd use it like this:
There's a bit going on in that `let`, most of it highly contrived, just so I can show off chained reactions. Okay, okay. All I wanted was an excuse to use the phrase chained reactions.
In reality, the approach taken above is inefficient. Every time `app-db` changes, the `:sorted-items` query is going to be re-run and it's going to re-sort items. But items might not have changed since last time. Some other part of `app-db` may have changed. We don't want to re-sort items each time something unrelated changes.
While contrived, the calculation of `num` is interesting.
We can fix that up:
In reality, the approach taken above is inefficient. Every time `app-db` changes, the `:sorted-items` query is going to be re-run and it's going to re-sort items. But items might not have changed. Some other part of `app-db` may have changed. We don't want to re-sort items each time something unrelated changes.
We can fix that up by slightly changing our subscription function:
```Clojure
(register
@ -428,9 +442,11 @@ We can fix that up:
(reaction (sort-by @sort-kw @items))))) ;; reaction #2
```
Be aware that the second reaction will only be triggered if `items` does not test `identical?` to the previous value. **Yes, that sort of optimisation is built into chain `reactions`.** Which means the component render function (which is wrapped in another reaction) won't rerun if `app-db` changes, unless items changes. Now we're very efficient.
So now there's one reaction which uses the output of the another reaction.
If I were doing this for real (rather than just demoing possibilities), I'd probably create a simple subscription for items (unsorted), and then do the sort in the component itself (as a reaction, similar to how 'num' is done in the example above). After all, it is the component which needs to show sorted, so it should do that work.
Be aware that the second reaction will only be triggered if `@items` does not test `identical?` to the previous value. **Yes, that sort of optimisation is built into chain `reactions`.** Which means the component render function (which is wrapped in another reaction) won't rerun if `app-db` changes, unless items changes. Now we're very efficient.
If I were doing this for real (rather than just showing possibilities), I'd probably create a simple subscription for items (unsorted), and then do the sort in the component itself (as a reaction, similar to how `num` was done in the example above). After all, it is the component which needs to show sorted, so it should explicitly do that work.
Summary:
- you can chain reactions.
@ -447,6 +463,8 @@ While the first flow has FRP-nature, the 2nd flow does not.
When I think about these two flows, I imagine [one of those school diagrams](http://thumbnails-visually.netdna-ssl.com/water-cycle_521f29b8b6271_w1500.png) showing the water cycle. Rivers taking water down to the oceans, and evaporation/clouds taking water back over the mountains to fall again as rain. Repeat.
There is a cycle, but there's two kinds of flows.
### Event Flow
In response to user interaction, a DOM will generate
@ -471,7 +489,9 @@ app-db --> components --> Hiccup --> Reagent --> VDOM --> React -->
```
Generally, when the user manipulates the GUI, the state of the application changes. In our case,
that means the `app-db` will change. After all, it **is** the state. And the DOM presented to the user is a function of that state. So that tends to be the cycle: DOM events dispatch, handlers manage them, which cause `app-db` changes, which then cause a re-render, and the users sees something different. That's our water cycle.
that means the `app-db` will change. After all, it **is** the state. And the DOM presented to the user is a function of that state.
So that tends to be the cycle: DOM events dispatch, handlers manage them, which cause `app-db` changes, which then cause a re-render, and the users sees something different. That's our water cycle.
So handlers, which look after events, are the part of the system which do `app-db` mutation. You
could almost imagine them as a "stored procedure" in a
@ -482,12 +502,12 @@ database analogies.
Events are data. You choose the format.
Our implementation chooses a vector format. For example:
Our reference implementation chooses a vector format. For example:
[:delete-item 42]
The first item in the vector identifies the event and
the rest of the vector is the optional parameters -- in this case, the id (42) of the item to delete.
the rest of the vector is the optional parameters -- in the example above, the id (42) of the item to delete.
Here are some other example events:
@ -520,9 +540,9 @@ Notice the `on-click` handler:
With re-frame, we try to keep the DOM as passive as possible. It is simply a rendering of `app-db`. So that "on-click" is a simple as we can make it.
There is a single `dispatch` function in the entire app, and it takes only one parameter, the event vector.
There is a single `dispatch` function in the entire framework, and it takes only one parameter, the event vector.
Let's update our diagram to show dispatch:
Let's update our diagram to show `dispatch`:
```
app-db --> components --> Hiccup --> Reagent --> VDOM --> React --> DOM
@ -531,20 +551,20 @@ app-db --> components --> Hiccup --> Reagent --> VDOM --> React -->
handlers <---------------------------------------- (dispatch [event-id other params])
```
**Rule**: `components` are as passive as possible when it comes to handling events. Do the minimum. On the other hand, `components` can be as complex as needed when it comes to creating the visuals.
**Rule**: `components` are as passive as possible when it comes to handling events. They shoud do the minimum in this regard. On the other hand, `components` can be as complex as needed when it comes to creating the visuals.
### Event Handlers
Collectively, event handlers provide the control logic in the applications.
Collectively, event handlers provide the control logic in a re-frame application.
Almost all event handlers mutate `app-db` in some way. Adding an item here, or deleting that one there. So often CRUD, but sometimes much more. Sometimes with async results.
Almost all event handlers mutate `app-db` in some way. Adding an item here, or deleting that one there. So, often CRUD, but sometimes much more, and sometimes with async results.
Even though handlers appear to be about `app-db` mutation, re-frame requires them to be pure functions with a signature of:
```
(state-of-app-db, event-vector) -> new-state
```
re-frame passes to an event handler two parameters: the current state of `app-db` plus the event, and the job of a handler to return a modified version of the state (which re-frame will then put back into the `app-db`). XXX currently not true but it will be shortly. **[TODO: You have XXX here???]**
re-frame passes to an event handler two parameters: the current state of `app-db` plus the event, and the job of a handler to return a modified version of the state (which re-frame will then put back into the `app-db`). **XXX currently not true but it will be shortly.**
```Clojure
(defn handle-delete
@ -556,35 +576,34 @@ Because handlers are pure functions, and because they generally only have to han
### Routing
`dispatch` has to call the right handler. Handlers have to be registered.
`dispatch` has to call the right handler for each event. Named event handlers have to be registered.
```Clojure
(register
:delete-item ;; the event id
:delete-item ;; the event id (name)
handle-delete) ;; the handler function for that event
```
### State Transition
Above, I commented that collectively, handlers represent the control layer of the application.
Above, I commented that collectively handlers represent the control layer of the application.
Most of what they do is to manage state transitions. The application is in state X, and event Y arrives, so the handler moves the app to state Z.
Most of what they do is to manage state transitions. Eg: the application is in state X, and event E arrives, so the handler moves the app to state Y.
Although I've done nothing to try and implement it, this is obviously fertile territory for using [statecharts](http://www.amazon.com/Constructing-User-Interface-Statecharts-Horrocks/dp/0201342782).
Although I've done nothing to try and implement it yet, this appears beautifully setup for using [statecharts](http://www.amazon.com/Constructing-User-Interface-Statecharts-Horrocks/dp/0201342782).
### Talking To The Server
### Talking To A Server
Some events handlers will need to initiate an async server connection (e.g. GET or POST something).
The event handlers should organise that the `on-success` or `on-fail` handlers for these HTTP requests themselves simply dispatch an event.
But also, note that you can't dispatch while inside of a handler, unless it is async. Why? Because handlers are given a snapshot of the `app-db`.
The initiating event handlers should organise that the `on-success` or `on-fail` handlers for these HTTP requests themselves simply dispatch an event.
**Notes**:
- all events are handled via a call to `dispatch`. GUI events, async HTTP events, everything.
- because of the name `dispatch`, you might mistkenly think this is somehow async. In our implementation, it isn't. Its just a function call.
- If the handler does a lot of work and hogs the thread, this will freeze the GUI. XXX Nice Solution needed.
- a handler istelf can't dispatch synchronously. It can kick off an HTTP request and organise for the on-success handler to dispatch, but that is async. (With a bit of work this rule could be relaxed, if it was found to be necessary).
- `dispatch` will cause a handler functon to be called. But the process is async. The call is queued.
- if you (further) dispatch in handler, then that will be async too. The associated handler is queued for calling later. Why? Partially because handlers are given a snapshot of the `app-db` and can't be nested.
- if you kick off an HTTP request in a handler, then organise for the on-success or on-fail handlers to dispatch their outcome. All events are handled via dispatch.
- if a handler does a lot of work and hogs the thread, this will freeze the GUI because browsers only give us one execution thrrad . **XXX Nice Solution needed. **
### In Summary
@ -594,6 +613,9 @@ To build an app using re-frame, you'll have to:
- write and register subscription functions (query layer).
- write component functions (view layer).
- write and register event handler functions (control layer and/or state transition layer).
All the parts are lovely and simple. And they plug together nicely.
[SPAs]:http://en.wikipedia.org/wiki/Single-page_application
[Reagent]:http://reagent-project.github.io/
@ -606,4 +628,4 @@ To build an app using re-frame, you'll have to:
[datascript]:https://github.com/tonsky/datascript
[Hoplon]:http://hoplon.io/
[Pedestal App]:https://github.com/pedestal/pedestal-app
[Herbert Schema]:https://github.com/miner/herbert
[Herbert Schema]:https://github.com/miner/herbert