Swig 使用指南
一、如何使用
1、API
swig.init({
allowErrors: false,
autoescape: true,
cache: true,
encoding: 'utf8',
filters: {},
root: '/',
tags: {},
extensions: {},
tzOffset: 0
});
options:
allowErrors: 預設值為 false。将所有模闆解析和編譯錯誤直接輸出到模闆。如果為 true，則将引發錯誤，抛出到 Node.js 程序中，可能會使您的應用程式崩潰。
autoescape: 預設true，強烈建議保持。字元轉換表請參閱轉義過濾器。true: HTML安全轉義
false: 不轉義，除非使用轉義過濾器或者轉義标簽
'js': js安全轉義
cache: 更改為 false 将重新編譯每個請求的模闆的檔案。正式環境建議保持true。
encoding: 模闆檔案編碼
root: 需要搜尋模闆的目錄。如果模闆傳遞給 swig.compileFile 絕對路徑(以/開頭)，Swig不會在模闆root中搜尋。如果傳遞一個數組，使用第一個比對成功的數組項。
tzOffset: 設定預設時區偏移量。此設定會使轉換日期過濾器會自動的修正相應時區偏移量。
filters:自定義過濾器或者重寫預設過濾器，參見自定義過濾器指南。
tags: 自定義标簽或者重寫預設标簽，參見自定義标簽指南。
extensions: 添加第三方庫，可以在編譯模闆時使用，參見參見自定義标簽指南。
2、nodejs
var tpl = swig.compileFile("path/to/template/file.html");
var renderedHtml = tpl.render({ vars: 'to be inserted in template' });
或者
var tpl = swig.compile("Template string here");
var renderedHtml = tpl({ vars: 'to be inserted in template' });
3、結合Express
npm install express
npm install consolidate
然後
app.engine('.html', cons.swig);
app.set('view engine', 'html');
4、浏覽器
Swig浏覽器版本的api基本與nodejs版相同，不同點如下：
不能使用swig.compileFile，浏覽器沒有檔案系統
你必須提前使用swig.compile編譯好模闆
按順序使用extends, import, and include，同時在swig.compile裡使用參數templateKey來查找模闆var template = swig.compile('
{% block content %}{% endblock %}
', { filename: 'main' });
var mypage = swig.compile('{% extends "main" %}{% block content %}Oh hey there!{% endblock %}', { filename: 'mypage' });
二、基礎
1、變量
{{ foo.bar }}
{{ foo['bar'] }}
如果變量未定義，輸出空字元。
變量可以通過過濾器來修改：
{{ name|title }} was born on {{ birthday|date('F jS, Y') }}
// Jane was born on July 6th, 1985
2、邏輯标簽
參見标簽部分。
3、注釋
4、空白
模闆裡的空白在最終輸出時預設保留，如果需要去掉空白，可以在邏輯标簽前後加上空白控制服-：
{% for item in seq -%}
{{ item }}
{%- endfor %}
三、模闆繼承
Swig 使用 extends 和 block 來實作模闆繼承
layout.html
{% block title %}My Site{% endblock %}
{% block head %}
{% endblock %}
{% block content %}{% endblock %}
index.html
{% extends 'layout.html' %}
{% block title %}My Page{% endblock %}
{% block head %}
{% parent %}
{% endblock %}
{% block content %}
This is just an awesome page.
{% endblock %}
四、變量過濾器
用于修改變量。變量名稱後用 | 字元分隔添加過濾器。您可以添加多個過濾器。
1、例子
{{ name|title }} was born on {{ birthday|date('F jS, Y') }}
and has {{ bikes|length|default("zero") }} bikes.
也可以使用 filter 标簽來為塊内容添加過濾器
{% filter upper %}oh hi, paul{% endfilter %}
2、内置過濾器
add(value)：使變量與value相加，可以轉換為數值字元串會自動轉換為數值。
addslashes：用 \ 轉義字元串
capitalize：大寫首字母
date(format[, tzOffset])：轉換日期為指定格式
format：格式
tzOffset：時區
default(value)：預設值(如果變量為undefined，null，false)
escape([type])：轉義字元預設： &, , ", '
js: &, , ", ', =, -, ;
first：傳回數組第一個值
join(glue)：同[].join
json_encode([indent])：類似JSON.stringify, indent為縮進空格數
last：傳回數組最後一個值
length：傳回變量的length，如果是object，傳回key的數量
lower：同''.toLowerCase()
raw：指定輸入不會被轉義
replace(search, replace[, flags])：同''.replace
reverse：翻轉數組
striptags：去除html/xml标簽
title：大寫首字母
uniq：數組去重
upper：同''.toUpperCase
url_encode：同encodeURIComponent
url_decode：同decodeURIComponemt
3、自定義過濾器
建立一個 myfilter.js 然後引入到 Swig 的初始化函數中
swig.init({ filters: require('myfilters') });
在 myfilter.js 裡，每一個 filter 方法都是一個簡單的 js 方法，下例是一個翻轉字元串的 filter：
exports.myfilter = function (input) {
return input.toString().split('').reverse().join('');
};
你的 filter 一旦被引入，你就可以向下面一樣使用：
{{ name|myfilter }}
{% filter myfilter %}
I shall be filtered
{% endfilter %}
你也可以像下面一樣給 filter 傳參數：
exports.prefix = function(input, prefix) {
return prefix.toString() + input.toString();
};
{{ name|prefix('my prefix') }}
{% filter prefix 'my prefix' %I will be prefixed with "my prefix".{% endfilter %}
{% filter prefix foo %}I will be prefixed with the value stored to `foo`.{% endfilter %}
五、标簽
1、内置标簽
extends：使目前模闆繼承父模闆，必須在檔案最前
參數file：父模闆相對模闆 root 的相對路徑
block*：定義一個塊，使之可以被繼承的模闆重寫，或者重寫父模闆的同名塊
參數name：塊的名字，必須以字母數字下劃線開頭
parent*：将父模闆中同名塊注入目前塊中
include*：包含一個模闆到目前位置，這個模闆将使用目前上下文
參數file: 包含模闆相對模闆 root 的相對路徑
參數ignore missing：包含模闆不存在也不會報錯
參數with x：設定 x 至根上下文對象以傳遞給模闆生成。必須是一個鍵值對
參數only：限制模闆上下文中用 with x 定義的參數
{% include template_path %}
{% include "path/to/template.js" %}
你可以标記 ignore missing，這樣如果模闆不存在，也不會抛出錯誤
{% include "foobar.html" ignore missing %}
本地聲明的上下文變量，預設情況不會傳遞給包含的模闆。例如以下情況，inc.html 無法得到 foo 和 bar
{% set foo = "bar" %}
{% include "inc.html" %}
{% for bar in thing %}
{% include "inc.html" %}
{% endfor %}
如果想把本地聲明的變量引入到包含的模闆種，可以使用 with 參數來把後面的對象建立到包含模闆的上下文中
{% set foo = { bar: "baz" } %}
{% include "inc.html" with foo %}
{% for bar in thing %}
{% include "inc.html" with bar %}
{% endfor %}
如果目前上下文中 foo 和 bar 可用，下面的情況中，隻有 foo 會被 inc.html 定義
{% include "inc.html" with foo only %}
only 必須作為最後一個參數，放在其他位置會被忽略
raw：停止解析标記中任何内容，所有内容都将輸出
參數file: 父模闆相對模闆 root 的相對路徑
for*：周遊對象和數組
參數x：目前循環疊代名
參數in：文法标記
參數y：可疊代對象。可以使用過濾器修改
{% for x in y %}
{% if loop.first %}
- {% endif %}
- {{ loop.index }} - {{ loop.key }}: {{ x }}
{% if loop.last %}
{% endif %}
{% endfor %}
特殊循環變量
loop.index：目前循環的索引(1開始)
loop.index0：目前循環的索引(0開始)
loop.revindex：目前循環從結尾開始的索引(1開始)
loop.revindex0：目前循環從結尾開始的索引(0開始)
loop.key：如果疊代是對象，是目前循環的鍵，否則同 loop.index
loop.first：如果是第一個值傳回 true
loop.last：如果是最後一個值傳回 true
loop.cycle：一個幫助函數，以指定的參數作為周期
```html
{% for item in items %}
{{ item }}
{% endfor %}
在 for 标簽裡使用 else
{% for person in people %}
{{ person }}
{% else %}
There are no people yet!
{% endfor %}
if：條件語句
參數：接受任何有效的 JavaScript 條件語句，以及一些其他人類可讀文法
{% if x %}{% endif %}
{% if !x %}{% endif %}
{% if not x %}{% endif %}
{% if x and y %}{% endif %}
{% if x && y %}{% endif %}
{% if x or y %}{% endif %}
{% if x || y %}{% endif %}
{% if x || (y && z) %}{% endif %}
{% if x [operator] y %}
Operators: ==, !=, , >=, ===, !==
{% endif %}
{% if x == 'five' %}
The operands can be also be string or number literals
{% endif %}
{% if x|length === 3 %}
You can use filters on any operand in the statement.
{% endif %}
{% if x in y %}
If x is a value that is present in y, this will return true.
{% endif %}
else 和 else if
{% if foo %}
Some content.
{% else if "foo" in bar %}
Content if the array `bar` has "foo" in it.
{% else %}
Fallback content.
{% endif %}
autoescape：改變目前變量的自動轉義行為
參數on：目前内容是否轉義
參數type：轉義類型，js 或者 html，預設 html
假設
some_html_output = '
Hello "you" & \'them\'
';
然後
{% autoescape false %}
{{ some_html_output }}
{% endautoescape %}
{% autoescape true %}
{{ some_html_output }}
{% endautoescape %}
{% autoescape true "js" %}
{{ some_html_output }}
{% endautoescape %}
将會輸出
Hello "you" & 'them'
<p>Hello "you" & 'them' </p>
\u003Cp\u003EHello \u0022you\u0022 & \u0027them\u0027\u003C\u005Cp\u003E
set：設定一個變量，在目前上下文中複用
參數name：變量名
參數=：文法标記
參數value：變量值
{% set foo = [0, 1, 2, 3, 4, 5] %} {% for num in foo %}
{{ num }}
{% endfor %}
macro：建立自定義可服用的代碼段
參數...: 使用者定義
{% macro input type name id label value error %}
{{ label }}
{% endmacro %}
然後像下面使用
{{ input("text", "fname", "fname", "First Name", fname.value, fname.errors) }}
{{ input("text", "lname", "lname", "Last Name", lname.value, lname.errors) }}
輸出如下
First Name
Last Name
import：允許引入另一個模闆的宏進入目前上下文
參數file：引入模闆相對模闆 root 的相對路徑
參數as：文法标記 var: 配置設定給宏的可通路上下文對象
{% import 'formmacros.html' as form %}
{# this will run the input macro #}
{{ form.input("text", "name") }}
{# this, however, will NOT output anything because the macro is scoped to the "form" object: #}
{{ input("text", "name") }}
filter：對整個塊應用過濾器
參數filter_name: 過濾器名字
參數... : 若幹傳給過濾器的參數 父模闆相對模闆 root 的相對路徑
{% filter uppercase %}
oh hi, {{ name }}
{% endfilter %}
{% filter replace "." "!" "g" %}
Hi. My name is Paul.
{% endfilter %}
輸出
OH HI, PAUL Hi! My name is Paul!
spaceless：嘗試移除html标簽間的空格
{% spaceless %}
{% for num in foo %}
{{ loop.index }}
{% endfor %}
{% endspaceless %}
輸出
123
![swig 轉義html,SWIG Compatibility[圖]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)