Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow to convey viewers out-of-band using metadata #58

Merged
merged 5 commits into from
Jan 20, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.DS_Store
.cache/
.clerk/
.cpcache/
.lsp/
/node_modules/
Expand Down
24 changes: 24 additions & 0 deletions notebooks/viewer_api_meta.clj
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
;; # Metadata-Based Viewer API
^{:nextjournal.clerk/visibility :hide-ns}
(ns ^:nextjournal.clerk/no-cache viewers-meta
(:require [nextjournal.clerk :as clerk]))

;; Clerk's viewer api has been based on functions like in the following example.

(def tabular-data
(clerk/table {:col-1 ["a" "b" "c"] :col-2 ["a" "b" "c"]}))

;; This isn't always what you want as it performs a transformation of your data.
(keys tabular-data)

;; You can alternatively use metadata on the form to convey the viewer.
^{::clerk/viewer clerk/table}
(def tabular-data-untouched
{:col-1 ["a" "b" "c"] :col-2 ["a" "b" "c"]})

;; And see that it remains untouched. This comes with the added benefit that changing a viewer does not require a recomputation.
(keys tabular-data-untouched)

;; This also works on literals, not just on vars. Though you will less care about transformation in that case – as you'll not be holding a reference to it. As you see in the following example, you can also use keywords instead of functions. This is useful when you don't want to require Clerk.
^{::clerk/viewer :html}
[:h1 "Ohai Hiccup 👋"]
16 changes: 9 additions & 7 deletions src/nextjournal/clerk.clj
Original file line number Diff line number Diff line change
Expand Up @@ -119,17 +119,19 @@
visibility (if-let [fv (hashing/->visibility form)] fv doc-visibility)
cached-result? (and (not no-cache?)
cas-hash
(-> cas-hash ->cache-file fs/exists?))]
(-> cas-hash ->cache-file fs/exists?))
viewer-on-form-meta (let [v (-> form meta ::viewer)]
(cond-> v (symbol? v) resolve))]
#_(prn :cached? (cond no-cache? :no-cache
cached-result? true
cas-hash :no-cas-file
:else :no-digest-file)
:hash hash :cas-hash cas-hash :form form :var var :ns-effect? ns-effect?)
(fs/create-dirs config/cache-dir)
(let [introduced-var var]
(or (when cached-result?
(lookup-cached-result results-last-run introduced-var hash cas-hash visibility))
(eval+cache! form hash digest-file introduced-var no-cache? visibility)))))
(cond-> (or (when cached-result?
(lookup-cached-result results-last-run var hash cas-hash visibility))
(eval+cache! form hash digest-file var no-cache? visibility))
viewer-on-form-meta (assoc :nextjournal/viewer viewer-on-form-meta))))

#_(eval-file "notebooks/test123.clj")
#_(eval-file "notebooks/how_clerk_works.clj")
Expand Down Expand Up @@ -313,6 +315,7 @@
"rule_30"
"visibility"
"viewer_api"
"viewer_api_meta"
"viewers/html"
"viewers/image"
"viewers/markdown"
Expand Down Expand Up @@ -350,8 +353,7 @@
- `:bundle?` builds a single page app versus a folder with an html page for each notebook (defaults to `true`)
- `:path-prefix` a prefix to urls
- `:out-path` a relative path to a folder to contain the static pages (defaults to `\"public/build\"`)
- `:git/sha`, `:git/url` when both present, each page displays a link to `(str url \"blob\" sha path-to-notebook)`
"
- `:git/sha`, `:git/url` when both present, each page displays a link to `(str url \"blob\" sha path-to-notebook)`"
[{:as opts :keys [paths out-path bundle? browse?]
:or {paths clerk-docs
out-path (str "public" fs/file-separator "build")
Expand Down
19 changes: 17 additions & 2 deletions src/nextjournal/clerk/view.clj
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,23 @@
(update result :nextjournal/value (fn [data] (str "data:" content-type ";base64, "
(.encodeToString (java.util.Base64/getEncoder) data)))))

(defn ->result [ns {:nextjournal/keys [value blob-id]} lazy-load?]
(let [described-result (v/describe value {:viewers (v/get-viewers ns (v/viewers value))})


(defn apply-viewer-unwrapping-var-from-def [value viewer]
(let [value (if (get value :nextjournal.clerk/var-from-def)
(-> value :nextjournal.clerk/var-from-def deref)
value)]
(if (var? viewer)
(viewer value)
{:nextjournal/value value
:nextjournal/viewer viewer})))

#_(apply-viewer-unwrapping-var-from-def [:h1 "hi"] :html)
#_(apply-viewer-unwrapping-var-from-def [:h1 "hi"] (resolve 'nextjournal.clerk/html))

(defn ->result [ns {:nextjournal/keys [value blob-id viewer]} lazy-load?]
(let [value (cond-> value viewer (apply-viewer-unwrapping-var-from-def viewer))
described-result (v/describe value {:viewers (v/get-viewers ns (v/viewers value))})
content-type (:nextjournal/content-type described-result)]
(merge {:nextjournal/viewer :clerk/result
:nextjournal/value (cond-> (try {:nextjournal/edn (->edn (cond-> described-result
Expand Down
8 changes: 7 additions & 1 deletion test/nextjournal/clerk_test.clj
Original file line number Diff line number Diff line change
Expand Up @@ -69,4 +69,10 @@

(testing "random expression doesn't get cached with no-cache"
(is (not= (clerk/eval-string "(ns ^:nextjournal.clerk/no-cache my-random-test-ns) (java.util.UUID/randomUUID)")
(clerk/eval-string "(ns ^:nextjournal.clerk/no-cache my-random-test-ns) (java.util.UUID/randomUUID)")))))
(clerk/eval-string "(ns ^:nextjournal.clerk/no-cache my-random-test-ns) (java.util.UUID/randomUUID)"))))

(testing "assigning viewers from form meta"
(is (match? {:blocks [{:result {:nextjournal/viewer #'nextjournal.clerk/table}}]}
(clerk/eval-string "^{:nextjournal.clerk/viewer nextjournal.clerk/table} (def markup [:h1 \"hi\"])")))
(is (match? {:blocks [{:result {:nextjournal/viewer :html}}]}
(clerk/eval-string "^{:nextjournal.clerk/viewer :html} (def markup [:h1 \"hi\"])")))))