From 5abdb74424cc70cf94bfb478da60383853628feb Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 4 Dec 2018 10:51:17 +0200
Subject: [PATCH 1/8] Improved frontend docs

---
 doc/frontend/basics.md      | 33 ++++++++++++++++++++++++++-------
 doc/frontend/browser.md     |  6 ++++--
 doc/frontend/controllers.md | 20 ++++++++++----------
 3 files changed, 40 insertions(+), 19 deletions(-)

diff --git a/doc/frontend/basics.md b/doc/frontend/basics.md
index d7330883..3c57b83f 100644
--- a/doc/frontend/basics.md
+++ b/doc/frontend/basics.md
@@ -1,12 +1,31 @@
 # Frontend basics
 
-* https://github.com/metosin/reitit/tree/master/examples/frontend
+Reitit frontend integration is built from multiple layers:
+
+- Core functions which are enchanted with few browser specific
+features
+- [Browser integration](./browser.md) for attaching Reitit to hash-change or HTML5
+history events
+- Stateful wrapper for easy use of history integration
+- Optional [controller extension](./controllers.md)
+
+## Core functions
 
 `reitit.frontend` provides few useful functions wrapping core functions:
 
-- `match-by-path` version which parses a URI using JavaScript, including
-query-string, and also coerces the parameters.
-- `router` which compiles coercers by default
-- `match-by-name` and `match-by-name!` with optional `path-paramers` and
-logging errors to `console.warn` instead of throwing errors (to prevent
-React breaking due to errors).
+`match-by-path` version which parses a URI using JavaScript, including
+query-string, and also [coerces the parameters](../coercion/coercion.md).
+Coerced parameters are stored in match `:parameters` property. If coercion
+is not enabled, the original parameters are stored in the same property,
+to allow the same code to read parameters regardless if coercion is
+enabled.
+
+`router` which compiles coercers by default.
+
+`match-by-name` and `match-by-name!` with optional `path-paramers` and
+logging errors to `console.warn` instead of throwing errors to prevent
+React breaking due to errors.
+
+## Next
+
+[Browser integration](./browser.md)
diff --git a/doc/frontend/browser.md b/doc/frontend/browser.md
index 599f2765..210e5711 100644
--- a/doc/frontend/browser.md
+++ b/doc/frontend/browser.md
@@ -21,5 +21,7 @@ Check examples for simple Ring handler example.
 ## Easy
 
 Reitit frontend routers require storing the state somewhere and passing it to
-all the calls. Wrapper (`reitit.frontend.easy`) is provided which manages
-router instance and passes the instance to all calls.
+all the calls. Wrapper `reitit.frontend.easy` is provided which manages
+a router instance and passes the instance to all calls. This should
+allow easy use in most applications, as browser anyway can only have single
+event handler for page change events.
diff --git a/doc/frontend/controllers.md b/doc/frontend/controllers.md
index 95a0b90b..880342e1 100644
--- a/doc/frontend/controllers.md
+++ b/doc/frontend/controllers.md
@@ -26,7 +26,7 @@ and `start` get called again.
 You can add controllers to a route by adding them to the route data in the
 `:controllers` vector. For example:
 
-```clojure
+```cljs
 ["/item/:id"
  {:controllers [{:params (fn [match] (get-in match [:path-params :id]))
                  :start  (fn [item-id] (js/console.log :start item-id))
@@ -44,8 +44,7 @@ call
 the URL changes. You can call it from the `on-navigate` callback of
 `reitit.frontend.easy`:
 
-```clojure
-
+```cljs
 (ns frontend.core
   (:require [reitit.frontend.easy :as rfe]
             [reitit.frontend.controllers :as rfc]))
@@ -70,10 +69,10 @@ See also [the full example](https://github.com/metosin/reitit/tree/master/exampl
 
 ## Nested controllers
 
-When you nest routes in the route tree, the controllers get nested as well.
-Consider this route tree:
+When you nest routes in the route tree, the controllers get concatenated when
+route data is merged. Consider this route tree:
 
-```clojure
+```cljs
 ["/" {:controllers [{:start (fn [_] (js/console.log "root start"))}]}
  ["/item/:id"
   {:controllers [{:params (fn [match] (get-in match [:path-params :id]))
@@ -90,20 +89,22 @@ Consider this route tree:
   started with the parameter `something-else`. The root controller stays on the
   whole time since its parameters do not change.
 
-## Authentication
+## Tips
+
+### Authentication
 
 Controllers can be used to load resources from a server. If and when your
 API requires authentication you will need to implement logic to prevent controllers
 trying to do requests if user isn't authenticated yet.
 
-### Run controllers and check authentication
+#### Run controllers and check authentication
 
 If you have both unauthenticated and authenticated resources, you can
 run the controllers always and then check the authentication status
 on controller code, or on the code called from controllers (e.g. re-frame event
 handler).
 
-### Disable controllers until user is authenticated
+#### Disable controllers until user is authenticated
 
 If all your resources require authentication an easy way to prevent bad
 requests is to enable controllers only after authentication is done.
@@ -119,7 +120,6 @@ Similar solution could be used to describe required resources as data (maybe
 even GraphQL query) per route, and then have code automatically load
 missing resources.
 
-
 ## Controllers elsewhere
 
 * [Controllers in Keechma](https://keechma.com/guides/controllers/)

From 9d6b0071fc49b8819782a841073baa00cd39effa Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 4 Dec 2018 14:22:35 +0200
Subject: [PATCH 2/8] Call :stop for controllers in reverse order

---
 modules/reitit-frontend/src/reitit/frontend/controllers.cljs | 2 +-
 test/cljs/reitit/frontend/controllers_test.cljs              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
index 8556314d..02024919 100644
--- a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
@@ -33,7 +33,7 @@
                                       (pad-same-length new-controllers old-controllers))
                                  (keep identity)
                                  vec)]
-    (doseq [controller (map :old changed-controllers)]
+    (doseq [controller (reverse (map :old changed-controllers))]
       (apply-controller controller :stop))
     (doseq [controller (map :new changed-controllers)]
       (apply-controller controller :start))
diff --git a/test/cljs/reitit/frontend/controllers_test.cljs b/test/cljs/reitit/frontend/controllers_test.cljs
index b4d2238c..27a44ff6 100644
--- a/test/cljs/reitit/frontend/controllers_test.cljs
+++ b/test/cljs/reitit/frontend/controllers_test.cljs
@@ -62,7 +62,7 @@
       (swap! controller-state rfc/apply-controllers
              {:data {:controllers []}})
 
-      (is (= [:stop-1 [:stop-3 1]] @log))
+      (is (= [[:stop-3 1] :stop-1] @log))
       (is (= [] @controller-state))
       (reset! log []))
     ))

From c314707afbb4952c54f69f00b74d8773081d8b84 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 4 Dec 2018 14:22:59 +0200
Subject: [PATCH 3/8] Add utils to create common controller :params functions

---
 .../src/reitit/frontend/controllers.cljs      | 26 +++++++++--
 .../src/reitit/frontend/history.cljs          |  2 +
 .../reitit/frontend/controllers_test.cljs     | 43 ++++++++++++++++++-
 3 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
index 02024919..9b11bb5b 100644
--- a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
@@ -1,4 +1,5 @@
-(ns reitit.frontend.controllers)
+(ns reitit.frontend.controllers
+  "Provides apply-controllers function")
 
 (defn- pad-same-length [a b]
   (concat a (take (- (count b) (count a)) (repeat nil))))
@@ -10,6 +11,25 @@
   (if-let [f (:params controller)]
     (f match)))
 
+(def static
+  "Static params means that the identity of controller
+  doesn't not depend on Match, i.e. any parameters.
+
+  This is same as just not defining :params."
+  nil)
+
+(defn parameters
+  "Given map of parameter-type => list of keys,
+  returns function taking Match and returning
+  value containing given parameter types and their
+  keys.
+
+  The resulting function can be used for :params."
+  [p]
+  (fn [match]
+    (into {} (for [[param-type ks] p]
+               [param-type (select-keys (get (:parameters match) param-type) ks)]))))
+
 (defn apply-controller
   "Run side-effects (:start or :stop) for controller.
   The side-effect function is called with controller params."
@@ -19,8 +39,8 @@
 
 (defn apply-controllers
   "Applies changes between current controllers and
-  those previously enabled. Resets controllers whose
-  parameters have changed."
+  those previously enabled. Reinitializes controllers whose
+  identity has changed."
   [old-controllers new-match]
   (let [new-controllers (mapv (fn [controller]
                                 (assoc controller ::params (get-params controller new-match)))
diff --git a/modules/reitit-frontend/src/reitit/frontend/history.cljs b/modules/reitit-frontend/src/reitit/frontend/history.cljs
index 35d8a091..4ec295fa 100644
--- a/modules/reitit-frontend/src/reitit/frontend/history.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/history.cljs
@@ -1,4 +1,6 @@
 (ns reitit.frontend.history
+  "Provides integration to hash-change or HTML5 History
+  events."
   (:require [reitit.core :as reitit]
             [reitit.core :as r]
             [reitit.frontend :as rf]
diff --git a/test/cljs/reitit/frontend/controllers_test.cljs b/test/cljs/reitit/frontend/controllers_test.cljs
index 27a44ff6..b0acb600 100644
--- a/test/cljs/reitit/frontend/controllers_test.cljs
+++ b/test/cljs/reitit/frontend/controllers_test.cljs
@@ -64,5 +64,46 @@
 
       (is (= [[:stop-3 1] :stop-1] @log))
       (is (= [] @controller-state))
+      (reset! log []))))
+
+(deftest controller-data-parameters
+  (let [log (atom [])
+        controller-state (atom [])
+        static {:start (fn [params] (swap! log conj [:start-static]))
+                :stop  (fn [params] (swap! log conj [:stop-static]))
+                :params rfc/static}
+        controller {:start (fn [params] (swap! log conj [:start params]))
+                    :stop  (fn [params] (swap! log conj [:stop params]))
+                    :params (rfc/parameters {:path [:foo]})}]
+
+    (testing "init"
+      (swap! controller-state rfc/apply-controllers
+             {:data {:controllers [static controller]}
+              :parameters {:path {:foo 1}}})
+
+      (is (= [[:start-static]
+              [:start {:path {:foo 1}}]] @log))
+      (is (= [(assoc static ::rfc/params nil)
+              (assoc controller ::rfc/params {:path {:foo 1}})]
+             @controller-state))
       (reset! log []))
-    ))
+
+    (testing "params change"
+      (swap! controller-state rfc/apply-controllers
+             {:data {:controllers [static controller]}
+              :parameters {:path {:foo 5}}})
+
+      (is (= [[:stop {:path {:foo 1}}]
+              [:start {:path {:foo 5}}]] @log))
+      (is (= [(assoc static ::rfc/params nil)
+              (assoc controller ::rfc/params {:path {:foo 5}})]
+             @controller-state))
+      (reset! log []))
+
+    (testing "stop"
+      (swap! controller-state rfc/apply-controllers
+             {:data {:controllers []}})
+
+      (is (= [[:stop {:path {:foo 5}}]
+              [:stop-static]] @log))
+      (reset! log []))))

From 36109f142cc872f48e5cea65267e69cb2c422b77 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 4 Dec 2018 14:53:23 +0200
Subject: [PATCH 4/8] Replace controller :params with :identity and :parameters

---
 CHANGELOG.md                                  | 15 ++++--
 .../src/reitit/frontend/controllers.cljs      | 49 ++++++++++---------
 .../reitit/frontend/controllers_test.cljs     | 31 ++++++------
 3 files changed, 53 insertions(+), 42 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9086fc55..25c79d3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,12 @@
+## Unreleased
+
+* Frontend controllers:
+    * Controller `:params` function has been deprecated
+    * Controller `:identity` function works the same as `:params`
+    * New `:parameters` option can be used to declare which parameters
+    controller is interested in, as data, which should cover most
+    use cases: `{:start start-fn, :parameters {:path [:foo-id]}}`
+
 ## 0.2.13 (2019-01-26)
 
 * Don't throw `StringIndexOutOfBoundsException` with empty path lookup on wildcard paths, fixes [#209](https://github.com/metosin/reitit/issues/209)
@@ -25,7 +34,7 @@
 
 * new options `:inject-match?` and `:inject-router?` on `reitit.http/ring-handler` and `reitit.http/routing-interceptor` to optionally not to inject `Router` and `Match` into the request. See [performance guide](https://metosin.github.io/reitit/performance.html#faster!) for details.
 
-### dependencies 
+### dependencies
 
 * updated:
 
@@ -250,7 +259,7 @@
   * Swagger enchancements
   * Better spec coercion via `st/coerce` using spec walking & inference: many simple specs (core predicates, `spec-tools.core/spec`, `s/and`, `s/or`, `s/coll-of`, `s/keys`, `s/map-of`, `s/nillable` and `s/every`) can be transformed without needing spec to be wrapped. Fallbacks to old conformed based approach.
   * [example app](https://github.com/metosin/reitit/blob/master/examples/ring-spec-swagger/src/example/server.clj).
-  
+
 * updated deps:
 
 ```clj
@@ -396,7 +405,7 @@ Sample apps demonstraing the current status of `reitit`:
   * when Keywords are used in place of middleware / interceptor, a lookup is done into Router option `::middleware/registry` (or `::interceptor/registry`) with the key. Fails fast with missing registry entries.
   * fixes [#32](https://github.com/metosin/reitit/issues/32).
   * full documentation [here](https://metosin.github.io/reitit/ring/middleware_registry.html).
-  
+
  ```clj
 (require '[reitit.ring :as ring])
 (require '[reitit.middleware :as middleware])
diff --git a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
index 9b11bb5b..bf46a3c7 100644
--- a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
@@ -4,38 +4,41 @@
 (defn- pad-same-length [a b]
   (concat a (take (- (count b) (count a)) (repeat nil))))
 
-(defn get-params
-  "Get controller parameters given match. If controller provides :params
-  function that will be called with the match. Default is nil."
-  [controller match]
-  (if-let [f (:params controller)]
-    (f match)))
+(defn get-identity
+  "Get controller identity given controller and match.
 
-(def static
-  "Static params means that the identity of controller
-  doesn't not depend on Match, i.e. any parameters.
+  To select interesting properties from Match :parameters option can be used.
+  Resulting value is map of param-type => param => value.
 
-  This is same as just not defining :params."
-  nil)
+  For other uses, :identity option can be used to provide function from
+  Match to identity.
 
-(defn parameters
-  "Given map of parameter-type => list of keys,
-  returns function taking Match and returning
-  value containing given parameter types and their
-  keys.
+  Default value is nil, i.e. controller identity doesn't depend on Match."
+  [{:keys [identity parameters params]} match]
+  (assert (not (and identity parameters))
+          "Use either :identity or :parameters for controller, not both.")
+  (when params
+    (js/console.warn "Controller :params is deprecated. Replace with :identity or :parameters option."))
+  (cond
+    parameters
+    (into {} (for [[param-type ks] parameters]
+               [param-type (select-keys (get (:parameters match) param-type) ks)]))
 
-  The resulting function can be used for :params."
-  [p]
-  (fn [match]
-    (into {} (for [[param-type ks] p]
-               [param-type (select-keys (get (:parameters match) param-type) ks)]))))
+    identity
+    (identity match)
+
+    ;; Support deprecated :params for transition period. Can be removed later.
+    params
+    (params match)
+
+    :else nil))
 
 (defn apply-controller
   "Run side-effects (:start or :stop) for controller.
   The side-effect function is called with controller params."
   [controller method]
   (when-let [f (get controller method)]
-    (f (::params controller))))
+    (f (::identity controller))))
 
 (defn apply-controllers
   "Applies changes between current controllers and
@@ -43,7 +46,7 @@
   identity has changed."
   [old-controllers new-match]
   (let [new-controllers (mapv (fn [controller]
-                                (assoc controller ::params (get-params controller new-match)))
+                                (assoc controller ::identity (get-identity controller new-match)))
                               (:controllers (:data new-match)))
         changed-controllers (->> (map (fn [old new]
                                         ;; different controllers, or params changed
diff --git a/test/cljs/reitit/frontend/controllers_test.cljs b/test/cljs/reitit/frontend/controllers_test.cljs
index b0acb600..70fbcd9c 100644
--- a/test/cljs/reitit/frontend/controllers_test.cljs
+++ b/test/cljs/reitit/frontend/controllers_test.cljs
@@ -15,15 +15,15 @@
                       :stop  (fn [_] (swap! log conj :stop-2))}
         controller-3 {:start (fn [{:keys [foo]}] (swap! log conj [:start-3 foo]))
                       :stop  (fn [{:keys [foo]}] (swap! log conj [:stop-3 foo]))
-                      :params (fn [match]
-                                {:foo (-> match :parameters :path :foo)})}]
+                      :identity (fn [match]
+                                  {:foo (-> match :parameters :path :foo)})}]
 
     (testing "single controller started"
       (swap! controller-state rfc/apply-controllers
              {:data {:controllers [controller-1]}})
 
       (is (= [:start-1] @log))
-      (is (= [(assoc controller-1 ::rfc/params nil)] @controller-state))
+      (is (= [(assoc controller-1 ::rfc/identity nil)] @controller-state))
       (reset! log []))
 
     (testing "second controller started"
@@ -31,8 +31,8 @@
              {:data {:controllers [controller-1 controller-2]}})
 
       (is (= [:start-2] @log))
-      (is (= [(assoc controller-1 ::rfc/params nil)
-              (assoc controller-2 ::rfc/params nil)]
+      (is (= [(assoc controller-1 ::rfc/identity nil)
+              (assoc controller-2 ::rfc/identity nil)]
              @controller-state))
       (reset! log []))
 
@@ -42,8 +42,8 @@
               :parameters {:path {:foo 5}}})
 
       (is (= [:stop-2 [:start-3 5]] @log))
-      (is (= [(assoc controller-1 ::rfc/params nil)
-              (assoc controller-3 ::rfc/params {:foo 5})]
+      (is (= [(assoc controller-1 ::rfc/identity nil)
+              (assoc controller-3 ::rfc/identity {:foo 5})]
              @controller-state))
       (reset! log []))
 
@@ -53,8 +53,8 @@
               :parameters {:path {:foo 1}}})
 
       (is (= [[:stop-3 5] [:start-3 1]] @log))
-      (is (= [(assoc controller-1 ::rfc/params nil)
-              (assoc controller-3 ::rfc/params {:foo 1})]
+      (is (= [(assoc controller-1 ::rfc/identity nil)
+              (assoc controller-3 ::rfc/identity {:foo 1})]
              @controller-state))
       (reset! log []))
 
@@ -70,11 +70,10 @@
   (let [log (atom [])
         controller-state (atom [])
         static {:start (fn [params] (swap! log conj [:start-static]))
-                :stop  (fn [params] (swap! log conj [:stop-static]))
-                :params rfc/static}
+                :stop  (fn [params] (swap! log conj [:stop-static]))}
         controller {:start (fn [params] (swap! log conj [:start params]))
                     :stop  (fn [params] (swap! log conj [:stop params]))
-                    :params (rfc/parameters {:path [:foo]})}]
+                    :parameters {:path [:foo]}}]
 
     (testing "init"
       (swap! controller-state rfc/apply-controllers
@@ -83,8 +82,8 @@
 
       (is (= [[:start-static]
               [:start {:path {:foo 1}}]] @log))
-      (is (= [(assoc static ::rfc/params nil)
-              (assoc controller ::rfc/params {:path {:foo 1}})]
+      (is (= [(assoc static ::rfc/identity nil)
+              (assoc controller ::rfc/identity {:path {:foo 1}})]
              @controller-state))
       (reset! log []))
 
@@ -95,8 +94,8 @@
 
       (is (= [[:stop {:path {:foo 1}}]
               [:start {:path {:foo 5}}]] @log))
-      (is (= [(assoc static ::rfc/params nil)
-              (assoc controller ::rfc/params {:path {:foo 5}})]
+      (is (= [(assoc static ::rfc/identity nil)
+              (assoc controller ::rfc/identity {:path {:foo 5}})]
              @controller-state))
       (reset! log []))
 

From 9e30836839978750853cf9aaba8a6686d10fbe57 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 4 Dec 2018 15:02:16 +0200
Subject: [PATCH 5/8] Update controller docs

---
 doc/frontend/controllers.md                   | 32 ++++++++++---------
 .../src/reitit/frontend/controllers.cljs      |  7 ++--
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/doc/frontend/controllers.md b/doc/frontend/controllers.md
index 880342e1..4ee8de14 100644
--- a/doc/frontend/controllers.md
+++ b/doc/frontend/controllers.md
@@ -9,32 +9,34 @@ Controllers run code when a route is entered and left. This can be useful to:
 
 ## How controllers work
 
-A controller consists of three functions:
+A controller map can contain these properties:
 
-* `params` which takes a Match and returns an arbitrary value.
-* `start` which takes the result of params and whose return value is discarded.
-* `stop` which takes the result of params and whose return value is discarded.
+* `identity` function which takes a Match and returns an arbitrary value,
+* or `parameters` value, which declares which parameters should affect
+controller identity
+* `start` & `stop` functions, which are called with controller identity
 
-When you navigate to a route that has a controller, `params` gets called first
-and then `start` is called with its return value. When you exit that route,
-`stop` is called with the return value of `params.`
+When you navigate to a route that has a controller, controller identity
+is first resolved by calling `identity` function, or by using `parameters`
+declaration, or if neither is set, the identity is `nil`. Next controller
+is initialized by calling `start` is called with the identity value.
+When you exit that route, `stop` is called with the return value of `params.`
 
-If you navigate to the same route with different parameters, `params` gets
-called again. If the return value changes from the previous return value, `stop`
-and `start` get called again.
+If you navigate to the same route with different match, identity gets
+resolved again. If the identity changes from the previous value, controller
+is reinitialized: `stop` and `start` get called again.
 
 You can add controllers to a route by adding them to the route data in the
 `:controllers` vector. For example:
 
 ```cljs
 ["/item/:id"
- {:controllers [{:params (fn [match] (get-in match [:path-params :id]))
-                 :start  (fn [item-id] (js/console.log :start item-id))
-                 :stop   (fn [item-id] (js/console.log :stop item-id))}]}]
+ {:controllers [{:parameters {:path [:id]}
+                 :start  (fn [parameters] (js/console.log :start (-> parameters :path :id)))
+                 :stop   (fn [parameters] (js/console.log :stop (-> parameters :path :id)))}]}]
 ```
 
-If you leave out `params`, `start` and `stop` get called with `nil`. You can
-leave out `start` or `stop` if you do not need both of them.
+You can leave out `start` or `stop` if you do not need both of them.
 
 ## Enabling controllers
 
diff --git a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
index bf46a3c7..b86c366a 100644
--- a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
@@ -7,8 +7,9 @@
 (defn get-identity
   "Get controller identity given controller and match.
 
-  To select interesting properties from Match :parameters option can be used.
-  Resulting value is map of param-type => param => value.
+  To select interesting properties from Match :parameters option can be set.
+  Value should be param-type => [param-key]
+  Resulting value is map of param-type => param-key => value.
 
   For other uses, :identity option can be used to provide function from
   Match to identity.
@@ -35,7 +36,7 @@
 
 (defn apply-controller
   "Run side-effects (:start or :stop) for controller.
-  The side-effect function is called with controller params."
+  The side-effect function is called with controller identity value."
   [controller method]
   (when-let [f (get controller method)]
     (f (::identity controller))))

From bcfa7878ea7cfa606e3a69d7fbf91232e78eb5bd Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Fri, 8 Feb 2019 10:23:31 +0200
Subject: [PATCH 6/8] Tune wording

---
 doc/frontend/basics.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/frontend/basics.md b/doc/frontend/basics.md
index 3c57b83f..42e0e5e5 100644
--- a/doc/frontend/basics.md
+++ b/doc/frontend/basics.md
@@ -2,9 +2,8 @@
 
 Reitit frontend integration is built from multiple layers:
 
-- Core functions which are enchanted with few browser specific
-features
-- [Browser integration](./browser.md) for attaching Reitit to hash-change or HTML5
+- Core functions with some additional browser oriented features
+- [Browser integration](./browser.md) for attaching Reitit to hash-change or HTML
 history events
 - Stateful wrapper for easy use of history integration
 - Optional [controller extension](./controllers.md)

From 648c92bef813a09ce678d81d2ddb24a7ca60e864 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Fri, 8 Feb 2019 10:39:40 +0200
Subject: [PATCH 7/8] Only display controller :params deprecating warning once

---
 modules/reitit-frontend/src/reitit/frontend/controllers.cljs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
index b86c366a..d3d19778 100644
--- a/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/controllers.cljs
@@ -4,6 +4,9 @@
 (defn- pad-same-length [a b]
   (concat a (take (- (count b) (count a)) (repeat nil))))
 
+(def ^:private params-warning
+  (delay (js/console.warn "Reitit-frontend controller :params is deprecated. Replace with :identity or :parameters option.")))
+
 (defn get-identity
   "Get controller identity given controller and match.
 
@@ -19,7 +22,7 @@
   (assert (not (and identity parameters))
           "Use either :identity or :parameters for controller, not both.")
   (when params
-    (js/console.warn "Controller :params is deprecated. Replace with :identity or :parameters option."))
+    @params-warning)
   (cond
     parameters
     (into {} (for [[param-type ks] parameters]

From aaf9005a9b6a4901302718a9c544f1d85ef6c0fa Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Fri, 8 Feb 2019 10:39:55 +0200
Subject: [PATCH 8/8] Use :parameters instead of :params for controller example

---
 examples/frontend-controllers/src/frontend/core.cljs | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/examples/frontend-controllers/src/frontend/core.cljs b/examples/frontend-controllers/src/frontend/core.cljs
index f279c249..50986e76 100644
--- a/examples/frontend-controllers/src/frontend/core.cljs
+++ b/examples/frontend-controllers/src/frontend/core.cljs
@@ -65,12 +65,11 @@
        {:name ::item
         :parameters {:path {:id s/Int}
                      :query {(s/optional-key :foo) s/Keyword}}
-        :controllers [{:params (fn [match]
-                                 (:path (:parameters match)))
-                       :start (fn [params]
-                                (js/console.log "start" "item controller" (:id params)))
-                       :stop (fn [params]
-                               (js/console.log "stop" "item controller" (:id params)))}]}]]]
+        :controllers [{:parameters {:path [:id]}
+                       :start (fn [{:keys [path]}]
+                                (js/console.log "start" "item controller" (:id path)))
+                       :stop (fn [{:keys [path]}]
+                               (js/console.log "stop" "item controller" (:id path)))}]}]]]
     {:data {:controllers [{:start (log-fn "start" "root-controller")
                            :stop (log-fn "stop" "root controller")}]
             :coercion rsc/coercion}}))