From a0679e12a2dfea6acd731d3150aaf4a92c355470 Mon Sep 17 00:00:00 2001
From: Mike Thompson <mike.thompson@day8.com.au>
Date: Mon, 29 Aug 2016 13:11:15 +1000
Subject: [PATCH] More docs

---
 .idea/codeStyleSettings.xml          |  1 +
 docs/README.md                       |  9 ++-
 docs/The-ref-frame-logo.md           | 45 +++++++++++++
 docs/Using-Stateful-JS-Components.md | 94 ++++++++++++++++++++++++++++
 images/logo/README.md                | 37 +----------
 5 files changed, 150 insertions(+), 36 deletions(-)
 create mode 100644 docs/The-ref-frame-logo.md
 create mode 100644 docs/Using-Stateful-JS-Components.md

diff --git a/.idea/codeStyleSettings.xml b/.idea/codeStyleSettings.xml
index c374ce3..adb5ab9 100644
--- a/.idea/codeStyleSettings.xml
+++ b/.idea/codeStyleSettings.xml
@@ -12,5 +12,6 @@
       </value>
     </option>
     <option name="USE_PER_PROJECT_SETTINGS" value="true" />
+    <option name="PREFERRED_PROJECT_CODE_STYLE" value="Default (2)" />
   </component>
 </project>
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 044bd9f..054c750 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,4 +18,11 @@
 
 1. [Loading Initial Data](Loading-Initial-Data.md)
 2. [Talking To Servers](Talking-To-Servers.md)
-3. [Subscribing to External Data](Subscribing-To-External-Data.md)
\ No newline at end of file
+3. [Subscribing to External Data](Subscribing-To-External-Data.md)
+
+
+
+## Miscellaneous:
+
+1. [Using Stateful JS Components.md](Using-Stateful-JS-Components.md)
+2. [The re-frame Logo](The-ref-frame-logo.md)
diff --git a/docs/The-ref-frame-logo.md b/docs/The-ref-frame-logo.md
new file mode 100644
index 0000000..bc097cd
--- /dev/null
+++ b/docs/The-ref-frame-logo.md
@@ -0,0 +1,45 @@
+## The re-frame Logo
+
+![logo](/images/logo/re-frame_256w.png?raw=true)
+
+### Who
+
+Created by the mysterious deep thinker, known only as @martinklepsch.
+
+Some say he appears on high value stamps in Germany and that he once 
+punched a horse to the ground. Others say he loves recursion so much 
+that, in his wallet, he carries a photograph of his wallet.
+
+All we know for sure is that he wields [Sketch.app](https://www.sketchapp.com/) like
+Bruce Lee wielded nunchucks.
+
+### Genesis Theories
+
+Great, unexplained works encourage fan theories, and the re-frame logo
+is no exception.
+
+A noisy bunch think @martinklepsch wanted to `Put the 'f' back into infinity`. They have t-shirts. 
+
+Others speculate he created the logo as a bifarious rainbow homage
+to Frank Lloyd Wright's masterpiece, the Guggenheim Museum. A classic case 
+of premature abstraction and over engineering if you ask me. Their theory, not the Guggenheim.
+
+![](/images/logo/Guggenheim.jpg)
+
+The infamous "Bad Touch" faction look at the logo and see the cljs logo mating noisily with re-frame's official 
+architecture diagram. Attend one of their parties and you have a 50% chance of arrest. 
+
+![](/images/logo/Genesis.png)
+
+The Functional Fundamentalists, a stern bunch, see the logo as a flowing poststructuralist rebuttal of OO's
+vowel duplication and horizontal adjacency. Their approach, FF, is apparently fine because "everyone loves a
+fricative".
+
+For his part, @martinklepsch has never confirmed any theory, teasing us instead with coded clues 
+like "Will you please stop emailing me" and "Why did you say I hit a horse?".
+
+### Assets Where?
+
+Within this repo, look in `/images/logo/`
+
+
diff --git a/docs/Using-Stateful-JS-Components.md b/docs/Using-Stateful-JS-Components.md
new file mode 100644
index 0000000..433db75
--- /dev/null
+++ b/docs/Using-Stateful-JS-Components.md
@@ -0,0 +1,94 @@
+## Using Stateful JS Components 
+
+You know what's good for you, and you know what's right.  But it
+doesn't matter - the wickedness of the temptation is too much. 
+
+The JS world is brimming with shiny component baubles: D3, 
+Google Maps, Chosen, etc.  
+
+But they are salaciously stateful and mutative.  And, you, 
+raised in a pure, functional home, with caring, immutable parents, 
+know they are wrong.  But, my, how you still yearn for the sweet 
+thrill of that forbidden fruit. 
+
+I won't tell, if you don't.  But careful plans must be made  ... 
+
+
+### The overall plan 
+
+To use a stateful js component, you'll need to write two Reagent components:
+  - an **outer component** responsible for sourcing data via a subscription or r/atom or cursor, etc.  
+  - an **inner component** responsible for wrapping and manipulating the stateful JS component via lifecycle functions.  
+
+The pattern involves the outer component, which sources data, supplying this data to the inner component **via props**. 
+
+### Example Using Google Maps
+
+```cljs
+(defn gmap-inner []
+  (let [gmap    (atom nil)
+        options (clj->js {"zoom" 9})
+        update  (fn [comp]
+                  (let [{:keys [latitude longitude]} (reagent/props comp)
+                        latlng (js/google.maps.LatLng. latitude longitude)]
+                    (.setPosition (:marker @gmap) latlng)
+                    (.panTo (:map @gmap) latlng)))]
+
+    (reagent/create-class
+      {:reagent-render (fn []
+                         [:div
+                          [:h4 "Map"]
+                          [:div#map-canvas {:style {:height "400px"}}]])
+
+       :component-did-mount (fn [comp]
+                              (let [canvas  (.getElementById js/document "map-canvas")
+                                    gm      (js/google.maps.Map. canvas options)
+                                    marker  (js/google.maps.Marker. (clj->js {:map gm :title "Drone"}))]
+                                (reset! gmap {:map gm :marker marker}))
+                              (update comp))
+
+       :component-did-update update
+       :display-name "gmap-inner"})))
+
+
+
+(defn gmap-outer []
+  (let [pos (subscribe [:current-position])]   ;; obtain the data
+    (fn []
+      [gmap-inner @pos])))
+```
+
+
+Notes:
+  - `gmap-outer` obtains data via a subscription. It is quite simple - trivial almost.
+  - it then passes this data __as a prop__  to `gmap-inner`.  This inner component has the job of wrapping/managing the stateful js component (Gmap in our case above)
+  - when the data (delivered by the subscription) to the outer layer changes, the inner layer, `gmap-inner`, will be given a new prop - `@pos` in the case above.
+  - when the inner component is given new props, its entire set of lifecycle functions will be engaged. 
+  - the renderer for the inner layer ALWAYS renders the same, minimal container hiccup for the component.  Even though the `props` have changed, the same hiccup is output. So it will appear to React as if nothing changes from one render to the next. No work to be done. React/Reagent will leave the DOM untouched. 
+  - but this inner component has other lifecycle functions and this is where the real work is done.  
+  - for example, after the renderer is called (which ignores its props), `component-did-update` will be called. In this function, we don't ignore the props, and we use them to update/mutate the stateful JS component.  
+  - the props passed (in this case `@pos`) in must be a map, otherwise `(reagent/props comp)` will return nil.
+
+### Pattern Discovery 
+
+This pattern has been independently discovered by many. To my knowledge, 
+[this description of the Container/Component pattern](https://medium.com/@learnreact/container-components-c0e67432e005#.3ic1uipvu)
+is the first time it was written up.
+
+### Code Credit
+
+The example gmaps code above was developed by @jhchabran in this gist:
+https://gist.github.com/jhchabran/e09883c3bc1b703a224d#file-2_google_map-cljs
+
+### D3 Examples
+
+D3 (from @zachcp): 
+  - Blog Post: http://zachcp.org/blog/2015/reagent-d3/
+  - Code: https://github.com/zachcp/simplecomponent
+  - Example: http://zachcp.github.io/simplecomponent/
+
+
+### Advanced Lifecycle Methods
+
+If you mess around with lifecycle methods, you'll probably want to read Martin's explanations:
+https://www.martinklepsch.org/posts/props-children-and-component-lifecycle-in-reagent.html
diff --git a/images/logo/README.md b/images/logo/README.md
index 26a1685..fff87ac 100644
--- a/images/logo/README.md
+++ b/images/logo/README.md
@@ -1,40 +1,7 @@
-## The re-frame Logo
+
 
 ![logo](/images/logo/re-frame_256w.png?raw=true)
 
-Created by the mysterious @martinklepsch
-
-Some say he appears on high value stamps in Germany and that he once 
-punched a horse to the ground. Others say he loves recursion so much 
-that his wallet contains a photograph of his wallet.
-
-All we know for sure is that he wields [Sketch.app](https://www.sketchapp.com/) like
-Bruce Lee wielded nunchucks.
-
-## Genesis Theories
-
-Great, unexplained works encourage fan theories, and the re-frame logo
-is no exception.
-
-Some speculate @martinklepsch created it as a bifarious rainbow homage
-to Frank Lloyd Wright's Guggenheim.
-
-![](Guggenheim.jpg)
-
-Others see the cljs logo mating noisily with re-frame's official 
-architecture diagram.
-
-![](Genesis.png)
-
-Yet others see a poststructuralist rebuttal of OO's
-vowel duplication and horizontal adjacency. Their T-shirts claim:  
-> He's put the 'f' back into infinity
-
-For his part, Martin has never confirmed any theory, teasing us instead with coded clues 
-like "Will you please stop emailing me" and "Why did you say I hit a horse?".
-
-### Notes 
-
-Use [Sketch.app](https://www.sketchapp.com/) to update the `re-frame-logo.sketch` file.
+Created via [Sketch.app](https://www.sketchapp.com/). See the file `re-frame-logo.sketch`
 
 Unfortunately the gradients are not exported properly so we can't provide an SVG here for now.