feat: Dynamic links - replaceLink function (#150)

docs/Links.md

@@ -0,0 +1,11 @@
+# Dynamic Links
+
+You can replace hyperlinks in the template file with dynamic links by using the `replaceLink` function after a placeholder link in the document: 
+
+<code>
+{<i>%=replaceLink(url)%</i>}
+</code>
+
+The value of `url` is not validated, it is converted to string if needed. 
+
+The expression replaces the link URL in the hyperlink preceding this expression, therefore, it should be placed immediately after the link, we want to modify.

docs/index.md

@@ -17,6 +17,7 @@ You can find the project on [Stencil's GitHub](https://github.com/erdos/stencil)
 - Reuse parts of templates with [Fragments](Fragments.md)
 - Run it in [Standalone Mode](Standalone.md) for batch processing
 - [Dynamic images](Images.md)
+- [Dynamic links](Links.md)
 
 
 ## For Programmers

examples/links/README.md

@@ -0,0 +1,4 @@
+# Replace links in template
+
+In this example, you can see how to replace hyperlinks in a `for` loop in the template document. 
+The `urls` array in the input JSON map contains the URLs generated into the result.

examples/links/data.json

@@ -0,0 +1,6 @@
+{
+ "urls": [
+ "https://stencil.erdos.dev",
+ "https://httpbin.org/get?data=1&data2=2"
+ ]
+}

src/stencil/ooxml.clj

@@ -121,4 +121,6 @@
  "http:https://schemas.microsoft.com/office/spreadsheetml/2016/revision10" "xr10"})
 
 ;; drawing, binary large image or picture
-(def blip :xmlns.http%3A%2F%2Fschemas.openxmlformats.org%2Fdrawingml%2F2006%2Fmain/blip)
+(def blip :xmlns.http%3A%2F%2Fschemas.openxmlformats.org%2Fdrawingml%2F2006%2Fmain/blip)
+;; hyperlinks
+(def hyperlink :xmlns.http%3A%2F%2Fschemas.openxmlformats.org%2Fwordprocessingml%2F2006%2Fmain/hyperlink)

src/stencil/postprocess/links.clj

@@ -0,0 +1,53 @@
+(ns stencil.postprocess.links
+ (:require [clojure.zip :as zip]
+ [stencil.functions :refer [call-fn]]
+ [stencil.log :as log]
+ [stencil.ooxml :as ooxml]
+ [stencil.model.relations :as relations]
+ [stencil.types :refer [ControlMarker]]
+ [stencil.util :refer [fail find-first iterations dfs-walk-xml-node]]))
+
+(set! *warn-on-reflection* true)
+
+;; Tells if the reference of an adjacent hyperlink node should be replaced in postprocess step.
+(defrecord ReplaceLink [relation] ControlMarker)
+
+(defn- update-link [link-node, ^ReplaceLink data]
+ (assert (= ooxml/hyperlink (:tag link-node)))
+ (assert (instance? ReplaceLink data))
+ (let [current-rel (-> link-node :attrs ooxml/r-id)
+ new-val (-> data .relation)]
+ (assert new-val)
+ (log/debug "Replacing hyperlink relation {} by {}" current-rel new-val)
+ (assoc-in link-node [:attrs ooxml/r-id] new-val)))
+
+(defn- replace-link [marker-loc]
+ (if-let [link-loc (->> (zip/remove marker-loc)
+ (iterations zip/prev)
+ (find-first (comp #{ooxml/hyperlink} :tag zip/node)))]
+ (zip/edit link-loc update-link (zip/node marker-loc))
+ (fail "Did not find hyperlink to replace. The location of target link must precede the replaceLink() function call location." {})))
+
+(defn replace-links [xml-tree]
+ (dfs-walk-xml-node
+ xml-tree
+ (partial instance? ReplaceLink)
+ replace-link))
+
+;; This duplicates both stencil.postprocess.image/->relation-id,
+;; and stencil.model.relations/->relation-id
+;; TODO: maybe make stencil.model.relations/->relation-id public
+(defn- ->relation-id [] (str (gensym "srel")))
+
+(defn- link-url->relation [url]
+ (let [new-rel (->relation-id)]
+ {:new-id new-rel
+ :stencil.model/type relations/rel-type-hyperlink
+ :stencil.model/target url
+ :stencil.model/mode "External"}))
+
+;; replaces the nearest link's URK with the parameter value
+(defmethod call-fn "replaceLink" [_ url]
+ (let [new-relation (link-url->relation (str url))]
+ (relations/add-extra-file! new-relation)
+ (->ReplaceLink (:new-id new-relation))))

src/stencil/tree_postprocess.clj

@@ -4,6 +4,7 @@
  [stencil.postprocess.whitespaces :refer :all]
  [stencil.postprocess.ignored-tag :refer :all]
  [stencil.postprocess.images :refer :all]
+ [stencil.postprocess.links :refer :all]
  [stencil.postprocess.list-ref :refer :all]
  [stencil.postprocess.fragments :refer :all]
  [stencil.postprocess.html :refer :all]))
@@ -28,5 +29,7 @@
 
  #'replace-images
 
+ #'replace-links
+
  ;; call this first. includes fragments and evaluates them too.
  #'unpack-fragments))

test/stencil/api_test.clj

@@ -133,6 +133,12 @@
  (with-open [template (prepare "test-resources/test-image-1.docx")]
  (render! template data :output f :overwrite? true))))
 
+(deftest test-link
+ (let [data {"url" "https://stencil.erdos.dev/?data=1&data2=2"}
+ f (java.io.File/createTempFile "stencil" ".docx")]
+ (with-open [template (prepare "test-resources/test-link-1.docx")]
+ (render! template data :output f :overwrite? true))))
+
 (deftest test-multipart
  (let [template (prepare "test-resources/multipart/main.docx")
  body (fragment "test-resources/multipart/body.docx")