diff --git a/README.md b/README.md index a79a2d8..76b38e7 100644 --- a/README.md +++ b/README.md @@ -3,247 +3,10 @@ [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. +**This is the Java 6 branch.** It is identical in every way to the master branch, except for the use of a version of +Jtwig that has been very slightly modified to be Java 6 compatible. -## Usage - -**WARNING: This library is still in early development. May not be ready for production use!** - -### Leiningen - -!["clj-jtwig version"](https://clojars.org/clj-jtwig/latest-version.svg) - -#### 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 version maintained in -[this branch](https://github.com/gered/clj-jtwig/tree/java6). It 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.* - -!["clj-jtwig version"](https://clojars.org/clj-jtwig-java6/latest-version.svg) - -### 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}} -``` - -If a variable's name has any special characters (such as a `-` character), you can access it using 'subscript' syntax -instead. - -```jinja -Customer name: {{customer['full-name'}} -``` - -If a "root" variable has special characters in it's name, you can also access it using the same syntax, but you will -need to access it off of the `model` variable which all variables set in the template are bound to. - -```jinja -Order number: {{model['customer-order'].orderNumber}} -``` - -Otherwise, you normally don't need to include `model`, it is implicit. - - -### 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 routes: - -```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' - (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 | `abs(number)`
Returns the absolute value of a number. -| batch | `batch(items, batch_size, filler_item)`
"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. -| blank_if_null | `blank_if_null(value)`
If the value given is null, returns a blank string instead of "null". -| butlast | `butlast(collection)`
Returns all items from a list except for the last one. -| capitalize | `capitalize(value)`
Capitalizes a value. The first character will be uppercase, all others lowercase. -| concat | `concat(values, ...)`
Concatenates any number of values together as strings. -| convert_encoding | `convert_encoding(string, output_charset, input_charset)`
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 | `date_format(date, format, timezone)`
Formats a date to a given format. The format specifier is the same as supported by `SimpleDateFormat`. -| date_modify | `date_modify(date, modifier)`
Modifies a date with a given modifier string. Can be 'seconds', 'minutes', 'hours', 'days', 'months' or 'years'. -| default | `default(value, default_value)`
Returns the passed default value if the value is undefined or empty, otherwise the value of the variable. -| dump | `dump(value)`
Uses `clojure.pprint/pprint` to dump the entire value of a variable to a string and returns that string. -| escape | `escape(value, strategy)`
Escapes a string for safe insertion into the final output. The second parameter specifies the escape strategy: 'html' (default), 'js' or 'xml'. -| first | `first(collection)`
Returns the first "element" of a sequence, or a string. -| format | `format(format_string, values, ...)`
Formats a given string by replacing the placeholders (placeholders follow the `String.format` notation). -| join | `join(sequence, separator)`
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 | `json_encode(value)`
Returns the JSON representation of the given value. -| keys | `keys(map)`
Returns the keys of a map. It is useful when you want to iterate over the keys of a map. -| last | `last(collection)`
Returns the last "element" of a sequence, or a string. -| length | `length(collection)`
Returns the number of items of a sequence or mapping, or the length of a string. -| lower | `lower(string)`
Converts a value to lowercase. -| max | `max(values, ...)`
Returns the biggest value of a sequence or a set of values. -| merge | `merge(first_collection, second_collection)`
Merges a list with another list. -| min | `min(values, ...)`
Returns the lowest value of a sequence or a set of values. -| nl2br | `nl2br(string)`
Inserts HTML line breaks before all newlines in a string -| nth | `nth(sequence, index, value_if_not_found)`
Returns a value from a list corresponding with the index specified. -| number_format | `number_format(number, num_decimals, decimal_point_char, thousand_sep_char)`
Formats numbers. You can control the number of decimal places, decimal point, and thousands separator using the arguments. -| random | `random(collection)`
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 | `range(low, high, step)`
Returns a list containing an arithmetic progression of integers. An optional third argument specifies the 'step' which by default is 1. -| replace | `replace(string, placeholder_and_replacements_map)`
Formats a given string by replacing the placeholders (placeholders are free-form). -| rest | `rest(collection)`
Returns all the items from a list except for the first one. -| reverse | `reverse(sequence)`
Reverses a sequence, or a string. -| round | `round(number, rounding_method)`
Rounds a number to a given precision. -| second | `second(collection)`
Returns the second item of a sequence. -| slice | `slice(sequence, start, length)`
Extracts a slice of a sequence, or a string where the 2 last arguments specify the start and end indices respectively. -| sort | `sort(sequence)`
Sorts a list in ascending order. -| sort_descending | `sort_descending(sequence)`
Sorts a list in descending order. -| sort_by | `sort_by(sequence_of_maps, sort_key)`
Sorts a list of maps in ascending order. The second argument specifies the key who's value is to be used for sorting comparisons. -| sort_descending_by | `sort_descending_by(sequence_of_maps, sort_key)`
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 | `split(string, delimiter)`
Splits a string by the given delimiter and returns a list of strings. -| striptags | `striptags(string)`
Strips HTML/XML tags and replaces adjacent whitespace with one space. -| title | `title(string)`
Returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase. -| trim | `trim(string)`
Strips whitespace (or other characters) from the beginning and end of a string. -| upper | `upper(string)`
Converts a value to uppercase. -| url_encode | `url_encode(string_or_map)`
Percent encodes a given string as URL segment or a map of key/values as a query string. - -## Caching - -Jtwig provides support for compiling templates so that subsequent renders can be performed faster. clj-jtwig builds on -this support by providing a very simple caching mechanism when rendering templates from files. Template files are -compiled the first time they are rendered and then the compiled result cached. From then on, each time that same -template file is rendered, the source file on disk is checked to see if it has been modified since it was last cached, -and if so we re-load, compile and cache it before rendering it again. - -Caching is turned on by default, but can be turned off if necessary via -`clj-jtwig.core/toggle-compiled-template-caching!`. - -An important thing to be aware of when using templates that extend others, or include others is that only the -template who's filename is passed to one of the render functions is checked to see if it has been updated. If your -templates include other template files but those included files are never directly rendered themselves, then they will -not get recompiled and cached unless the parent template is updated as well. This can be a problem during development -of an application, so you may want to turn caching off during development. - -## Debugging Tips - -One other helpful use of `model` is for debugging when working with a lot of data being passed to a template. You can -dump the entire set of variables passed to the template using the `dump` function. - -```jinja -{{model|dump}} -``` +[Please see the master branch for more information about clj-jtwig.](https://github.com/gered/clj-jtwig/tree/java6) ## License