Ah, getting started! This chapter introduces you to the foundations of Clojure web development using Luminus, a popular web application template for Leiningen. In this chapter, you will:
- Generate a new web application using the Luminus Leiningen template
- Get an introduction to the popular libraries, which Luminus uses to handle the various aspects of a web application, and what those libraries do
- Get an overview of the directory structure generated by Luminus
- Learn how to fire up the web application on your development machine
In this chapter, we'll create a new web application called hipstr, an application that will help us track our vinyl collection and endow us with obscure credibility. We'll build this application with each subsequent chapter by creating our own route handlers, interacting with a database, authenticating users, validating form input, and reading/writing cookies. By the end of this book, we'll know the Clojure web basics well enough that we'll be wearing plaid shirts and sipping bourbon aged in casks from a place nobody's ever heard of.
Our project will rely heavily on Leiningen, a build and task tool for Clojure. Leiningen allows us to easily maintain our application's dependencies, assists us in common tasks such as database migrations, running tests, producing binaries (jars and wars), and a plethora of other things. Leiningen is akin to Java's build tool Maven (http://maven.apache.org), and Ruby's Rake (http://github.com/jimweirich/rake). As Leiningen's web page (http://leiningen.org) concisely puts it: for automating Clojure projects without setting your hair on fire.
If you haven't already installed Leiningen 2.x, head over to http://leiningen.org/#install and follow the four simple instructions. It will take just 60 seconds, and the world of Clojure will become your oyster.
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.
Tip
At the time of this writing, the Luminus template was at version 1.16.7. To ensure the code examples in this book work, you can force Leiningen to use a specific version of Luminus by modifying Leiningen's profiles.clj file (typically found in your home directory, in a folder called .lein) to include the specific version of Luminus. For example:
:user {:plugins [[luminus/lein-template "1.16.7"]]}This modification will ensure that version 1.16.7 of the Luminus template is used when generating a Luminus-based application.
Just try the following command:
# lein new luminus hipstr >> Generating a lovely new luminus project named hipstr…
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.
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/).