From c39378bb7981b7d0e2c0edd63164567211a42781 Mon Sep 17 00:00:00 2001
From: Dan Holmsand <holmsand@gmail.com>
Date: Wed, 26 Feb 2014 13:17:18 +0100
Subject: [PATCH] Explain binary clock demo

---
 demo/reagentdemo/news.cljs             |  1 +
 demo/reagentdemo/news/binaryclock.cljs |  2 +-
 demo/reagentdemo/news/clockpost.cljs   | 62 +++++++++++++++++++++-----
 3 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/demo/reagentdemo/news.cljs b/demo/reagentdemo/news.cljs
index e7e63df..c079f89 100644
--- a/demo/reagentdemo/news.cljs
+++ b/demo/reagentdemo/news.cljs
@@ -10,6 +10,7 @@
 
 (defn main []
   [:div
+   [title "Reagent news"]
    [clock/main {:summary true}]
    [anyargs/main {:summary true}]
    [async/main {:summary true}]
diff --git a/demo/reagentdemo/news/binaryclock.cljs b/demo/reagentdemo/news/binaryclock.cljs
index 42fa6d2..e9eb915 100644
--- a/demo/reagentdemo/news/binaryclock.cljs
+++ b/demo/reagentdemo/news/binaryclock.cljs
@@ -45,6 +45,6 @@
   (let [{:keys [time show-100s]} @clock-state]
     (if show-100s
       (r/next-tick update-time)
-      (js/setTimeout update-time 333))
+      (js/setTimeout update-time 1000))
     [clock time show-100s
      #(swap! clock-state update-in [:show-100s] not)]))
diff --git a/demo/reagentdemo/news/clockpost.cljs b/demo/reagentdemo/news/clockpost.cljs
index beb6b60..5a7b564 100644
--- a/demo/reagentdemo/news/clockpost.cljs
+++ b/demo/reagentdemo/news/clockpost.cljs
@@ -1,6 +1,6 @@
 (ns reagentdemo.news.clockpost
   (:require [reagent.core :as r :refer [atom]]
-            [reagent.debug :refer-macros [dbg println]]
+            [reagent.debug :refer-macros [dbg]]
             [reagentdemo.syntax :refer-macros [get-source]]
             [reagentdemo.page :refer [title link page-map]]
             [reagentdemo.common :as common :refer [demo-component]]
@@ -15,7 +15,11 @@
                    :no-heading true}])
 
 (defn main [{:keys [summary]}]
-  (let [head "Binary clock"]
+  (let [head "A binary clock"
+        lexclock {:href "http://www.lexicallyscoped.com/2014/01/23/clojurescript-react-om-binary-clock.html"}
+        hopclock {:href "http://pmbauer.github.io/2014/01/27/hoplon-binary-clock/"}
+        om {:href "https://github.com/swannodette/om"}
+        hoplon {:href "http://hoplon.io"}]
     
     [:div.reagent-demo
      [:h1 [link {:href main} head]]
@@ -24,21 +28,26 @@
 
       (when-not summary
         [:div
-         ;; [demo-component {:comp binaryclock/main}]
-         [binaryclock/main]
-         [:p [:strong "Click to toggle 1/100th seconds."]]])
+         [:div.clearfix
+          [binaryclock/main]]
+         [:div [:strong "Click to toggle 1/100th seconds."]]])
 
-      [:h2 "A simple binary clock in Reagent"]
+      [:p "Fredrik Dyrkell wrote a very nice " [:a lexclock "binary
+      clock"] " using " [:a om "Om"] ". I thought I’d replicate that
+      using Reagent for fun (another re-write, using " [:a
+      hoplon "Hoplon"] ", can be seen " [:a hopclock "here"] ")."]
 
-      [:p "some text"]
+      [:p "So, without further ado, here is a binary clock using Reagent."]
       
       (if summary
         [link {:href main
                :class 'news-read-more} "Read more"]
         [:div.demo-text
 
+         [fn-src :nsr]
+
          [:p "We start with the basics: The clock is built out of
-         cells, that are light or dark if the bit they correspond to
+         cells, with a light colour if the bit the cell corresponds to
          is set."]
 
          [fn-src :cell]
@@ -68,9 +77,42 @@
 
          [fn-src :clock-state :update-time]
 
-         [:p "And finally we use the clock component like this:"]
+         [:p "And finally we use the " [:code "clock"] " component.
+         The current time is scheduled to be updated, after a suitable
+         delay, every time the main component is rendered ("
+         [:code "reagent.core/next-tick"] " is just a front for "
+         [:code "requestAnimationFrame"] "):"]
 
-         [fn-src :main]])]]))
+         [fn-src :main]
+
+         [:h2 "How it all works"]
+
+         [:p "Reading through the source, it may look like the entire
+         clock component is recreated from scratch whenever the time
+         changes. "]
+
+         [:p "That is an illusion: Reagent and React together
+         makes sure that only the parts of the DOM that actually need
+         to change are updated. For example, the "
+          [:code "column-pair"] " function corresponding to hours only
+         runs once every hour."]
+
+         [:p "And that’s what makes Reagent and React fast. Try
+         clicking on the clock to toggle the display of 1/100th
+         seconds. Most browsers should have no trouble at all keeping
+         up (even if they won’t actually show every 1/100th second:
+         they are typically limited to roughly 60 fps)."]
+
+         [:p "But it is a very handy illusion. Almost the entire UI is
+         made up of pure functions, transforming immutable data into
+         other immutable data structures. That makes them easy to
+         reason about, and trivial to test. You don’t have to care
+         about ”model objects”, or about how to update the DOM
+         efficiently. "]
+
+         [:p "Just pass arguments to component functions, return a UI
+         description that corresponds to those arguments, and leave it
+         to React to actually display that UI."]])]]))
 
 (swap! page-map assoc
        "news/binary-clock.html" main)