hype.core — io.logicblocks/hype 2.0.1-RC2

Hypermedia functions for ring routers.

hype currently provides support for:

• generating paths or URLs,
• including template parameters, and
• converting between paths and URLs.

hype includes built in backends for bidi and reitit and includes extension points allowing other routers to be supported.

absolute-path->absolute-url clj

(absolute-path->absolute-url request absolute-path)

Builds an absolute URL by appending absolute-path to the base URL of request.

The request should be a ring request or equivalent. The URL is returned as a string.

absolute-path-for clj

(absolute-path-for router route)

(absolute-path-for router
                   route
                   {:keys [path-params path-template-params
                           path-template-param-key-fn query-params
                           query-param-key-fn query-template-params
                           query-template-param-key-fn]
                    :or {path-params {}
                         path-template-params {}
                         path-template-param-key-fn csk/->camelCaseString
                         query-params {}
                         query-param-key-fn csk/->camelCaseString
                         query-template-params []
                         query-template-param-key-fn csk/->camelCaseString}
                    :as params})

Builds an absolute path for route based on router and params where:

• router is a reitit router or a bidi routes data structure,
• route is a keyword identifying the name of the route for which to build a path,
• params is an optional map which optionally includes any of:
  • path-params: parameters defined in the routes as route patterns, specified as a map,
  • path-template-params: parameters that should remain templatable in the resulting path, specified as a map from path parameter name to template variable name, as keywords.
  • path-template-param-key-fn: a function to apply to path template variable names before including in the path, camel casing by default.
  • query-params: parameters that should be appended to the path as query string parameters, specified as a map,
  • query-param-key-fn: a function to apply to query parameter keys before including in the path, camel casing by default,
  • query-template-params: parameters that should be appended to the path as query string template parameters, specified as a sequence of parameter names,
  • query-template-param-key-fn: a function to apply to query template parameter keys before including in the path, camel casing by default.

The path is returned as a string.

Examples:

;; bidi
(def router
  ["/" {"index.html" :index
          "articles/" {"index.html" :article-index
                         [:id "/article.html"] :article}}])
;; or reitit
(def router
  (reitit/router
    [["/index.html" :index]
     ["/articles/index.html" :article-index]
     ["/articles/:id/article.html" :article]]))

(absolute-path-for router :index)
; => "/index.html"

(absolute-path-for router :article
  {:path-params {:id 10}})
; => "/articles/10/article.html"

(absolute-path-for router :article
  {:path-template-params {:id :article-id}})
; => "/articles/{articleId}/article.html"

(absolute-path-for router :article
  {:path-template-params {:id :articleID}
   :path-template-param-key-fn clojure.core/identity})
; => "/articles/{articleID}/article.html"

(absolute-path-for router :article-index
  {:query-params {:latest true
                  :sort-direction "descending"}
   :query-template-params [:per-page :page]})
; => "/articles/index.html?latest=true&sortDirection=descending{&perPage,page}"

(absolute-path-for router :article
  {:path-params {:id 10}
   :query-template-params [:include-author, :include-images]})
; => "/articles/10/article.html{?includeAuthor,includeImages}"

(absolute-path-for router :article-index
  {:query-params {:latest true
                  :sort-direction "descending"}
   :query-param-key-fn clojure.core/identity
   :query-template-params [:per-page :page]
   :query-template-param-key-fn clojure.core/identity})
; => "/articles/index.html?latest=true&sort-direction=descending{&per-page,page}"

absolute-url-for clj

(absolute-url-for request router route)

(absolute-url-for request router route params)

Builds an absolute URL for route based on request, router and params where:

• router is a reitit router or a bidi routes data structure,
• route is a keyword identifying the name of the route for which to build a path,
• params is an optional map which optionally includes any of:
  • path-params: parameters defined in the routes as route patterns, specified as a map,
  • path-template-params: parameters that should remain templatable in the resulting path, specified as a map from path parameter name to template variable name, as keywords.
  • path-template-param-key-fn: a function to apply to path template variable names before including in the path, camel casing by default.
  • query-params: parameters that should be appended to the path as query string parameters, specified as a map,
  • query-param-key-fn: a function to apply to query parameter keys before including in the path, camel casing by default,
  • query-template-params: parameters that should be appended to the path as query string template parameters, specified as a sequence of parameter names,
  • query-template-param-key-fn: a function to apply to query parameter template keys before including in the path, camel casing by default.

The request should be a ring request or equivalent. The URL is returned as a string.

Examples: (require '[ring.mock.request :as ring-mock])

(def request (ring-mock/request "GET" "https://localhost:8080/help"))

;; bidi
(def router
  ["/" {"index.html" :index
          "articles/" {"index.html" :article-index
                         [:id "/article.html"] :article}}])
;; or reitit
(def router
  (reitit/router
    [["/index.html" :index]
     ["/articles/index.html" :article-index]
     ["/articles/:id/article.html" :article]]))

(absolute-url-for request router :index)
; => "https://localhost:8080/index.html"

(absolute-url-for request router :article
  {:path-params {:id 10}})
; => "https://localhost:8080/articles/10/article.html"

(absolute-url-for request router :article
  {:path-template-params {:id :article-id}})
; => "https://localhost:8080/articles/{articleId}/article.html"

(absolute-url-for request router :article
  {:path-template-params {:id :articleID}
   :path-template-param-key-fn clojure.core/identity})
; => "https://localhost:8080/articles/{articleID}/article.html"

(absolute-url-for request router :article-index
  {:query-params {:latest true
                  :sort-direction "descending"}
   :query-template-params [:per-page :page]})
; => "https://localhost:8080/articles/index.html?latest=true&sortDirection=descending{&perPage,page}"

(absolute-url-for request router :article
  {:path-params {:id 10}
   :query-template-params [:include-author :include-images]})
; => "https://localhost:8080/articles/10/article.html{?includeAuthor,includeImages}"

(absolute-url-for request router :article-index
  {:query-params {:latest true
                  :sort-direction "descending"}
   :query-param-key-fn clojure.core/identity
   :query-template-params [:per-page :page]
   :query-template-param-key-fn clojure.core/identity})
; => "https://localhost:8080/articles/index.html?latest=true&sort-direction=descending{&per-page,page}"

Backend clj protocol

path-for clj

(path-for _ route-name parameters)

BackendFactory clj protocol

backend-for clj

(backend-for thing)

base-url clj

(base-url request)

Returns the URL used to reach the server based on request.

The request should be a ring request or equivalent. The URL is returned as a string.