View on GitHub

Surge.js

Download this project as a .zip file Download this project as a tar.gz file

Tutorial

Introduction

Surge.js is a Javascript template engine. It will be compile the compile to javascript function.

Get Started

Write a demo template in script block with type="text/template":

<script type="text/template" id="demo0">
<ul id="products">
{% for product in products %}
<li>
  <h2 title="{{ product.title|title}}">{{ product.title | title | truncate:20 }}</h2>
  Only {{ product.price }}
  <p>{{ product.description | truncate: 200  }}</p>
</li>
{% endfor %}
</ul>
</script>

The Data source:

var data = {
  products:[
    {title:'The product name short description-1', price:199.89, description:'The detail information about the product-1.'},
    {title:'The product name short description-2', price:299.89, description:'The detail information about the product-2.'},
    {title:'The product name short description-3', price:399.89, description:'The detail information about the product-3.'},
    {title:'The product name short description-4', price:499.89, description:'The detail information about the product-4.'},
  ]
};

Run demo.

Syntax

The Syntax of Surge.js is very like Liquid or Django template. Which use "{{" and "}}" for marking up the variable, "{%" and "%}" for marking up flow control, "{#" and "#}" for marking up comment block. And also, you can use Javascript function to filter variable, that is named filter. The surge define some builtin filters, can also, you can define your own filter, just use surge.register function to register the filter.

Variable

The variable is marked up with {{ and }}. Example: 

<h1>{{ product.name }}</h1>
<p>{{ product.description }}</p>

Actually, you can aslo use constant, Such as :{{ 12 }}, {{ "Welcome, You."}}. Even, you don't need to worry about " and ', you can code like this:

<li title="{{ "Demo" }}">{{ product.name }}<li>
<li title='{{ 'Demo' }}'>{{ product.name }}<li>

Filter

The filter is just the javascript function, The filter usage is like:

{{ product.name | title }}
{{ product.name | title | truncate: 20 }}
{{ product.name | truncate: 20 |title }}

The both of "title" and "truncate" are filters. which decleard like function title(a) {... and function truncate(a, count) {.... The Surge.js will compile these code to js expression, like below codes:

title(product.name)
truncate(title(product.name), 20)
title(truncate(product.name, 20))

The filter is not only used in variable, but also you can use filters with if and for tags. The following chapters will discuss them.

Builtin filters

The Surge.js predefine some filters.

trim

Trim the white space started with string or ended with string.

Input source:

{{ "   abc  "|trim }}

Output: abc

ltrim

Trim the white space started with string.

Input source:

{{ "   abc  "|ltrim }}

Output: "abc "

rtrim

Trim the white space ended with string.

Input source:

{{ "   abc  "|rtrim }}

Output: " abc"

add

Adds the argument to the value.

Input source:

{{ 12|add:12 }}

Output: 24

capfirst

Capitalizes the first character of the value. If the first character is not a letter, this filter has no effect.

Input source:

{{ "surge"|capfirst }}

Output: "Surge"

cut

Removes all values of arg from the given string. The argment can be regex pattern.

Input source:

{{ "String with spaces"|cut:" " }}

Output: "Stringwithspaces"

default

If value evaluates to False, uses the given default. Otherwise, uses the value.

Input source:

{{ value|default:"nothing" }}

If value is one of "", 0, [], false, undefined, the output will be "nothing", or output is value.

[] is not false in javascript.

sort

Takes a list of object and returns that list sorted by the key given in the argument, or use default argument.

For example:

{{ value|sort:"name" }}

If value is:

[
  {'name': 'zed', 'age': 19},
  {'name': 'amy', 'age': 22},
  {'name': 'joe', 'age': 31},
]

then the output would be:

[
  {'name': 'amy', 'age': 22},
  {'name': 'joe', 'age': 31},
  {'name': 'zed', 'age': 19},
]

Also this filter can used with Array argument, For example:

{{ value|sort }}

If value is:

[1,15,80,9,10,12]

Or

["1", "15", "80", "9", "10", "12"]

then the output would be:

[1,9,10,12,15,90]

Or

["1", "10", "12", "15", "9", "90"]

This would be diff with js. Array.sort function will sort the item in Array as string, so the output would be: [1, 10, 12, 15, 9, 90] in js.

reverse

Takes a list of dictionaries and returns that list sorted in reverse order by the key given in the argument. This works exactly the same as the above filter, but the returned value will be in reverse order.

escape

Escapes a string's HTML. Specifically, it makes these replacements:

length

Returns the length of the value. This works for both strings and lists.

For example:

{{ value|length }}

If value is ['a', 'b', 'c', 'd'], the output will be 4.

lower

Converts a string into all lowercase.

For example:

{{ value|lower }}

If value is Still MAD At Yoko, the output will be still mad at yoko.

upper

Converts a string into all uppercase.

For example:

{{ value|upper }}

If value is "Joel is a slug", the output will be "JOEL IS A SLUG".

striptags

Strips all [X]HTML tags.

For example:

{{ value|striptags }}

If value is "<b>Joel</b> <button>is</button> a <span>slug</span>", the output will be "Joel is a slug".

title

Converts a string into titlecase by making words start with an uppercase character and the remaining characters lowercase. This tag makes no effort to keep "trivial words" in lowercase.

For example:

{{ value|title }}

If value is "my FIRST post", the output will be "My First Post".

truncate

Truncates a string if it is longer than the specified number of characters. Truncated strings will end with a translatable ellipsis sequence ("...").

Argument: Number of characters to truncate to

For example:

{{ value|truncate:9 }}

If value is "Joel is a slug", the output will be "Joel is ...".

Create Your Own Filters

Create Your Own Filters

Tag

Tag

if

if

for

for

Comment

Comment