darkleaf.router

https://github.com/darkleaf/router.git


    git clone 'https://github.com/darkleaf/router.git'
      

      

(ql:quickload :darkleaf.router)

★76

Router

Bidirectional RESTfull Ring router for clojure and clojurescript.

Comparation

| library | clj | cljs | dsl | named routes | mountable apps | abstraction | export format | extensibility | | — | — | — | — | — | — | — | — | — | | compojure | ✓ | | macros | | | url | | | | secretary | | ✓ | macros | ✓ | | url | | protocols | | bidi | ✓ | ✓ | data/functions | ✓ | | url | route description data | protocols | | darkleaf/router | ✓ | ✓ | functions | ✓ | ✓ | resource | explain data | protocols |

Usage

(ns app.some-ns
  (:require [darkleaf.router :as r]
            [ring.util.response :refer [response]]))

(r/defcontroller controller
  (index [req]
    (let [request-for (::r/request-for req)]
      (response (str (request-for :index [:pages] {}))))))

(def routing (r/resources :pages :page controller))

(def handler (r/make-handler routing))
(def request-for (r/make-request-for routing))

(handler {:uri "/pages", :request-method :get}) ;; call index action from controller
(request-for :index [:pages] {}) ;; returns {:uri "/pages", :request-method :get}

Single routing namespace: ``` clojure (ns app.routing (:require [darkleaf.router :as r] [app.controllers.session :as session] [app.controllers.users :as users] [app.controllers.users.pm-bonus :as users.pm-bonus] [app.controllers.projects.status :as projects.status] [app.controllers.tasks :as tasks] [app.controllers.tasks.comments :as tasks.comments]))

(def routes (r/group (r/resource :main main/controller :segment false) (r/resource :session session/controller) (r/section :account (r/resources :invites :invite account.invites/controller)) (r/resources :users :user users/controller (r/resource :statistics users.statistics/controller) (r/resource :pm-bonus users.pm-bonus/controller)) (r/resources :projects :project projects/controller (r/resource :status projects.status/controller) (r/resource :completion projects.completion/controller)) (r/resources :tasks :task tasks/controller (r/resource :status tasks.status/controller) (r/resources :comments tasks.comments/controller)))) ```

Multiple routing namespaces: ``` clojure (ns app.routes.main (:require [darkleaf.router :as r]))

(r/defcontroller controller (show [req] …))

(def routes (r/resource :main main-controller :segment false))

(ns app.routes (:require [darkleaf.router :as r] [app.routes.session :as session] [app.routes.users :as users] [app.routes.tasks :as tasks]))

(def routes (r/group main/routes session/routes account/routes users/routes projects/routes tasks/routes)) ```

Use cases

Rationale

Routing libraries work similarly on all programming languages: they only map uri with a handler using templates. For example compojure, sinatra, express.js, cowboy.

There are some downsides of this approach.

No reverse or named routing. Url is set in templates as a string.
Absence of structure. Libraries do not offer any ways of code structure, that results of chaos in url and unclean code.
Inability to mount an external application. Inability to create html links related with mount point.
Inability to serialize routing and use it in other external applications for request forming.

Most of these problems are solved in Ruby on Rails.

If you know the action, controller name and parameters, you can get url, for example: edit_admin_post_path(@post.id).
You can use rest resources to describe routing. Actions of controllers match to handlers. However, framework allows to add non-standart actions into controller, that makes your code unlean later.
There is an engine support. For example, you can mount a forum engine into your project or decompose your application into several engines.
There is an API for routes traversing, which uses rake routes command. The library js-routes brings url helpers in js.

Solution my library suggests.

Knowing action, scope and params, we can get the request, which invokes the handler of this route: (request-for :edit [:admin :post] {:post "1"}).
The main abstraction is the rest resource. Controller contains only standard actions. You can see resource composition how to deal with it.
Ability to mount an external application. See example for details.
The library interface is identical in clojure and clojurecript, that allows to share the code between server and client using .cljc files. You can also export routing description with cross-platform templates as a simple data structure. See example for details.

Resources

| Action name | Scope | Params | Http method | Url | Type | Used for | | — | — | — | — | — | — | — | | index | [:pages] | {} | Get | /pages | collection | display a list of pages | | show | [:page] | {:page 1} | Get | /pages/1 | member | display a specific page | | new | [:page] | {} | Get | /pages/new | collection | display a form for creating new page | | create | [:page] | {} | Post | /pages | collection | create a new page | | edit | [:page] | {:page 1} | Get | /pages/1/edit | member | display a form for updating page | | update | [:page] | {:page 1} | Patch | /pages/1 | member | update a specific page | | put | [:page] | {:page 1} | Put | /pages/1 | member | upsert a specific page, may be combined with edit action | | destroy | [:page] | {:page 1} | Delete | /pages/1 | member | delete a specific page |

(ns app.some-ns
  (:require [darkleaf.router :as r]
            [ring.util.response :refer [response]]))

;; all items are optional
(r/defcontroller pages-controller
  (middleware [h]
    (fn [req] (h req)))
  (collection-middleware [h]
    (fn [req] (h req)))
  (member-middleware [h]
    (fn [req] (h req)))
  (index [req]
    (response "index resp"))
  (show [req]
    (response "show resp"))
  (new [req]
    (response "new resp"))
  (create [req]
    (response "create resp"))
  (edit [req]
    (response "edit resp"))
  (update [req]
    (response "update resp"))
  (put [req]
    (response "put resp"))
  (destroy [req]
    (response "destroy resp")))

;; :index [:pages] {} -> /pages
;; :show [:page] {:page 1} -> /pages/1
(r/resources :pages :page pages-controller)

;; :index [:people] {} -> /menschen
;; :show [:person] {:person 1} -> /menschen/1
(r/resources :people :person people-controller :segment "menschen")

;; :index [:people] {} -> /
;; :show [:person] {:person 1} -> /1
(r/resources :people :person people-controller :segment false)

;; :put [:page :star] {:page 1} -> PUT /pages/1/star
(r/resources :pages :page pages-controller
  (r/resource :star star-controller)

There are 3 types of middlewares:

middleware applied to all action handlers including nested.
collection-middleware applied only to index, new and create actions.
member-middleware applied to show, edit, update, put, delete and all nested handlers, look here for details.

Please see test for all examples.

Resource

| Action name | Scope | Params | Http method | Url | Used for | — | — | — | — | — | — | | show | [:star] | {} | Get | /star | display a specific star | | new | [:star] | {} | Get | /star/new | display a form for creating new star | | create | [:star] | {} | Post | /star | create a new star | | edit | [:star] | {} | Get | /star/edit | display a form for updating star | | update | [:star] | {} | Patch | /star | update a specific star | | put | [:star] | {} | Put | /star | upsert a specific star, may be combined with edit action | | destroy | [:star] | {} | Delete | /star | delete a specific star |

;; all items are optional
(r/defcontroller star-controller
  ;; will be applied to nested routes too
  (middleware [h]
    (fn [req] (h req)))
  (show [req]
    (response "show resp"))
  (new [req]
    (response "new resp"))
  (create [req]
    (response "create resp"))
  (edit [req]
    (response "edit resp"))
  (update [req]
    (response "update resp"))
  (put [req]
    (response "put resp"))
  (destroy [req]
    (response "destroy resp")))

;; :show [:star] {} -> /star
(r/resource :star star-controller)

;; :show [:star] {} -> /estrella
(r/resource :star star-controller :segment "estrella")

;; :show [:star] {} -> /
(r/resource :star star-controller :segment false)

;; :index [:star :comments] {} -> /star/comments
(r/resource :star star-controller
  (r/resources :comments :comment comments-controller)