Luminus file structure

The luminus template generates web applications using a fairly typical directory structure. However, it also produces a number of Clojure namespaces that can cause a bit of confusion if you're brand new to Clojure web development. You can either open the project using your favorite Clojure editor, or do the following from the terminal:

# find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'

Note The preceding command line is a nasty thing to eyeball and type. You can copy and paste the preceding command from http://bit.ly/1F3TmdJ.

In either case, you should see output similar to the following:

Luminus generates three directories at the root of the application directory: resources , src , and test .

The resources directory contains the files that will compose the front end of our applications. The public folder contains resources publicly available to the client, such as our JavaScript, CSS, and images. By contrast, the templates directory contains our Selmer templates used for the heavy rendering of HTML parts. All of these files will be made available on our class path; however, only those in the public folder will be actually available to the client.

The src directory contains all of the necessary namespaces for running our application, and the test directory contains all the necessary namespaces for testing our src .

In addition to the directories, however, Luminus also generated some files in the src directory. These files are the bare minimum requirement to successfully run our application, and each one handles specific functionality. Let's take a brief look at the base functionality contained in each file.

util.clj 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)))

session_manager.clj 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 {}}]))

layout.clj 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.clj 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.

routes/home.clj 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: A / route, which renders the result of calling the home-page function, which ultimately renders the home page you see at startup

A /about route, which renders the result of the about-page function, responsible for rendering the about.html page 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.

handler.clj 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.