diff --git a/CHANGES.md b/CHANGES.md index a2a1a61..60779fa 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,8 +2,8 @@ #### Headline - - Docs: a rewritten README and a new "Introduction" section in `/docs` - - [#218](https://github.com/Day8/re-frame/issues/218) Make it okay to use `subscribe` in Form-1 components + - The README and `/docs` have been substantially reworked. + - [#218](https://github.com/Day8/re-frame/issues/218) Make it okay to use `subscribe` in Form-1 components. This is a big deal. #### Breaking diff --git a/docs/ApplicationState.md b/docs/ApplicationState.md index d1be34b..2d812cb 100644 --- a/docs/ApplicationState.md +++ b/docs/ApplicationState.md @@ -115,13 +115,18 @@ source of data is elsewhere. ### Get You A Leveragable Schema -You really do need a schema for `app-db`. Yes, it is optional, and I breezed past this -earlier, but now I'm thumping the table and my face is red with intensity. You need one. +You really need a schema for `app-db`. -The [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc) (in this repo) shows how to check `app-db` against your schema -after every single event has been processed. +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`. Good. -This is 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 +how to write code which checks `app-db` against this spec after every single event has been +processed. + +Specs are leveragable. Watch how:
https://www.youtube.com/watch?v=VNTQ-M_uSo8 *** diff --git a/docs/CodeWalkthrough.md b/docs/CodeWalkthrough.md index 23b2585..cf258e7 100644 --- a/docs/CodeWalkthrough.md +++ b/docs/CodeWalkthrough.md @@ -2,12 +2,16 @@ ## Initial Code Walk-through -At this point in your reading, you are armed with: +At this point, you are about 50% of the way to understanding re-frame. You are armed with: - a high level understanding of the 6 domino process (from re-frame's README) - an understanding of application state (from the previous tutorial) +By the end of this tutorial, you'll be at 70%, which is good +enough to start coding by yourself. + In this tutorial, **we'll look at re-frame code**. + ## Table Of Contents @@ -35,42 +39,34 @@ In this tutorial, **we'll look at re-frame code**. ## What Code? This repo contains an example application called ["simple"](https://github.com/Day8/re-frame/tree/develop/examples/simple), -which has around 70 lines of code. We'll look at every line of the [file](https://github.com/Day8/re-frame/blob/develop/examples/simple/src/simple/core.cljs). - -You are currently about 50% the way to understanding re-frame. By the -end of this tutorial, you'll be at 70%, which is good -enough to start coding by yourself. - -## What Does It Do? +which has around 70 lines of code. We'll look at every line of [the file](https://github.com/Day8/re-frame/blob/develop/examples/simple/src/simple/core.cljs). This app: - displays the current time in a nice big, colourful font - - provides a text input field into which you can type a hex colour code, - like "#CCC", for the time display + - provides a single text input field, into which you can type a hex colour code, + like "#CCC", used for the time display - +Here's what it looks like: ![Example App image](../images/example_app.png) -To run the code: - * Install Java 8 (http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +To run the code: + * Install Java 8 * Install leiningen (http://leiningen.org/#install) Then: -1. `git clone https://github.com/Day8/re-frame.git` -2. `cd re-frame/examples/simple` -3. `lein do clean, figwheel` -4. open http://localhost:3449/example.html - - -The source file we'll be reviewing is: -https://github.com/Day8/re-frame/blob/master/examples/simple/src/simpleexample/core.cljs + 1. `git clone https://github.com/Day8/re-frame.git` + 2. `cd re-frame/examples/simple` + 3. `lein do clean, figwheel` + 4. open http://localhost:3449/example.html ## Namespace -Because this example is so small, the code is in a single namespace. -Within it, we'll need access to both `reagent` and `re-frame`. -So, we start like this: +Because this example is tiny, the code is in a single namespace which you can find here: +https://github.com/Day8/re-frame/blob/master/examples/simple/src/simpleexample/core.cljs + +Within this namespace, we'll need access to both `reagent` and `re-frame`. +So, at the top, we start like this: ```clj (ns simple.core (:require [reagent.core :as reagent] diff --git a/docs/MentalModelOmnibus.md b/docs/MentalModelOmnibus.md index 5faf168..1baf5f8 100644 --- a/docs/MentalModelOmnibus.md +++ b/docs/MentalModelOmnibus.md @@ -8,6 +8,9 @@ patterns of thought that produced that government are left intact, then those patterns will repeat themselves.
> -- Robert Pirsig, Zen and the Art of Motorcycle Maintenance + + + The tutorials initially focus on the **domino narrative**. The goal is to efficiently explain the mechanics of re-frame, and get you reading and writing code ASAP. @@ -16,9 +19,9 @@ and get you reading and writing code ASAP. which will deepen your understanding of its design, and help you to get the best from it. -This tutorial is a tour -of these ideas, justifications and insights. It is a little rambling, but -I'm hoping you'll have had at least one "Aaaah, I see" moment before the end. +This tutorial is a tour of these ideas, justifications and insights. +It is a little rambling, but I'm hoping it will deliver for you +at least one "Aaaah, I see" moment before the end. @@ -94,6 +97,7 @@ wrong places and you'll end up with a tire fire of an Architecture. ## It does Event Sourcing + How did that error happen, you puzzle, shaking your head ruefully? What did the user do immediately prior? What state was the app in that this event was so problematic? @@ -124,6 +128,7 @@ Here's Martin Fowler's [description of Event Sourcing](http://martinfowler.com/e ## It does a reduce + Here's an interesting way of thinking about the re-frame data flow ... diff --git a/images/mental-model-omnibus.jpg b/images/mental-model-omnibus.jpg new file mode 100644 index 0000000..abd45b8 Binary files /dev/null and b/images/mental-model-omnibus.jpg differ