Source

Clj-StringTemplate / README

Full commit
-*- markdown -*-

# Clj-StringTemplate

Clj-StringTemplate is a simple wrapper around the StringTemplate
library. The supported operations are:

* Load view template from classpath
* Load view template from directory
* Populate view template with attribute/values
* Render view template as java.lang.String


## Usage

FIXME: Maven/Leiningen dependency details are here: FIXME

Examples for usage can be found in the tutorial below:


## Building/Installation

You will need Maven 2 to build from sources. Execute the following:

    $ mvn clean package  # packages up a JAR in "target" dir
    $ mvn install        # to install to your local Maven repo
    $ mvn clojure:gendoc # generate Clojure API documentation


## License

Copyright (C) 2010 Shantanu Kumar (kumar.shantanu at gmail dot com)

Distributed under the Apache 2 License.


# Tutorial

Clj-StringTemplate can be used by including the following in your
namespace:

    (ns example.app
      (:use org.bituf.clj-stringtemplate))


## Load view template from classpath

    (get-view-from-classpath "hello")

The snippet above will look for the file called <i>hello.st</i> at the
top level in classpath, and will return the view template.

    (get-view-from-classpath "foo/hello")

The above snippet will look for the file called <i>hello.st</i> under
the package <i>foo</i> at the top level in classpath, and will return
the view template.

    (get-view-from-classpath "foo/bar/hello")

The above snippet will do the same as the earlier one, but under the
package <i>foo.bar</i>.


## Load view template from directory

    (get-view-from-dir "hello" "/home/joe/templates")

The above snippet will look for the file
<i>/home/joe/templates/hello.st</i> and will return the view template.

    (get-view-from-dir "foo/hello" "/home/joe/templates")

The above snippet will look for the file
<i>/home/joe/templates/foo/hello.st</i> and will return the view
template.

    (get-view-from-dir "foo/bar/hello" "/home/joe/templates")

The above snippet will look for the file
<i>/home/joe/templates/foo/bar/hello.st</i> and will return the view
template.


## Populate view template with attribute/values

    (let [view (get-view-from-classpath "hello")]
      (fill-view! view "name" "Henry")
      ...)

The snippet above sets value for the attribute "name" in the view
template.

    (let [view (get-view-from-classpath "hello")]
      (fill-view! view "names" ["Henry" "Neal" "Rama"])
      ...)

The snippet above sets a multi-value (essentially a List) for the
attribute "names" in the view template.

    (let [view (get-view-from-classpath "hello")]
      (fill-view! view {"names" ["Henry" "Neal" "Rama"]
                        "title" "List of names"} )
      ...)

The snippet above sets the corresponding values for the
attributes "names" and "title" in the view template.


## Render view template as <i>java.lang.String</i>

    (let [view   (get-view-from-classpath "hello")
          filled (fill-view! view "name" "Henry")]
      (println (render-view filled)))


## Transform keyword-key/value map to string-key/value map

    (kv-to-sv {:a 10 :b 20 :c 30})

The snippet above will produce the output {"a" 10 "b" 20 "c" 30}. Such
transformations may be useful to convert typical Clojure maps to a
format suitable for StringTemplate view templates.