The Liquid markup language is an open-source template language created by Shopify and written in Ruby. In the context of our plugins, it is used to create templates for custom invoices or issue reports.
Basics
There are two types of markup in liquid: Output and Tag.
Output:- Output is surrounded by
{{ two curly brackets }} - Output blocks will always be replaced with the data which they reference.
- For instance, if your liquid template has a company object exposed to it, you can print the name of the company to the screen by referencing
{{ company.name }}
- Tags are surrounded by
{% a curly bracket and a percent %} - Tags drive the logic of templates. They are responsible for loops and branching logic such as If / Else.
Output
Here is a simple example of Output:
Hello {{name}}
Hello {{person.name}}
Hello {{ 'seth' }}
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.
Hello {{ 'seth' | upcase }}
Hello seth has {{ 'seth' | length }} letters!
Hello {{ '*seth*' | format_text | upcase }}
Hello {{ 'now' | format_date }}
Standard Liquid Filters
| date | reformat a date (syntax reference) |
|---|---|
| capitalize | capitalize words in the input sentence |
| downcase | convert an input string to lowercase |
| upcase | convert a input string to uppercase |
| first | get the first 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 |
| sort | sort elements of the array |
| size | return the size of an array or string |
| strip_html | strip html from string |
| strip_newlines | strip all newlines (\n) from string |
| newline_to_br | replace each newline (\n) with html break |
| replace | replace each occurrence Ex: {{ foofoo | replace:foo, bar }} #=> barbar |
| replace_first | replace the first occurrence Ex: {{ barbar | replace_first:bar,foo }} #=> foobar |
| remove | remove each occurrence Ex: {{ foobarfoobar | remove:foo }} #=> barbar |
| remove_first | remove the first occurrence Ex: {{ barbar | remove_first:bar }} #=> bar |
| truncate | truncate a string down to x characters |
| truncatewords | truncate a string down to x words |
| prepend | prepend a string Ex: {{ bar | prepend:foo }} #=> foobar |
| append | append a string Ex: {{ foo | append:bar }} #=> foobar |
| minus | subtraction e.g {{ 4 | minus:2 }} #=> 2 |
| plus | addition e.g {{ 1 | plus:1 }} #=> 11
{{ 1 | plus:1 }} #=> 2 |
| times | multiplication e.g {{ foo | times:4 }} #=> foofoofoofoo
{{ 5 | times:4 }} #=> 20 |
| divided_by | division e.g {{ 10 | divided_by:2 }} #=> 5 |
RedmineCRM specific filters
| underscore | replace spaces and slashes to '_' |
|---|---|
| dasherize | replace spaces and slashes to '-' |
| multi_line | replace end of line in text to |
| rjust | right justify and padd a string |
| ljust | left justify and padd a string |
| textile | textiliaze a string |
| currency | formats number as a currency Ex: {{ 100 | currency: USD }} #=> $100.00 |
| custom_field | return object custom field value Ex: {{ invoice | custom_field: "Test custom field" }}
#=> <Test custom field value> To use a custom field value inside a logical construct(if/else, loop), assign its value to a variable first: {% assign value = invoice | custom_field: "Test custom field"%}
{% if value == ... |
| attachment | return disk file name of object attachment Ex: {{ invoice | attachment: "test.jpg" }}
#=> /var/www/redmine/files/12314234_test.jpg |
Tags
Tags are how you can include logic in your template. Below are the tags available to you inside Cashboard.
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:
{% if value == ... |
|_<. attachment | return disk file name of object attachment Ex: {{ invoice | attachment: "test.jpg" }}
#=> /var/www/redmine/files/12314234_test.jpg |
Tags
Tags are how you can include logic in your template. Below are the tags available to you inside Cashboard.
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:
{% assign name = 'freestyle' %}
{% for t in collections.tags %}
{% if t == name %}
<p>Freestyle!</p>
{% endif %}
{% endfor %}
Another way of doing this would be to assign true/false values to the variable:
{% assign freestyle = false %}
{% for t in collections.tags %}{% if t == 'freestyle' %}
{% assign freestyle = true %}
{% endif %}{% endfor %}
{% if freestyle %}
<p>Freestyle!</p>
{% endif %}
If / Else
If else should be well known from any language imaginable. Liquid allows you to write simple expressions in the if.
{% if invoice.contact %}
Hi {{ invoice.contact.name }}
{% endif %}
{% if invoice.contact.name == 'seth' %}
hi seth
{% endif %}
{% if invoice.contact.name != 'seth' %}
you aren't seth
{% endif %}
{% if invoice.contact.address == null %}
no address on file
{% endif %}
{% if invoice.lines == empty %}
no items have been added to this invoice
{% endif %}
{% if invoice.total > 0 %}
you still need to pay this invoice
{% else %}
thanks for paying this invoice
{% endif %}
For Loops
Liquid allows for loops over collections. This is great in the Invoices plugin to loop over things like the line items in an invoice.
{% for item in invoice.lines %}
{{ item.description }}
{% endfor %}
During every for loop there are following helper variables available for extra styling needs:
forloop.length # => length of the entire for loop forloop.index # => index of the current iteration forloop.index0 # => index of the current iteration (zero based) forloop.rindex # => how many items are still left? forloop.rindex0 # => how many items are still left? (zero based) forloop.first # => is this the first iteration? forloop.last # => is this the last iteration?
There are several attributes you can use to influence which items you receive in your loop. limit lets you restrict how many items you get offset lets you start the collection with the nth item.
# array = [1,2,3,4,5,6]
{% for item in array limit:2 offset:2 %}
{{ item }}
{% endfor %}
# results in 3,4
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:
# if item.quantity is 4...
{% for i in (1..item.quantity) %}
{{ i }}
{% endfor %}
# results in 1,2,3,4