Lambda Island

In this closing episode of the Luminus introduction, you’ll learn how to extend the template language with custom filters, and how to generate HTML components in code using Hiccup.

Transcript

In part 1 we set up our database, and implemented the rendering of wiki pages. In the second part we saw how to add a form to edit the pages, and we ended by showing the custom markup for links within our wiki, that we’re planning to implement.

In this third and final part of the introduction to Luminus, we’ll implement a custom filter to render these links, and we’ll handle creating new pages, so that the wiki is fully functional.

This is the syntax we want to use for links. Right now that doesn’t work yet, because they’re not valid markdown. For them to work we’ll have to do some extra processing when rendering a page. The Selmer templating system lets you write your own filters, so we’ll make one called wiki-links to render our links.

<!-- wiki-page.html -->
{{body|wiki-links|markdown}}

This filter isn’t defined yet, let’s fix that. The layout namespace is where Luminus puts custom tags and filters. You can see the markdown filter that we used earlier, as well as the csrf-field tag we needed for the form.

Add a new filter called wiki-links. We’ll just pass through the content for now. Let’s test that, everything should still work as before.

(ns lambwiki.layout
  ,,,)
,,,

(defn wiki-links [content]
  content)

(filters/add-filter! :wiki-links wiki-links)

Now we need to pull out those links, which I’m doing with a regular expression. I have to admit it looks horrible, as regular expressions often do. I’ll add a link in the show notes to a regex fiddle so you can play around with it a bit. (http://refiddle.com/9rip)

Let’s implement this step by step. This first version should verify that that regexp is doing its job.

(ns lambwiki.layout
  (:require ,,,
            [clojure.string :as str]))

(defn wiki-links [content]
  (str/replace content #"\[\[([^\]]+)\]\]" "<a>$1</a>"))

Sure enough, they’re links now, but they don’t go anywhere yet.

To fix that, we need to turn the human readable title into something more suitable for use in a URL. This regexp replaces every sequence of one or more non-word characters with a single dash. We’ll also make everything lower case for consistency.

How can we use that function now to generate the links? Turns out string/replace can take a function as its final argument, instead of a string. That gives us a bit more flexibility. This inner function receives a vector containing both the fully matched form including the outer brackets, and the title part that’s inside the capturing group. With some destructuring you can ignore the first part and just get the title.

(ns lambwiki.layout
  (:require ,,,
            [clojure.string :as str]))

(defn- title->uri-slug [title]
  (str/lower-case (str/replace title #"\W+" "-")))

(defn wiki-links [content]
  (str/replace content #"\[\[([^\]]+)\]\]"
               (fn [[_ title]]
                 (str "<a href=\"" (title->uri-slug title) "\">" title "</a>"))))

So now it renders the links, but when the page doesn’t exist yet, the link should go straight to the form so we can edit the page. Cause right now all we get is a 404.

We need to check if there’s a corresponding page when rendering each link. I’ll use a bit more clj-refactor magic here. First I introduce a let form, then use “expand let” until it’s at the right scope.

Now I’ll use that uri-slug to see if there’s a corresponding page. If there is then we get the old behavior, if the page doesn’t exist the link goes to the edit route so you get a form. I’m also adding an extra class on those links, so we can style them a bit differently.

(ns lambwiki.layout
  (:require ,,,
            [lambwiki.db.core :refer [find-page-by-uri-slug]]))

(defn- title->uri-slug [title]
  (str/lower-case (str/replace title #"\W+" "-")))

(defn wiki-links [content]
  (str/replace content #"\[\[([^\]]+)\]\]"
               (fn [[_ title]]
                 (let [uri-slug (title->uri-slug title)]
                   (if (find-page-by-uri-slug {:uri_slug uri-slug})
                     (str "<a href=\"/" uri-slug "\">" title "</a>")
                     (str "<a class=\"new-page-link\" href=\"/" uri-slug "/edit\">" title "</a>"))))))

Links to new pages should show up bright red.

Now it’s really starting to feel like a wiki, what with them colored links and all, but we’re still getting 404s. Let’s have another look at the edit route.

/* resources/public/screen.css */

/* ... */

.new-page-link {
  color: red;
}

When the page doesn’t exist it does nothing. Instead we’ll also render the form page. It also needs to know the uri slug of the new page so the form can submit to the right place. For that we can pass the params map right through.

(ns lambwiki.routes.home)
,,,

  (GET "/:uri_slug/edit" {{:keys [uri_slug] :as params} :params}
    (if-let [page (find-page-by-uri-slug {:uri_slug uri_slug})]
      (edit-page page)
      (edit-page params)))

So far so good, let’s try that. Yeah we need to handle saving new pages as well, but the POST went to the right URI, so that’s good.

Saving new pages is not that different from how we handle existing pages. We will still have to create a revision, but before we can do that we need to create a new page. Don’t forget to add that create-page! function to the namespace.

(ns lambwiki.routes.home)
,,,

  (POST "/:uri_slug" {{:keys [uri_slug title body] :as params} :params}
    (let [page (or (find-page-by-uri-slug {:uri_slug uri_slug})
                   (create-page! {:uri_slug uri_slug}))]
      (create-revision! {:page_id (:id page)
                         :body body
                         :title title})
      (wiki-page params)))

Awesome! That totally works. I wish I knew more about lambs, so I could populate this wiki a bit more. Oh well let’s just make some stuff up.

Something bothers me about this workflow though, I’m already choosing a title when I create the link, and now I have to enter it again in the form. Let’s fix that.

Let’s have another look at that wiki-links function. Does it bother you? It bothers me. It’s generating HTML by mashing a bunch of strings together. How terribly uncivilized. Let’s clean that up a bit with the help of Hiccup.

I’m using clj-refactor again to add a new project dependency. If you’re following along at home and you don’t have clj-refactor, just add this section to project.clj, and then restart your REPL.

(defproject lambwiki
  ,,,

  :dependencies [,,,
                 [hiccup "1.0.5"]]

  ,,,)

Hiccup lets you write HTML using Clojure Syntax, so with simple vectors, keywords, and maps. These are much easier to compose than strings.

(hiccup/html [:div [:p {:class "important"} "Lambs have" [:a {:href "/tentacles"} "Tentacles"]]])
;;=> "<div><p class=\"important\">Lambs have<a href=\"/tentacles\">Tentacles</a></p></div>"

Let me rewrite this link generation using Hiccup syntax. Wrap the result in hiccup/html, and we’re good to go. Doesn’t that look a whole lot better?

(ns lambwiki.layout
  (:require ,,,
            [hiccup.core :as hiccup]))

(defn wiki-links [content]
  (str/replace content #"\[\[([^\]]+)\]\]"
   (fn [[_ title]]
     (let [uri-slug (title->uri-slug title)]
       (hiccup/html
        (if (find-page-by-uri-slug {:uri_slug uri-slug})
          [:a {:href (str "/" uri-slug)} title]
          [:a {:class "new-page-link" :href (str "/" uri-slug "/edit")} title]))))))

Ok, now what I’ll do is add a query parameter to those new page links, so we don’t lose track of the title of the link.

Let’s refactor this a bit first because it’s getting unwieldy. The only part of the link that really changes are the attributes, if I pull those into their own function it becomes a bit easier to see what’s going on.

Now that we’re sticking random user input in the URL we need to make sure to properly encode it. If our needs got more complex than we should consider using a proper URL library, but for now Ring’s url-encode function will do the trick.

(ns lambwiki.layout
  (:require ,,,
            [ring.util.codec :refer [url-encode]]))

(defn- link-attrs [title uri-slug]
  (if (find-page-by-uri-slug {:uri_slug uri-slug})
    {:href (str "/" uri-slug)}
    {:href (str "/" uri-slug "/edit?title=" (url-encode title)) :class "new-page-link" }))

(defn wiki-links [content]
  (str/replace content #"\[\[([^\]]+)\]\]"
   (fn [[_ title]]
     (let [uri-slug (title->uri-slug title)]
       (html [:a (link-attrs title uri-slug) title])))))

Let’s try that. The title is in the link now, and it’s get prepopulated in the form.

Maybe that’s a bit surprising, but remember how in this route we passed the params map right through to the function that renders the form? Before the params only contained the uri slug, but now they contain the title as well.

  (GET "/:uri_slug/edit" {{:keys [uri_slug] :as params} :params}
    (if-let [page (find-page-by-uri-slug {:uri_slug uri_slug})]
      (edit-page page)
      (edit-page params)))

And that’s it, time to wrap this up.

git add -A
git commit

I hope you enjoyed this guided tour of Luminus. We covered a lot of ground in these two episodes, from migrations and queries, to routes, templates, and custom content filters. We didn’t have time to cover any of those aspects in depth, but hopefully this has given you enough material to start tinkering.

Introduction to Luminus, part 3