status-im/re-frame
2
0
Fork 0
mirror of https://github.com/status-im/re-frame.git synced 2025-02-23 15:28:09 +00:00
Code Issues Projects Releases Wiki Activity

Tweaks to the readme

Browse Source
This commit is contained in:
mike-thompson-day8 2015-05-03 01:41:16 +10:00
parent 25ed816603
commit 70987e5318
1 changed files with 55 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
README.md
View File

@ -1,4 +1,4 @@
# re-frame: Derived Values, Flowing [![Build Status](https://travis-ci.org/Day8/re-frame.png?branch=master)](https://travis-ci.org/Day8/re-frame) # re-frame: Derived Values, Flowing
> This, milord, is my family's axe. We have owned it for almost nine hundred years, see. Of course, > This, milord, is my family's axe. We have owned it for almost nine hundred years, see. Of course,
@ -23,10 +23,12 @@ Either:
## re-frame ## re-frame
re-frame is a pattern for writing [SPAs] in ClojureScript, using [Reagent]. re-frame is a pattern for writing [SPAs] in ClojureScript, using [Reagent].
This repo contains both a **description of this pattern** and a **reference implementation**. This repo contains both a **description of this pattern** and a **reference implementation**.
To quote McCoy: "It's MVC, Jim, but not as we know it".
To build a re-frame app, you: To build a re-frame app, you:
- design your app's data structure (data layer) - design your app's data structure (data layer)
- write and register subscription functions (query layer) - write and register subscription functions (query layer)
@ -54,13 +56,18 @@ Features:
It also has a charming xkcd reference (soon) It also has a charming xkcd reference (soon)
and a hilarious, insiders-joke T-shirt, ideal for conferences (in design). and a hilarious, insiders-joke T-shirt, ideal for conferences (in design).
What could possibly go wrong? What could possibly go wrong?
## Using It
__Warning__: this is a long document. That was the summary. The rest is a tutorial. [![Build Status](https://travis-ci.org/Day8/re-frame.png?branch=master)](https://travis-ci.org/Day8/re-frame)
[![Clojars Project](http://clojars.org/re-frame/latest-version.svg)](http://clojars.org/re-frame)
__Warning__: okay, that was the summary. What follows is a lengthy tutorial with a [Where Do I Go Next](#Where-Do-I-Go-Next) section at the end.
## Table of Contents ## Tutorial Table of Contents
*generated by [DocToc](https://github.com/thlorenz/doctoc)*
- [What Problem Does It Solve?](#what-problem-does-it-solve) - [What Problem Does It Solve?](#what-problem-does-it-solve)
- [Correct Acronym?](#correct-acronym) - [Correct Acronym?](#correct-acronym)
@ -69,33 +76,34 @@ __Warning__: this is a long document. That was the summary. The rest is a tutor
- [Guiding Philosophy](#guiding-philosophy) - [Guiding Philosophy](#guiding-philosophy)
- [FRP Clarifications](#frp-clarifications) - [FRP Clarifications](#frp-clarifications)
- [Explaining re-frame](#explaining-re-frame) - [Explaining re-frame](#explaining-re-frame)
- [On Data](#on-data) - [On Data](#on-data)
- [The Big Ratom](#the-big-ratom) - [The Big Ratom](#the-big-ratom)
- [The Benefits Of Data-In-The-One-Place](#the-benefits-of-data-in-the-one-place) - [The Benefits Of Data-In-The-One-Place](#the-benefits-of-data-in-the-one-place)
- [Flow](#flow) - [Flow](#flow)
- [How Flow Happens In Reagent](#how-flow-happens-in-reagent) - [How Flow Happens In Reagent](#how-flow-happens-in-reagent)
- [Components](#components) - [Components](#components)
- [Truth Interlude](#truth-interlude) - [Truth Interlude](#truth-interlude)
- [Components Like Templates?](#components-like-templates) - [Components Like Templates?](#components-like-templates)
- [React etc.](#react-etc) - [React etc.](#react-etc)
- [Subscribe](#subscribe) - [Subscribe](#subscribe)
- [Just A Read-Only Cursor?](#just-a-read-only-cursor) - [Just A Read-Only Cursor?](#just-a-read-only-cursor)
- [The Signal Graph](#the-signal-graph) - [The Signal Graph](#the-signal-graph)
- [A More Efficient Signal Graph](#a-more-efficient-signal-graph) - [A More Efficient Signal Graph](#a-more-efficient-signal-graph)
- [The 2nd Flow](#the-2nd-flow) - [The 2nd Flow](#the-2nd-flow)
- [Event Flow](#event-flow) - [Event Flow](#event-flow)
- [What are events?](#what-are-events) - [What are events?](#what-are-events)
- [Dispatching Events](#dispatching-events) - [Dispatching Events](#dispatching-events)
- [Event Handlers](#event-handlers) - [Event Handlers](#event-handlers)
- [Routing](#routing) - [Routing](#routing)
- [Control Via FSM](#control-via-fsm) - [Control Via FSM](#control-via-fsm)
- [As A Reduce](#as-a-reduce) - [As A Reduce](#as-a-reduce)
- [Derived Data, Everywhere, flowing](#derived-data-everywhere-flowing) - [Derived Data, Everywhere, flowing](#derived-data-everywhere-flowing)
- [Logging And Debugging](#logging-and-debugging) - [Logging And Debugging](#logging-and-debugging)
- [Talking To A Server](#talking-to-a-server) - [Talking To A Server](#talking-to-a-server)
- [The CPU Hog Problem](#the-cpu-hog-problem) - [The CPU Hog Problem](#the-cpu-hog-problem)
- [In Summary](#in-summary) - [In Summary](#in-summary)
- [Licence](#licence) - [Where Do I Go Next](#Where-Do-I-Go-Next)
- [Licence](#licence)
## What Problem Does It Solve? ## What Problem Does It Solve?
@ -129,7 +137,7 @@ but not as we know it".
In re-frame, none of the M, V, or C bits are objects, they In re-frame, none of the M, V, or C bits are objects, they
are pure functions (or pure data), are pure functions (or pure data),
and they are all wired together via reactive data flows. It is sufficiently different in nature and they are all wired together via reactive data flows. It is sufficiently different in nature
from (traditional, Smalltalk) MVC that calling it MVC would likely just be confusing. I'd from (traditional, Smalltalk) MVC that calling it MVC would likely just be confusing. So, I'd
love an alternative. love an alternative.
Perhaps it is a RACES framework - Reactive-Atom Component Event Perhaps it is a RACES framework - Reactive-Atom Component Event
@ -146,13 +154,13 @@ insider's joke, conference T-Shirt.
Not much about re-frame is original or clever. You'll find Not much about re-frame is original or clever. You'll find
no ingenious use of functional zippers, transducers or core.async. no ingenious use of functional zippers, transducers or core.async.
Re-frame does use Reagent's features in a slightly novel way. Re-frame does use Reagent's features in a novel way.
And I did actively reject the current ClojureScript fashion of using Cursors. And I did actively reject the current ClojureScript fashion of using
But, for the most part, re-frame is just a mashup of Cursors. And, yes, the event middleware concept has turned out nicely.
But, for the most part, re-frame is simply a mashup of
emerging ideas. emerging ideas.
(For the record, (For the record, one day I'd love to develop something original and clever).
one day I'd love to develop something original and clever).
## Client Side Bias ## Client Side Bias
@ -438,7 +446,7 @@ no parameters and it returns a ClojureScript vector (formatted as Hiccup).
Here is a slightly more interesting (parameterised) component (function): Here is a slightly more interesting (parameterised) component (function):
```Clojure ```Clojure
(defn greet ;; greet has a parameter now (defn greet ;; greet has a parameter now
[name] ;; 'name' is a ratom holding a string [name] ;; 'name' is a ratom holding a string
[:div "Hello " @name]) ;; dereference 'name' to extract the contained value [:div "Hello " @name]) ;; dereference 'name' to extract the contained value
@ -463,7 +471,7 @@ because in a minute, when we get to `subscriptions`, we'll be directly using `re
might as well bite the bullet here and now ... and, anyway, it is pretty easy... might as well bite the bullet here and now ... and, anyway, it is pretty easy...
```Clojure ```Clojure
(defn greet ;; a component - data in, Hiccup out. (defn greet ;; a component - data in, Hiccup out.
[name] ;; name is a ratom [name] ;; name is a ratom
[:div "Hello " @name]) ;; dereference name here, to extract the value within [:div "Hello " @name]) ;; dereference name here, to extract the value within
@ -1092,7 +1100,7 @@ How did that exception happen, you wonder, shaking your head? What did the user
to the exception? What state was the app in that this event was so disastrous? to the exception? What state was the app in that this event was so disastrous?
To debug it, you need to know this information: To debug it, you need to know this information:
1. the state the app immediately before the exception 1. the state of the app immediately before the exception
2. What final event then caused your app to fall in a screaming mess. 2. What final event then caused your app to fall in a screaming mess.
Well, with re-frame you need to record (have available): Well, with re-frame you need to record (have available):
@ -1169,6 +1177,19 @@ To build an app using re-frame, you'll have to:
- write and register event handler functions (control layer and/or state transition layer). - write and register event handler functions (control layer and/or state transition layer).
### Where Do I Go Next?
Your next steps with re-frame should be:
- look at the examples: https://github.com/Day8/re-frame/tree/master/examples
- use the lein template: https://github.com/Day8/re-frame-template​
- read more in the Wiki: https://github.com/Day8/re-frame/wiki
You might also be interested in James MacAulay's excellent work (not re-frame!):
https://github.com/jamesmacaulay/zelkova
If you want reusable layout and widget components, consider this sister project:
https://github.com/Day8/re-com
### Licence ### Licence
Copyright © 2015 Michael Thompson Copyright © 2015 Michael Thompson