gered/clj-jtwig
Archived
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge branch 'master' into java6

Browse source
This commit is contained in:
Gered 2014-03-04 19:00:23 -05:00
parent 9400b70bdc f431c88696
commit d9c079451d
1 changed files with 199 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

201
README.md
View file

@ -1,10 +1,207 @@
# clj-jtwig # clj-jtwig
Wrapper allowing easy use of [JTwig](http://jtwig.org) in Clojure applications. [Twig](http://twig.sensiolabs.org/) templates in Clojure, provided by [Jtwig](http://jtwig.org). clj-jtwig is a simple
Clojure wrapper around Jtwig to make using it in Clojure applications simple.
For more information on Twig templates, you can refer to the [Twig documentation](http://twig.sensiolabs.org/documentation)
and the [Jtwig documentation](http://jtwig.org/documentation). Please note that Jtwig is not yet a full implementation
of Twig, so some things you see on the Twig documentation might not yet be available in Jtwig, and as a result, not
available in clj-jtwig.
## Usage ## Usage
TODO ### Leiningen
```clojure
[clj-jtwig "0.2.1"]
```
#### Java 6
Jtwig targets Java 7 so you can't use it on Java 6. If you are deploying applications into a Java 6 environment and
want to still use clj-jtwig, you can use the java6 version (maintained in
[this branch](https://github.com/gered/clj-jtwig/tree/java6)). This makes use of an otherwise vanilla Jtwig library
that has been very slightly modified so that it compiles for Java 6. No other changes have been made and this fork is
only being maintained by me *purely* for use with clj-jtwig. *It is not supported by the Jtwig developers.*
```clojure
[clj-jtwig-java6 "0.2.1"]
```
### Rendering Templates
Getting up and running with clj-jtwig is easy:
```clojure
(ns yourapp.core
(:require [clj-jtwig.core :refer [render]]))
(defn say-hello [name]
(render "Hello {{name}}!" {:name name})
(say-hello "Gered") ; returns "Hello Gered!"
```
You can also render from files by providing a full path and filename to `clj-jtwig.core/render-file`. Most of the time
you'll want to render from a resource file that is bundled along with your app, in which case you can provide a path
and filename relative to the classpath to `clj-jtwig.core/render-resource`.
```clojure
(render-file "/Users/gered/say-hello.twig" {:name "Gered"})
; 'say-hello.twig' in this case would be located at '[your-app]/resources/say-hello.twig'
(render-resource "say-hello.twig" {:name "Gered"})
```
From these examples we can see that the second argument to `render`, `render-file` and `render-resource` is a map of
variables that can be referred to in the template (basically it is the template 'model'). You can nest data and refer
to it using 'dot' syntax like in Java.
```jinja
City of residence: {{address.city}}
```
### Web Apps
For web apps built on Compojure, you can do something like:
```clojure
(ns yourwebapp.views
(:require [clj-jtwig.core :refer [render-resource]]
[clj-jtwig.functions :refer [deftwigfn]]
[ring.util.response :refer [content-type response]]
[compojure.response :refer [Renderable]]))
(deftype JtwigRenderable [template-filename params]
Renderable
(render [this request]
(content-type
(response
(render-resource
template-filename
; add a var 'context' which contains the current servlet context path which you will want to prefix
; on to your css/js/img and other links that you render in your html
(assoc params :context (or (:context request) ""))))
"text/html; charset=utf-8")))
; params is an optional map that will get passed to clj-jtwig.core/render-resource. this is will need to contain
; any variables you want to use in 'template-filename'
(defn render [template-filename & [params]]
(JtwigRenderable. template params))
```
And then in your route:
```clojure
(ns yourwebapp.routes
(:use compojure.core)
(:require [yourwebapp.views :refer [render]]))
(defn home-page []
; in this case, 'home.html' would be located at '[yourwebapp]/resources/views/home.html'
(layout/render "views/home.html" {:name "Gered"}))
(defroutes yourwebapp-routes
(GET "/" [] (home-page)))
```
### Functions
Adding custom functions is also easy:
```clojure
(ns yourapp.core
(:require [clj-jtwig.core :refer [render]]
[clj-jtwig.functions :refer [deftwigfn]]))
(deftwigfn "sayHello" [name]
(str "Hello " name "!"))
```
Then your functions can be used in your templates:
```clojure
(render "{{ sayHello(name) }}" {:name "Gered"}) ; "Hello Gered!"
; or you can call it using the 'pipe' (filter) syntax
(render "{{ name|sayHello }}" {:name "Gered"}) ; "Hello Gered!"
; you can also nest functions and/or chain filters together
(render "{{ name|upper|sayHello }}" {:name "Gered"}) ; "Hello GERED!"
(render "{{ sayHello(upper(name)) }}" {:name "Gered"}) ; "Hello GERED!"
```
For convenience, you can also define one or more aliases for functions:
```clojure
(ns yourapp.core
(:require [clj-jtwig.core :refer [render]]
[clj-jtwig.functions :refer [defaliasedtwigfn]]))
(defaliasedtwigfn "sayHello" [name]
["sayHi"]
(str "Hello " name "!"))
; elsewhere in your app's code ...
(render "{{ sayHello(name) }}" {:name "Gered"}) ; "Hello Gered!"
(render "{{ sayHi(name) }}" {:name "Gered"}) ; "Hello Gered!"
```
The `deftwigfn` and `defaliasedtwigfn` are macros that call `clj-jtwig.functions/add-function!` under the hood. If you
prefer, that function can be used directly. Those macros are simply a convenience so you can write template functions
in a 'defn'-style syntax.
#### Standard Library Functions
A number of functions are provided out of the box by Jtwig. A few more are provided to fill in some gaps by clj-jtwig.
| Function | Description
|----------|------------
| [abs](http://jtwig.org/documentation/functions#item_7) | Returns the absolute value of a number.
| [batch](http://jtwig.org/documentation/functions#item_8) | "Batches" items by returning a list of lists with the given number of items. If you provide a second parameter, it is used to fill missing items.
| blankIfNull | If the value given is null, returns a blank string instead of "null".
| [capitalize](http://jtwig.org/documentation/functions#item_9) | Capitalizes a value. The first character will be uppercase, all others lowercase.
| concat | Concatenates any number of values together as strings.
| [convert_encoding](http://jtwig.org/documentation/functions#item_10) | Converts a string from one encoding to another. The first argument is the expected output charset and the second one is the input charset.
| [date_format](http://jtwig.org/documentation/functions#item_11) | Formats a date to a given format. The format specifier is the same as supported by `SimpleDateFormat`.
| [date_modify](http://jtwig.org/documentation/functions#item_13) | Modifies a date with a given modifier string. Can be 'seconds', 'minutes', 'hours', 'days', 'months' or 'years'.
| [default](http://jtwig.org/documentation/functions#item_14) | Returns the passed default value if the value is undefined or empty, otherwise the value of the variable.
| dump | Uses `clojure.pprint/pprint` to dump the entire value of a variable to a string and returns that string.
| [escape](http://jtwig.org/documentation/functions#item_15) | Escapes a string for safe insertion into the final output. The second parameter specifies the escape strategy: 'html' (default), 'js' or 'xml'.
| [first](http://jtwig.org/documentation/functions#item_16) | Returns the first "element" of a sequence, or a string.
| [format](http://jtwig.org/documentation/functions#item_17) | Formats a given string by replacing the placeholders (placeholders follow the `String.format` notation).
| [join](http://jtwig.org/documentation/functions#item_18) | Returns a string which is the concatenation of the items of a sequence. The second parameter specifies a string to place between joined elements (blank string by default).
| [json_encode](http://jtwig.org/documentation/functions#item_19) | Returns the JSON representation of the given value.
| [keys](http://jtwig.org/documentation/functions#item_20) | Returns the keys of a map. It is useful when you want to iterate over the keys of a map.
| [last](http://jtwig.org/documentation/functions#item_21) | Returns the last "element" of a sequence, or a string.
| [length](http://jtwig.org/documentation/functions#item_22) | Returns the number of items of a sequence or mapping, or the length of a string.
| [lower](http://jtwig.org/documentation/functions#item_23) | Converts a value to lowercase.
| max | Returns the biggest value of a sequence or a set of values.
| [merge](http://jtwig.org/documentation/functions#item_26) | Merges a list with another list.
| min | Returns the lowest value of a sequence or a set of values.
| [nl2br](http://jtwig.org/documentation/functions#item_24) | Inserts HTML line breaks before all newlines in a string
| nth | Returns a value from a list corresponding with the index specified.
| [number_format](http://jtwig.org/documentation/functions#item_25) | Formats numbers. You can control the number of decimal places, decimal point, and thousands separator using the arguments.
| random | Returns a random item from a list or set of values. If an single number argument is provided, returns a random number from 0 to the number specified.
| range | Returns a list containing an arithmetic progression of integers. An optional third argument specifies the 'step' which by default is 1.
| [replace](http://jtwig.org/documentation/functions#item_27) | Formats a given string by replacing the placeholders (placeholders are free-form).
| rest | Returns all the items from a list except for the first one.
| [reverse](http://jtwig.org/documentation/functions#item_28) | Reverses a sequence, or a string.
| [round](http://jtwig.org/documentation/functions#item_29) | Rounds a number to a given precision.
| second | Returns the second item of a sequence.
| slice | Extracts a slice of a sequence, or a string where the 2 last arguments specify the start and end indices respectively.
| sort | Sorts a list in ascending order.
| sortDescending | Sorts a list in descending order.
| sortBy | Sorts a list of maps in ascending order. The second argument specifies the key who's value is to be used for sorting comparisons.
| sortDescendingBy |Sorts a list of maps in descending order. The second argument specifies the key who's value is to be used for sorting comparisons.
| split | Splits a string by the given delimiter and returns a list of strings.
| striptags | Strips HTML/XML tags and replaces adjacent whitespace with one space.
| title | Returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase.
| trim | Strips whitespace (or other characters) from the beginning and end of a string.
| upper | Converts a value to uppercase.
| url_encode | Percent encodes a given string as URL segment or an array as query string.
## License ## License