enlive-tutorial

An Introduction to Enlive Though Christophe Grand’s Enlive has been around for sometime now the Clojure community has been slow to embrace this useful library. I believe this is due simply to the lack of good introductory documentation based on real examples. Please let me know if you find this tutorial useful or helpful in any way. Feel free to suggest additions, corrections, and improvements (even better fork the repo and send me a patch). What You need to Know Not much. This tutorial assumes little about your exposure to Clojure. At the very least you’ll need to have the Java Virtual Machine (JVM) installed. I won’t go into great detail about Clojure’s features but I’ll try to explain any concepts which may impede your understanding of Enlive’s functionality. As the tutorials progress they will be more useful to you if you have some experience with a modern webframework that ships with a HTML templating library. If you do know Clojure the tutorials are fairly amenable to skimming. My only real assumption is that you have some experience at the command line. Enlive has many features and I can’t possibly cover them all here. Fortunately the Clojure community is vibrant and helpful. If you run into issues or have questions join the Enlive mailing list or jump on the #clojure channel on irc.freenode.net. HTML Templating There are two real camps in HTML templating. The first which almost everyone is familiar with is the PHP style template: <?php for($i = 0; $i < $len; $i++) { ?><p>Foo <?echo $i?></p><? } ?> This is of course enough to drive anyone insane and some templating solutions like the one in Django have made marginal improvements: {% for i in foo %} <p>Foo {{ i }}</p> {% endfor %} This is a bit easier on the eyes. But this isn’t very composable and you’re stuck with a limited subset of your programming language. By not composable I mean that building pages is largely a copy and paste affair even when templating solutions support inheritance. This has driven many programmers to discard templating DSLs and to generate markup directly in code. While this is fast and flexible as you now have the power of function composition, it also means that you’re putting quite a bit of distance between yourself and a designer comfortable writing HTML and CSS. There are a few existing solutions that have a novel approach to this problem such as Pure. Which brings us to Enlive. Enlive gives you the advantages of designer accessible templates (since they’re just HTML) without losing the power of function composition. As a result, your designer can create all the various widgets for your website using only HTML and CSS and you can compose your pages from any combination of their designs. Why Enlive? Enlive presents a different approach from the more popular templating solutions: Code and markup are completely separate. You get to use CSS like syntax to manipulate HTML. Template inheritance isn’t some fancy trick, it’s just function composition. You have access to the full power of Clojure to manipulate your templates (yes, macros!). When working with the standard templating solutions you generally need to answer one of two questions, either “What type of text am I going to generate?” or “What type of HTML emitting functions should I write?” In contrast, with Enlive you usually break down the problem thus: Determine which selectors match the part of the HTML document that you care about. Determine which templates and snippets you need to write to compose your pages. What We’ll Cover There are six examples in total. The first one covers grabbing the headlines and points from Hackers News. The next one shows how to make the code less redundant. The third scrapes the New York Times front page since that presents more challenges than Hacker News. The fourth example shows how to use Ring and Enlive together. The fifth example shows how things like looping are achieved without writing any code into the markup. The sixth example shows that Enlive can do all the fancy template inheritance magic you might be used to if you’re coming from Django or some other popular modern webframework. Clone This Repo The usual: git clone git://github.com/swannodette/enlive-tutorial.git Install Leiningen In order to start playing around as fast possible you should use Leiningen. It’ll take only a couple minutes to get through the instructions here. Leiningen is the easy_install (Python) and gems (Ruby) of the Clojure world. Phil Hagelberg and Co. have done a considerable amount of excellent work to make dependency management simple. I truly envy the new Clojurians who do not know the dark times before lein repl and lein swank :) Once you have Leiningen installed, switch into this repository’s directory. From there run the following command: lein deps This will install all of the dependencies required for getting through the tutorial. This might take a minute and and will probably generate a lot of output. While this may seem disconcerting, this means you’ll have a fully functioning Clojure setup without needing to bother with installing Emacs, configuring VIM, or an mucking around with an IDE. Once the the dependencies are installed enter the following command at your terminal: lein repl This will launch a Clojure REPL (Read-Eval-Print-Loop) that has the classpath set properly. Be very thankful if you don’t know what the last sentence means. Managing the classpath is one of the few real annoyances when programming Clojure and it’s largely Java’s fault. Your First Scrape with Enlive – Hacker News Enlive is fantastic for scraping the content of webpages. It allows you to scrape content by using a syntax very similar to CSS selectors. In the REPL type the following lines (note that user=> is the REPL prompt, not something you type in): user=> (load "tutorial/scrape1") nil user=> (in-ns 'tutorial.scrape1) nil tutorial.scrape1=> *base-url* "https://news.ycombinator.com/" The first line loads the file. Note tha