How to use Liquid with NationBuilder
NationBuilder uses the open source liquid template language to access objects and variables. Liquid allows our customers complete design freedom while maintaining the integrity of our servers. There are two basic types of markup in liquid: Output and Tags.
Table of Contents
- Logic Tags
- Comparison & Logic Operators
- Output Tags
- Object Reference Guide
- Filters
- More Liquid & Template Examples
Tags are surrounded by {% a curly bracket and a percent %} and drive the logic of templates. They are responsible for loops and branching logic.
Logic Tags
Liquid logic tags use comparison and logic operators to test for true or false. Comparison operators are used to determine equality or difference between variables or values, while logical operators are used to determine the logic between them .
Comparison & Logic Operators
Equal
{% if page.slug == "blog" %}{% include "banner" %}{% endif %}
This conditional statement checks to see if the page slug equals blog. If it is true, it will display the include "banner."
Not Equal
{% if page.slug != "blog" %}{% include "blog-ad" %}{% endif %}
This conditional statement checks to see if the page slug is not blog. If it is not, it will display the include "blog-ad."
Bigger Than
{% if page.headline.size > 0 %}
<div id="headline"><h2>{{ page.headline }}</h2></div>
{% endif %}
This conditional statement checks to see if the page headline is bigger than 0 characters. If it is true, it will display it.
Less Than
{% if page.donations_count < 1 %}
JUST STARTED
{% else %}
{{ page.donations_amount_format }} raised
{% endif %}
This conditional statement checks to see if the page has less than 1 donation. For everything else, it will display the words "JUST STARTED." If it has more, it will display the amount raised.
Bigger or Equal
{% if page.petition.signatures_with_images.size >= 4 %}
<div class="padtop">
{% for signature in page.petition.signatures_with_images %}
<img src="{{ signature.large_square_image_url }}" border="0" width="140" height="140">
{% endfor %}
</div>
{% endif %}
This conditional statement checks to see if the page has petition signatures with images. If it is true, it will display petition images in a forloop.
Less or Equal
{% if event.event.rsvps_count <= 1 %}
{{ event.event.rsvps_count }} rsvp{% if event.event.rsvps_count > 1 %}s{% endif %}
{% endif %}
These conditional statements check to see if there are 1 or less than 1 RSVPs to an event. If true, it will display "rsvp" and if there are more than 1, it will display "rsvps".
Or
{% if page.slug == 'europe_signup' or page.slug == 'asia_signup' or page.slug == 'australia_signup' %}
{% include "signup_header" %}
{% else %}
This conditional statement checks to see if the page slug is any of those, if any are true it will display the "signup_header" on those pages.
And
{% if page.petition.is_image? and page.petition.signatures_with_images.size >= 4 %}
<div class="padtop">
{% for signature in page.petition.signatures_with_images %}
<img src="{{ signature.large_square_image_url }}" border="0" width="140" height="140">
{% endfor %}
</div>
{% endif %}
This conditional statement checks to see if the page has signatures with images, and if there are 4 or more. If both are true, it will display petition images in a forloop.
Contains
{% if request.current_signup.tags contains "Regional Organizer" %}
{% include "admin_nav" %}
{% endif %}
This conditional statement checks if a logged-in user is tagged as "Regional Organizer." If that is true, it will display the special admin nav.
Outputs are surrounded by {{ two curly brackets }} and are replaced with the data they reference. You can use these output variables to display dynamic content.
Output Variables and objective reference guide
User & Account Output Variables
|
All of these links go to separate pages.
Page Output Variables
All of these links go to separate pages.
Special Outputs
<script type="text/javascript" src="{{ theme['jquery.fancybox.pack.js'] }}"></ script>
Produces a direct link to the javascript file: jquery.fancybox.pack.js, located under Pages>Theme>Files.
Now
{{ "now" | date: "%A, %B %d, %Y" }} = Monday, December 09, 2024
Use the date filters below to customize the output of the {{ "now" }} drop
Filters
Filters are simple methods used in Output markup, and run from left to right. When there are no more filters, the template will receive the resulting string.
String Filters
Append
{{ page.headline | append: ''}}
Appends an image at the end of the Page Headline output.
{{ page.headline | append: ' by Author'}}
Appends the words 'by Author' to the end of the Page Headline output.
Capitalize
{{ page.headline | capitalize }}
Capitalizes the first words in a page's headline field.
Date
- %a - The abbreviated weekday name ("Sun'')
- %A - The 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 - Day of the month (01..31)
- %H - Hour of the day, 24-hour clock (00..23)
- %I - Hour of the day, 12-hour clock (01..12)
- %j - Day of the year (001..366)
- %m - Month of the year (01..12)
- %M - Minute of the hour (00..59)
- %p - Meridian indicator ("AM'' or "PM'')
- %S - Second of the minute (00..60)
- %U - Week number of the current year, starting with the first Sunday as the first day of the first week (00..53)
- %W - Week number of the current year, starting with the first Monday as the first day of the first week (00..53)
- %w - Day of the week (Sunday is 0, 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 century
- %Z - Time zone name
- %% - Literal "%'' character
{{ event.event.local_start_at | date: '%A, %B %d, %Y at %I:%M %p' }}{% if page.event.is_multi_day? %} through {{ page.event.local_end_at | event_date }}{% endif %}
Will display the date in this format: "Sunday, September 29, 2012 at 6:30pm through October 01, 2012"
Default
{{ '' | default: "Default Text" }} = Default Text
The default value is returned if the variable resolves to nil or an empty string "". A string containing whitespace characters will not resolve to the default value.
Downcase
{{ page.headline | downcase }}
Converts the page headline output into all lowercase letters.
Escape
{{ "test
" | escape }}
HTML tags are not rendered: <p>test</p>
Prepend
{{ page.headline | prepend: ''}}
Adds an image in front of the Page Headline output.
Remove
{{ post.blog_post.content | remove: 'the' }}
Removes all occurrences of 'the' in the output for the blog post content tag.
Remove First
{{ post.blog_post.content | remove_first: 'the' }}
Removes only the first occurrence of 'the' in the output for the blog post content tag.
Replace
{{ "polar bears and polar ice caps" | replace: 'polar', 'brown' }}
The resulting text would be "brown bears and brown ice caps"
Replace_first
{{ "polar bears and polar ice caps" | replace_first: 'polar', 'brown' }}
The resulting text would be: "brown bears and polar ice caps"
Slice
{{ "hello" | slice: 0 }} = h
{{ "hello" | slice: 1 }} = e
{{ "hello" | slice: 1,3 }} = ell
The slice filter returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring of one character will be returned.
Split
{% assign split_pieces = "these-are-words-with-a-split-character" | split: '-' %}
{{ split_pieces[0] }} = these
{{ split_pieces[1] }} = are
{{ split_pieces[2] }} = words
{{ split_pieces[3] }} = with
{{ split_pieces[4] }} = a
{{ split_pieces[5] }} = split
{{ split_pieces[6] }} = character
The split filter takes on a substring as a delimiter to divide a string into an array.
Strip
{{ ' too many spaces ' | strip }} = "too many spaces"
Strips tabs, spaces, and newlines (whitespace) from both the left and right sides of a string.
Left Strip
{{ ' too many spaces ' | lstrip }} = "too many spaces "
Strips tabs, spaces, and newlines (whitespace) from only the left side of a string.
Right Strip
{{ ' too many spaces ' | rstrip }} = " too many spaces"
Strips tabs, spaces, and newlines (whitespace) from only the right side of a string.
Strip HTML
{{ post.blog_post.content | strip_html }}
Removes all html tags from the blog post content.
Truncate Characters
{{ post.headline | truncatechars:10 }}
Limits the amount of characters displayed from the Post Headline to 10.
Truncate Words
{{ post.headline | truncatewords:10 }}
Limits the amount of characters displayed from the Post Headline to 10.
Paginate
{{ page.blog.most_recent_blog_posts | paginate }}
Paginates the most recent blog posts.
Uniq
{% assign duplicateItems = "one one two two three three four four" %}
{{ duplicateItems | split: ' ' | uniq }} = "onetwothreefour"
Removes any duplicate instances of an element in an array.
Upcase
{{ page.headline | upcase }}
Converts the page headline output into all capital letters.
URL Encode
{{ " & " | url_encode }}
Replaces any special characters with appropriate %XX replacements, including the ampersand (&): %3Chello%3E+%26+%3Cgoodbye%3E
md5
{{ page.name | md5 }}
Converts a string into an MD5 hash, e.g. page.name: fff5fd234956c4c841290a9c423f9a81
sha256
{{ page.name | sha256 }}
Converts a string into a SHA-256 hash, e.g. page.name: 1589bc5b0028a0281915e82ef56907632e295e77340223a72d935828713b50d1
hmac_sha1
{% assign my_secret_string = "MySecretString" | hmac_sha1: "secret_key" %}
My encoded string is: {{ my_secret_string }}
Converts a string into a SHA-1 hash, e.g.
My encoded string is: 3bd702e964f598b21130064c4c62e0779936c123
hmac_sha256
{% assign my_secret_string = "MySecretString" | hmac_sha256: "secret_key" %}
My encoded string is: {{ my_secret_string }}
Converts a string into a SHA-256 hash, e.g.
My encoded string is: 95be5b9ec4695051549e7fe35bd6191ae6e414e7e91eb5430a43d7bfffc45a8a
hmac_sha512
{% assign my_secret_string = "MySecretString" | hmac_sha512: "secret_key" %}
My encoded string is: {{ my_secret_string }}
Converts a string into a SHA-512 hash, e.g.
My encoded string is: 48252f4340451f55fdefd71b0bd5883ae88ab007d3f5210d98b0ad86ddf8682c3308bc25970ff20fbcdbd59154b02863251daa3ef25940696841e4a73e5977fb
Math Filters
Plus
{{ '10' | plus:5 }} = 15
Minus
{{ '10' | minus:5 }} = 5
Times
{{ '10' | times:5 }} = 50
Divided By
{{ '20' | divided_by:5 }} = 4
Modulo
{{ '26' | modulo:5 }} = 1
Divides an output by a number and returns the remainder.
Round
{{ '10.34' | round }} = 10
Rounds the output to the nearest integer.
{{ '10.345678' | round: 2 }} = 10.35
Rounds the output to the nearest specified number of decimal places.
Ceil
{{ '10.34' | ceil }} = 11
Rounds an output up to the nearest integer.
Floor
{{ '10.34' | floor }} = 10
Rounds an output down to the nearest integer.
Array Filters
Join
{{ 'site.page_tags' | join: ', ' }} = tag1, tag2, tag3
Combines the elements of an array with the character passed as the delimiter. The result is a single string.
First
{{ 'site.page_tags' | first }} = tag1
Returns the first element of an array
Last
{{ 'site.page_tags' | last }} = tag3
Returns the last element of an array
Map
{% assign mapped_tags = site | map: 'page_tags' %}
{{ mapped_tags }}= tag1tag2tag3
Accepts an array element's attribute as a parameter and creates a string out of each array element's value.
Size
{{ 'site.page_tags' | size }} = 3
Returns the size of a string or an array.
Size can be used in dot notation, in cases where it needs to be used inside a tag:
{% if array.element.size > 10 %}
There are 10 of this element.
{% endif %}