From 2f0f406c8964d6cf9be45de86b394a8e223614be Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Thu, 22 Dec 2016 21:15:31 +1100 Subject: [PATCH] Improve docs navigation and remove unnecessary Tables of Contexts --- docs/ApplicationState.md | 23 +++++++++++++---------- docs/Effects.md | 18 +++++++++--------- docs/Solve-the-CPU-hog-problem.md | 19 ++++++------------- docs/The-re-frame-logo.md | 17 ++++++----------- 4 files changed, 34 insertions(+), 43 deletions(-) diff --git a/docs/ApplicationState.md b/docs/ApplicationState.md index 6d9609a..4dc5f03 100644 --- a/docs/ApplicationState.md +++ b/docs/ApplicationState.md @@ -1,7 +1,9 @@ ## Application State -

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...

— Fogus (@fogus) April 11, 2014
- +
+ + +
### The Big Ratom @@ -42,7 +44,8 @@ Further Notes: 2. In the documentation and code, I make a distinction between `app-db` (the `ratom`) and `db` which is the (map) `value` currently stored **inside** this `ratom`. Be aware of that naming as you read code. 3. re-frame creates and manages an `app-db` for you, so - you don't need to declare one yourself (see the 1st FAQ if you want to inspect the value it holds). + you don't need to declare one yourself (see the [the first FAQ](FAQs/Inspecting-app-db.md) if you want + to inspect the value it holds). 4. `app-db` doesn't actually have to be a `ratom` containing a map. It could, for example, be a [datascript](https://github.com/tonsky/datascript database). In fact, any database which can signal you when it changes would do. We'd love! to be using [datascript](https://github.com/tonsky/datascript database) - so damn cool - @@ -69,7 +72,7 @@ Again, this simplicity causes a certain class of bugs or design problems to evap so that, at any moment, we can validate all the data in the application. **All of it!** We do this check after every single "event handler" runs (event handlers compute new state). And this enables us to catch errors early (and accurately). It increases confidence in the way -that Types can increase confidence, only [a good schema can provide more +that Types can increase confidence, only [a good schema can potentially provide more **leverage** than types](https://www.youtube.com/watch?v=nqY4nUMfus8). 4. Undo/Redo [becomes straight forward to implement](https://github.com/Day8/re-frame-undo). @@ -91,22 +94,22 @@ source of data is elsewhere. ### Create A Leveragable Schema -You really need a `spec` schema for `app-db`. The derived power is immense. +You need to create a [spec](http://clojure.org/about/spec) schema for `app-db`. You want that leverage. Of course, that means you'll have to learn [spec](http://clojure.org/about/spec) and there's some overhead in that, so maybe, just maybe, in your initial experiments, you can get away without one. But not for long. Promise me you'll write a `spec`. Promise me. Okay, good. -The [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc) -shows how to use a spec. Look in `src/db.cljs` for the spec itself, and then in `src/events.cljs` for +Soon we'll look at the [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc) +which shows how to use a spec. (Check out `src/db.cljs` for the spec itself, and then in `src/events.cljs` for how to write code which checks `app-db` against this spec after every single event has been -processed. +processed.) -Specs are more leveragable than types. This is a big interesting idea which is not yet mainstream. +Specs are potentially more leveragable than types. This is a big interesting idea which is not yet mainstream. Watch how:
https://www.youtube.com/watch?v=VNTQ-M_uSo8 -Also, the mighty Rich Hickey (poor audio):
+Also, watch the mighty Rich Hickey (poor audio):
https://vimeo.com/195711510 ### How do I inspect it? diff --git a/docs/Effects.md b/docs/Effects.md index 5a19228..1a9ade2 100644 --- a/docs/Effects.md +++ b/docs/Effects.md @@ -54,18 +54,18 @@ Like this: An effects map contains instructions. -Each key/value pair in the map is one instruction - the `key` uniquely identifies -the particular side effect required, and the `value` for that `key` provides -further data. The structure of `value` is different for each side-effect. +Each key/value pair in the map is one instruction - the `key` uniquely identifies +the particular side effect required, and the `value` for that `key` provides +further data. The structure of `value` is different for each side-effect. -Here's the two instructions from the example above: +Here's the two instructions from the example above: ```cljs {:db (assoc db :flag a) ;; side effect on app-db :dispatch [:do-something-else 3]} ;; dispatch this event ``` The `:db` `key` instructs that "app-db" should be `reset!` to the -`value` supplied. +`value` supplied. And the `:dispatch` `key` instructs that an event should be dispatched. The `value` is the vector to dispatch. @@ -73,19 +73,19 @@ dispatched. The `value` is the vector to dispatch. There's many other possible effects, like for example `:dispatch-later` or `:set-local-store`. -And so on. And so on. Which brings us to a problem. +And so on. And so on. Which brings us to a problem. ### Infinite Effects -While re-frame supplies a number of builtin effects, the set of +While re-frame supplies a number of builtin effects, the set of possible effects is open ended. -What if you use PostgreSQL and want an effect which issues mutating +What if you use PostgreSQL and want an effect which issues mutating queries? Or what if you want to send logs to Logentries or metrics to DataDog. Or write values to windows.location. And what happens if your database is X, Y or Z? -The list of effects is long and varied, with everyone needing to use a +The list of effects is long and varied, with everyone needing to use a different combination. So effect handling has to be extensible. You need a way to define diff --git a/docs/Solve-the-CPU-hog-problem.md b/docs/Solve-the-CPU-hog-problem.md index 8bef64e..82368ae 100644 --- a/docs/Solve-the-CPU-hog-problem.md +++ b/docs/Solve-the-CPU-hog-problem.md @@ -1,17 +1,4 @@ - - -## Table Of Contents -- [Solving The CPU Hog Problem](#solving-the-cpu-hog-problem) -- [The re-frame Solution](#the-re-frame-solution) -- [A Sketch](#a-sketch) - - [Why Does A Redispatch Work?](#why-does-a-redispatch-work) - - [Variations](#variations) - - [Cancel Button](#cancel-button) - - [Further Notes](#further-notes) -- [Forcing A One Off Render](#forcing-a-one-off-render) - - ## Solving The CPU Hog Problem @@ -234,3 +221,9 @@ You only need this technique when you: If you handle via multiple chunks you don't have to do this, because you are repeatedly handing back control to the browser/UI. Its just when you are going to tie up the CPU for a one, longish chunk. + + + + + + diff --git a/docs/The-re-frame-logo.md b/docs/The-re-frame-logo.md index 5081fb1..ea2eec2 100644 --- a/docs/The-re-frame-logo.md +++ b/docs/The-re-frame-logo.md @@ -1,14 +1,3 @@ - - -## Table Of Contents - -- [The re-frame Logo](#the-re-frame-logo) - - [Who](#who) - - [Genesis Theories](#genesis-theories) - - [Assets Where?](#assets-where) - - - ## The re-frame Logo ![logo](/images/logo/re-frame_256w.png?raw=true) @@ -59,3 +48,9 @@ and "Why did you say I hit a horse?". Within this repo, look in `/images/logo/` + + + + + +