diff options
| -rw-r--r-- | README.md | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..be9f685 --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +# Abra + +A small [clojure][1] library for reverse-routing in [compojure][2] +applications. + +[1]: http://clojure.org +[2]: https://github.com/weavejester/compojure + +# Usage + +Include `abra` by adding the following to your dependencies: + + [org.clojars.czan/abra "0.1.0"] + +At the very bottom of your middleware stack (closest to your actual +handlers), apply the `abra.core/wrap-reverse-routing` middleware (any +lower-level middleware must then be applied with +`abra.core/add-middleware`). + +Instead of `compojure.core/`{`defroutes`,`routes`,`context`}, use +`abra.core/`{`defroutes`,`routes`,`context`}. + +As an example: + + (require '[abra.core :refer [routes context] :as abra]) + (def app (-> (routes (context "/api" [] + (-> #'api-routes + (abra/add-middleware api))) + (-> #'site-routes + (abra/add-middleware site))) + abra/wrap-reverse-routing)) + +When giving a route a name, wrap it in a call to +`abra.core/register-route`: + + (defroutes site-routes + (register-route :username + (GET "/username/" [] + (str "a username")))) + +`register-route` currently only supports the standard `compojure` +methods: `GET`, `POST`, `PUT`, `DELETE`, `HEAD` and `ANY`. + +To later retrieve this url, use the `abra.core/url-for` function: + + (defroutes api-routes + (GET "/" [] + (str "url: " (url-for :username)))) + +The `url-for` function at present does not indicate the method to be +used for the url, although this information may be exposed in future. + +A route may also require parameters, in which case the `url-for` +function must be provided the correct number of additional parameters: + + (defroutes test-routes + (context "/user/:id" [id] + (register-route :user-attr + (GET "/:attr" [attr] + (str id "::" attr)))) + (GET "/" [] + (str (url-for :user-attr 10 "name")))) |