Luminus A Clojure web framework
WhatisLuminus?
Luminus是基于一套轻量级类的微架构。它的目的是提供一个强大的，可扩展的，易于使用的平台。用Luminus你可以将重点放在开发你的应用程序上而不用在意其他的任何干扰。
Whydevelop web applications with Clojure?
Rapiddevelopment --快速发展
可以用REPL立即开始hacking和嵌入式开发服务器
Productivity--生产力
JVM结合Clojure意味着不用在生产力和性能之间做出选择
Interactivity --互动性
可以立即检测到你所作出的更改，而无需重新编译或重新启动
Flexibility--灵活性
选择适合你的组件，在项目的结构上有完全的控制权
Matureecosystem--成熟的生态系统
获得了许多现有的Clojure和Java库的支持
Powerfultools--功能强大的工具
用Leiningen来构建和部署应用程序很容易，可包括Heroku在内的享受一系列的部署选项
Yourfirstapplication
1.Guestbook Application
本教程将引导您使用Luminus动态通过建立一个简单的留言板程序。该留言薄允许用户留言、查看别人留下的消息。应用程序将显示HTML模板，基本的数据库访问，以及项目的结构。
如果你没有一个已经喜欢了的Clojure编辑器，那么建议你使用LightTable按照本教程操作。
2.Installing Leiningen
要使用Luminus语言，你需要进行Leiningen安装。安装Leiningen是一个简单的过程，包括以下步骤。
1.下载脚本
2.把它设置成可执行的（如：chmod +x lein）
3.把它放在你的$路径。（如：~ /bin）
4.运行lein self-install并等待安装完成。
wget https://raw.github.com/technomancy/leiningen/stable/bin/lein chmod +x lein mv lein ~/bin lein self-install
3.Creating a new application
一旦你Leiningen安装好后，你可以在终端运行以下命令来初始化你的应用：
leinnew luminus guestbook +h2
cdguestbook
以上将创建以H2嵌入式数据库为引擎支持一个新的模板工程。
现在我们可以按照如下步骤运行项目：
>leinring server
guestbookstarted successfully...
2013-03-01 19:05:30.389:INFO:oejs.Server:jetty-7.6.1.v20120215
Startedserver on port 3000
2013-03-01 19:05:30.459:INFO:oejs.AbstractConnector:StartedSelectChannelConnect
19:05:30.459:INFO:oejs.AbstractConnector:[email protected]:3000
将会弹出一个新的浏览器窗口，你应该可以看到你的应用程序在运行。请注意，如果你不想弹出一个新的浏览器，你可以运行：
leinring server-headless
你也可以通过如下自定义端口：
leinring server-headless 8000
4.Anatomy of a Luminus application
新创建的应用程序具有以下结构
Procfile
README.md
project.clj
src
└ log4j.xml
guestbook
└ handler.clj
layout.clj
middleware.clj
util.clj
repl.clj
db
└ core.clj
schema.clj
routes
└ home.clj
test
└ guestbook
└ test
└ handler.clj
resources
└ templates
└ about.html
base.html
home.html
└ public
└ css
└ screen.css
fonts
└ glyphicons-halflings-regular.eot
glyphicons-halflings-regular.svg
glyphicons-halflings-regular.ttf
glyphicons-halflings-regular.woff
img
js
md
└ docs.md
让我们来看看在应用程序的根文件夹的文件的作用：
procfile -用于促进Heroku部署。
readme.md -应用程序文档通常存放处。
project.clj -用于由Leiningen管理项目的配置和依赖。
5.The Source Directory
所有的代码均在SRC文件夹下。由于我们的应用程序称为留言簿，这是项目的根命名空间。让我们来看看已经为我们创造的所有的命名空间。
guestbook
handler.clj -定义应用程序的基本路线，这是程序的入口点
layout.clj -一个布局帮助的命名空间，我们定义的任何网页都需要将有他们的路径添加到这里
middleware.clj -一个命名空间包含程序自定义中间件
util.clj -用于一般的辅助功能，它是预先提供的MD - HTML助手
repl.clj -提供从REPL中来启动和停止应用的功能
log4j.xml记录配置
guestbook.db
db命名空间是用来定义程序的模型和处理数据持久层。
core.clj -用于存储函数用与与数据库交互
schema.clj-用于定义连接参数和数据库表
guestbook.routes
routes命名空间是在我们主页面的routes和controllers所在的位置。当你添加更多的routes，如authentication（认证），或specificworkflows（特定的工作流程），你应该在这里为他们创建的命名空间。
home.clj --一个定义home和程序相关页面的命名空间
6.The Test Directory
这里用于安置我们程序的测试，已经为我们定义两个测试的样品。
7.The ResourcesDirectory
这是用于安置我们程序所有的静态资源。已经有文件夹CSS, JavaScript,images,和 markdown被定义。
HTML templates
模板目录是用于表示应用程序页面的Selmer模板。
about.html -关于页
base.html-为网站的基本布局
html -首页
8.Adding Dependencies
正如上面提到的，所有依赖关系管理通过更新project.clj文件。在根文件夹可找到我们已经创建了的应用程序的项目文件，它应该如下所示：
(defproject
guestbook "0.1.0-SNAPSHOT"
:url "http://example.com/FIXME"
:description "FIXME: write description"
:dependencies
[[com.h2database/h2 "1.4.178"]
[ring-server "0.3.1"]
[environ "0.5.0"]
[com.taoensso/timbre "3.2.1"]
[markdown-clj "0.9.44"]
[korma "0.3.1"]
[com.taoensso/tower "2.0.2"]
[selmer "0.6.6"]
[org.clojure/clojure "1.6.0"]
[log4j
"1.2.17"
:exclusions
[javax.mail/mail
javax.jms/jms
com.sun.jdmk/jmxtools
com.sun.jmx/jmxri]]
[compojure "1.1.8"]
[lib-noir "0.8.3"]]
:plugins
[[lein-ring "0.8.7"] [lein-environ "0.5.0"]]
:ring
{:handler guestbook.handler/app,
:init guestbook.handler/init,
:destroy guestbook.handler/destroy}
:profiles
{:uberjar {:aot :all}
:production
{:ring
{:open-browser? false, :stacktraces? false, :auto-reload? false}},
:dev
{:dependencies [[ring-mock "0.1.5"] [ring/ring-devel "1.2.2"]],
:env {:dev true}}}
:min-lein-version "2.0.0")
正如你所看到的project.clj仅仅是一个包含key/value描述应用不同的方面对Clojure列表。如果您需要添加任何自定义依赖zhixu简单地把它们添加到：dependencies vector(依赖向量)。
9.Accessingthe Database
首先，我们将为应用程序创建一个模型，这样做，我们将开放位于src/guestbook/db 文件夹下得schema.clj文件。在这里，我们已经为我们的数据库连接做出了定义。定义一个简单的map，包含JDBC驱动程序JDBCdriver，协议protocol，用户user，密码password，和使用H2数据库的数据库文件。
(def db-spec {:classname "org.h2.Driver"
:subprotocol "h2"
:subname (str (io/resource-path) db-store)
:user "sa"
:password ""
:naming {:keys clojure.string/upper-case
:fields clojure.string/upper-case}})
接下来，我们有一个函数名为create-users-table内有user表定义（注）。我们会用一个create-guestbook-table 函数代替这个函数：
(defn create-guestbook-table []
(sql/db-do-commands
db-spec
(sql/create-table-ddl
:guestbook
[:id "INTEGER PRIMARY KEY AUTO_INCREMENT"]
[:timestamp :timestamp]
[:name "varchar(30)"]
[:message "varchar(200)"]))
(sql/db-do-prepared db-spec
"CREATE INDEX timestamp_index ON guestbook (timestamp)"))
留言表将存储所有的域描述信息，例如注释者的姓名，邮件的内容和时间戳。
我们也将更新create-tables函数来调用它：
(defn create-tables "creates the database tables used by the application" [] (create-guestbook-table))
用创建的表，我们可以在我们的留言里加入读和写的功能。让我们打开src/guestbook/db/ core.clj文件并添加他们。我们看到，已经有一些处理用户表的代码。我们会用下面的代码替代他们：
(ns guestbook.db.core
(:use korma.core
[korma.db :only (defdb)])
(:require [guestbook.db.schema :as schema]))
(defdb db schema/db-spec)
(defentity guestbook)
(defn save-message
[name message]
(insert guestbook
(values {:name name
:message message
:timestamp (new java.util.Date)})))
(defn get-messages []
(select guestbook))
上面我们创建一个实体来代表我们在架构命名空间里创建留言表。然后我们添加函数save-message 和get-messages与它互动。
10.Running Code on Startup
句柄handler命名空间包含一个函数init。当应用程序启动时，这个函数将被调用一次。让我们添加代码以检查数据库是否已经初始化，如果需要则进行初始化。
我们首先需要参考架构命名空间为了使用initialized? 以及 create-tables的功能。
(ns guestbook.handler
(:use ...)
(:require ...
[guestbook.db.schema :as schema]))
接下来，我们更新init函数
(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"
[]
(timbre/set-config!
[:appenders :rotor]
{:min-level :info
:enabled? true
:async? false ; should be always false for rotor
:max-message-per-msecs nil
:fn rotor/appender-fn})
(timbre/set-config!
[:shared-appender-config :rotor]
{:path "guestbook.log" :max-size (* 512 1024) :backlog 10})
(if (env :selmer-dev) (parser/cache-off!))
;;initialize the database if needed
(if-not (schema/initialized?) (schema/create-tables))
(timbre/info "guestbook started successfully"))
由于我们改变了我们程序的init函数，所以关掉服务（ctrl+c）并重新启动服务（lein ring server)
11.Creating Pages and HandlingForm Input
我们的routes均定义在guestbook.routes.home 命名空间里. 打开它，从数据库中读取信息的跳转需要增加一些逻辑.首先，需要增加referenc给我们的 db 命名空间:
(ns guestbook.routes.home
(:use ...)
(:require ...
[guestbook.db.core :as db]))
接下来，改变 home-page 控制器:
(defn home-page [& [name message error]]
(layout/render "home.html"
{:error error
:name name
:message message
:messages (db/get-messages)}))
目前，我们可以为模板增加一些额外的参数,参数是从数据库中的信息列表.
我们希望用户可以发布新messages,因此需要在handler增加一个controller theform posts:
(defn save-message [name message]
(cond
(empty? name)
(home-page name message "Somebody forgot to leave a name")
(empty? message)
(home-page name message "Don't you have something to say?")
:else
(do
(db/save-message name message)
(home-page))))
最后，我们对controller添加routes 到 home-routes 定义中:
(defroutes home-routes (GET "/" [] (home-page)) (POST "/" [name message] (save-message name message)) (GET "/about" [] (about-page)))
现在，我们的控制器已经setup，打开 home.html 模板.
{% extends "templates/base.html" %}
{% block content %}
<div class="jumbotron">
<h1>Welcome to guestbook</h1>
<p>Time to start building your site!</p>
<p><a class="btn btn-primary btn-lg" href="http://luminusweb.net">Learn more »</a></p>
</div>
<div class="row-fluid">
<div class="span8">
{{content|safe}}
</div>
</div>
{% endblock %}
更新内容，使其能够循环展现消息列表:
{% extends "templates/base.html" %}
{% block content %}
<div class="jumbotron">
<h1>Welcome to guestbook</h1>
</div>
<div class="row-fluid">
<div class="span8">
<ul>
{% for item in messages %}
<li>
<time>{{item.timestamp|date:"yyyy-MM-dd HH:mm"}}</time>
<p>{{item.message}}</p>
<p> - {{item.name}}</p>
</li>
{% endfor %}
</ul>
</div>
</div>
{% endblock %}
就如你看到的，我们使用iterator去跑messages.每个message 都是一个 map ，包含message, name, 和 timestamp 关键字, 我们可以通过 name 获得它. 另外，注意 useof the date filter to format the timestamps into a human readableform.
接下来，为了展现控制器可能出现的错误需要增加 error 模块:
{% if error %}
<p class="error">{{error}}</p>
{% endif %}
简单测试一下error模块是否起作用。最后，创建一个允许用户提交message的form:
<form action="/" method="POST">
<p>
Name:
<input type="text" name="name" value={{name}}>
</p>
<p>
Message:
<textarea rows="4" cols="50" name="message">
{{message}}
</textarea>
</p>
<input type="submit" value="comment">
</form>
home.html template 应该是这样的:
{% extends "templates/base.html" %}
{% block content %}
<div class="jumbotron">
<h1>Welcome to guestbook</h1>
</div>
<div class="row-fluid">
<div class="span8">
<ul>
{% for item in messages %}
<li>
<time>{{item.timestamp|date:"yyyy-MM-dd HH:mm"}}</time>
<p>{{item.message}}</p>
<p> - {{item.name}}</p>
</li>
{% endfor %}
</ul>
{% if error %}
<p class="error">{{error}}</p>
{% endif %}
</div>
<div class="span8">
<form action="/" method="POST">
<p>
Name:
<input type="text" name="name" value="{{name}}" />
</p>
<p>
Message:
<textarea rows="4" cols="50" name="message" />{{message}}</textarea>
</p>
<input type="submit" value="comment" />
</form>
</div>
</div>
{% endblock %}
最后，更新 screen.css 文件，让页面更美观:
body {
height: 100%;
padding-top: 70px;
font: 14px 'Helvetica Neue', Helvetica, Arial, sans-serif;
line-height: 1.4em;
background: #eaeaea;
color: #4d4d4d;
width: 550px;
margin: 0 auto;
-webkit-font-smoothing: antialiased;
-moz-font-smoothing: antialiased;
-ms-font-smoothing: antialiased;
-o-font-smoothing: antialiased;
font-smoothing: antialiased;
}
input[type=submit] {
margin: 0;
padding: 0;
border: 0;
line-height: 1.4em;
background: none;
vertical-align: baseline;
}
input[type=submit], textarea {
font-size: 24px;
font-family: inherit;
border: 0;
padding: 6px;
border: 1px solid #999;
box-shadow: inset 0 -1px 5px 0 rgba(0, 0, 0, 0.2);
-moz-box-sizing: border-box;
-ms-box-sizing: border-box;
-o-box-sizing: border-box;
box-sizing: border-box;
}
input[type=submit]:hover {
background: rgba(0, 0, 0, 0.15);
box-shadow: 0 -1px 0 0 rgba(0, 0, 0, 0.3);
}
textarea {
position: relative;
line-height: 1em;
width: 100%;
}
.error {
font-weight: bold;
color: red;
}
.jumbotron {
position: relative;
background: white;
z-index: 2;
border-top: 1px dotted #adadad;
}
h1 {
width: 100%;
font-size: 70px;
font-weight: bold;
text-align: center;
}
ul {
margin: 0;
padding: 0;
list-style: none;
}
li {
position: relative;
font-size: 16px;
padding: 5px;
border-bottom: 1px dotted #ccc;
box-shadow: 0 2px 6px 0 rgba(0, 0, 0, 0.2),
0 25px 50px 0 rgba(0, 0, 0, 0.15);
}
li:last-child {
border-bottom: none;
}
li time {
font-size: 12px;
padding-bottom: 20px;
}
form:before, .error:before {
content: '';
position: absolute;
top: 0;
right: 0;
left: 0;
height: 15px;
border-bottom: 1px solid #6c615c;
background: #8d7d77;
}
form, .error {
width: 520px;
padding: 30px;
margin-bottom: 50px;
background: #fff;
border: 1px solid #ccc;
position: relative;
box-shadow: 0 2px 6px 0 rgba(0, 0, 0, 0.2),
0 25px 50px 0 rgba(0, 0, 0, 0.15);
}
form input {
width: 50%;
clear: both;
}
重新加载页面，会有新发现. 试着增加 comment 看看是否起作用.
12.Packaging the application
打包：
lein ring uberjar
直接运行包：
java -jartarget/guestbook-0.1.0-SNAPSHOT-standalone.jar
如果想部署的话，比如Apache Tomcat,运行：
lein ring uberwar
可以部署在你想要的地方。