Skip to main content
  1. Home
  2. Support
  3. Documentation
  4. Website HOWTOs

Liquid Basics Dev

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


Liquid Tags

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

  • {% comment %} - Comments will be hidden.

    • Comments

    Messages contained within a comment tag will not display. They will also be hidden from the page's HTML source code.

  • {% raw %} - No liquid will be parsed within these tags.

    • Raw

    The raw tag prevents the {{ output_tag }} from executing.

  • {% if %} - Conditional statement to determine if something is true or not.

    • If

    This conditional will check if the page is the homepage, and if it is, it will display the welcome message.

    This conditional uses {% elsif %} for multiple if statements.

  • {% else %} - Indicates everything else that was not included in conditional statement.

    • Else

    This will check if the page is the homepage, and if it is, it will display the welcome message. Everything else will see a different message.

  • {% unless %} - Conditional statement to determine if not true, then it will do something.

    • Unless

    This will check if the signup first name is not john, and if it is not, it will display the welcome message.

  • {% case %} - If you need more than one condition you can use the Case Statement.

    • Case

    This will display a different partial template for navigation depending on the page slug.

  • {% for %} - Use "for loops" if you want to display an array of objects in a group.

    • For loops

    This will display an array of recent supporters with images.

    Attributes to influence objects you receive from loop:

    • limit:# - lets you restrict how many objects you get in an array.
    • offset:# - lets you start the array with the nth item.

    Limits the number of recent blog posts to 10, starting from 0.

    Reversing the loop:

    Reverses the order of the most recent blog posts, showing the oldest in the forloop first.

    Helper variables for extra styling:

    • 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 objects are still left?
    • forloop.rindex0 - how many objects are still left? (zero based)
    • forloop.first - is this the first iteration?
    • forloop.last - is this the last iteration?

    'index == 1' means the first slide in the page features forloop (slider).

  • {% tablerow %} - Generates table rows/cells for a loop of objects in array.

    • Table Row

    • limit:# - lets you restrict how many objects you get in an array.
    • cols:# - lets you set the number of columns.

    This will generate a 2 column table of linked past event names.

    Helper variables for extra styling:

    • tablerowloop.length - length of the entire table row
    • 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?

  • {% cycle %} -Usually used within a loop to alternate between values.

    • Cycle

    This will generate a single column table listing past event names in alternating red and green rows.

  • {% capture %} - Block tag that captures text into a new variable.

    • Capture

    This newly-created output of {{ fullurl }} will now produce the URL of the page you are on.

  • {% assign %} - Assigns some value to a variable.

    • Assign

    This assigns the thermo_width a value of 370px.

  • {% include %} - Insert a partial template into your layout.

    • Include

    This will insert the _features.html partial template wherever the tag is placed.

  • {% subpage %} - Associate a page slug with an HTML snippet for display.

    • Subpage

    This will display the content of the HTML snippet with the settings of the page_slug in question. More detailed instructions on this method and on creating an HTML snippet can be found here.

  • {% tag %} - Associate pages with a specific page tag with an HTML snippet for display.

    • Tag

    This will display the content of the HTML snippet with the settings of pages tagged with the specific page tag's slug. More detailed instructions on this method can be found here.

    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.

    • Equal

    This conditional statement checks to see if the page slug equals blog. If it is true, it will display the include "banner."

  • != not equal.

    • Not Equal

    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.

    • Bigger Than

    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.

    • Less Than

    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.

    • Bigger or Equal

    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.

    • Less or Equal

    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 this or that.

    • Or

    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 must be this and that.

    • And

    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 includes the substring if used on a string, or element if used on an array.

    • Contains

    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.

    Back to top
    Liquid Output and Object Reference Guide

    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

  • nation settings - Output variables for website settings and overall nation stats.

    • Website Setting Output Variables

  • site
  • settings
  • election

    • All of these links go to separate pages.

  • user & account variables - Output variables for user sessions, profiles and account settings.

    • User & Account Output Variables

  • request
  • signup
  • account
  • user_session
  • profile_note
  • activation
  • password
  • password_reset
  • flag
  • unsubscribe
  • capital
  • broadcaster
  • mailing
  • address
  • tweet
  • twilio_phone

    • All of these links go to separate pages.

  • page variables - Output variables for different page-type templates.

    • Page Output Variables

  • page
  • page_attachments
  • page_follower
  • page_tag
  • page_tagging
  • page_signup_tagging
  • flash
  • feature
  • activity
  • comment
  • page.basic
  • page.blog
  • page.blog_post
  • page.calendar
  • page.event
  • event_host
  • event_rsvp
  • event_ticket_level
  • page.donation
  • donation
  • merchant_account
  • order
  • order_item
  • page.endorsement
  • endorsement
  • page.survey
  • survey_question
  • survey_question_possible_response
  • survey_question_response
  • page.signup
  • signup
  • page.faq
  • page.question
  • page.feedback
  • page.invoice
  • page.leaderboard
  • leaderboard
  • leaderboard_entry
  • page.moneybomb
  • page.paid_membership
  • paid_membership_page_level
  • page.press_release
  • page.petition
  • petition_signature
  • page.rule
  • rule
  • rule_violation
  • page.suggestion
  • page.suggestion_box
  • page.volunteer_signup
  • volunteer
  • volunteer_type
  • page.vote_pledge
  • vote_pledge
  • pledge_variables
  • page.voter_registration
  • page.activity_stream
  • activity

    • All of these links go to separate pages.

    Special Outputs

  • theme['filename'] - Generates absolute link to a file in theme directory.

    • Produces a direct link to the javascript file: jquery.fancybox.pack.js, located under Pages>Theme>Files.

  • now - Displays the current date and time.

    • Now

    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 - Append characters to a string.

    • Append

    Appends an image at the end of the Page Headline output.

    Appends the words 'by Author' to the end of the Page Headline output.

  • capitalize - Capitalizes the first word in a string.

    • Capitalize

    Capitalizes the first words in a page's headline field.

  • date - Reformat a date syntax reference.

    • 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

    Will display the date in this format: "Sunday, September 29, 2012 at 6:30pm through October 01, 2012"

  • default - Displays a default value for an empty variable.

    • Default

    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 - Convert an input string to lowercase.

    • Downcase

    Converts the page headline output into all lowercase letters.

  • escape - Escapes a string without rendering HTML tags

    • Escape

    HTML tags are not rendered: <p>test</p>

  • prepend - Prepend characters to a string.

    • Prepend

    Adds an image in front of the Page Headline output.

  • remove - Removes all occurrences of the substring from the input.

    • Remove

    Removes all occurrences of 'the' in the output for the blog post content tag.

  • remove_first - Removes only the first occurrence of the substring from the input.

    • Remove First

    Removes only the first occurrence of 'the' in the output for the blog post content tag.

  • replace - Replaces one thing from the input with another.

    • Replace

    The resulting text would be "brown bears and brown ice caps"

  • replace_first - Replaces only the first instance of a string from the input with another.

    • Replace_first

    The resulting text would be: "brown bears and polar ice caps"

  • slice - Returns a substring.

    • Slice

    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 - Divides a string into an array based on a substring.

    • Split

    The split filter takes on a substring as a delimiter to divide a string into an array.

  • strip - Strips whitespace from a string.

    • Strip

    Strips tabs, spaces, and newlines (whitespace) from both the left and right sides of a string.

  • lstrip - Strips whitespace from the left side of a string.

    • Left Strip

    Strips tabs, spaces, and newlines (whitespace) from only the left side of a string.

  • rstrip - Strips whitespace from the right side of a string.

    • Right Strip

    Strips tabs, spaces, and newlines (whitespace) from only the right side of a string.

  • strip_html - Strips all html tags from the text passed to the block.

    • Strip HTML

    Removes all html tags from the blog post content.

  • truncatechars - Truncate a string down to x characters. (replaced truncate)

    • Truncate Characters

    Limits the amount of characters displayed from the Post Headline to 10.

  • truncatewords - Truncate a string down to x words.

    • Truncate Words

    Limits the amount of characters displayed from the Post Headline to 10.

  • paginate - Segments output into numbered pages when long.

    • Paginate

    Paginates the most recent blog posts.

  • uniq - Removes duplicate instances of an element.

    • Uniq

    Removes any duplicate instances of an element in an array.

  • upcase - Convert an input string to uppercase.

    • Upcase

    Converts the page headline output into all capital letters.

  • url_encode - Replaces all characters in a string with their escaped variants for use in URLs.

    • URL Encode

    Replaces any special characters with appropriate %XX replacements, including the ampersand (&): %3Chello%3E+%26+%3Cgoodbye%3E

    Math Filters

  • plus - Adding input to object.

    • Plus

  • minus - Subtracting input from object.

    • Minus

  • times - Multiplying object by x.

    • Times

  • divided_by - Dividing object by x.

    • Divided By

  • modulo - Returns the remainder after dividing numbers.

    • Modulo

    Divides an output by a number and returns the remainder.

  • round - Rounds output to the nearest integer or specificed number of decimal places.

    • Round

    Rounds the output to the nearest integer.

    Rounds the output to the nearest specified number of decimal places.

  • ceil - Rounds up to the nearest integer.

    • Ceil

    Rounds an output up to the nearest integer.

  • floor - Rounds down to the nearest integer.

    • Floor

    Rounds an output down to the nearest integer.

    Array Filters

  • join - Combines the elements of an array.

    • Join

    Combines the elements of an array with the character passed as the delimiter. The result is a single string.

  • first - Returns the first element of an array.

    • First

    Returns the first element of an array

  • last - Returns the last element of an array.

    • Last

    Returns the last element of an array

  • map - Creates a string from the values of one array element.

    • Map

    Accepts an array element's attribute as a parameter and creates a string out of each array element's value.

  • size - Returns the size of a string or an array.

    • Size

    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:


    Back to top

    Dive into more custom theme documentation