Labyricorn/liquid
1
0
Fork 0
mirror of https://github.com/Shopify/liquid.git synced 2026-09-29 07:05:12 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated date syntax reference link.

zumwalt
2014-09-08 09:46:35 -07:00
parent 4a8375dee3
commit 35576edbf2
1 changed files with 373 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Liquid-for-Designers.md → Liquid for Designers.md
+373 -373
@@ -1,374 +1,374 @@
There are two types of markup in Liquid: Output and Tag. There are two types of markup in Liquid: Output and Tag.
* Output markup (which may resolve to text) is surrounded by * Output markup (which may resolve to text) is surrounded by
```liquid ```liquid
{{ matched pairs of curly brackets (ie, braces) }} {{ matched pairs of curly brackets (ie, braces) }}
``` ```
* Tag markup (which cannot resolve to text) is surrounded by * Tag markup (which cannot resolve to text) is surrounded by
```liquid ```liquid
{% matched pairs of curly brackets and percent signs %} {% matched pairs of curly brackets and percent signs %}
``` ```
## Output ## Output
Here is a simple example of Output: Here is a simple example of Output:
```liquid ```liquid
Hello {{name}} Hello {{name}}
Hello {{user.name}} Hello {{user.name}}
Hello {{ 'tobi' }} Hello {{ 'tobi' }}
``` ```
<a name="filters"></a> <a name="filters"></a>
### Advanced output: Filters ### Advanced output: Filters
Output markup takes filters. Filters are simple methods. The first parameter 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 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 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. no more filters, the template will receive the resulting string.
```liquid ```liquid
Hello {{ 'tobi' | upcase }} Hello {{ 'tobi' | upcase }}
Hello tobi has {{ 'tobi' | size }} letters! Hello tobi has {{ 'tobi' | size }} letters!
Hello {{ '*tobi*' | textilize | upcase }} Hello {{ '*tobi*' | textilize | upcase }}
Hello {{ 'now' | date: "%Y %h" }} Hello {{ 'now' | date: "%Y %h" }}
``` ```
### Standard Filters ### Standard Filters
* `date` - reformat a date ([syntax reference](http://docs.shopify.com/themes/liquid-basics/output#date)) * `date` - reformat a date ([syntax reference](http://docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date))
* `capitalize` - capitalize words in the input sentence * `capitalize` - capitalize words in the input sentence
* `downcase` - convert an input string to lowercase * `downcase` - convert an input string to lowercase
* `upcase` - convert an input string to uppercase * `upcase` - convert an input string to uppercase
* `first` - get the first element of the passed in array * `first` - get the first element of the passed in array
* `last` - get the last element of the passed in array * `last` - get the last element of the passed in array
* `join` - join elements of the array with certain character between them * `join` - join elements of the array with certain character between them
* `sort` - sort elements of the array * `sort` - sort elements of the array
* `map` - map/collect an array on a given property * `map` - map/collect an array on a given property
* `size` - return the size of an array or string * `size` - return the size of an array or string
* `escape` - escape a string * `escape` - escape a string
* `escape_once` - returns an escaped version of html without affecting existing escaped entities * `escape_once` - returns an escaped version of html without affecting existing escaped entities
* `strip_html` - strip html from string * `strip_html` - strip html from string
* `strip_newlines` - strip all newlines (\n) from string * `strip_newlines` - strip all newlines (\n) from string
* `newline_to_br` - replace each newline (\n) with html break * `newline_to_br` - replace each newline (\n) with html break
* `replace` - replace each occurrence *e.g.* `{{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'` * `replace` - replace each occurrence *e.g.* `{{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'`
* `replace_first` - replace the first occurrence *e.g.* `{{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'` * `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` - remove each occurrence *e.g.* `{{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'`
* `remove_first` - remove the first occurrence *e.g.* `{{ 'barbar' | remove_first:'bar' }} #=> 'bar'` * `remove_first` - remove the first occurrence *e.g.* `{{ 'barbar' | remove_first:'bar' }} #=> 'bar'`
* `truncate` - truncate a string down to x characters * `truncate` - truncate a string down to x characters
* `truncatewords` - truncate a string down to x words * `truncatewords` - truncate a string down to x words
* `prepend` - prepend a string *e.g.* `{{ 'bar' | prepend:'foo' }} #=> 'foobar'` * `prepend` - prepend a string *e.g.* `{{ 'bar' | prepend:'foo' }} #=> 'foobar'`
* `append` - append a string *e.g.* `{{ 'foo' | append:'bar' }} #=> 'foobar'` * `append` - append a string *e.g.* `{{ 'foo' | append:'bar' }} #=> 'foobar'`
* `minus` - subtraction *e.g.* `{{ 4 | minus:2 }} #=> 2` * `minus` - subtraction *e.g.* `{{ 4 | minus:2 }} #=> 2`
* `plus` - addition *e.g.* `{{ '1' | plus:'1' }} #=> '11'`, `{{ 1 | plus:1 }} #=> 2` * `plus` - addition *e.g.* `{{ '1' | plus:'1' }} #=> '11'`, `{{ 1 | plus:1 }} #=> 2`
* `times` - multiplication *e.g* `{{ 5 | times:4 }} #=> 20` * `times` - multiplication *e.g* `{{ 5 | times:4 }} #=> 20`
* `divided_by` - division *e.g.* `{{ 10 | divided_by:2 }} #=> 5` * `divided_by` - division *e.g.* `{{ 10 | divided_by:2 }} #=> 5`
* `split` - split a string on a matching pattern *e.g.* `{{ "a~b" | split:"~" }} #=> ['a','b']` * `split` - split a string on a matching pattern *e.g.* `{{ "a~b" | split:"~" }} #=> ['a','b']`
* `modulo` - remainder, *e.g.* `{{ 3 | modulo:2 }} #=> 1` * `modulo` - remainder, *e.g.* `{{ 3 | modulo:2 }} #=> 1`
## Tags ## Tags
Tags are used for the logic in your template. New tags are very easy to code, 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 so I hope to get many contributions to the standard tag library after releasing
this code. this code.
Here is a list of currently supported tags: Here is a list of currently supported tags:
* **assign** - Assigns some value to a variable * **assign** - Assigns some value to a variable
* **capture** - Block tag that captures text into a variable * **capture** - Block tag that captures text into a variable
* **case** - Block tag, its the standard case...when block * **case** - Block tag, its the standard case...when block
* **comment** - Block tag, comments out the text in the 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. * **cycle** - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
* **for** - For loop * **for** - For loop
* **if** - Standard if/else block * **if** - Standard if/else block
* **include** - Includes another template; useful for partials * **include** - Includes another template; useful for partials
* **raw** - temporarily disable tag processing to avoid syntax conflicts. * **raw** - temporarily disable tag processing to avoid syntax conflicts.
* **unless** - Mirror of if statement * **unless** - Mirror of if statement
### Comments ### Comments
Comment is the simplest tag. It just swallows content. Comment is the simplest tag. It just swallows content.
```liquid ```liquid
We made 1 million dollars {% comment %} in losses {% endcomment %} this year We made 1 million dollars {% comment %} in losses {% endcomment %} this year
``` ```
### Raw ### Raw
Raw temporarily disables tag processing. Raw temporarily disables tag processing.
This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
```liquid ```liquid
{% raw %} {% raw %}
In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not. In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
{% endraw %} {% endraw %}
``` ```
### If / Else ### If / Else
`if / else` should be well-known from any other programming language. `if / else` should be well-known from any other programming language.
Liquid allows you to write simple expressions in the `if` or `unless` (and Liquid allows you to write simple expressions in the `if` or `unless` (and
optionally, `elsif` and `else`) clause: optionally, `elsif` and `else`) clause:
```liquid ```liquid
{% if user %} {% if user %}
Hello {{ user.name }} Hello {{ user.name }}
{% endif %} {% endif %}
``` ```
``` ```
# Same as above # Same as above
{% if user != null %} {% if user != null %}
Hello {{ user.name }} Hello {{ user.name }}
{% endif %} {% endif %}
``` ```
```liquid ```liquid
{% if user.name == 'tobi' %} {% if user.name == 'tobi' %}
Hello tobi Hello tobi
{% elsif user.name == 'bob' %} {% elsif user.name == 'bob' %}
Hello bob Hello bob
{% endif %} {% endif %}
``` ```
```liquid ```liquid
{% if user.name == 'tobi' or user.name == 'bob' %} {% if user.name == 'tobi' or user.name == 'bob' %}
Hello tobi or bob Hello tobi or bob
{% endif %} {% endif %}
``` ```
```liquid ```liquid
{% if user.name == 'bob' and user.age > 45 %} {% if user.name == 'bob' and user.age > 45 %}
Hello old bob Hello old bob
{% endif %} {% endif %}
``` ```
```liquid ```liquid
{% if user.name != 'tobi' %} {% if user.name != 'tobi' %}
Hello non-tobi Hello non-tobi
{% endif %} {% endif %}
``` ```
```liquid ```liquid
# Same as above # Same as above
{% unless user.name == 'tobi' %} {% unless user.name == 'tobi' %}
Hello non-tobi Hello non-tobi
{% endunless %} {% endunless %}
``` ```
```liquid ```liquid
# Check for the size of an array # Check for the size of an array
{% if user.payments == empty %} {% if user.payments == empty %}
you never paid ! you never paid !
{% endif %} {% endif %}
{% if user.payments.size > 0 %} {% if user.payments.size > 0 %}
you paid ! you paid !
{% endif %} {% endif %}
``` ```
```liquid ```liquid
{% if user.age > 18 %} {% if user.age > 18 %}
Login here Login here
{% else %} {% else %}
Sorry, you are too young Sorry, you are too young
{% endif %} {% endif %}
``` ```
```liquid ```liquid
# array = 1,2,3 # array = 1,2,3
{% if array contains 2 %} {% if array contains 2 %}
array includes 2 array includes 2
{% endif %} {% endif %}
``` ```
```liquid ```liquid
# string = 'hello world' # string = 'hello world'
{% if string contains 'hello' %} {% if string contains 'hello' %}
string includes 'hello' string includes 'hello'
{% endif %} {% endif %}
``` ```
### Case Statement ### Case Statement
If you need more conditions, you can use the `case` statement: If you need more conditions, you can use the `case` statement:
```liquid ```liquid
{% case condition %} {% case condition %}
{% when 1 %} {% when 1 %}
hit 1 hit 1
{% when 2 or 3 %} {% when 2 or 3 %}
hit 2 or 3 hit 2 or 3
{% else %} {% else %}
... else ... ... else ...
{% endcase %} {% endcase %}
``` ```
*Example:* *Example:*
```liquid ```liquid
{% case template %} {% case template %}
{% when 'label' %} {% when 'label' %}
// {{ label.title }} // {{ label.title }}
{% when 'product' %} {% when 'product' %}
// {{ product.vendor | link_to_vendor }} / {{ product.title }} // {{ product.vendor | link_to_vendor }} / {{ product.title }}
{% else %} {% else %}
// {{page_title}} // {{page_title}}
{% endcase %} {% endcase %}
``` ```
### Cycle ### Cycle
Often you have to alternate between different colors or similar tasks. Liquid Often you have to alternate between different colors or similar tasks. Liquid
has built-in support for such operations, using the `cycle` tag. has built-in support for such operations, using the `cycle` tag.
```liquid ```liquid
{% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %}
``` ```
will result in will result in
``` ```
one one
two two
three three
one one
``` ```
If no name is supplied for the cycle group, then it's assumed that multiple If no name is supplied for the cycle group, then it's assumed that multiple
calls with the same parameters are one group. calls with the same parameters are one group.
If you want to have total control over cycle groups, you can optionally specify 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. the name of the group. This can even be a variable.
```liquid ```liquid
{% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %}
``` ```
will result in will result in
``` ```
one one
two two
one one
two two
``` ```
### For loops ### For loops
Liquid allows `for` loops over collections: Liquid allows `for` loops over collections:
```liquid ```liquid
{% for item in array %} {% for item in array %}
{{ item }} {{ item }}
{% endfor %} {% endfor %}
``` ```
When iterating a hash, `item[0]` contains the key, and `item[1]` contains the value: When iterating a hash, `item[0]` contains the key, and `item[1]` contains the value:
```liquid ```liquid
{% for item in hash %} {% for item in hash %}
{{ item[0] }}: {{ item[1] }} {{ item[0] }}: {{ item[1] }}
{% endfor %} {% endfor %}
``` ```
During every `for` loop, the following helper variables are available for extra During every `for` loop, the following helper variables are available for extra
styling needs: styling needs:
```liquid ```liquid
forloop.length # => length of the entire for loop forloop.length # => length of the entire for loop
forloop.index # => index of the current iteration forloop.index # => index of the current iteration
forloop.index0 # => index of the current iteration (zero based) forloop.index0 # => index of the current iteration (zero based)
forloop.rindex # => how many items are still left? forloop.rindex # => how many items are still left?
forloop.rindex0 # => how many items are still left? (zero based) forloop.rindex0 # => how many items are still left? (zero based)
forloop.first # => is this the first iteration? forloop.first # => is this the first iteration?
forloop.last # => is this the last iteration? forloop.last # => is this the last iteration?
``` ```
There are several attributes you can use to influence which items you receive in There are several attributes you can use to influence which items you receive in
your loop your loop
`limit:int` lets you restrict how many items you get. `limit:int` lets you restrict how many items you get.
`offset:int` lets you start the collection with the nth item. `offset:int` lets you start the collection with the nth item.
```liquid ```liquid
# array = [1,2,3,4,5,6] # array = [1,2,3,4,5,6]
{% for item in array limit:2 offset:2 %} {% for item in array limit:2 offset:2 %}
{{ item }} {{ item }}
{% endfor %} {% endfor %}
# results in 3,4 # results in 3,4
``` ```
Reversing the loop Reversing the loop
```liquid ```liquid
{% for item in collection reversed %} {{item}} {% endfor %} {% for item in collection reversed %} {{item}} {% endfor %}
``` ```
Instead of looping over an existing collection, you can define a range of 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 to loop through. The range can be defined by both literal and variable
numbers: numbers:
```liquid ```liquid
# if item.quantity is 4... # if item.quantity is 4...
{% for i in (1..item.quantity) %} {% for i in (1..item.quantity) %}
{{ i }} {{ i }}
{% endfor %} {% endfor %}
# results in 1,2,3,4 # results in 1,2,3,4
``` ```
### Variable Assignment ### Variable Assignment
You can store data in your own variables, to be used in output or other tags as 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 desired. The simplest way to create a variable is with the `assign` tag, which
has a pretty straightforward syntax: has a pretty straightforward syntax:
```liquid ```liquid
{% assign name = 'freestyle' %} {% assign name = 'freestyle' %}
{% for t in collections.tags %}{% if t == name %} {% for t in collections.tags %}{% if t == name %}
<p>Freestyle!</p> <p>Freestyle!</p>
{% endif %}{% endfor %} {% endif %}{% endfor %}
``` ```
Another way of doing this would be to assign `true / false` values to the Another way of doing this would be to assign `true / false` values to the
variable: variable:
```liquid ```liquid
{% assign freestyle = false %} {% assign freestyle = false %}
{% for t in collections.tags %}{% if t == 'freestyle' %} {% for t in collections.tags %}{% if t == 'freestyle' %}
{% assign freestyle = true %} {% assign freestyle = true %}
{% endif %}{% endfor %} {% endif %}{% endfor %}
{% if freestyle %} {% if freestyle %}
<p>Freestyle!</p> <p>Freestyle!</p>
{% endif %} {% endif %}
``` ```
If you want to combine a number of strings into a single string and save it to 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 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 "captures" whatever is rendered inside it, then assigns the captured value to
the given variable instead of rendering it to the screen. the given variable instead of rendering it to the screen.
```liquid ```liquid
{% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %} {% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
<label for="{{ attribute_name }}">Color:</label> <label for="{{ attribute_name }}">Color:</label>
<select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}"> <select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}">
<option value="red">Red</option> <option value="red">Red</option>
<option value="green">Green</option> <option value="green">Green</option>
<option value="blue">Blue</option> <option value="blue">Blue</option>
</select> </select>
``` ```