Ascribe

Liquid Tags

Liquid uses tags to hold the logic in a template. There are only a handful of tags to learn in Liquid, covering comments, branching, looping, working with variables, and generating useful HTML markup. Tags are surrounded by {% %} pairs.

Comments

The simplest tag pair is comment and endcomment. Anything you surround with these tags will not appear in the generated markup. You can use this to create comments, including multi-line comments, in Liquid templates. For example:

{% comment %}
This template is used to generate our home page,
including links to recent projects.
{% endcomment %}

This will not generate any output at all - not even an HTML comment.

Branching

Liquid includes if, else, endif, unless, endunless, and case tags to allow branching logic within a template. Use Ruby-style operators to test for equality and inequality: == to check if two things are the same, != to check if two things are different.

To branch with if, use a simple expression within the if tag, and close your expression with an endif. For example, you can add the second line of your company's street address to a page if it actually has content:

{% if company.street2 != blank }
	<span class="address">{{ company.street2 }}</span>
{% endif %}

To include alternative markup, you can use the else tag. For example, this snippet will deliver different markup depending on whether or not a project's location has been entered into Ascribe:

{% if project.location_determined? %}
	{{ project.city }}, {{project.state}}
{% else %}
   Location not yet determined
{% endif %}

Note that there is no "elsif" tag in Liquid; for more complex logic you'll need to use nested if tags, or a case tag.

Sometimes you may find that your template is more readable if you use unless, which is the logical inverse of if. Markup within an unless ... endunless block will only be output if the supplied condition evaluates to false:

{% unless company.street2 == blank }
	<span class="address">{{ company.street2 }}</span>
{% endunless %}

To check multiple conditions on the same variable, you can use the case, when, and endcase tags:

{% case project.role %} 
{% when 'Developer' %}
	We are the developers of this project.
{% when 'Engineering' %}
    We are providing engineering services to this project.
{% else %}
    We are proud to be a part of this project.
{% end %}

Looping

Liquid supplies for and endfor to loop over collections:

{% for project in projects %}
	<li>{{ forloop.index }}. {{ project.title }}</li>
{% endfor %}

This will generate markup listing all of your projects, similar to this:

<li>1. New Office Building</li>
<li>2. Shopping Center Remodel</li>
<li>3. Site Survey - Grand Road</li>
<li>4. Plant Addition</li>

Note the use of the special forloop helper variable, which is available whenever you are in a for loop. It makes 7 properties available:

forloop.length
the number of items in the entire collection
forloop.index
the 1-based location of the current item in the collection
forloop.index0
the 0-based location of the current item in the collection
forloop.rindex
the 1-based distance of the current item from the end of the collection
forloop.rindex0
the 0-based distance of the current item from the end of the collection
forloop.first
returns true if this is the first item in the collection
forloop.last
returns true if this is the last item in the collection

If you want to work with only part of a collection, you can use the limit and offset modifiers within the for tag. For example, to display just the 4th through 6th projects (assuming the collection has at least six projects in it) you could use this code:

{% for project in projects limit:3 offset:3 %}
	<li>{{ project.title }}</li>
{% endfor %}

Note that offset is 0-based.

Working with Variables

The assign and capture tags are useful for creating your own variables within a template.

The assign tag lets you give a name to the result of an expression, so that you can refer to it by name later in the template. For example:

{% assign: mail = company.email %}

The assign tag itself produces no output, but after running this line of code you can insert the company's email address anywhere in the template by using the new variable name:

{{ mailtag }}

To encapsulate an entire section of output for later re-use, use the capture and endcapture tags. For example, this markup will save the entire list of projects in a variable:

{% capture project_list %}
	{% for project in projects %}
		<li>{{ forloop.index }}. {{ project.title }}</li>
    {% endfor %}
{% endcapture %}

After executing this code, you can insert the project list anywhere in the template by using the new variable name:

{{ project_list }}

Markup Helpers

The cycle, tablerow, and ifchanged tags can be used to generate common markup patterns in your templates.

The cycle tag lets you cycle through different types of output. For example, consider this code:

<ul>
	{% for project in projects %}
		<li style="background-color: {% cycle '#fbeec3', '#fdf6e2' %};" >
			{{ forloop.index }}. {{ project.title }}
		</li>
	{% endfor %}
</ul>

The effect of this code is to alternately color rows of the output list, as shown here:

Cycle

If you need to have multiple cycles on a single web page, you can name them:

{% cycle 'project background': #fbeec3', '#fdf6e2' %}
{% cycle 'photo background': #fbeec3', '#fdf6e2' %}

This will make the two different cycles track their position independently.

The tablerow tag acts like a for tag, except that it outputs its contents as cells within a table row. You still need to supply the outer <table> tags for the table:

<table>
	{% tablerow project in projects %}
		{{ project.title }}
	{% endtablerow %}
</table>

This results in the following markup:

<table>
	<tr class="row1">
		<td class="col1">
			New Office Building
		</td>
		<td class="col2">
			Shopping Center Remodel
		</td>
		<td class="col3">
			Site Survey - Grand Road
		</td>
		<td class="col4">
			Plant Addition
		</td>
	</tr>
</table>

Finally, the ifchanged tag outputs its contents only if the last call to ifchanged rendered different output. This is handy for nested lists and similar reporting:

{% for project in projects | sort %}
	{% ifchanged %} 
		<h3> {{ project.title | truncate: 1, "" }}</h3>
	{% endifchanged %}
	<p>{{ project.title }}</p>
{% endfor %}

This will give you a list of projects with alphabetical headings:

Ifchanged