Clojure Web Development Essentials

The basic makeup of a Leiningen task can be summarized as follows:

# lein $TASK $TASK_ARGUMENTS

In the preceding shell pseudo-command, we invoke Leiningen using its binary. The lein $TASK argument is the Leiningen task we want to execute (such as install, jar, etc.), and $TASK_ARGUMENTS is any information required for that task to do its job, including additional subtasks and the arguments for a given subtask. You can see a full list of the available tasks in Leiningen by executing the following command:

# lein --help

You can also view the help content for a specific Leiningen task by executing the following command:

# lein help $TASK

You can use these commands whenever you need to know how to do something in Leiningen.

Leiningen can generate an application skeleton (or scaffolding) from a plethora of different templates. There's a template for nearly everything such as clojurescript projects, web applications (of course), and much more.

To generate a new application, we use the new Leiningen task whose basic syntax is as follows:

# lein new [$TEMPLATE_NAME] $PROJECT_NAME

The new task expects, at a minimum, a name for the project ($PROJECT_NAME). Optionally, we can provide a specific template to use ($TEMPLATE_NAME). If we don't specify a template, then lein will use the default template, which is a general template for developing libraries.

For our project we'll use the Luminus template, an excellent template for web applications. Luminus generates a project and wires in the libraries to support pretty much every aspect of web development including sessions, cookies, route handling, and template rendering.

:user {:plugins [[luminus/lein-template "1.16.7"]]}

Just try the following command:

# lein new luminus hipstr
>> Generating a lovely new luminus project named hipstr…

The preceding command will generate a fully runnable application in a directory called hipstr. You can run the application by using cd hipstr to enter into the hipstr directory and then execute the following command:

# lein ring server
>>(Retrieving im/chit/cronj/1.0.1/cronj-1.0.1.pom from clojars)
>>…a whole bunch of Retrieving…
>>…and other output…
>>Started server on port 3000

In the preceding command line, the lein ring server command updates our class path with the dependencies required to compile and run the app. It then launches the development server (an embedded Jetty server) and starts serving on port 3000. Lastly, it launches our default web browser and navigates to the root page.

The subsequent output of lein ring server is a series of debug statements that lets us know what the heck is going on during the startup process. Any generated exceptions or problems that occur while attempting to launch the application will be emitted as part of this output.

If anything doesn't go as planned, or you're stumped and confused, feel free to check the Luminus documentation at http://www.luminusweb.net. You can also get some help from people in the Luminus community (https://groups.google.com/forum/?fromgroups#!forum/luminusweb) or the Ring community (https://groups.google.com/forum/?fromgroups#!forum/ring-clojure). Of course, there's always the Clojure group on Google Groups (https://groups.google.com/forum/).

The hipstr.util namespace is a simple namespace where you can put various helper functions you find yourself frequently using during the development of your application. Out of the box, Luminus generates a hipstr.util namespace with a single function, md->html, which converts markdown into HTML. Typically, I try to avoid namespaces such as util.clj because they eventually turn into the junk drawer in your kitchen, but they can be useful on smaller projects if things don't get too crowded. The following block of code shows the hipstr.util namespace:

(ns hipstr.util
  (:require [noir.io :as io]
            [markdown.core :as md]))

(defn md->html
  "reads a markdown file from public/md and returns an HTML
   string"
  [filename]
  (md/md-to-html-string (io/slurp-resource filename)))

One of lib-noir's exposed functionalities is session management (which we'll discuss in detail in Chapter 10, Sessions and Cookies). The default session pool in Luminus is an in-memory session pool, a shortcoming of which is that expired sessions are only removed from memory when the server handles a request associated with an expired session. As a result, old stale sessions can linger in memory indefinitely, straining memory resources on the server. Luminus boilerplates a cronj job in the hipstr.sessions-manager namespace, which occasionally removes stale, unused sessions. By default, the job runs every 30 minutes. Take a look at the following lines of code:

(ns hipstr.session-manager
  (:require [noir.session :refer [clear-expired-sessions]]
            [cronj.core :refer [cronj]]))

(def cleanup-job
  (cronj
    :entries
    [{:id "session-cleanup"
      :handler (fn [_ _] (clear-expired-sessions))
      :schedule "* /30 * * * * *"
      :opts {}}]))

The hipstr.layout namespace houses the functions that are used to render the HTTP response body. By default, Luminus creates a single function, render, which will render any Selmer template onto the HTTP response.The following lines of code is for the hipstr.layout namespace:

(ns hipstr.layout
  (:require [selmer.parser :as parser]
            [clojure.string :as s]
            [ring.util.response :refer [content-type response]]
            [compojure.response :refer [Renderable]]
            [environ.core :refer [env]]))

(def template-path "templates/")

(deftype RenderableTemplate [template params]
  Renderable
  (render [this request]
    (content-type
      (->> (assoc params
        (keyword
        (s/replace template #".html" "-selected"))"active"
          :dev (env :dev)
            :servlet-context
              (if-let [context (:servlet-context request)]
              ;; If we're not inside a serlvet environment
              ;; (for example when using mock requests), then
              ;; .getContextPath might not exist
              (try (.getContextPath context)
                (catch IllegalArgumentException _ 
                context))))
            (parser/render-file (str template-path template))
           response)
          "text/html; charset=utf-8")))

(defn render [template & [params]]
(RenderableTemplate. template params))

The key to the hipstr.layout namespace is that it remains high level and generic. You should avoid writing functions with domain knowledge in this namespace, and instead focus on generating response bodies. If you put an explicit URL or filename in this namespace, you're probably doing it wrong.

Middleware, for the unfamiliar, is a function that can work with an incoming request prior to the request being handled by the main application (that is our proverbial business logic). Its function is similar to how a car moves through an assembly line; each employee working the line is responsible for interacting with the car in some specific way. Much like how at the end of the assembly line the car is in its final state and ready for consumption, so is the request in its final state and ready for processing by the main application. The following code is for the hipstr.middleware namespace:

(ns hipstr.middleware
  (:require [taoensso.timbre :as timbre]
            [selmer.parser :as parser]
            [environ.core :refer [env]]
            [selmer.middleware :refer [wrap-error-page]]
            [prone.middleware :refer [wrap-exceptions]]
            [noir-exception.core :refer [wrap-internal-error]]))

(defn log-request [handler]
  (fn [req]
    (timbre/debug req)
    (handler req)))

(def development-middleware
  [wrap-error-page
   wrap-exceptions])

(def production-middleware
  [#(wrap-internal-error % :log (fn [e] (timbre/error e)))])

(defn load-middleware []
  (concat (when (env :dev) development-middleware)
          production-middleware))

The hipstr.middleware namespace has two primary responsibilities. The first is that it ties together all the different middleware we want across any of our runtime environments. The second is that it gives us a place to add additional middleware, if desired. Of course, there's nothing prohibiting us from writing our middleware in a new namespace, but for the sake of simplicity and for this book, we'll simply create additional middleware in the hipstr.middleware namespace.

One of the directories that Luminus generated was a route folder. Routes are what tie a request to a specific handler (or, in layman's terms, a chunk of code to be executed based on the URL the request is sent to). Luminus generates 2 routes for us:

Take a look at the following lines of code:

(ns hipstr.routes.home
  (:require [compojure.core :refer :all]
            [hipstr.layout :as layout]
            [hipstr.util :as util]))

(defn home-page []
  (layout/render
    "home.html" {:content (util/md->html "/md/docs.md")}))

(defn about-page []
  (layout/render "about.html"))

(defroutes home-routes
  (GET "/" [] (home-page))
  (GET "/about" [] (about-page)))

We will create a couple of our own routing namespaces over the course of this book. The routes we'll create in those namespaces will follow the same pattern demonstrated in the preceding hipster.routes.home namespace. We'll talk a bit more about routes in Chapter 4, URL Routing and Template Rendering.

Everything we've seen in this chapter is brought together into a single, harmonious, running application in the hipstr.handler namespace, explained in the following lines of code. Opening the file for a cursory scan reveals our cron job to clean up expired sessions, the home-routes from the hipstr.routes.home namespace, the configuration of our Timbre logging, and so on.

(ns hipstr.handler
  (:require [compojure.core :refer [defroutes]]
    ; ... snipped for brevity …
    [cronj.core :as cronj]))

(defroutes base-routes
  (route/resources "/")
  (route/not-found "Not Found"))

(defn init
  "init will be called once when
    app is deployed as a servlet on
    an app server such as Tomcat
    put any initialization code here"
  []
  ;… snipped for brevity …)

(defn destroy
  "destroy will be called when your application
   shuts down, put any clean up code here"
  []
  ; ... snipped for brevity ...)

;; timeout sessions after 30 minutes
(def session-defaults
  {:timeout (* 60 30)
   :timeout-response (redirect "/")})

(defn- mk-defaults
       "set to true to enable XSS protection"
       [xss-protection?]
       ;... snipped for brevity ...
)

(def app (app-handler
            ;; add your application routes here
            [home-routes base-routes]
            ;; add custom middleware here
            :middleware (load-middleware)
            :ring-defaults (mk-defaults false)
            ;; add access rules here
            :access-rules []
            ;; serialize/deserialize the following data formats
            ;; available formats:
            ;; :json :json-kw :yaml :yaml-kw :edn :yaml-in-html
            :formats [:json-kw :edn :transit-json]))

We'll get into detail about what all is happening, and when, in Chapter 2, Ring and the Ring Server.

The last Luminus generated namespace, hipstr.repl, is one that often confuses beginners because it's strikingly similar to hipster.handler. The hipstr.repl namespace has a start-server and stop-server function, much like hipster.handler. However, hipstr.repl allows us to start and stop our development server from the Clojure REPL. This might seem like a weird thing to do, but by running our server from the REPL we can modify our running system and the changes will be "automagically" reloaded in our server. No need for the time consuming and frustrating "compile-deploy-restart-grab-a-coffee-and-twiddle-your-thumbs cycle!"

(ns hipstr.repl
  (:use hipstr.handler
        ring.server.standalone
        [ring.middleware file-info file]))

(defonce server (atom nil))

(defn get-handler []
  ;; #'app expands to (var app) so that when we reload our code,
  ;; the server is forced to re-resolve the symbol in the var
  ;; rather than having its own copy. When the root binding
  ;; changes, the server picks it up without having to restart.
  ; ... snipped for brevity ...
)

(defn start-server
  "used for starting the server in development mode from REPL"
  [& [port]]
  ; ... snipped for brevity ...
)

(defn stop-server []
  ;… snipped for brevity …
)

Incorporating the REPL into your development workflow is a wonderful thing to do. You can load your namespace into the REPL while you work on it and test the code while you're developing right then and there. In fact, some IDEs such as LightTable take this a step further, and will "live-evaluate" your code as you type. The ability of running the dev server from the REPL completes the circle.