Liquid语言是一种标记语言, 将模板转化为相应的代码从而进行相关的”编译”. 被广泛用于多种工具中, 最为著名就是Github的Jekyll静态网页生成系统. Liquid使用Ruby编写而成.
Liquid语言有两大类标记: 一种是结果型(Output), 一种是语句型, 前者进行输出为text, 后者主要进行语句相关操作,如if, for等.
Output型使用{{ output }} 进行, 而Tag型则采用 {% tag %}.
Output型
一种直接输出, 例如变量. {{ var }}
一种是过滤器, 采用: {{ var | filter1 |filter2 }}形式, filter相当于一个处理函数, 对变量进行操作并返回新值. 新值用于下一个过滤器或者用于直接输出为结果. 过滤器可以见下面介绍. jekyll有额外的过滤器参考模板部分.
Tag型
说白了就是一般的语句, 包括If/Unless/Case判断, For/Loop循环等. 写完Tag后一般需要有后续的EndTagname. 如: {% if %} {% endif %}. 一些例子用法参考后面的介绍.
先说一下, Liquid支持 and
, or
, !=
, ==
, contains
(包含), true
, false
.
常用tag包括:
- {%
assign
var=value %} 赋值语句. 没有end. - {%
capture
var %} context {% endcapture %} 将中间的内容赋值给变量. 因此可以不是简单的值而是获取变量经操作后再赋值.更强大. - {%
if
condition %}, {%elsif
condition %}, {%else
%}, {%endif
%} 系列. 支持and, or, 不支持not. if not使用 {%unless
condition %} .. {%endunless
%}进行. 注意是 elsif 而不是elseif. - {%
case
var %}, {%when
value %}, {%else
%}, {%endcase
%} 系列, 多种条件选择. - {%
for
varin
array %}, {%else
%}, {%endfor
%} 循环, 后面可以跟一些修饰符parameter:value
进一步控制. else可用于数组为空时的情况. 另外也支持 {%break
%}和{%continue
%}打断虚幻. - {%
cycle
[groupname:] val1, val2, .. %} 循环逐个列出指定内容. 注意没有end. 每调用一次就会列出下个值. groupname是列的时候区分组的, 默认不加列名就是只有一个组. - {%
comment
%} .. {%endcomment
%} , Liquid注释(不是HTML注释), 不解释也不显示. - {%
raw
%} … {%endraw
%}, 不作为Liquid解释, 会作为源码显示. 例如本文上边文字部分由该对tag包围. 很重要! - {%
include
filename %}, 将另一个文件作为模板片段插入.
新建tag可以使用Ruby进行, 参考最后for programmer的部分.
在Jekyll里还包括:
- {%
include_relative
filename %} 以当前文件所在目录来定位文件进行插入. {% include %}的包含则在_includes
文件夹内. - {%
highlight
lang linenos %} {%endhighlight
%} Rouge或Pygments语法高亮. lang对应相应编程语言, 如vb.net(更多参考:Rouge与支持语言, Pygments与支持语言)linenos是打开行号显示, 非必要. - {%
post_url
/subdir/2010-07-21-name-of-post %} 可以将_posts里的blog文件名转化为相应url. 注意地址, 注意没有后缀. - {%
gist
user/gistID filename %} 插入Gist内容. user和gistID对应在Gist的网址里.文件名可用于指定gist中某文件(非必要选项). 需要额外安装jekyll-gist插件, 建议直接使用gist的embed功能.
if tab实例 (用的highlight的tag, 先包裹raw的tag去liquid解析, 再包含代码):
1
2
3
4
5
{% if user.name == 'tobi' %}
Hello tobi
{% elsif user.name == 'bob' %}
Hello bob
{% endif %}
Liquid Home
Liquid is a template engine which was crafted for very specific requirements
- It has to have simple markup and beautiful results. Template engines which don’t produce good looking results are no fun to use.
- It needs to be non-evaling and secure. Liquid templates are made so that users can edit them. You don’t want your server running code that your users wrote.
- It has to be stateless. The compile and render steps have to be separate, so that the expensive parsing and compiling can be done once; later on, you can just render it by passing in a hash with local variables and objects.
- It needs to be able to style emails as well as HTML.
Stuff to read, watch, etc.
- Class reference
- Liquid for Programmers
- Liquid for Designers
- Liquid screencast
- Ports of Liquid to other environments:
- liquid.js (JavaScript)
- DotLiquid (C#)
- php-liquid (PHP)
- Template::Liquid (Perl)
- CFML-LIQUID (CFML/ColdFusion)
- liquid.as (ActionScript 3)
- Liqp (Java)
- Liquid (Go)
- Liquid.NET (C#)
Who uses Liquid?
- Shopify
- eLocal
- Mephisto
- Harmony
- Chameleon
- Cashboard
- Adobe Business Catalyst
- Voog
- Zendesk
- YikeSite (CMS)
- Simplicant (Applicant Tracking System)
- 3scale (API Management System)
- Chaptercore
- ScreenSteps Live
- PokerAffiliateSolutions
- Desk.com
- Ronin
- AboutOne
- RightScale
- Menumill
- Moxie Software
- Rusic
- Development Seed
- peerTransfer
- NationBuilder
- Pronto Avenue
- Device Magic
- Spiceworks
- PufferPages (CMS)
- Displet
- Paspartout
- TrackGrid
- Jekyll
- Octopress
- Vnda
- LeadFormance
- 23 Video
- CrystalCommerce
- Rackspace
- Talent Technology
- WebKite
- Adam Ralph
- Quaderno
- LocomotiveCMS
- Customer.io
- Mixture.io
- MakePlans
- Planning Center Services
- Planning Center Resources
- RoQua
- Evrone
- Liquid.as
- Open Liquid
- 500px
- VTEX
- Xorcode
- MobiCheckin (registration forms)
- Educative-Games.org
- GiftFold
- Reamaze
- Sitebox.io
- Stunning
- Vero (Email Marketing Software)
- GoDaddy
- SendOwl
- FOX21.at
- Bright Sites
- Mode Analytics
- Helpjuice
- Freshdesk
- Continuity Control
- Mitingu
- Festiment
- Unsound Music Festival
- Expertory
- Appboy
- Disco
- LavoWeb
- DediConcept
- Lucid
- Fedora
- Jumpseller
- Openbay
- Sayan’s Blog
- Industry Mailout
- Near Me Marketplaces
- Growing with the Web
- Mercury Flight
- Drip
- Sixty AS
- Thinkific
- dotmailer
- meowbox
- Embulk
- …Add yours :)
Why should I use Liquid?
- You want to allow your users to edit the appearance of your application, but don’t want them to run insecure code on your server.
- You want to render templates directly from the database.
- You like Smarty-style template engines.
- You need a template engine which does HTML just as well as emails.
- You don’t like the markup language of your current template engine.
Liquid for designer
There are two types of markup in Liquid: Output and Tag.
- Output markup (which may resolve to text) is surrounded by
- Tag markup (which cannot resolve to text) is surrounded by
Output
Here is a simple example of Output:
Advanced output: Filters
Output markup takes filters. Filters are simple methods. The first parameter is always the output of the left side of the filter. The return value of the filter will be the new left value when the next filter is run. When there are no more filters, the template will receive the resulting string.
Standard Filters
date
- reformat a date (syntax reference)capitalize
- capitalize words in the input sentencedowncase
- convert an input string to lowercaseupcase
- convert an input string to uppercasefirst
- get the first element of the passed in arraylast
- get the last element of the passed in arrayjoin
- join elements of the array with certain character between themsort
- sort elements of the arraymap
- map/collect an array on a given propertysize
- return the size of an array or stringescape
- escape a stringescape_once
- returns an escaped version of html without affecting existing escaped entitiesstrip_html
- strip html from stringstrip_newlines
- strip all newlines (\n) from stringnewline_to_br
- replace each newline (\n) with html breakreplace
- replace each occurrence e.g.{{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'
replace_first
- replace the first occurrence e.g.{{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'
remove
- remove each occurrence e.g.{{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'
remove_first
- remove the first occurrence e.g.{{ 'barbar' | remove_first:'bar' }} #=> 'bar'
truncate
- truncate a string down to x characters. It also accepts a second parameter that will append to the string e.g.{{ 'foobarfoobar' | truncate: 5, '.' }} #=> 'foob.'
truncatewords
- truncate a string down to x wordsprepend
- prepend a string e.g.{{ 'bar' | prepend:'foo' }} #=> 'foobar'
pluralize
- return the second word if the input is not1
, otherwise return the first word e.g.{{ 3 | pluralize: 'item', 'items' }} #=> 'items'
append
- append a string e.g.{{ 'foo' | append:'bar' }} #=> 'foobar'
slice
- slice a string. Takes an offset and length, e.g.{{ "hello" | slice: -3, 3 }} #=> llo
minus
- subtraction e.g.{{ 4 | minus:2 }} #=> 2
plus
- addition e.g.{{ '1' | plus:'1' }} #=> 2
,{{ 1 | plus:1 }} #=> 2
times
- multiplication e.g{{ 5 | times:4 }} #=> 20
divided_by
- integer division e.g.{{ 10 | divided_by:3 }} #=> 3
round
- rounds input to the nearest integer or specified number of decimalssplit
- split a string on a matching pattern e.g.{{ "a~b" | split:"~" }} #=> ['a','b']
modulo
- remainder, e.g.{{ 3 | modulo:2 }} #=> 1
Tags
Tags are used for the logic in your template. New tags are very easy to code, so I hope to get many contributions to the standard tag library after releasing this code.
Here is a list of currently supported tags:
- assign - Assigns some value to a variable
- capture - Block tag that captures text into a variable
- case - Block tag, its the standard case…when block
- comment - Block tag, comments out the text in the block
- cycle - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
- for - For loop
- break - Exits a for loop
- continue Skips the remaining code in the current for loop and continues with the next loop
- if - Standard if/else block
- include - Includes another template; useful for partials
- raw - temporarily disable tag processing to avoid syntax conflicts.
- unless - Mirror of if statement
Comments
Any content that you put between {% comment %}
and {% endcomment %}
tags is turned into a comment.
Raw
Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
If / Else
if / else
should be well-known from any other programming language.
Liquid allows you to write simple expressions in the if
or unless
(and
optionally, elsif
and else
) clause:
Case Statement
If you need more conditions, you can use the case
statement:
Example:
Cycle
Often you have to alternate between different colors or similar tasks. Liquid
has built-in support for such operations, using the cycle
tag.
will result in
one
two
three
one
If no name is supplied for the cycle group, then it’s assumed that multiple calls with the same parameters are one group.
If you want to have total control over cycle groups, you can optionally specify the name of the group. This can even be a variable.
will result in
one
two
one
two
For loops
Liquid allows for
loops over collections:
When iterating a hash, item[0]
contains the key, and item[1]
contains the value:
During every for
loop, the following helper variables are available for extra
styling needs:
There are several attributes you can use to influence which items you receive in your loop
limit:int
lets you restrict how many items you get.
offset:int
lets you start the collection with the nth item.
Reversing the loop
Instead of looping over an existing collection, you can define a range of numbers to loop through. The range can be defined by both literal and variable numbers:
A for loop can take an optional else
clause to display a block of text when there are no items in the collection:
Variable Assignment
You can store data in your own variables, to be used in output or other tags as
desired. The simplest way to create a variable is with the assign
tag, which
has a pretty straightforward syntax:
Another way of doing this would be to assign true / false
values to the
variable:
If you want to combine a number of strings into a single string and save it to
a variable, you can do that with the capture
tag. This tag is a block which
“captures” whatever is rendered inside it, then assigns the captured value to
the given variable instead of rendering it to the screen.
Liquid for programmer
First steps
It’s very simple to get started with Liquid. A Liquid template is rendered in two steps: Parse and Render. For an overview of the Liquid syntax, please read Liquid for Designers.
@template = Liquid::Template.parse("hi {{name}}") # Parses and compiles the template
@template.render( 'name' => 'tobi' ) # Renders the output => "hi tobi"
The parse
step creates a fully compiled template which can be re-used as often
as you like. You can store it in memory or in a cache for faster rendering
later.
All parameters you want Liquid to work with have to be passed as parameters to
the render
method. Liquid does not know about your Ruby local, instance, and
global variables.
Extending Liquid
Extending Liquid is very easy. However, keep in mind that Liquid is a young library and requires some outside help. If you create useful filters and tags, please consider making a pull request with them.
Create your own filters
Creating filters is very easy. Basically, they are just methods which take one
parameter and return a modified string. You can use your own filters by passing
an array of modules to the render call like this: @template.render(assigns,
[MyTextFilters, MyDateFilters])
.
module TextFilter
def textilize(input)
RedCloth.new(input).to_html
end
end
@template = Liquid::Template.parse(" {{ '*hi*' | textilize }} ")
@template.render({}, :filters => [TextFilter]) # => "<strong>hi</strong>"
Alternatively, you can register your filters globally:
module TextFilter
def textilize(input)
RedCloth.new(input).to_html
end
end
Liquid::Template.register_filter(TextFilter)
Once the filter is globally registered, you can simply use it:
@template = Liquid::Template.parse(" {{ '*hi*' | textilize }} ")
@template.render # => "<b>hi</b>"
Create your own tags
To create a new tag, simply inherit from Liquid::Tag
and register your block
with Liquid::Template
.
class Random < Liquid::Tag
def initialize(tag_name, max, tokens)
super
@max = max.to_i
end
def render(context)
rand(@max).to_s
end
end
Liquid::Template.register_tag('random', Random)
@template = Liquid::Template.parse(" {% random 5 %}")
@template.render # => "3"
Create your own tag blocks
All tag blocks are parsed by Liquid. To create a new block, you just have to
inherit from Liquid::Block
and register your block with Liquid::Template
.
class Random < Liquid::Block
def initialize(tag_name, markup, tokens)
super
@rand = markup.to_i
end
def render(context)
value = rand(@rand)
super.sub('^^^', value.to_s) # calling `super` returns the content of the block
end
end
Liquid::Template.register_tag('random', Random)
text = " {% random 5 %} you have drawn number ^^^, lucky you! {% endrandom %} "
@template = Liquid::Template.parse(text)
@template.render # will return "you have drawn number 1, lucky you!" in 20% of cases
Caching of classes
If you get errors like A copy of ... has been removed from the module tree but is still active!
it’s probably because Liquid is caching your classes in development mode, the solution is to disable it in test and development modes:
# in config/environments/development.rb and config/environments/test.rb
Liquid.cache_classes = false