From 657a6935be694b7b8f0ebeb81fe99bfc1f26b935 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 27 Aug 2016 12:41:26 +1000 Subject: [PATCH] Miscellaneous doc tweaks --- docs/Basic-App-Structure.md | 21 ++++++++++++++------- docs/EffectfulHandlers.md | 10 ++++++---- docs/coeffects.md | 23 ++++++++++++----------- images/logo/README.md | 16 ++++++++-------- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/docs/Basic-App-Structure.md b/docs/Basic-App-Structure.md index 5958148..42267ad 100644 --- a/docs/Basic-App-Structure.md +++ b/docs/Basic-App-Structure.md @@ -9,7 +9,7 @@ To build a re-frame app, you: For simpler apps, you should put code for each layer into separate files: ``` src -├── core.cljs <--- entry point, plus history +├── core.cljs <--- entry point, plus history, routing, etc ├── db.cljs <--- schema, validation, etc (data layer) ├── subs.cljs <--- subscription handlers (query layer) ├── views.cljs <--- reagent components (view layer) @@ -18,20 +18,27 @@ src For a living example of this approach, look at the [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc). -### There's A Gotcha +### There's A Small Gotcha If you adopt this structure there's a gotcha. -events.cljs and subs.cljs will never be `required` by any other namespaces. To the Google Closure dependency mechanism it appears as if these two namespaces are not needed and it doesn't load them. +`events.cljs` and `subs.cljs` will never be `required` by any other +namespaces. To the Google Closure dependency mechanism it appears as +if these two namespaces are not needed and it doesn't load them. -And, if the code in these namespaces does not get loaded, the registrations in them never happen. You'll be baffled as to why none of your events handlers are registered. +And, if the code does not get loaded, the registrations in these namespaces +never happen. You'll then be baffled as to why none of your events handlers +are registered. -Once you twig to what's going on, the solution is easy. You must explicitly `require` both namespaces, `events` and `subs`, in your `core` namespace. Then they'll be loaded and the registrations will occur as the loading happens. +Once you twig to what's going on, the solution is easy. You must +explicitly `require` both namespaces, `events` and `subs`, in your `core` +namespace. Then they'll be loaded and the registrations will occur +as that loading happens. ## Larger Apps -Assuming your larger apps has multiple "panels" (or "views") which are relatively independent, you might use this structure: - +Assuming your larger apps has multiple "panels" (or "views") which are +relatively independent, you might use this structure: ``` src ├── panel-1 diff --git a/docs/EffectfulHandlers.md b/docs/EffectfulHandlers.md index 4a5fd9d..d1cf830 100644 --- a/docs/EffectfulHandlers.md +++ b/docs/EffectfulHandlers.md @@ -298,7 +298,7 @@ More on side effects in a minute, but let's double back to coeffects. ### The Coeffects -So far we've written our new style `-fx handlers like this: +So far we've written our new style `-fx` handlers like this: ```clj (reg-event-fx :my-event @@ -314,10 +314,11 @@ It is now time to name that first argument: { ... })) ``` -When you use the `-fx` form of registration, the first argument of your handler will be a map of coeffects which we name `cofx`. +When you use the `-fx` form of registration, the first argument +of your handler will be a map of coeffects which we name `cofx`. In that map will be the complete set of "inputs" required by your function. The complete -set of computational resources (data) needed to perform its computation. But how? +set of computational resources (data) needed to perform its computation. But how? This will be explained in an upcoming tutorial, I promise, but for the moment, take it as a magical given. @@ -332,7 +333,8 @@ Remember this impure handler from before: (assoc db :defaults defaults)))) ``` -We'd now rewrite that as a pure handler, like this: +It was impure because it obtained an input from other than its arguments. +We'd now rewrite it as a pure handler, like this: ```clj (reg-event-fx ;; notice the -fx :load-localstore diff --git a/docs/coeffects.md b/docs/coeffects.md index 7f79a48..296c8bb 100644 --- a/docs/coeffects.md +++ b/docs/coeffects.md @@ -35,7 +35,7 @@ handler, making this common case easy to program. But sometimes an event handler needs other data inputs to perform its computation. Things like a random number, or a GUID, -or the current datetime. It might even need access to a +or the current datetime. Perhaps it needs access to a DataScript connection. @@ -50,17 +50,17 @@ This handler obtains data directly from LocalStore: (assoc db :defaults val)))) ``` -This works, but there's a cost. +This works, but there's a cost. Because it has directly accessed LocalStore, this event handler is not -pure, and impure functions cause well-documented paper cuts. +pure, and impure functions cause well-documented paper cuts. ### How We Want It -Our goal in this tutorial is to rewrite this event handler so -that it __only__ uses data from arguments. +Our goal in this tutorial will be to rewrite this event handler so +that it __only__ uses data from arguments. This will take a few steps. -To make this happen, we first switch to +The first is that we first switch to using `reg-event-fx` (instead of `reg-event-db`). Event handlers registered via `reg-event-fx` are slightly @@ -85,8 +85,9 @@ right value. Nice! But how do we make this magic happen? ### Abracadabra -Each time an event handler is executed, a brand new `context` is created, and within that -`context` is a brand new `:coeffect` map, which is initially totally empty. +Each time an event handler is executed, a brand new `context` +is created, and within that `context` is a brand new `:coeffect` +map, which is initially totally empty. That pristine `context` value (containing a pristine `:coeffect` map) is threaded through a chain of Interceptors before it finally reaches our event handler, @@ -114,11 +115,11 @@ Something like this (this handler is the same as before, except for one detail): {:db (assoc db :defaults val))})) ``` -Look at that - my event handler has a new Interceptor! It is injecting the right key/value pair (`:local-store`) -into `context's` `:coeffeects`, which then goes on to be the first argument +Look at that - my event handler has a new Interceptor! It is injecting the +right key/value pair (`:local-store`) +into `context's` `:coeffeects`, which itself then goes on to be the first argument to our event handler (`cofx`). - ### `inject-cofx` `inject-cofx` is part of the re-frame API. diff --git a/images/logo/README.md b/images/logo/README.md index 86aeec1..b2fcd39 100644 --- a/images/logo/README.md +++ b/images/logo/README.md @@ -13,23 +13,23 @@ Bruce Lee wielded nunchucks. ## Genesis Theories -While we shouldn't presume to fathom the cavernous depths of Martin's creativity, -great, unexplained works always encourage fan theories. +Great, unexplained works always encourage fan theories, and the re-frame logo +is no exception. -Some have -speculated the re-frame logo was created as a bifarious rainbow omage to Frank Lloyd Wright's Guggenheim. +Some speculate @martinklepsch created it as a bifarious rainbow omage +to a utilities room in Frank Lloyd Wright's Guggenheim. ![](Guggenheim.jpg)

-Others disagree and, instead, insist he visually folded (foldv) the cljs logo across re-frame's official -architecture diagram to form a flowing poststructuralist rebuttal of OO's tyrannical duplicate -letter adjacency. +Others see the cljs logo folded across re-frame's official +architecture diagram, forming a flowing poststructuralist rebuttal of OO's +duplicate letter adjacency, and Jackson Pollock's Fractal Expressionism. ![](Genesis.png) -But, are we better off never knowing? Art requires no answer. +You be the judge. ### Instructions