All Topics

#2192 [ANN] afSlim v1.0.0 - Concise HTML Templates

SlimerDude Thu 3 Oct 2013

afSlim Preview Release

afSlim is a library for generating HTML from concise, lightweight templates. afSlim is based on Jade for javascript and Slim for Ruby.

API Docs: http://repo.status302.com/doc/afSlim/#overview
Install: fanr install -r http://repo.status302.com/fanr/ afSlim
Download: http://repo.status302.com/browse/afSlim
Source: https://bitbucket.org/AlienFactory/afslim

Features include:

indentation driven - closing tags not needed
CSS shortcut notation for #id and .class attributes
${...} notation to interpolate 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
    div You can even embed <abbr>HTML</abbr> tags!

    | Use the pipe character for text.
      Text may also 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"]}!

    // embedding Javascript is easy!
    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: Whitespace indentation is very important! If your HTML looks wrong, click Show Whitespace in your editor / IDE and make sure you are not mixing up tabs and 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>

Whitespace around the attributes is optional:

a (href="http://fantom.org.") Fantom
a(href="http://fantom.org.") Fantom

Attributes may also be enclosed in square brackets. Handy when using Fantom interpolation:

div[data-type="${ calculateWombat() }"]

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. So the following:

p
  | More recently, I discovered
    Fantom
    a niffty pragmatic language

May be re-written as:

p | More recently, I discovered
    Fantom
    a niffty pragmatic language

This is handy for writing <script> tags:

script (type="text/javascript") |
  console.info("Hello...");       // note the leading 2 spaces
  console.info("     ...Pips!");  // note the leading 2 spaces

Note you must indent the text by at least 2 whitespace characters to ensure the text is inside the | character. Remember what you're actually writing is a condensed version of:

script (type="text/javascript")
 |
  console.info("Hello...");
  console.info("     ...Pips!");

This means that, even though it looks okay to the naked eye, indenting the script by 1 Tab will not work!

A personal formatting preference is to use the | character for each line of text, prefixed with a tab. Text may then be freely mixed with elements and it all lines up nicely. Example using > to show tabs:

p>  | More recently, I discovered
>   a (href="http://fantom.org/") Fantom
>   |  a niffty pragmatic language (*)
>   | which runs on Java and .NET

(*) Note: the extra leading space at the start of the line prevents it from butting up against the previous <a> tag:

<a href="http://fantom.org/">Fantom</a> a niffty pragmatic language --> Fantom a niffty pragmatic language

and not

<a href="http://fantom.org/">Fantom</a>a niffty pragmatic language --> Fantoma niffty pragmatic language

HTML Escaping

Similar to Fantom Str interpolation, you can output Fantom expressions anywhere in the template 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

Just like efan, Slim templates may be nested inside one another, effectively allowing you to componentise your templates. This is accomplished by passing body functions 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.slim:

head
  title ${ctx}
body
  == renderBody()

index.slim:

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>

Have fun!

andy Fri 4 Oct 2013

Hadn't seen Slim before - cool stuff!