What is Liquid?

Liquid is an open source templating language built by Shopify. They have excellent documentation if you want to go deeper, but we’ve pulled out the important bits you need to know to get the most out of Consent Kit in this article.

We use Liquid in our templates and emails to do two things:

1. Minimise the effort for Researchers creating specific forms for their project
2. Ensure generated forms are inline with what was agreed by the organisation

We primarily use two elements from Liquid: Objects and Tags.

Objects

Objects tell Liquid where to show content. Objects are denoted by double curly braces: {% raw %}{{ object }}{% endraw %}.

For example, if I put this into an Org Template:

“Hello, my name is {% raw %}{{ researcher.name }}{% endraw %}. I work for {% raw %}{{ organisation.name }}{% endraw %}.”

If I generated a form using that template, it would give me:

“Hello, my name is Phil Hesketh. I work for Consent Kit.”

At the point of generating a form to be used in a project, Consent Kit takes a snapshot of your Org Template and populates all of these Objects with information relative to the person who is generating the form.

For a complete list of objects available to you in Consent Kit - checkout our Template cheat sheet.

Tags

Tags are a bit more complicated. They create the logic and control flow for templates and are denoted by curly braces and percent signs.

Any text used inside these tags is not visible when a form is generated. This means that you can assign variables and create conditions and loops without showing any of the Liquid logic on the page.

Conditional tags

Conditional tags are handy when you want to check that something is true or not before populating part of your consent form with content.

Let’s look at an example that will display content only if a condition is true.

{% highlight liquid %} {% raw %} {% if researcher.email %} {{ researcher.email }} {%- else -%} [ enter researcher email address here ] {%- endif -%} {% endraw %} {% endhighlight %}

{% raw %}{% if researcher.email %}{% endraw %} is a shorthand to say: “If researcher.email equals true” (ie: If the researcher who has generated this consent form has an email address in Consent Kit) “Then include this next bit of text in the form”.

If they do have an email address in the system, it uses an Object to populate that information when the form is generated. If they don’t, it will insert the placeholder text from the {% raw %}{%- else -%}{% endraw %} to instruct the researcher to enter their email address manually.

Finally, the conditional tag must be closed with {% raw %}{%- endif -%}{% endraw %}.

Case Tags

Case tags are useful when you want to populate content, but you have more than one possible outcome (eg: not just true or false).

We use case tags to populate parts of the form which change depending on the type of research being done. For example:

{% raw %}
{%- case event.category -%}
  {%- when "interview" -%}
    This text will only appear for an interview.
  {%- when "workshop" -%}
    This text will only appear for a workshop.
  {%- when "usability_testing" -%}
    This text will only appear for a usability test.
  {%- else -%}
    This text will appear if no event category is selected.
{% endcase %}
{% endraw %}

This is essentially a chain of conditions. It starts with a “case” or thing to look at (in this case, a study). Then it asks questions of that case until it finds one that is true. When it finds one that is true, it populates the generated form with the content from that section.

Let’s break this down.

{% raw %}
{%- case event.category -%}
{% endraw %}

Is saying: “If there is a study associated with this form, then…”

{% raw %}{%- when "interview" -%}{% endraw %} means: “If that event is an interview - then display the text from this part only.” ie: “This text will only appear if the form is being used for an interview.”

If there is a study and it is not an interview, it will ignore whatever text is in the interview bit and move onto the next statement: {% raw %}{%- when "workshop" -%}{% endraw %}.

You might have noticed that the last statement before the endcase just says {% raw %}{% else %}{% endraw %}. This is a catch all to say “if none of these things are true, then display this instead.” This will always be true, so it should only be just before the endcase.

Liquid will search through as many statements as you want to include until it reaches the first one that is true or it gets to the {% raw %}{% endcase %}{% endraw %}.

For a complete list of tags available to you in Consent Kit - checkout our Template cheat sheet.

Controlling whitespace

You might have noticed that some of the tags we use are formatted like this: {% raw %}{% case event.category %}{% endraw %} while others are like this {% raw %}{%- case event.category -%}{% endraw %}.

The hyphens within the tag tell Liquid to remove any whitespace from around the content when it is generated. Without this, your text would break onto a new line at the point of including the tag and then resume on another new line after it.

If you find that that is happening to you - check your tags for hyphens!