Vash

"... the 60 billion double-dollar template-maker!" ~ The previous README, and no one else, ever.

Vash is a template engine that offers a swift flow between code and content using Razor Syntax ¹ . This document ² is intended for users of Vash, and also serves as a reference for Vash's implementation of Razor Syntax.

• Features
• Syntax Example
• Quick Start
  • nodejs
  • express
  • Browser - Vanilla
  • Browser - Browserify et al
  • Browser - RequireJS
• Playground
• Syntax
  • The Transition Character: @
  • Expressions
  • Advanced Expressions
  • Explicit Expressions
  • Code Blocks
  • Keyword Blocks
  • Comments
  • HTML Escaping
  • Explicit Markup
• Configuration
  • vash.config.useWith
  • vash.config.modelName
  • vash.config.helpersName
  • vash.config.htmlEscape
  • vash.config.debug
  • vash.config.debugParser
  • vash.config.debugCompiler
  • vash.config.simple
  • vash.config.favorText
• Template Options
  • asContext
  • onRenderEnd
• Helper System
• Built-in Helpers
  • vash.helpers.raw
  • vash.helpers.escape
  • vash.helpers.tplcache
• Layout Helpers
  • vash.helpers.extend
  • vash.helpers.block
  • vash.helpers.append
  • vash.helpers.prepend
  • vash.helpers.include
• Compiled Helpers
• Buffer API
• Precompiling Templates
• Vash Runtime (Browser)
• Compile-time API
  • vash.compile
  • vash.compileHelper
  • vash.compileBatch
• Runtime API
  • vash.link
  • vash.lookup
  • vash.install
  • vash.uninstall
• vash(1)
  • Installation
  • --target-namespace
  • --property-name
  • --helper
• Contributing / Building
• Getting Help
• Special Thanks
• License

Features

• Mix code and content without ugly delineators, like `Syntax Example ======================

  How are you @model.name? Today is a sunny day on the planet Gunsmoke.

  @model.forEach(function(m){
  • @m.name
  })

Quick Start

nodejs

var vash = require('vash');
var tpl = vash.compile('<p>I am a @model.t!</p>');

var out = tpl({ t: 'template' });
// <p>I am a template!</p>

express

Check out vash-express-example for a full example of hooking up vash as a view engine for express 3. But it's basically as simple as:

var express = require('express');

var app = express();
app.set('view engine', 'vash');

More information is also available in the [Layout Helpers][] sections.

Browser - Vanilla

var tpl = vash.compile( '<p>I am a @model.t!</p>' );
document.querySelector('#content').innerHTML = tpl({ t: 'template' });

But you should probably be precompiling your templates. See [Precompiling Templates][] for more info. Then you can just include the Vash runtime instead of the entire compiler.

Browser - Browserify et al

Just require Vash, and compile. If you want something fancier, try vashify! Then you can directly require any .vash file and it will be resolved as compiled template:

var tpl = require('my-awesome-template.vash');
document.querySelector('#content').innerHTML = tpl({ t: 'template' });

Browser - RequireJS

RequireJS support has been recently dropped. However Vash does support CJS environments, so as long as you configure RequireJS to consume Vash as a CJS project (including node_modules resolution), everything should work.

Playground

Vash now has a playground of sorts at CodePen.io. It uses the current version of vash.js from the build folder. Fork it to test your own template ideas!

Syntax

For the following examples, assume a model is passed into the compiled function. If a model is explicitly defined, it will appear as:

// model = { what: 'hello!' }

The Transition Character: @

Vash uses the @ symbol to transition between code and markup. To escape and print a literal @, use a double @, like this: @@.

Expressions

The most basic usage of Vash is an implicit expression. Vash is smart enough to know what's valid JS and what's not, and can usually do what you want it to do. An expression is an @ followed by a valid JS identifier. This is then interpolated automatically.

input:

// model = { what: 'hello!' }
<p>@what</p>

output:

<p>hello!</p>

The model comment is just to show that the object passed into the compiled template contains a key that matches the expression.

To allow for the fastest render time possible, Vash by default requires the model to be addressed explicitly. This is to avoid using a with statment in the compiled template, which is approximately 25 times slower. The above example then becomes:

input:

<p>@model.what</p>

output:

<p>hello!</p>

As you can see, the output is exactly the same. The name used to reference the model is configurable via [vash.config.modelName][]. Typical values are model and it.

Advanced Expressions

Vash typically knows when an expression ends, even when the expression is complex. For example:

input:

<p>@model.what().who[2]('are you sure')('yes, it\'s ok')( model.complex ? 'FULL POWER' : '' )</p>

This will work just fine, assuming you have a model that actually contains that complexity! I hope you don't, and if so, I feel bad.

Callbacks work as well:

input:

// model = ['a', 'b']
@model.forEach(function(item){
	<li>@item</li>
})

outputs:

<li>a</li><li>b</li>

Vash also knows the difference between JS dot notation and a period.

input:

// model = { description: 'living' }
<p>Plants are @model.description.</p>

output:

<p>Plants are living.</p>

And empty brackets, because they're not valid JS:

input:

// model = { formName: 'addresses' }
<input name="@model.formName[]" type="text">

output:

<input name="addresses[]" type="text">

Email addresses, to an extent, are fine as well. Vash makes a trade-off. It uses the following regex to validate an email address:

/^([a-zA-Z0-9.%]+@[a-zA-Z0-9.\-]+\.(?:ca|co\.uk|com|edu|net|org))\b/

Email addresses can actually contain many more valid characters, and are really hard to validate. Vash can handle a typical email address with ease:

input:

<a href="mailto:vash@planetgunsmoke.com">Email Me</a>

output:

<a href="mailto:vash@planetgunsmoke.com">Email Me</a>

If you have a complex email address that confuses Vash, then you should use an explicit expression instead.

Explicit Expressions

An explicit expression is simply an expression that, instead of being composed of @ and a valid JS identifier, is surrounded by parenthesis.

input:

<p>@(model.what)</p>

output:

<p>hello!</p>

Why would you ever need this? Perhaps you want to do something like:

input:

// model = { hasIceCream: true }
<p class="@( model.hasIceCream ? 'ice-cream' : '')">Ice Cream</p>

output:

<p class="ice-cream">Ice Cream</p>

You could even create an anonymous function.

input:

@(function(type){ return type + ' cream'; }('banana'))

output:

banana cream

As you can see, Vash does not require a model to be referenced, or even passed in.

Code Blocks

Sometimes, AGAINST ALL ODDS, a template may need some quick computation of values to avoid repeating yourself. Unlike expressions and explicit expressions, a code block does not directly output. To compare to PHP, expressions are like , while a code block is like .

A code block is simply @{ }.

input:

@{ var rideOn = 'shooting star'; }

output:

That's right, nothing! Here's a better example:

input:

@{
	var total = model.price + model.tax;
}

<p>Your total is: $@total</p>

output:

<p>Your total is: $2.70</p>

Anything is valid within a code block, such as function declarations or even something as complex as defining a prototype. You can also use markup within a code block, and it will behave as expected:

input:

@{ <p>This works!</p> }

output:

<p>This works!</p>

A code block just tells Vash, "expect the next stuff to be code until otherwise".

Keyword Blocks

Vash is aware of keywords, and will open a code block automatically for you.

input:

// model = { type: 'banana' }
@if(model.type){
	<p>I'm a @model.type!</p>
} else if(model.name){
	<p>My name is @model.name.</p>
} else {
	<p>I DON'T KNOW WHO OR WHAT I AM...</p>
}

output:

<p>I'm a banana!</p>

This also works for while, for, do, try/catch, with, switch, function, and other keywords.

You don't even need to worry about whitespace or newlines:

input:

// model = 1
@switch(model){case 1:<p></p>break;case 2:<b></b>break;}

output:

<p></p>

Comments

Vash also supports comments that are not compiled into the template. These are delineated with @* and *@

input:

@* I am a comment that extends
over multiple lines *@
<p>BANANA!</p>

output:

<p>BANANA!</p>

HTML Escaping

By default, Vash escapes any HTML-like values before outputting them.

input:

// model = { what: '<img>' }
<p>@model.what</p>

output:

<p>&lt;img /&gt;</p>

If you are sure that you trust the content and/or need to display HTML-like values, you can escape the HTML escaping via a call to Vash's [helper system][]: html.raw.

input:

// model = { what: '<img>' }
<p>@html.raw(model.what)</p>

output:

<p><img></p>

This behavior can be disabled using [vash.config.htmlEscape][].

Explicit Markup

Sometimes you may wish to tell Vash that what you're typing is markup or content, as opposed to code. Take the following example:

input:

// model = ['a']
@model.forEach(function(item){
	this should be content @item
})

output:

(Error when compiling)

In this situation, you have two options. The first is the @: (at colon) escape. It tells Vash that until it sees a newline, treat the input as content, not code.

input:

// model = ['a']
@model.forEach(function(item){
	@: this should be content @item
})

output:

this should be content a

The other option, in the event that more than one line is needed, is by using an imaginary HTML tag named `