SlimUser Guide
Overview
afSlim
is a library for generating HTML from concise, lightweight templates. afSlim
is based on Jade for javascript and Slim for Ruby.
Features include:
- indentation driven - closing tags not needed
- CSS shortcut notation for id and class attributes
${...}
notation to interpolate with Fantom code- efan template generation
- Template nesting with Layout pattern.
.
ALIEN-AID: Turn
afSlim
templates into powerful components with afEfanExtra!
Quick Start
Example.slim:
doctype html html head title afSlim Example meta (name="keywords" content="fantom html template language") body h1 Slim Example h2 Element shortcut notation: div#slimer This div has an ID of 'slimer' div.wombat This div has a class of 'wombat' div (style="color: red;") Attributes are specified in brackets | Use the pipe character for text. It also lets text be spanned across multiple lines! // This is a Slim comment /! This is a HTML comment | Use -- to execute Fantom code -- echo("Hello Pips!") | Use == to print the result of a fantom expression == "Hello " + ctx["name"] + "!" // Use $(...) notation to embed Fantom expressions | Hello ${ctx["name"]}! // Use the | char for javascript snippets script (type="text/javascript") | for (var i=0; i<3; i++) { console.info("Greetings from Slim!"); }
Example.fan:
using afSlim ... ctx := ["name":"Emma"] Slim().renderFromFile(`Example.slim`.toFile, ctx) // --> HTML!
Syntax
The first non-whitespace characters of each line defines the content of the line:
. -- fantom code == fantom eval // Slim comment /! HTML comment a-Z HTML element | plain text
ALIEN-AID: Because whitespace indentation is important, if your HTML looks wrong, you may have mixed up tabs and sapces. Click the
Show Whitespace
button in your editor / IDE and ensure you're using all tabs or all spaces.
Doctype
Start a line with doctype
to print a document type. Currently only html
is supported:
doctype html --> <!DOCTYPE html>
The doctype defines the element endings for tags. Example, doctype html
will ensure elements are rendered as valid HTML 5 tags as described in W3C HTML 5 Syntax.
Elements
Element lines are formatted as:
element[#id][.class][.class] [(attributes)] [text] div Text here --> <div>Text here</div> div#wombat Text here --> <div id="wombat">Text here</div> div.wombat Text here --> <div class="wombat">Text here</div> div(data-type="wombat") --> <div data-type="wombat"></div>
Note that attributes may also be enclosed in square brackets and curly brackets. Which is handy should you want to include brackets as attribute data.
div[data-type="(wombat)"] --> <div data-type="(wombat)"></div> div{data-type="(wombat)"} --> <div data-type="(wombat)"></div>
Use all the shortcuts together:
div#robert.juice.media (data-on="You Tube") Rap News --> <div id="robert" class="juice media" data-on="You Tube">Rap News</div>
Slim Comments
Start any line with //
to add a slim comment.
// This is a Slim comment
Slim comments do not appear in the generated html, but do appear in the efan template.
HTML Comments
Start any line with /!
to add a HTML comment.
/! This is a HTML comment --> <!-- This is a HTML comment -->
HTML comments do appear in the generated HTML.
Fantom Code
Start any line with --
to write Fantom code. Use to call efan helper methods.
-- echo("Hello Mum!")
Note because Slim does not have end tags, you do not specify opening or closing { curly } brackets to denote blocks of code. Due to indentation, Slim works out where they should be.
-- if (ctx.doughnuts.isEmpty) | You're not a *real* policeman! -- else ul -- ctx.doughnuts.each |nut| li ${nut.filling}
Fantom Eval
Start any line with ==
to evaluate a line of Fantom code and print it out in the template
== ctx.doughnut.filling
The resulting string is printed raw and is not HTML escaped.
Plain Text
Any line starting with a |
denotes plain text and is printed raw. You can even embed HTML:
| Look at how <small>BIG</small> I am!
Unlike other line types, text may flow / span multiple lines.
| Use the pipe character for text. It also lets text be spanned across multiple lines!
You can use |
as the first character of an element, handy for writing <script> tags:
script (type="text/javascript") | console.info("Hello..."); console.info(" ...Pips!");
HTML Escaping
You can output Fantom expressions anywhere in the template by using the standard ${...}
notation;
div Mmmm... ${ctx.doughnut.filling} is my favourite!
By default all text rendered via ${...}
is XML escaped. To print raw / unescaped text use $${...}
. Backslash escape any expression to ignore it and print it as is.
To summarise:
. ${...} escaped \${...} ignored $${...} raw / unescaped \$${...} ignored
Layout Pattern / Nesting Templates
afSlim templates may be nested inside one another, effectively allowing you to componentise your templates. This is accomplished by passing body functions in to the efan render()
method and calling renderBody()
to invoke it.
This is best explained in an example. Here we will use the layout pattern:
layout.efan:
head title ${ctx} body == renderBody()
index.efan:
html == ctx.layout.render("Cranberry Whips") ...my cool page content...
Code to run the above example:
Index.fan:
using afSlim class Index { Str renderIndex() { index := Slim().compileFromFile(`index.slim` .toFile, EfanRenderer#) layout := Slim().compileFromFile(`layout.slim`.tofile, Str#) return index.render(layout) } }
This produces an amalgamation of the two templates:
<html> <head> <title>Cranberry Whips</title> </head> <body> ...my cool page content... </body> </html>
Release Notes
v0.0.6
- New: re-jigged the Slim API and merged in methods from
SlimCompiler
. - New: Compressed needless whitespace from resulting HTML templates.
- Chg: Updated to use afEfan 1.3
v0.0.4
- Chg: Updated to use afEfan 1.2
v0.0.2
- New: Preview Release