Replace controller :params with :identity and :parameters

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)

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
+(defn get-identity
-  "Get controller parameters given match. If controller provides :params
+  "Get controller identity given controller and match.
-  function that will be called with the match. Default is nil."
-  [controller match]
-  (if-let [f (:params controller)]
-    (f match)))
 
-(def static
+  To select interesting properties from Match :parameters option can be used.
-  "Static params means that the identity of controller
+  Resulting value is map of param-type => param => value.
-  doesn't not depend on Match, i.e. any parameters.
 
-  This is same as just not defining :params."
+  For other uses, :identity option can be used to provide function from
-  nil)
+  Match to identity.
 
-(defn parameters
+  Default value is nil, i.e. controller identity doesn't depend on Match."
-  "Given map of parameter-type => list of keys,
+  [{:keys [identity parameters params]} match]
-  returns function taking Match and returning
+  (assert (not (and identity parameters))
-  value containing given parameter types and their
+          "Use either :identity or :parameters for controller, not both.")
-  keys.
+  (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."
+    identity
-  [p]
+    (identity match)
-  (fn [match]
+
-    (into {} (for [[param-type ks] p]
+    ;; Support deprecated :params for transition period. Can be removed later.
-               [param-type (select-keys (get (:parameters match) param-type) ks)]))))
+    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

test/cljs/reitit/frontend/controllers_test.cljs

@@ -15,7 +15,7 @@
                       :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]
+                      :identity (fn [match]
                                   {:foo (-> match :parameters :path :foo)})}]
 
     (testing "single controller started"
@@ -23,7 +23,7 @@
              {: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)
+      (is (= [(assoc controller-1 ::rfc/identity nil)
-              (assoc controller-2 ::rfc/params 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)
+      (is (= [(assoc controller-1 ::rfc/identity nil)
-              (assoc controller-3 ::rfc/params {:foo 5})]
+              (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)
+      (is (= [(assoc controller-1 ::rfc/identity nil)
-              (assoc controller-3 ::rfc/params {:foo 1})]
+              (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]))
+                :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]})}]
+                    :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)
+      (is (= [(assoc static ::rfc/identity nil)
-              (assoc controller ::rfc/params {:path {:foo 1}})]
+              (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)
+      (is (= [(assoc static ::rfc/identity nil)
-              (assoc controller ::rfc/params {:path {:foo 5}})]
+              (assoc controller ::rfc/identity {:path {:foo 5}})]
              @controller-state))
       (reset! log []))