mirror of https://github.com/status-im/reagent.git
Update new documentation to be in line with @mike-thompson-day8 recommendations; (#2)
This commit is contained in:
Matthew Jaoudi
jmlsf
parent
7ab3101ff7
commit
cb5a3a3532
|
|
@ -0,0 +1,122 @@
|
|||
# Batching and Timing: How Reagent Renders Changes to Application State
|
||||
|
||||
Changes in application state (as represented by Reagent’s `atom`s) are not rendered immediately to the DOM. Instead, Reagent waits until the browser is ready to repaint the window, and then all the changes are rendered in one single go.
|
||||
|
||||
This is good for all sorts of reasons:
|
||||
|
||||
* Reagent doesn't have to spend time doing renderings that no one would ever see (because changes to application state happened faster than the browser could repaint).
|
||||
* If two or more atoms are changed simultaneously, this now leads to only one re-rendering, and not two.
|
||||
* The new code does proper batching of renderings even when changes to atoms are done outside of event handlers (which is great for e.g core.async users).
|
||||
* Repaints can be synced by the browser with for example CSS transitions, since Reagent uses requestAnimationFrame to do the batching. That makes for example animations smoother.
|
||||
|
||||
In short, Reagent renders less often, but at the right times. For a much better description of why async rendering is good, see David Nolen’s [excellent explanation here.](http://swannodette.github.io/2013/12/17/the-future-of-javascript-mvcs/)
|
||||
|
||||
## The bad news
|
||||
|
||||
Lunches in general tend to be non-free, and this is no exception. The downside to async rendering is that you can no longer depend on changes to atoms being immediately available in the DOM. (Actually, you couldn't have truly relied upon it anyway because React.js itself does batching inside event handlers.)
|
||||
|
||||
The biggest impact is in testing: be sure to call `reagent.core/flush` to force Reagent to synchronize state with the DOM.
|
||||
|
||||
## An example
|
||||
|
||||
Here is an example to (hopefully) demonstrate the virtues of async rendering. It consists of a simple color chooser (three sliders to set the red, green and blue components of a base color), and shows the base color + a bunch of divs in random matching colors. As soon as the base color is changed, a new set of random colors is shown.
|
||||
|
||||
If you change one of the base color components, the base color should change immediately, and smoothly (on my Macbook Air, rendering takes around 2ms, with 20 colored divs showing).
|
||||
|
||||
But perhaps more interesting is to see what happens when the updates can’t be made smoothly (because the browser simply cannot re-render the colored divs quickly enough). On my machine, this starts to happen if I change the number of divs shown to above 150 or so.
|
||||
|
||||
As you increase the number of divs, you’ll notice that the base color no longer changes quite so smoothly when you move the color sliders.
|
||||
|
||||
But the crucial point is that the sliders **still work**. Without async rendering, you could quickly get into a situation where the browser hangs for a while, doing updates corresponding to an old state.
|
||||
|
||||
With async rendering, the only thing that happens is that the frame rate goes down.
|
||||
|
||||
Btw, I find it quite impressive that React manages to change 500 divs (12 full screens worth) in slightly more than 40ms. And even better: when I change the number of divs shown, it only takes around 6ms to re-render the color palette (because the individual divs don’t have to be re-rendered, divs are just added or removed from the DOM as needed).
|
||||
|
||||
```clojure
|
||||
(ns example
|
||||
(:require [reagent.core :as r]))
|
||||
(defn timing-wrapper [f]
|
||||
(let [start-time (r/atom nil)
|
||||
render-time (r/atom nil)
|
||||
now #(.now js/Date)
|
||||
start #(reset! start-time (now))
|
||||
stop #(reset! render-time (- (now) @start-time))
|
||||
timed-f (with-meta f
|
||||
{:component-will-mount start
|
||||
:component-will-update start
|
||||
:component-did-mount stop
|
||||
:component-did-update stop})]
|
||||
(fn []
|
||||
[:div
|
||||
[:p [:em "render time: " @render-time "ms"]]
|
||||
[timed-f]])))
|
||||
|
||||
(def base-color (r/atom {:red 130 :green 160 :blue 120}))
|
||||
(def ncolors (r/atom 20))
|
||||
(def random-colors (r/atom nil))
|
||||
|
||||
(defn to-rgb [{:keys [red green blue]}]
|
||||
(let [hex #(str (if (< % 16) "0")
|
||||
(-> % js/Math.round (.toString 16)))]
|
||||
(str "#" (hex red) (hex green) (hex blue))))
|
||||
|
||||
(defn tweak-color [{:keys [red green blue]}]
|
||||
(let [rnd #(-> (js/Math.random) (* 256))
|
||||
tweak #(-> % (+ (rnd)) (/ 2) js/Math.floor)]
|
||||
{:red (tweak red) :green (tweak green) :blue (tweak blue)}))
|
||||
|
||||
(defn reset-random-colors [color]
|
||||
(reset! random-colors
|
||||
(repeatedly #(-> color tweak-color to-rgb))))
|
||||
|
||||
(defn color-choose [color-part]
|
||||
[:div.color-slider
|
||||
(name color-part) " " (color-part @base-color)
|
||||
[:input {:type "range" :min 0 :max 255
|
||||
:value (color-part @base-color)
|
||||
:on-change (fn [e]
|
||||
(swap! base-color assoc
|
||||
color-part (-> e .-target .-value int))
|
||||
(reset-random-colors @base-color))}]])
|
||||
|
||||
(defn ncolors-choose []
|
||||
[:div.color-slider
|
||||
"number of color divs " @ncolors
|
||||
[:input {:type "range" :min 0 :max 500
|
||||
:value @ncolors
|
||||
:on-change #(reset! ncolors (-> % .-target .-value int))}]])
|
||||
|
||||
(defn color-plate [color]
|
||||
[:div.color-plate
|
||||
{:style {:background-color color}}])
|
||||
|
||||
(defn palette []
|
||||
(let [color @base-color
|
||||
n @ncolors]
|
||||
[:div
|
||||
[:p "base color: "]
|
||||
[color-plate (to-rgb color)]
|
||||
[:div.color-samples
|
||||
[:p n " random matching colors:"]
|
||||
(map-indexed (fn [k v]
|
||||
^{:key k} [color-plate v])
|
||||
(take n @random-colors))]]))
|
||||
|
||||
(defn color-demo []
|
||||
(reset-random-colors @base-color)
|
||||
(fn []
|
||||
[:div
|
||||
[:h2 "Matching colors"]
|
||||
[color-choose :red]
|
||||
[color-choose :green]
|
||||
[color-choose :blue]
|
||||
[ncolors-choose]
|
||||
[timing-wrapper palette]]))
|
||||
```
|
||||
|
||||
## Tapping into the rendering loop
|
||||
|
||||
The `next-tick` function allows you to tap into the rendering loop. The function passed to `next-tick` is invoked immediately before the next rendering (which is in turn triggered using `requestAnimationFrame`).
|
||||
|
||||
The `after-update` is similar: it works just like `next-tick`, except that the function given is invoked immediately after the next rendering.
|
||||
|
|
@ -212,3 +212,46 @@ Here's some further notes about Reagent's mechanics:
|
|||
- Reagent will just interpret it. So this is what happens in the case of a `Form-1` function.
|
||||
- If, however, this render function returns another function - ie. it is a `Form-2` outer function returning the inner function - then Reagent knows to replace the Component's render function with the newly returned inner function forever thereafter. So the outer will have been called once but, from that point forward, the inner function will be used for all further rendering. In fact, Reagent will instantly call the inner function after the outer returns it, because Reagent wants a first rendering (hiccup) for the component.
|
||||
5. So, in the case of `Form-2`, the outer function is called once and once only (with initial props/parameters), and the inner is called at least once (with initial props/parameters), but probably many, many times thereafter. Both will be called with the same arrangement of props/parameters - although the inner render function will see different values in those props/parameters, over time.
|
||||
|
||||
## Appendix B - with-let macro
|
||||
|
||||
The `with-let` macro looks just like `let` – but the bindings **only execute once**, and it takes an optional `finally` clause, that runs when the component is no longer rendered. This can be particularly useful because it can prevent the need for a form-2 component in many instances (like creating a local reagent atom in your component).
|
||||
|
||||
For example: here's a component that sets up an event listener for mouse moves, and stops listening when the component is removed.
|
||||
|
||||
```clojure
|
||||
(defn mouse-pos-comp []
|
||||
(r/with-let [pointer (r/atom nil)
|
||||
handler #(swap! pointer assoc
|
||||
:x (.-pageX %)
|
||||
:y (.-pageY %))
|
||||
_ (.addEventListener js/document "mousemove" handler)]
|
||||
[:div
|
||||
"Pointer moved to: "
|
||||
(str @pointer)]
|
||||
(finally
|
||||
(.removeEventListener js/document "mousemove" handler))))
|
||||
```
|
||||
|
||||
The same thing could of course be achieved with React lifecycle methods, but that would be a lot more verbose.
|
||||
|
||||
`with-let` can also be combined with `track` (and other Reactive contexts). For example, the component above could be written as:
|
||||
|
||||
```clojure
|
||||
(defn mouse-pos []
|
||||
(r/with-let [pointer (r/atom nil)
|
||||
handler #(swap! pointer assoc
|
||||
:x (.-pageX %)
|
||||
:y (.-pageY %))
|
||||
_ (.addEventListener js/document "mousemove" handler)]
|
||||
@pointer
|
||||
(finally
|
||||
(.removeEventListener js/document "mousemove" handler))))
|
||||
|
||||
(defn tracked-pos []
|
||||
[:div
|
||||
"Pointer moved to: "
|
||||
(str @(r/track mouse-pos))])
|
||||
```
|
||||
|
||||
The `finally` clause will run when mouse-pos is no longer tracked anywhere, i.e in this case when tracked-pos is unmounted.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,166 @@
|
|||
# Interop with React
|
||||
|
||||
A little understanding of what reagent is doing really helps when trying to use React libraries and reagent together.
|
||||
|
||||
## Creating React Elements directly
|
||||
|
||||
The `reagent.core/create-element` function simply calls React's `createElement` function (and therefore, it expects either a string representing an HTML element or a React Component).
|
||||
|
||||
As an example, here are four ways to create the same element:
|
||||
|
||||
```clojure
|
||||
(defn integration []
|
||||
[:div
|
||||
[:div.foo "Hello " [:strong "world"]]
|
||||
|
||||
(r/create-element "div"
|
||||
#js{:className "foo"}
|
||||
"Hello "
|
||||
(r/create-element "strong"
|
||||
#js{}
|
||||
"world"))
|
||||
|
||||
(r/create-element "div"
|
||||
#js{:className "foo"}
|
||||
"Hello "
|
||||
(r/as-element [:strong "world"]))
|
||||
|
||||
[:div.foo "Hello " (r/create-element "strong"
|
||||
#js{}
|
||||
"world")]])
|
||||
(defn mount-root []
|
||||
(reagent/render [integration]
|
||||
(.getElementById js/document "app")))
|
||||
```
|
||||
|
||||
This works because `reagent/render` itself expects (1) a React element or (2) a Hiccup form. If passed an element, it just uses it. If passed a Hiccup, it creats a (cached) React component and then creates an element from that component.
|
||||
|
||||
## Creating React Elements from Hiccup forms
|
||||
|
||||
The `reagent.core/as-element` function creates a React element from a Hiccup form. In the previous section, we discussed how `reagent/render` expects either (1) a Hiccup form or (2) a React Element. If it encounters a Hiccup form, it calls `as-element` on it. When you have a React component that wraps children, you can pass Hiccup forms to it wrapped in `as-element`.
|
||||
|
||||
## Creating Reagent "Components" from React Components
|
||||
|
||||
The function `reagent/adapt-react-class` will turn a React Component into something that can be placed into the first position of a Hiccup form, as if it were a Reagent function. Take, for example the react-flip-move library and assume that it has been properly imported as a React Component called `FlipMove`. By wrapping FlipMove with `adapt-react-class`, we can use it in a Hiccup form:
|
||||
|
||||
```clojure
|
||||
(defn top-articles [articles]
|
||||
[(reagent/adapt-react-class FlipMove)
|
||||
{:duration 750
|
||||
:easing "ease-out"}
|
||||
articles]
|
||||
```
|
||||
|
||||
There is also a convenience mechanism `:>` (colon greater-than) that shortens this and avoid some parenthesis:
|
||||
|
||||
```clojure
|
||||
(defn top-articles [articles]
|
||||
[:> FlipMove
|
||||
{:duration 750
|
||||
:easing "ease-out"}
|
||||
articles]
|
||||
```
|
||||
|
||||
This is the equivalent JavaScript:
|
||||
|
||||
```clojure
|
||||
const TopArticles = ({ articles }) => (
|
||||
<FlipMove duration={750} easing="ease-out">
|
||||
{articles}
|
||||
</FlipMove>
|
||||
);
|
||||
```
|
||||
|
||||
## Creating React Components from Reagent "Components"
|
||||
|
||||
The `reagent/reactify-component` will take a Form-1, Form-2, or Form-3 reagent "component". For example:
|
||||
|
||||
```clojure
|
||||
(defn exported [props]
|
||||
[:div "Hi, " (:name props)])
|
||||
|
||||
(def react-comp (r/reactify-component exported))
|
||||
|
||||
(defn could-be-jsx []
|
||||
(r/create-element react-comp #js{:name "world"}))
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
* `adapt-react-class` and `reactify-component` are not perfectly symmetrical, because `reactify-component` requires that the reagent component accept everything in a single props map, including its children.
|
||||
|
||||
## Example: "Decorator" Higher-Order Components
|
||||
|
||||
Some React libraries use the decorator pattern: a React component which takes a component as an argument and returns a new component as its result. One example is the React DnD library. We will need to use both `adapt-react-class` and `reactify-component` to move back and forth between React and reagent:
|
||||
|
||||
```clojure
|
||||
(defn react-dnd-component
|
||||
[]
|
||||
(let [decorator (DragDropContext HTML5Backend)]
|
||||
[(reagent/adapt-react-class
|
||||
(decorator (reagent/reactify-component top-level-component)))]))
|
||||
```
|
||||
|
||||
This is the equivalent javascript:
|
||||
|
||||
```clojure
|
||||
import HTML5Backend from 'react-dnd-html5-backend';
|
||||
import { DragDropContext } from 'react-dnd';
|
||||
|
||||
class TopLevelComponent {
|
||||
/* ... */
|
||||
}
|
||||
|
||||
export default DragDropContext(HTML5Backend)(TopLevelComponent);
|
||||
```
|
||||
|
||||
## Example: Function-as-child Components
|
||||
|
||||
Some React components expect a function as their only child. React autosizer is one such example.
|
||||
|
||||
```clojure
|
||||
[(reagent/adapt-react-class AutoSizer)
|
||||
{}
|
||||
(fn [dims]
|
||||
(let [dims (js->clj dims :keywordize-keys true)]
|
||||
(reagent/as-element [my-component (:height dims)])))]
|
||||
```
|
||||
|
||||
## Getting props and children of current component
|
||||
|
||||
Because you just pass argument to reagent functions, you typically don't need to think about "props" and "children" as distinct things. But reagent does make a distinction and it is helpful to understand this particularly when interoperating with native elements and React libraries.
|
||||
|
||||
Specifically, if the first argument to your reagent function is a map, that is assigned to `this.props` of the underlying reagent component. All other arguments are assigned as children to `this.props.children`.
|
||||
|
||||
When interacting with native React components, it may be helpful to access props and children, which you can do with `reagent.core/current-component`. This function returns an object that allows you retrieve the props and children passed to the current component.
|
||||
|
||||
Beware that `current-component` is only valid in component functions, and must be called outside of e.g event handlers and for expressions, so it’s safest to always put the call at the top, as in `my-div` here:
|
||||
|
||||
```clojure
|
||||
(ns example
|
||||
(:require [reagent.core :as r]))
|
||||
|
||||
(defn my-div []
|
||||
(let [this (r/current-component)]
|
||||
(into [:div.custom (r/props this)]
|
||||
(r/children this))))
|
||||
|
||||
(defn call-my-div []
|
||||
[:div
|
||||
[my-div "Some text."]
|
||||
[my-div {:style {:font-weight 'bold}}
|
||||
[:p "Some other text in bold."]]])
|
||||
```
|
||||
|
||||
## React Interop Macros
|
||||
|
||||
Reagent provides two utility macros `$` and `$!` for getting and setting javascript properties in a way that is safe for advanced compilation.
|
||||
|
||||
`($ o :foo)` is equivalent to `(.-foo o)`
|
||||
`($ o foo arg1 arg2)` is the same as `(.foo o arg1 arg2)`
|
||||
|
||||
Similarly,
|
||||
|
||||
`($! o :foo 1)` is equivalent to `(set! (.-foo o) 1)`
|
||||
|
||||
Note, these are not necessary if your JavaScript library has an externs file or if externs inference is on and working.
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
# Managing state: atoms, cursors, Reactions, and tracking
|
||||
|
||||
Although it is possible to update reagent componetns by remounting the entire component tree with `react.core/render`, Reagent comes with a sophisticated state management library based on `reagent.core/atom`, which allows components to track application state and update only when needed. Reagent also provides cursors, which are like ratoms but can be constructed from portions of one or more other ratoms to limit or expand which ratoms a component watches. Finally, Reagent provides a set of tracking primitives called reactions and a set of utility functions to build more customized state management.
|
||||
|
||||
**TODO is this right?**
|
||||
|
||||
## Intro to atoms
|
||||
|
||||
Reagent provides an implementation of atom that you can create with `reagent/atom` and use just like a normal Clojure atom, which are often referred to as "ratoms" to distinguish from normal atoms. Reagent tracks any dereferences to ratoms made during a component's render function.
|
||||
|
||||
```clojure
|
||||
(ns example
|
||||
(:require [reagent.core :as r]))
|
||||
|
||||
(def click-count (r/atom 0))
|
||||
|
||||
(defn counting-component []
|
||||
[:div
|
||||
"The atom " [:code "click-count"] " has value: "
|
||||
@click-count ". "
|
||||
[:input {:type "button" :value "Click me!"
|
||||
:on-click #(swap! click-count inc)}]])
|
||||
```
|
||||
|
||||
### Mutating a ratom
|
||||
|
||||
You manipulate using the standard `reset!` and `swap!` functions.
|
||||
|
||||
```clojure
|
||||
(reset! state-atom {:counter 0})
|
||||
```
|
||||
|
||||
```clojure
|
||||
(swap! state-atom assoc :counter 15)
|
||||
```
|
||||
|
||||
### Dereferencing a ratom
|
||||
|
||||
You access the atom using `deref` or the shorthand `@`.
|
||||
|
||||
```clojure
|
||||
(:counter (deref state-atom))
|
||||
(:counter @state-atom)
|
||||
```
|
||||
|
||||
### The effect of dereferencing a ratom
|
||||
|
||||
* A dereference to the ratom during its render function will cause that component to re-render whenever any part of that ratom is updated. (See the section below on cursors to get finer control over update behavior.)
|
||||
* Dereferencing a ratom in a callback or event handler after the render function has run will not make the component react to any changes to the ratom (though of course any _changes_ to the ratom made in an event handler will make any watching components re-render).
|
||||
|
||||
### rswap!
|
||||
|
||||
`rswap!` works like standard `swap!` except that it
|
||||
|
||||
* always returns `nil`
|
||||
* allows recursive applications of `rswap!` on the same atom
|
||||
|
||||
That makes `rswap!` especially suited for event handling.
|
||||
|
||||
Here’s an example that uses event handling with `rswap!`:
|
||||
|
||||
```clojure
|
||||
(defn event-handler [state [event-name id value]]
|
||||
(case event-name
|
||||
:set-name (assoc-in state [:people id :name]
|
||||
value)
|
||||
:add-person (let [new-key (->> state :people keys (apply max) inc)]
|
||||
(assoc-in state [:people new-key]
|
||||
{:name ""}))
|
||||
state))
|
||||
|
||||
(defn emit [e]
|
||||
;; (js/console.log "Handling event" (str e))
|
||||
(r/rswap! app-state event-handler e))
|
||||
|
||||
(defn name-edit [id]
|
||||
(let [p @(r/track person id)]
|
||||
[:div
|
||||
[:input {:value (:name p)
|
||||
:on-change #(emit [:set-name id (.-target.value %)])}]]))
|
||||
|
||||
(defn edit-fields []
|
||||
(let [ids @(r/track person-keys)]
|
||||
[:div
|
||||
[name-list]
|
||||
(for [i ids]
|
||||
^{:key i} [name-edit i])
|
||||
[:input {:type 'button
|
||||
:value "Add person"
|
||||
:on-click #(emit [:add-person])}]]))
|
||||
```
|
||||
|
||||
All events are passed through the emit function, consisting of a trivial application of `rswap!` and some optional logging. This is the only place where application state actually changes – the rest is pure functions.
|
||||
|
||||
The actual event handling is done in event-handler, which takes state and event as parameters, and returns a new state (events are represented by vectors here, with an event name in the first position).
|
||||
|
||||
All the UI components have to do is then just to return some markup, and set up routing of events through the emit function.
|
||||
|
||||
This architecture basically divides the application into two logical functions:
|
||||
|
||||
* The first takes state and an event as input, and returns the next state.
|
||||
|
||||
* The other takes state as input, and returns a UI definition.
|
||||
|
||||
This simple application could probably just as well use the common `swap!` instead of `rswap!`, but using `swap!` in React’s event handlers may trigger warnings due to unexpected return values, and may cause severe headaches if an event handler called by emit itself emits a new event (that would result in lost events, and much confusion).
|
||||
|
||||
For a more structured version of a similar approach, see the excellent re-frame framework.
|
||||
|
||||
**TODO: is this the right example for rswap? If this is just re-frame light, maybe this shouldn't be in here. It would be better to have a more concise example.**
|
||||
|
||||
## Cursors
|
||||
|
||||
Any component that dereferences a state atom will update whenever any part of it is updated. If you are storing all state in a single atom (not uncommon), it will cause every component to update whenever the state is updated. Performance-wise, this may be acceptable, depending on how many elements you have and how often your state updates, because React itself will not manipulate the DOM unless the components actually change.
|
||||
|
||||
Reagent provides cursors, which behave like atoms but operate like pointers into a larger atom (or into multiple parts of multiple atoms).
|
||||
|
||||
Cursors are created with `reagent/cursor`, which takes a ratom and a keypath (like `get-in`):
|
||||
|
||||
```clojure
|
||||
;; First create a ratom
|
||||
(def state (reagent/atom {:foo {:bar "BAR"}
|
||||
:baz "BAZ"
|
||||
:quux "QUUX"}))
|
||||
;; Now create a cursor
|
||||
(def bar-cursor (reagent/cursor state [:foo :bar]))
|
||||
|
||||
(defn quux-component []
|
||||
(js/console.log "quux-component is rendering")
|
||||
[:div (:quux @state)])
|
||||
|
||||
(defn bar-component []
|
||||
(js/console.log "bar-component is rendering")
|
||||
[:div @bar-cursor])
|
||||
|
||||
(defn mount-root []
|
||||
(reagent/render [:div [quux-component] [bar-component]]
|
||||
(.getElementById js/document "app"))
|
||||
(js/setTimeout (fn [] (swap! state assoc :baz "NEW BAZ")) 1000)
|
||||
(js/setTimeout (fn [] (swap! state assoc-in [:foo :bar] "NEW BAR")) 2000))
|
||||
|
||||
|
||||
;; Console output:
|
||||
;; quux-component is rendering
|
||||
;; bar-component is rendering
|
||||
;; After 1 second:
|
||||
;; quux-component is rendering
|
||||
;; After 2 seconds:
|
||||
;; quux-component is rendering
|
||||
;; bar-component is rendering
|
||||
```
|
||||
|
||||
Both `bar-component` and `quux-component` update whenever their respective cursors/atoms update, but because `bar-component`'s cursor is limited only to the relevant portion of the app-state, it only re-renders when `[:foo :bar]` updates, whereas `quux-component` updates each time `app-state` changes, even though `:quux` never changes.
|
||||
|
||||
### More general cursors
|
||||
|
||||
The cursor mechanism is more general than described above. You can pass a function that performs arbitrary transformations on one or more atoms.
|
||||
**TODO (DO WE NEED TO EXPLAIN THIS?)**
|
||||
|
||||
Reagent also provides the `reagent/wrap` mechanism, which also derives a new atom but provides more general functionality. Where a cursor will always update the atom from which it was derived, `reagent/wrap` takes an atom and a callback that will be called whenever the derived atom is updated. Replacing `(r/cursor n [:first-name])` with `(r/wrap first-name swap! n assoc :first-name)]` gives essentially the same results.
|
||||
**TODO (WHAT UTILITY DOES THIS HAVE?)**
|
||||
|
||||
## Reactions
|
||||
|
||||
Reactions are like cursors called with a function.
|
||||
|
||||
When reactions produce a new result (as determined by `=`), they cause other dependent reactions and components to update.
|
||||
|
||||
The function `make-reaction`, and its macro `reaction` are used to create a `Reaction`, which is a type that belongs to a number of protocols such as `IWatchable`, `IAtom`, `IReactiveAtom`, `IDeref`, `IReset`, `ISwap`, `IRunnable`, etc. which make it atom-like: ie it can be watched, derefed, reset, swapped on, and additionally, tracks its derefs, behave reactively, and so on.
|
||||
|
||||
Reactions are what give `r/atom`, `r/cursor`, and function `r/cursor` and `r/wrap` their power.
|
||||
|
||||
`make-reaction` takes one argument, `f`, and an optional options map. The options map specifies what happens to `f`:
|
||||
|
||||
* `auto-run` (boolean) specifies whether `f` run on change
|
||||
* `on-set` and `on-dispose` are run when the reaction is set and unset from the DOM
|
||||
* `derefed` **TODO unclear**
|
||||
|
||||
**TODO EXAMPLE**
|
||||
|
||||
Reactions are executed asynchronously, so be sure to call `flush` if you depend on reaction side effects.
|
||||
|
||||
## The track function
|
||||
|
||||
`reagent.core/track` takes a function, and optional arguments for that function, and gives a derefable (i.e "atom-like") value, containing whatever is returned by that function. If the tracked function depends on a Reagent atom, it is called again whenever that atom changes – just like a Reagent component function. If the value returned by `track` is used in a component, the component is re-rendered when the value returned by the function changes.
|
||||
|
||||
In other words, `@(r/track foo x)` gives the same result as `(foo x)` – but in the first case, foo is only called again when the atom(s) it depends on changes.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```clojure
|
||||
(ns example.core
|
||||
(:require [reagent.core :as r]))
|
||||
(defonce app-state (r/atom {:people
|
||||
{1 {:name "John Smith"}
|
||||
2 {:name "Maggie Johnson"}}}))
|
||||
|
||||
(defn people []
|
||||
(:people @app-state))
|
||||
|
||||
(defn person-keys []
|
||||
(-> @(r/track people)
|
||||
keys
|
||||
sort))
|
||||
|
||||
(defn person [id]
|
||||
(-> @(r/track people)
|
||||
(get id)))
|
||||
|
||||
(defn name-comp [id]
|
||||
(let [p @(r/track person id)]
|
||||
[:li
|
||||
(:name p)]))
|
||||
|
||||
(defn name-list []
|
||||
(let [ids @(r/track person-keys)]
|
||||
[:ul
|
||||
(for [i ids]
|
||||
^{:key i} [name-comp i])]))
|
||||
```
|
||||
|
||||
Here, the name-list component will only be re-rendered if the keys of the :people map changes. Every name-comp only renders again when needed, etc.
|
||||
|
||||
Use of track can improve performance in three ways:
|
||||
|
||||
1. It can be used as a cache for an expensive function, that is automatically updated if that function depends on Reagent atoms (or other tracks, cursors, etc).
|
||||
2. It can also be used to limit the number of times a component is re-rendered. The user of track is only updated when the function’s result changes. In other words, you can use track as a kind of generalized, read-only cursor.
|
||||
3. Every use of track with the same arguments will only result in one execution of the function. E.g the two uses of `@(r/track people)` in the example above will only result in one call to the people function (both initially, and when the state atom changes).
|
||||
|
||||
_Note:_ Compared to reactions, `reagent.ratom/reaction` and `track` are similar. The main differences are that track uses named functions and variables, rather than depending on closures, and that you don’t have to manage their creation manually (since tracks are automatically cached and reused).
|
||||
|
||||
_Note:_ The first argument to track should be a named function, i.e not an anonymous one. Also, beware of lazy data sequences: don’t use deref (i.e ”@”) with the for macro, unless wrapped in doall (just like in Reagent components).
|
||||
|
||||
### The track! function
|
||||
|
||||
`track!` works just like track, except that the function passed is invoked immediately, and continues to be invoked whenever any atoms used within it changes.
|
||||
|
||||
For example, given this function:
|
||||
|
||||
```clojure
|
||||
(defn log-app-state []
|
||||
(prn @app-state))
|
||||
```
|
||||
|
||||
you could use `(defonce logger (r/track! log-app-state))` to monitor changes to app-state. `log-app-state` would continue to run until you stop it, using `(r/dispose! logger)`.
|
||||
|
|
@ -3,9 +3,13 @@
|
|||
|
||||
The Basics:
|
||||
|
||||
1. [Creating Reagent Components](/docs/CreatingReagentComponents.md)
|
||||
2. [Using [square brackets] instead of (parentheses)](/docs/UsingSquareBracketsInsteadOfParens.md)
|
||||
3. [When do components update?](/docs/WhenDoComponentsUpdate.md)
|
||||
1. [Using Hiccup to Describe HTML](/docs/UsingHiccupToDescribeHTML.md)
|
||||
2. [Creating Reagent Components](/docs/CreatingReagentComponents.md)
|
||||
3. [Using [square brackets] instead of (parentheses)](/docs/UsingSquareBracketsInsteadOfParens.md)
|
||||
4. [When do components update?](/docs/WhenDoComponentsUpdate.md)
|
||||
5. [[WIP] Managing State: atoms, cursors, Reactions, and tracking](/docs/ManagingState.md)
|
||||
6. [Batching and Timing: How Reagent Renders Changes to Application State](/docs/BatchingAndTiming.md)
|
||||
7. [Interop with React](/docs/InteropWithReact.md)
|
||||
|
||||
Also:
|
||||
* [purelyfunctional.tv ](https://purelyfunctional.tv/guide/reagent/) - an excellent written tutorial
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,101 @@
|
|||
# Using Hiccup to Describe HTML
|
||||
|
||||
Reagent uses a datastructure known as Hiccup to describe HTML. Hiccup describes HTML elements and user-defined components as a nested ClojureScript vector:
|
||||
|
||||
```clojure
|
||||
[:div {:class "parent"}
|
||||
[:p {:id "child-one"} "I'm first child element."]
|
||||
[:p "I'm the second child element."]]
|
||||
```
|
||||
|
||||
As described below, reagent provides a number of extensions and conveniences to Hiccup, but the general rules of Hiccup are as follows:
|
||||
|
||||
1. The first element is either a keyword or a symbol
|
||||
* If it is a keyword, the element is an HTML element where `(name keyword)` is the tag of the HTML element.
|
||||
* If it is a symbol, reagent will treat the vector as a component, as described in the next section.
|
||||
2. If the second element is a map, it represents the attributes to the element. The attribute map may be omitted.
|
||||
3. Any additional elements must either be Hiccup vectors representing child nodes or string literals representing child text nodes.
|
||||
|
||||
## Special treatment of `nil` child nodes
|
||||
|
||||
Reagent and React ignore nil nodes, which allow conditional logic in Hiccup forms:
|
||||
|
||||
```clojure
|
||||
(defn my-div [child?]
|
||||
[:div
|
||||
"Parent Element"
|
||||
(when child? [:div "Child element"])])
|
||||
```
|
||||
|
||||
In this example `(my-div false)` will evaluate to `[:div "Parent Element" nil]`, which reagent will simply treat the same as `[:div "Parent Element"]`.
|
||||
|
||||
## Special interpretation of `style` attribute
|
||||
|
||||
The `:style` attribute can be written a string or as a map. The following two are equivalent:
|
||||
|
||||
```clojure
|
||||
[:div {:style "color: red; font-weight: bold"} "Alert"]
|
||||
[:div {:style {:color "red"
|
||||
:font-weight "bold"}
|
||||
"Alert"]
|
||||
```
|
||||
|
||||
The map form is the same as [React's style attribute](https://reactjs.org/docs/dom-elements.html#style), except that when using the map form of the style attribute, the keys should be the same name as the CSS attribute as shown in the above example (not camel cased as is required JavaScript).
|
||||
|
||||
## Special interpretation of `class` attribute
|
||||
|
||||
In JavaScript, `class` is a reserved keyword, so React uses the `className` to specify class attibutes. Reagent just uses `class`.
|
||||
|
||||
As of reagent 0.8.0, the `class` attribute accepts a collection of classes and will remove any nil value:
|
||||
|
||||
```clojure
|
||||
[:div {:class ["a-class" (when active? "active") "b-class"]}]
|
||||
```
|
||||
|
||||
## Special notation for nested elements
|
||||
|
||||
Reagent extends standard Hiccup in one way: it is possible to "squeeze" elements together by using a `>` character.
|
||||
|
||||
This:
|
||||
|
||||
```clojure
|
||||
[:div
|
||||
[:p
|
||||
[:b "Nested Element"]]]
|
||||
```
|
||||
|
||||
can be written as:
|
||||
|
||||
```clojure
|
||||
[:div>p>b "Nested Element"]
|
||||
```
|
||||
|
||||
## Rendering Hiccup
|
||||
|
||||
The primary entrypoint to the reagent library is `reagent.core/render`.
|
||||
|
||||
```clojure
|
||||
(ns example
|
||||
(:require [reagent.core :as r]))
|
||||
|
||||
(defn render-simple []
|
||||
(r/render [:div [:p "Hello world!"]]
|
||||
(.-body js/document)))
|
||||
```
|
||||
|
||||
This `render` function expects one of two things:
|
||||
|
||||
1. A React Element, which will just be passed to React as is.
|
||||
2. A ClojureScript vector (i.e., a Hiccup form).
|
||||
|
||||
If it encounters a ClojureScript vector, it will interpret it as Hiccup. Reagent expects one of two things in the first position of the vector:
|
||||
|
||||
1. A keyword like `:div` or `:span`, which it will create using React.createElement
|
||||
2. A symbol like `my-component`.
|
||||
|
||||
If it is symbol, then reagent will evaluate a function by that name. Reagent expects one of three things from this function:
|
||||
|
||||
1. A Hiccup vector. Reagent creates a React component with the function as its render method and uses the Hiccup vector for the initial render.
|
||||
2. A ClojureScript function. Reagent will then create a React component with this inner function as the render method and will then call the inner function for the initial render.
|
||||
3. A React component. Reagent will render this using React.createElement. Note, this could be a result of calling (React.core/create-class) or it could be a React component you have imported from a JavaScript library.
|
||||
|
||||
Loading…
Reference in New Issue