Template syntax basics

Basics

There are two types of markup in liquid: Output and Tag.
Output is surrounded by {{ two curly brackets }}

Tags are surrounded by {% a curly bracket and a percent %}

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 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' }}

Acceptable tags and Comments

We sanitize all templates, so that you may not use javascript or tags that might be harmful to the application. Disallowed tags include, but aren't limited to:

  • HEAD
  • BODY
  • SCRIPT

Comments

HTML comments are automatically sanitized by our system. If you wish to place comments in your code, do it with a liquid comment, like so:

{{ # This is a comment in liquid, and won't show up on the 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


Cashboard specific Filters

format_date Formats a date in your account's selected date format.
(Set from the admin prefs.)
format_date_in_english Transforms a date into English of when that event happened.
(Ex 1 day ago, 2 months from now)
format_money Transforms money string into your home currency, and possibly your client's home currency if you've selected one for them.
format_number Allows specifying precision of numbers output to screen. The number passed in is the number of decimal places to print.
Ex: {{ item.quantity_estimate | format_number: 0 }}
format_text Transforms text using Markdown syntax. Automatically inserts HTML tags like P, BR, etc.
image_path Returns the proper image path for your file. Useful if you want to use it in a CSS document, or perhaps create your own image tags.
image_tag Creates an IMG tag for a file you've uploaded to the Cashboard server for use inside your document.
Ex: {{ 'image_name.jpg | image_tag }}
make_label Makes an input label, or heading for a table.
number_to_percentage Formats number as a percentage.
number_to_phone Formats as a phone number.
number_with_delimiter Shows a number with delimiter you specify.
Ex: {{ invoice.sales_tax | number_with_delimiter: ',' }}
plus_month Adds a number of months to a date
Ex: {{ invoice.due_date | plus_month: 1 }}
minus_month Subtracts a number of months to a date
Ex: {{ invoice.due_date | minus_month: 2 }}


Date filter reference

%a Abbreviated weekday ("Sun").
%A Full weekday name ("Sunday").
%b The abbreviated month name ("Jan").
%B The full month name ("January").
%c The preferred local date and time representation.
%d Date of the month (01.31).
%H Hour of the day, 24-hour clock (00.23).
%I Hour of the day, 12-hour clock (1:12).
%j Day of the year (001.366).
%K Hour of the day, 24-hour clock (1:12).
%m Month of the year (01.12).
%M Minute of the hour (00.59).
%p Meridian indicator (AM/PM).
%S Second of the minute (00.60).
%U The number of the week in the current year, starting with the first Sunday as the first day of the first week.
%W The number of the week in the current year, starting with the first Monday as the first day of the first week.
%w Day of the week (Sunday is 0, so 0...6).
%x Preferred representation for the date alone, no time.
%X Preferred representation for the time alone, no date.
%y Year without a century (00.99).
%Y Year with a century.
%Z Time zone name.
%% Literal % character.


Tags

Tags are for the 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 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 and assigns it to the given variable instead of rendering it to the screen. Here's how it works:

{% capture attribute_name %}{{ item.title }}-{{ i }}-color{% endcapture %}

<label for="{{ attribute_name }}">Color:</label>
<select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}">
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

If / Else

If else should be well known from any language imaginable. Liquid allows you to write simple expressions in the if.

{% if person %}
  Hi {{ person.name }}
{% endif %}

{% if person.name == 'seth' %}
  hi seth
{% endif %}

{% if person.name != 'seth' %} 
  you aren't seth
{% endif %}

{% if company.address == null %}
   no address on file
{% endif %}

{% if invoice.line_items == empty %}
   no items have been added to this invoice
{% endif %}

{% if invoice.total_due > 0 %}
   you still need to pay this invoice
{% else %}
   thanks for paying this invoice
{% endif %}

Case Statement

If you need more than one condition you can use the Case Statement

{% case line_item.quantity %}
  {% when 0 %}
    none
  {% when 1 %}
    one
  {% when 2 %}
    two
  {% else %}
    a few more...
{% endcase %}

Cycle

Often you have to alternate between different colors for similar tasks. Liquid has build in support for such operations using the cycle tag.

{% cycle 'one', 'two', 'three' %} 
{% cycle 'one', 'two', 'three' %} 
{% cycle 'one', 'two', 'three' %} 
{% cycle 'one', 'two', 'three' %}

...Will result in...

one
two
three
one

If no name is supplied for the cycle group then its 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.

{% cycle 'group 1': 'one', 'two', 'three' %} 
{% cycle 'group 1': 'one', 'two', 'three' %} 
{% cycle 'group 2': 'one', 'two', 'three' %} 
{% cycle 'group 2': 'one', 'two', 'three' %}

...Will result in...

one
two 
one
two

For Loops

Liquid allows for loops over collections. This is great in Cashboard to loop over things like the line items in an invoice.

{% for item in invoice.line_items %} 
  {{ 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

Includes

There are a few default liquid templates defined in Cashboard, but the system allows you to create as many as you want.

This is so you may take advantage of liquid includes. You can include any of these templates inside another template, like so.

{% include 'template_name' %}

This comes in handy if you wish to share layout, css information, or html between templates. One default template in particular is company information.

By default, this stores the company address output table for invoices and estimates. We re-use the html here, by passing it what company we wish to display information for:

{% include 'company' for account.company %}

Inside the company template, you can then access variables from account.company as the template name (company)

{{ company.name }}
{{ company.address }}

Tables

Liquid can also create table rows and cells for you. (you still need to wrap a table tag around the tablerow instruction)

<table>
  {% tablerow item in items cols: 3 limit: 12 %}
    {{ item.variable }}
  {% endtablerow %}
</table>

You can also find out whether a table cell is the first or last column in a row or directly query the column number:

tablerowloop.length     # => length of the entire for loop
tablerowloop.index      # => index of the current iteration 
tablerowloop.index0     # => index of the current iteration (zero based) 
tablerowloop.rindex     # => how many items are still left?
tablerowloop.rindex0    # => how many items are still left? (zero based)
tablerowloop.first      # => is this the first iteration?
tablerowloop.last       # => is this the last iteration? 
tablerowloop.col        # => index of column in the current row
tablerowloop.col0       # => index of column in the current row (zero based)
tablerowloop.col_first  # => is this the first column in the row?
tablerowloop.col_last   # => is this the last column in the row?

{% tablerow item in items cols: 3 %}
  {% if col_first %}
    First column: {{ item.variable }}
  {% else %}
    Different column: {{ item.variable }}
  {% endif %}
{% endtablerow %}

Recent Discussions

14 Jun, 2024 06:35 PM
27 May, 2024 10:46 PM
23 May, 2024 05:08 PM
20 Feb, 2024 06:55 PM
16 Jan, 2024 03:09 PM