Ltl

The Ltl template language (pronounced "little") uses a clean Jade-like syntax to generate HTML at doT-like speeds.

If you love tight code and fast rendering, you'll be right at home with Ltl.

Quick Start

Add ltl to your project:

npm install --save ltl

Compile and render templates:

var ltl = require("ltl");
var template = ltl.compile("#hi Hello ${who}!");
var result = template({who: "World"});

<div id="hi">Hello World!</div>

API

ltl.compile(code, [options])

code is a string of Ltl code.
options is an object with any of the following properties:
name will cause the template to cache at ltl.templates[name]
space causes HTML to be indented, using space as indentation.

ltl.setOption(name, value)

name is the name of a compiler option.
value is the default value you'd like to set it to.

Supported options:

tabWidth is the number of spaces that tabs are converted to before compilation. (Default: 4)

ltl.targets

Targets are key-value pairs of transpiler names and target language names.

Language

Nesting

Tag nesting is done with whitespace. You can use tabs or spaces, and Ltl can detect the number of spaces you're using.

html
  head
    title Hello World!
  body
    div Here is some content.

<!DOCTYPE html>
<html>
  <head>
    <title>Hello World!</title>
  </head>
  <body>
    <div>Here is some content.</div>
  </body>
</html>

<!DOCTYPE html> is automagically inserted before an <html> tag. If you would like to specify a custom doctype, you can use the shorthand doctype or ! syntax.

!(svg)

<!DOCTYPE svg>

Nesting can also be done with one-liners using >.

div>span Boo!

<div><span>Boo!</span></div>

IDs and Classes

HTML id and class attributes are done with # and .

div#myId.myClass.myOtherClass Hello

<div id="myId" class="myClass myOtherClass">Hello</div>

When there is no tag name, div is assumed

.hi Hello

<div class="hi">Hello</div>

Attributes

Attributes are contained in parentheses, and treated like they would be inside an HTML tag.

(style="display:none" data-something="peek-a-boo") Hide me

<div style="display:none;" data-something="peek-a-boo">Hide me</div>

Note: Unlike Jade, Ltl does not use commas between attributes.

Untagged Lines

If you want to insert a line of text without wrapping it in a tag, just start the line with a minus.

h1
  img(src="/logo.png")
  - Hello!

<h1><img src="/logo.png">Hello!</h1>

Blocks

You can output blocks of content as plain text, using :.

#blah:
  Bob Loblaw's Law Blog asks, "Why should YOU go
  to jail for a crime someone else noticed?"

<div id="blah">
  Bob Loblaw's Law Blog asks, "Why should YOU go
  to jail for a crime someone else noticed?"
</div>

Blocks can also be passed through filters, such as markdown.

:markdown
  # Ltl
  It's a recursive acronym for "Ltl Template Language".

<h1>ltl</h1><p>It's a recursive acronym for "Ltl Template Language".</p>

If a filter is unrecognized, Ltl will attempt to load it in the following ways:

Client-side: use window['FILTER_NAME']
Server-side: use require('FILTER_NAME')

A filter must have a function named compile or parse which accepts a state and returns a string, or it can be such a function itself.

Comments

Ltl comments are added by using // as a tag, and they do not output any HTML. The // tag can be used on one line or as a block.

h1 Comments
// No one will see this.
p Hello from http://lighter.io/ltl
//
  This won't be shown.
  Neither will this.

<h1>Comments</h1><p>Hello from http://lighter.io/ltl</p>

HTML comments are add by using - as a tag.

- Begin page
p Hello
- End page
-
  p Delete me

<!--Begin page--><p>Hello</p><!--End page--><!--<p>Delete me</p>-->

Interpolation

You can output the value of a state property with ${..}, and special HTML characters will be escaped for you to prevent silly little XSS attacks.

var code = '. Hello ${name}!';
var template = ltl.compile(code)
template({name: 'Sam'});

<div>Hello Sam!</div>

To encode for a URL rather than HTML, use &{}.

State: {query: "good brewpubs"}

a(href="?q=&{query}")

<a href="?q=good%20brewpubs">good brewpubs</a>

If you'd like your content to skip encoding (because you want your expression to output raw HTML tags rather than safely escaped text), use ={..}.

State: {unsafe: "<script>alert('Gotcha!')</script>"}

. ={unsafe}

<div><script>alert('Gotcha!')</script></div>

If you want to show ${..}, &{..} or ={..} blocks in your output, you can escape with a backslash.

code \${escaped} or \={raw}

<code>${escaped} or ={raw}

Variable Assignment

You can assign a value to a variable in the template state using =.

who = 'World'
. Hello ${who}!

<p>Hello World!</p>

Control

Use for..in to iterate over an array inside the state.

State: {list: ['IPA', 'Porter', 'Stout']}

ul
  for item in list
    li ${item}

<ul><li>IPA</li><li>Porter</li><li>Stout</li></ul>

Use for..of to iterate over object keys.

State: {pairings: {Coffee: 'coding', Beer: 'bloviating'}}

for drink, activity of pairings
  . ${drink} is for ${activity}.

<div><b>Coffee</b> is for <i>coding</i>.</div><div><b>Beer</b> is for <i>bloviating</i>.</div>

Conditionals

Use if, else or else if to render conditionally. The control statement's inline content gets evaluated as JavaScript.

if username == 'root'
  . Do as you please.
else if username
  . Do as you can.
else
  . Don't.

You can use builtin JavaScript objects and whatnot.

if Math.random() > 0.5
    p This has a 50/50 chance of showing.

Calling templates within templates

A template can call another template with @. To accomplish this, you must compile your templates with options.name, and they will be stored in ltl.cache. The template that's being called can access the data state.

var temp = ltl.compile('p\n @bold', {name: 'temp'});
var bold = ltl.compile('b ${text}', {name: 'bold'});
ltl.cache.temp({text: 'Hi!'});

<p><b>Hi!</b></p>

Templates can receive data using the attribute syntax, and they can receive a nested block of content (if passed), using the builtin scope variable block.

var layout = ltl.compile('html\n head>title ${title}\n body ${block}', {name: 'layout'});
var page = ltl.compile('@layout(title="Test")\n p It worked!', {name: 'page'});
ltl.cache.page();

<!DOCTYPE html>
<html>
  <head>
    <title>Test</title>
  </head>
  <body>
    <p>It worked!</div>
  </body>
</html>

Template properties

A template can have properties applied to it by using a plus symbol.

extra.ltl:

html
  head>title Template Properties
  body:md
    Properties can be used to provide hidden values to systems that compile
    Ltl templates, such as [Chug](http://lighter.io/chug).

+extra
  When compiled, the template will become a JavaScript function as usual.
  In addition, it will have a property called "extra", whose value will be
  a string containing the contents of this block.

+extra
  If the plus symbol is used more than once for the same property, the value
  of that property will be a concatenation of multiple blocks.

+also:md
  # Also supports filters
  Properties can have filters. This block will be evaluated as markdown,
  and the resulting value will be set as the "also" property of the template.

JS and CSS properties

The js and css properties of a template can be set using the plus symbol, just like other properties. Unlike including JS or CSS in a script or style tag block, these properties would need to be added to a page externally in order to affect the HTML.

js-and-css.ltl:

p This will be included in the template's rendered HTML.

+js
  console.log("This will not be included in the template's js property.");

+css
  p {color: black}

In addition, several languages that compile to JS/CSS are supported. Their compilers can be invoked using their corresponding file extensions. For JS, Ltl supports coffee, litcoffee, iced, es6, and ts. For CSS, it supports less, scss and styl.

coffee-and-less.ltl:

p:md
  This template will compile to a function which returns this paragraph, and
  the function will have **js** and **css** properties.

+coffee
  console.log "Hello from CoffeeScript!"

+styl
  @textColor: #000;

  p {
    color: @textColor;
  }

Inline JS and CSS

JavaScript and CSS can also be included inline in a template using directives that appear as tags. Just as with JS and CSS properties, these support compilers such as CoffeeScript and LESS.

inline-js-and-css.ltl

less
  a {color: #000;}

coffee
  state.linkText = 'hello'

a ${linkText}

The state variable in a template is called state, so the above would set the linkText value in the state object, and then it would render the following HTML if called:

<style>a {color: #000;}</style><a>hello</a>

lighterio/ltl

Ltl