Name: secretary
Owner: InterMine
Description: A client-side router for ClojureScript.
Forked from: gf3/secretary
Created: 2016-11-24 14:09:52.0
Updated: 2016-11-24 14:09:53.0
Pushed: 2016-07-26 17:20:03.0
Size: 841
Language: Clojure
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A client-side router for ClojureScript.
Add secretary to your project.clj :dependencies vector:
retary "1.2.3"]
For the current SNAPSHOT version use:
retary "1.2.4-SNAPSHOT"]
To get started :require secretary somewhere in your project.
app.routes
require [secretary.core :as secretary :refer-macros [defroute]]))
Note: starting ClojureScript v0.0-2371, :refer cannot be used to import macros into your project anymore. The proper way to do it is by using :refer-macros as above. When using ClojureScript v0.0-2755 or above, if (:require [secretary.core :as secretary]) is used, macros will be automatically aliased to secretary, e.g. secretary/defroute.
Secretary is built around two main goals: creating route matchers and dispatching actions. Route matchers match and extract parameters from URI fragments and actions are functions which accept those parameters.
defroute is Secretary's primary macro for defining a link between a
route matcher and an action. The signature of this macro is
[name? route destruct & body]. We will skip the name? part
of the signature for now and return to it when we discuss
named routes. To get clearer picture of this
let's define a route for users with an id.
route "/users/:id" {:as params}
s/console.log (str "User: " (:id params))))
In this example "/users/:id" is route, the route matcher,
{:as params} is destruct, the destructured parameters extracted
from the route matcher result, and the remaining
(js/console.log ...) portion is body, the route action.
Before going in to more detail let's try to dispatch our route.
retary/dispatch! "/users/gf3")
With any luck, when we refresh the page and view the console we should
see that User: gf3 has been logged somewhere.
By default the route matcher may either be a string or regular
expression. String route matchers have special syntax which may be
familiar to you if you've worked with Sinatra or
Ruby on Rails. When secretary/dispatch! is called with a
URI it attempts to find a route match and it's corresponding
action. If the match is successful, parameters will be extracted from
the URI. For string route matchers these will be contained in a map;
for regular expressions a vector.
In the example above, the route matcher
"/users/:id" successfully matched against "/users/gf3" and
extracted {:id "gf3} as parameters. You can refer to the table below
for more examples of route matchers and the parameters they return
when matched successfully.
Route matcher | URI | Parameters
———————|——————|————————–
"/:x/:y" | "/foo/bar" | {:x "foo" :y "bar"}
"/:x/:x" | "/foo/bar" | {:x ["foo" "bar"]}
"/files/*.:format" | "/files/x.zip" | {:* "x" :format "zip"}
"*" | "/any/thing" | {:* "/any/thing"}
"/*/*" | "/n/e/thing" | {:* ["n" "e/thing"]}
"/*x/*y" | "/n/e/thing" | {:x "n" :y "e/thing"}
#"/[a-z]+/\d+" | "/foo/123" | ["/foo/123"]
#"/([a-z]+)/(\d+)" | "/foo/123" | ["foo" "123"]
Now that we understand what happens during dispatch we can look at the
destruct argument of defroute. This part is literally sugar
around let. Basically whenever one of our route matches is
successful and extracts parameters this is where we destructure
them. Under the hood, for example with our users route, this looks
something like the following.
[{:as params} {:id "gf3"}]
.)
Given this, it should be fairly easy to see that we could have have written
route "/users/:id" {id :id}
s/console.log (str "User: " id)))
and seen the same result. With string route matchers we can go even further and write
route "/users/:id" [id]
s/console.log (str "User: " id)))
which is essentially the same as saying {:keys [id]}.
For regular expression route matchers we can only use vectors for destructuring since they only ever return vectors.
route #"/users/(\d+)" [id]
s/console.log (str "User: " id)))
If a URI contains a query string it will automatically be extracted to
:query-params for string route matchers and to the last element for
regular expression matchers.
route "/users/:id" [id query-params]
s/console.log (str "User: " id))
s/console.log (pr-str query-params)))
route #"/users/(\d+)" [id {:keys [query-params]}]
s/console.log (str "User: " id))
s/console.log (pr-str query-params)))
n both instances...
retary/dispatch! "/users/10?action=delete")
.. will log
ser: 10
{:action \"delete\"}"
While route matching and dispatch is by itself useful, it is often
necessary to have functions which take a map of parameters and return
a URI. By passing an optional name to defroute Secretary will
define this function for you.
route users-path "/users" []
s/console.log "Users path"))
route user-path "/users/:id" [id]
s/console.log (str "User " id "'s path"))
rs-path) ;; => "/users"
r-path {:id 1}) ;; => "/users/1"
This also works with :query-params.
r-path {:id 1 :query-params {:action "delete"}})
> "/users/1?action=delete"
If the browser you're targeting does not support HTML5 history you can call
retary/set-config! :prefix "#")
to prefix generated URIs with a “#“.
r-path {:id 1})
> "#/users/1"
You can extend Secretary's protocols to your own data types and records if you need special functionality.
IRenderRouteMost of the time the defaults will be good enough but on occasion you
may need custom route rendering. To do this implement IRenderRoute
for your type or record.
record User [id]
cretary/IRenderRoute
ender-route [_]
(str "/users/" id))
ender-route [this params]
(str (secretary/render-route this) "?"
(secretary/encode-query-params params))))
retary/render-route (User. 1))
> "/users/1"
retary/render-route (User. 1) {:action :delete})
> "/users/1?action=delete"
IRouteMatchesIt is seldom you will ever need to create your own route matching
implementation as the built in String and RegExp routes matchers
should be fine for most applications. Still, if you have a suitable
use case then this protocol is available. If your intention is to is
to use it with defroute your implementation must return a map or
vector.
goog.Historyexample
require [secretary.core :as secretary :refer-macros [defroute]]
[goog.events :as events]
[goog.history.EventType :as EventType])
import goog.History))
application
s/document.getElementById "application"))
n set-html! [el content]
set el "innerHTML" content))
retary/set-config! :prefix "#")
#/
route home-path "/" []
et-html! application "<h1>OMG! YOU'RE HOME!</h1>"))
#/users
route users-path "/users" []
et-html! application "<h1>USERS!</h1>"))
#/users/:id
route user-path "/users/:id" [id]
et [message (str "<h1>HELLO USER <small>" id "</small>!</h1>")]
(set-html! application message)))
#/777
route jackpot-path "/777" []
et-html! application "<h1>YOU HIT THE JACKPOT!</h1>"))
atch all
route "*" []
et-html! application "<h1>LOL! YOU LOST!</h1>"))
uick and dirty history configuration.
[h (History.)]
oog.events/listen h EventType/NAVIGATE #(secretary/dispatch! (.-token %)))
oto h (.setEnabled true)))
Distributed under the Eclipse Public License, the same as Clojure.