Contents x
    Liquid tags
    • 29 Oct 2024
    • 10 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Liquid tags

    • Updated on 29 Oct 2024
    • 10 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    How and when you can use Liquid templates

    Liquid templates allow you to add dynamic content to pages in your service.
    Dynamic content includes:

    • information entered by the user into input fields
    • conditional content based on user answers
    • mathematical calculations
    • date/time based content
    • looping content such as table rows

    Liquid templates can also be used when mapping API and email variables, and to build complex rule templates for page flow or validation conditions.

    You can include Liquid template tags in your content in Govforms Digital Service Builder anywhere you see the Liquid symbol:

    image.png

    image.png

    Liquid template syntax

    Refer to the Liquid template reference documentation:

    https://shopify.github.io/liquid/basics/introduction/

    Use the field ID of any input component to get the user-entered value for that field. Choice fields are set to the choice ID of the selected choice.

    Use the Govforms Enter test mode link in Prototype and QA environments to inspect the variables that are available for you to use in your Liquid tags:

    image.png

    Test mode allows you to inspect all form, condition, field and action variables. You can also change the value of any of them and evaluate templates to test the result under different conditions:

    image.png

    Standard tag filters

    You can use all of the standard Liquid JS filters documented here:

    https://liquidjs.com/filters/overview.html

    Additional tag filters

    In addition to the standard Liquid tags, Govforms provides an additional set of filters that you can use in your Liquid templates:

    Filter nameExampleDescription
    math{{ "(a + b) * (c \ 100)" | math: product1Price, product2Price, discountPc }}Performs mathematical calculations on the given inputs. You can provide up to 26 inputs. Each input will be mapped to the variable a, b, c, d and so on in the given mathematical expression. In this example, we are adding together the value of two text fields product1Price and product2Price, and then multiplying by the value of discountPc divided by 100.

    Refer to https://mathjs.org/docs/expressions/syntax.html for a list of the mathematical operators and functions available.

    is_number{{ myNumberField | is_number }}Evaluates to true if the given value is a number, otherwise evaluates to false. You can use this with logic tags to check if a field contains a number, for example:
    {% if myNumberField | is_number %}
    output something
    {% endif %}

    number{{ myNumberField | number }}Converts the given value from a text string to a number that can be used in numerical comparisons e.g. > (greater than) or < (less than)
    as_number{{ myNumberField | as_number }}Similar to number above but also removes any commas or £, $, € symbols from the given string.
    format_number{{ myNumberField | format_number }}
    {{ myNumberField | format_number, 2, 2 }}    		Outputs the given number for display, with commas separating groups of 1000. E.g. 12345 is output as 12,345. You can also pass in the minimum and maximum number of decimal digits to round or pad to.
    format_currency{{ myNumberField | format_currency }}
    {{ myNumberField | format_currency, true, true, "en-US", "CAN" }}    		Outputs the given number for display as a currency value, defaulting to GBP (sterling). You can also pass in additional optional parameters: The first boolean can be set to true to include pence, the next can be set to round even rather than down, and the next two control the locale and currency code to use.
    is_decimal{{ myNumberField | is_decimal }}Evaluates to true if the given value is a decimal number (i.e. it is a valid number that includes a decimal point), otherwise evaluates to false.

    is_integer{{ myNumberField | is_integer }}Evaluates to true if the given value is an integer number (i.e. it is a valid number that does not include a decimal point), otherwise evaluates to false.

    round_fixed{{ myNumber | round_fixed: 2 }}Rounds the given number to the given fixed number of decimal places. If you just want to round the given number but don't want to fix the number of decimal places in the output, use the standard Liquid round filter instead.

    not{{ myLogicExpression | not }}Evaluates to true if the given value is not true. Otherwise evaluates to false.

    to_json_string{{ myTextField | to_json_string }}Converts the given value to a JSON string. This will perform any escaping required to ensure user-entered values are represented correctly in a JSON payload. For example the problematic user-entered text O'Neill "Open&closed" [1] would be converted to the valid JSON string "O'Neill \"Open&closed\" [1]"

    parse_json{{ myJsonString | parse_json }}Converts the given JSON string to a JSON object.

    xpath{{ actions.myXmlApiAction.response | xpath: "bookstore/book" }}For legacy XML APIs, response data is received as plain text. Use this filter to run an xpath expression on the given XML string to retrieve data items.

    file_to_base64{{ myFileUploadFieldId | file_to_base64 }}Available for use in API call-out bodies only, provides the file content of the given file upload field as base64. Please note you cannot chain other filters with this filter, and that this filter will not be functional in the test mode console.

    base64_encode{{ "username:password" | base64_encode }}Encodes the given text string into base64.

    base64_decode{{ "dXNlcm5hbWU6cGFzc3dvcmQ=" | base64_decode }}Decodes the given base64 string back to text.

    timestamp{{ myDateField | timestamp }}Gets the given Govforms date field or date object as a number of milliseconds since Jan 1 1970. You can compare 2 dates by using this to get their timestamp, then compare the timestamp.
    gfdate_to_date{{ myDateField | gfdate_to_date }}Gets the given Govforms date field as a Date object.
    date_to_gfdate{{ dateObject | date_to_gfdate }}Gets the given Date object and converts it to a Govforms date field value.
    gfdate{{ myDateField | gfdate }}Deprecated; use gfdate_to_date instead.
    gfdate_to_string{{ myDateField | gfdate_to_string }}Gets the given Govforms date field as a JSON string in the format YYYY-MM-DD

    gftime_to_string{{ myTimeField | gftime_to_string }}Gets the given Govforms time field as a JSON string in the format HH:MM

    format_date{{ myDateField | gfdate | format_date: "yyyy-MM-dd'T'HH:mm:ss" }}Converts the given date object to any JSON string format. For details of the formatting pattens available refer to the reference documentation at https://date-fns.org/v2.0.0/docs/format
    parse_date{{ dateObject | parse_date: "yyyy-MM-dd'T'HH:mm:ss" }}Converts the given date string to a date object. The date string must be in the format pattern provided. The date object returned can be passed through other Liquid filters, like day_offset below. For details of the formatting pattens available refer to the reference documentation at https://date-fns.org/v2.0.0/docs/parse
    excel_date{{ myExcelFeedDate | excel_date }}Gets the given Excel-format date number as a standard date object that you can use in subsequent date filters (like day_offset). Govforms data feeds from Excel files will provide dates in the Excel format; use this filter to convert them.

    day_offset{{ now | day_offset: -1 }}Gets the given Govforms date field or date object with the given offset applied. The offset is a number of days. Provide a negative number to subtract days from the given date, or a positive number to add days. As per standard Liquid template syntax you can provide the keyword now to use the current date.

    month_offset{{ now | month_offset: 3 }}Gets the given Govforms date field or date object with the given offset applied. The offset is a number of months. Provide a negative number to subtract months from the given date, or a positive number to add months. As per standard Liquid template syntax you can provide the keyword now to use the current date.

    day_start{{ now | day_start }}Gets the start of the day (00:00) of the given Govforms date field or date object.

    day_end{{ now | day_end }}Gets the end of the day (23:59:59.999) of the given Govforms date field or date object.

    page_link{{ "Change colour" | page_link: "9bde83b9-f7ec-4d45-8e44-29435a3675f8", "myParam1Key", "myParam1Value", "myParam2Key", "myParam2Value" }}Renders a link to the page in your service with the given page ID. When clicked the current page will not be submitted so any user data input into it will be lost. You can link to previous pages in the journey or subsequent pages as long as all intervening in-scope pages have already been submitted by the user. For this reason, if you need to link to the next page use page_submit_link. You can find the page ID for any page in Page Settings. Optionally include any number of query parameter keys and values. You can access query parameters from the linked page using form.query.myParam1Key

    page_submit_link{{ "Click here to go to results page" | page_submit_link: "9bde83b9-f7ec-4d45-8e44-29435a3675f8", "myParam1Key", "myParam1Value", "myParam2Key", "myParam2Value" }}Renders a link to the page in your service with the given page ID. When clicked the current page will be submitted and any actions executed, and if there are validation errors the user will stay on the current page to fix them. You can link to previous pages in the journey, or the next page, or subsequent pages as long as all intervening in-scope pages have already been submitted by the user. If you need to link to the next page, use page_submit_link. You can find the page ID for any page in Page Settings. Optionally include any number of query parameter keys and values. You can access query parameters from the linked page using form.query.myParam1Key

    completed_answers_link{{ "Click here to view or save your answers" | completed_answers_link }}Gets a link to a page showing all the user's answers for the service. For the link to work, the user form must be in a completed state i.e. the user having reached the End page, or completed all their tasks.

    pdf_download_link{{ myPdfAction | pdf_download_link: "Click here to download a PDF of your answers" }}Gets a download link for a PDF containing the users answers. You must first add a PDF action to your service at the point the PDF should be generated (typically this is done upon final submission).

    pdf_view_link{{ myPdfAction | pdf_view_link: "Click here to download a PDF of your answers" }}Gets a link that will open a PDF containing the users answers in the user's browser. You must first add a PDF action to your service at the point the PDF should be generated (typically this is done upon final submission).

    restart_link{{ "Click here to make another application" | restart_link }}Gets a link that will clear the current session (if active) and restart the user journey.

    form_to_json{{ form | form_to_json }}Gets a JSON document containing a property for each field in the form that has a user answer, set to the user's answer.

    form_to_text{{ form | form_to_text }}Gets a structured plain text version of all user answers in the form.

    field_to_text{{ myFieldId | field_to_text: "myFieldId", form }}Gets a flat text representation of the given field. This can be used to map any field to text for example to display it in SharePoint, CSV, API or email outputs. The form parameter should always be set to form, though for legacy support form.fieldDefs is also accepted.
    Optionally, a field part ID can added as a final parameter. For address fields this is one of line1, line2, line3, line4, line5, postcode, country. For map select fields this is one of lat, lng, bng, nearPlace, nearFullDescription.

    odata_string_escape{{ myTextField | odata_string_escape }}Escapes single quotes in the given string to make them suitable for use in an OData expression, for example when defining a Liquid template for a custom Microsoft SharePoint list filter expression.

    uuid{{ "" | uuid }}Gets a random UUID.

    num_items{{ myObject | num_items }}Gets the number of keys in the given object.

    set{{ myObject | set: "myKey", "myValue" }}Sets the value of the given property (key) in the given object. If the object is undefined it is created before setting the property. Returns the object, allowing chaining of set calls.

    object_keys{{ myObject | object_keys }}Gets an array of all of the property names in the given object.

    object_values{{ myObject | object_values }}Gets an array of all of the property values in the given object.

    Was this article helpful?
      Copyright © Govforms Ltd 2018-2023