HTML Helpers

{% add_javascript inline %}

Outputs javascript code in an inline script

{% add_javascript inline [uniquename] [= attributes]? %}

Parameters

uniquename optionalstring

If included, only one inline script will be included for each uniquename. This makes it safe to add an inline script in one or more partial templates which may be included multiple times in a page.

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax.

Options

position optionalvalue

Where to output the script in the current page. Must be 'head', 'in_place', or 'body'. If 'head', the script will be output inside the HTML head, if 'in_place', the script will be output immediately to the the template. If 'body', the script will be output at the end of the 'body' tag.

other optionalvalue

Additional attributes to include on the script tag. Additional attributes must have string values

{% end_javascript %}

This method creates a new liquid context for storing and manipulating variables.

Example How to use the add_javascript methodAdd linked or inline JavaScript with add_javascript; use path, attributes, or inline blocks (once, in place, with nonce).

Add linked javascript from a path

{% add_javascript "/jQuery.js" %}

Adds the javascript file from the specified path to the page. This is the simplest way to add javascript to a page, and by default adds it in the head of the page.

Add linked javascript from a path with attributes

{% add_javascript "/jQuery" position:'head' async:true defer:true %}

Adds the javascript file to the head of the page with the async and defer attributes.

Add third-party javascript to the body with additional custom attributes

{% add_javascript "https://cdn.thirdpartyservice.com/path/to/script" position:'body' crossorigin:'anonymous' integrity:'sha384-...' %}

Adds the third-party javascript before the </body> tag with the additional custom attributes.

Add inline javascript once to body

{%- add_javascript inline xxkr_once = position:'body' -%}
function doSomething() {
	alert('I did something!');
}
doSomething();
{%- end_javascript -%}

Adds the inline javascript to the body of the page. Because the script is named (xxkr_once), the javascript will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each script to be included should have a unique name.

Reusing the same inline script name prevents the second script from being added

{%- add_javascript inline xxkr_once -%}
	doSomething();
{%- end_javascript -%}{%- add_javascript inline xxkr_once -%}
	doSomethingElse();
{%- end_javascript -%}

Because both scripts use the same name (xxkr_once), only the first script will be added to the page and the second script will be ignored. This may sometimes be the desired behavior, but to include both scripts either remove the name or ensure that both scripts have unique names.

Add inline javascript in place

{%- for item in (1..3) -%}
	{%- id itemid = prefix:'item_' -%}
	<div id="{{itemid}}">{{item}}</div>
	{%- add_javascript inline = position:'in_place' -%}doSomething('{{itemid}}');
{%- end_javascript %}
{% endfor -%}

Adds the inline javascript immediately to the template, which will result in a separate script tag for each item.

Add inline javascript in the head with a nonce attribute

{%- var nonce = '...' -%}
{%- add_javascript inline = position:'head' nonce:nonce -%}
	doSomething();
{%- end_javascript -%}

Adds the inline javascript to the head of the page with a nonce attribute. The nonce attribute is used to prevent cross-site scripting (XSS) attacks by ensuring that the script is only executed if the nonce is valid. The logic for determining the nonce is left to the developer.

{% add_javascript %}

Add a script asset to the current page via a <script> tag

{% add_javascript value attributes %}

Parameters

value requiredobject

The script to add: a Javascript object, its GUID, or its path, absolute or relative to the folder of the template being rendered, as for {% javascript %}. A value that starts with http://, https:// or // is used as the address as given. A script that is not found adds nothing and raises no error.

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax. Attributes for the script tag and optionally the position that you want it to be placed

Options

position optionalvalue

Where to output the script in the current page. Must be 'head', 'in_place', or 'body'. If 'head', the script will be output inside the HTML head, if 'in_place', the script will be output immediately to the the template. If 'body', the script will be output at the end of the 'body' tag. Any scripts added to the head or body will only be added once and additional attributes will be combined from each time it is added. If it is added to both the head and body it will be includined in the head. The default is 'head'. If the page has no head element (for 'head') or no body element (for 'body'), nothing is output and no error is raised; 'in_place' is not affected.

async optionalvalue

True to include the async attribute on the script tag, or false to omit it. If the same script is added multiple times with both true and false specified, the script tag will include the async attribute

defer optionalvalue

True to include the defer attribute on the script tag, or false to omit it. If the same script is added multiple times with both true and false specified, the script tag will include the defer attribute

other optionalvalue

Additional attributes to include on the script tag. Additional attributes must have string values

Example Add Anonymous Javascript In PlaceAdd inline anonymous JavaScript in place (e.g. for one-off scripts) with add_javascript inline.

{% add_javascript "https://cdn.thirdpartyservice.com/path/to/script" position:'in_place' crossorigin:'anonymous' %}

Example Add Deferred Async Javascript To BodyAdd JavaScript to the body with deferred or async loading (e.g. with add_javascript options).

{% add_javascript "/main" defer:true async:true position:'body' %}

Example How to use the add_javascript methodAdd linked or inline JavaScript with add_javascript; use path, attributes, or inline blocks (once, in place, with nonce).

Add linked javascript from a path

{% add_javascript "/jQuery.js" %}

Adds the javascript file from the specified path to the page. This is the simplest way to add javascript to a page, and by default adds it in the head of the page.

Add linked javascript from a path with attributes

{% add_javascript "/jQuery" position:'head' async:true defer:true %}

Adds the javascript file to the head of the page with the async and defer attributes.

Add third-party javascript to the body with additional custom attributes

{% add_javascript "https://cdn.thirdpartyservice.com/path/to/script" position:'body' crossorigin:'anonymous' integrity:'sha384-...' %}

Adds the third-party javascript before the </body> tag with the additional custom attributes.

Add inline javascript once to body

{%- add_javascript inline xxkr_once = position:'body' -%}
function doSomething() {
	alert('I did something!');
}
doSomething();
{%- end_javascript -%}

Adds the inline javascript to the body of the page. Because the script is named (xxkr_once), the javascript will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each script to be included should have a unique name.

Reusing the same inline script name prevents the second script from being added

{%- add_javascript inline xxkr_once -%}
	doSomething();
{%- end_javascript -%}{%- add_javascript inline xxkr_once -%}
	doSomethingElse();
{%- end_javascript -%}

Because both scripts use the same name (xxkr_once), only the first script will be added to the page and the second script will be ignored. This may sometimes be the desired behavior, but to include both scripts either remove the name or ensure that both scripts have unique names.

Add inline javascript in place

{%- for item in (1..3) -%}
	{%- id itemid = prefix:'item_' -%}
	<div id="{{itemid}}">{{item}}</div>
	{%- add_javascript inline = position:'in_place' -%}doSomething('{{itemid}}');
{%- end_javascript %}
{% endfor -%}

Adds the inline javascript immediately to the template, which will result in a separate script tag for each item.

Add inline javascript in the head with a nonce attribute

{%- var nonce = '...' -%}
{%- add_javascript inline = position:'head' nonce:nonce -%}
	doSomething();
{%- end_javascript -%}

Adds the inline javascript to the head of the page with a nonce attribute. The nonce attribute is used to prevent cross-site scripting (XSS) attacks by ensuring that the script is only executed if the nonce is valid. The logic for determining the nonce is left to the developer.

{% add_stylesheet inline %}

Outputs an inline stylesheet in a <style> tag.

{% add_stylesheet inline [uniquename] [= attributes]? %}

Parameters

uniquename optionalstring

If included, only one style tag will be included for each uniquename. This makes it safe to add an inline stylesheet in one or more partial templates which may be included multiple times in a page.

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax.

Options

position optionalvalue

Where to output the style tag in the current page. May either be "head", "body", or "in_place". If "head", the style tag will be output inside the HTML head, if "body", the style tag will be output at the end of the 'body' tag. If "in_place", the style/link tag will be output immediately to the template. The default is "head", which typically results in the best browser performance.

other optionalvalue

Additional attributes to include on the style tag (such as "media", "id", or "disabled"). Additional attributes must have string values

{% end_stylesheet %}

This method creates a new liquid context for storing and manipulating variables.

Example How to use the add_stylesheet methodAdd linked or inline stylesheets to a page with add_stylesheet; use path, third-party URL with attributes, or inline named/in-place blocks.

Add linked stylesheet from a path

{% add_stylesheet "/bootstrap/bootstrap.scss" %}

Adds the stylesheet from the specified path to the page. This is the simplest way to add a stylesheet to a page and may be used from any template.

Add third-party stylesheet with additional custom attributes

{% add_stylesheet "https://cdn.thirdpartyservice.com/path/to/stylesheet" crossorigin:'anonymous' integrity:'sha384-...' %}

Adds the third-party stylesheet to the head of the page with the specified crossorigin and integrity attributes.

Add inline stylesheet

{%- add_stylesheet inline xxkr_footer_frompage -%}
//Use your imagination here!
#footer {
  background-color: '{{entity.footer_background_color}}';
  color: '{{entity.footer_text_color}}';
}
{%- end_stylesheet -%}

Adds the inline stylesheet to the body of the page. Because the stylesheet is named (xxkr_once), the stylesheet will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each stylesheet to be included should have a unique name.Adds the inline stylesheet to the page. Because the stylesheet is named (xxkr_footer_frompage), the stylesheet will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each stylesheet to be included should have a unique name.

Add inline stylesheet in place

{%- for item in (1..3) -%}
	{%- id itemid = prefix:'item_' -%}
	<div id="{{itemid}}">{{item}}</div>
	{%- add_stylesheet inline = position:'in_place' -%}#{{itemid}} { background-color: '{{ cycle xxkr_itemcolor: '#CCC', 'rgba(242, 122, 55, 0.7)', 'black' }}'; }
{%- end_stylesheet -%}
{%- endfor -%}

Adds the inline stylesheet immediately to the page, which will result in a separate style tag for each item. There are typically better ways to achieve the same result, but there are times when this may be the most practical solution.

{% add_stylesheet %}

Add a stylesheet asset to the head of the current page via a <link> tag

{% add_stylesheet value attributes %}

Parameters

value requiredobject

The stylesheet to add: a Stylesheet object, its GUID, or its path, absolute or relative to the folder of the template being rendered, as for {% stylesheet %}. A value that starts with http://, https:// or // is used as the address as given. A stylesheet that is not found adds nothing and raises no error.

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax. Additional attributes to include on the link tag. Attributes must have string values. "link" and "rel" are not allowed as they will always be set by this method.

Options

position optionalvalue

Where to output the stylesheet in the current page. May either be "head", "body", or "in_place". If "head", the stylesheet will be output inside the HTML head, if "body", the stylesheet will be output at the end of the 'body' tag. If "in_place", the stylesheet will be output immediately to the template. The default is "head", which typically results in the best browser performance. If the page has no head element (for "head") or no body element (for "body"), nothing is output and no error is raised; "in_place" is not affected.

Example How to use the add_stylesheet methodAdd linked or inline stylesheets to a page with add_stylesheet; use path, third-party URL with attributes, or inline named/in-place blocks.

Add linked stylesheet from a path

{% add_stylesheet "/bootstrap/bootstrap.scss" %}

Adds the stylesheet from the specified path to the page. This is the simplest way to add a stylesheet to a page and may be used from any template.

Add third-party stylesheet with additional custom attributes

{% add_stylesheet "https://cdn.thirdpartyservice.com/path/to/stylesheet" crossorigin:'anonymous' integrity:'sha384-...' %}

Adds the third-party stylesheet to the head of the page with the specified crossorigin and integrity attributes.

Add inline stylesheet

{%- add_stylesheet inline xxkr_footer_frompage -%}
//Use your imagination here!
#footer {
  background-color: '{{entity.footer_background_color}}';
  color: '{{entity.footer_text_color}}';
}
{%- end_stylesheet -%}

Adds the inline stylesheet to the body of the page. Because the stylesheet is named (xxkr_once), the stylesheet will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each stylesheet to be included should have a unique name.Adds the inline stylesheet to the page. Because the stylesheet is named (xxkr_footer_frompage), the stylesheet will only be added once and can be used in one or more partial templates which may be included multiple times in a page. Each stylesheet to be included should have a unique name.

Add inline stylesheet in place

{%- for item in (1..3) -%}
	{%- id itemid = prefix:'item_' -%}
	<div id="{{itemid}}">{{item}}</div>
	{%- add_stylesheet inline = position:'in_place' -%}#{{itemid}} { background-color: '{{ cycle xxkr_itemcolor: '#CCC', 'rgba(242, 122, 55, 0.7)', 'black' }}'; }
{%- end_stylesheet -%}
{%- endfor -%}

Adds the inline stylesheet immediately to the page, which will result in a separate style tag for each item. There are typically better ways to achieve the same result, but there are times when this may be the most practical solution.

{% element %} (block)

Outputs a block-level HTML element with nested content and sanitized attributes.

{% element name attributes? / %}

Parameters

name requiredstring

HTML element tag name

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax. Attributes to include on the resulting HTML element. Each attribute must have a string value. The keys will be output as-is and the values will be HTML encoded.

{% endelement %}

This method creates a new liquid context for storing and manipulating variables.

Example Output content inside a div elementOutput content inside a div (or other wrapper) using output_content_inside or similar patterns.

{%- element 'div' id:'maincontent' class:'container wide' -%}
  {%- include '/maincontent' -%}
{%- endelement -%}

{% element / %} (self-closing)

Outputs a sanitized HTML element that is self-closed.

{% element name attributes? / %}

Parameters

name requiredstring

HTML element tag name

attributes optionaldictionary

Key:value pairs with unique keys. May use the variable arguments syntax. Attributes to include on the resulting HTML element. Each attribute must have a string value. The keys will be output as-is and the values will be HTML encoded.

Example Output self-closing input elementOutput a self-closing input (or other void) element, e.g. for forms, with correct markup.

{% element 'input' type:'text' name:'username' placeholder:'Username' required:required / %}

{% image_url %}

Resolves the URL for an image with the desired presets and other settings applied.

{% image_url output_to_template? [[var, set, or assign]? variable]? output_to_template? = image attributes? %}

Parameters

output_to_template optionalflag

If included the {% image_url %} will be output directly to the template.

var, set, or assign optionalkeyword

Optional. Specify either "var", "set" or "assign" to change which scope this {% image_url %} is stored on. "var" is the default behavior.

variable optionalvariable

output_to_template optionalflag

If included the {% image_url %} will be output directly to the template.

image requiredobject

Image object or its name/guid

attributes optionalcollection

Key:value pairs. May use the variable arguments syntax. Additional options for the image URL. Currently only supports presets

Options

preset optionalvalue

One or more image presets to apply to the image. May either be preset objects or space-separated preset codes. May be included multiple times to include multiple presets

Example How to use the image_url method to get URLs for images

Simple Use Case: output URL to template

{% image_url output_to_template = entity.image %}

https://domain.com/path/to/img.jpg

This example outputs the URL of the image stored in the entity.image object to the template.

Improved Use Case: apply presets to the image

{%- image_url img_path = entity.banner_image preset:"banner-size" preset:"sepia-simple" -%}
{%- image_url output_to_template = entity.image %} -> {{ img_path }}

https://domain.com/path/to/home-banner.jpg -> https://domain.com/path/with/banner-size/and/sepia-simple/home-banner.jpg

This example applies the banner-size and sepia-simple presets to the image stored in the page.banner_image object and outputs the URL to the template.

With extension, presets, and dynamic preset string

{%- var size = 'small' -%}
{%- var bordercolor = 'red' -%}
{%- var set_transparency = true -%}
{%- capture imageCode %}thumb-{{size}} border-{{bordercolor}}{% endcapture -%}
{%- capture img_arguments %}{% if set_transparency %}preset:"transparent20" {% endif %}preset:"border10"{% endcapture -%}
{%- image_url var img_path = entity.image *img_arguments preset:imageCode -%}

This example combines multiple advanced syntax options for dynamically applying presets to the image. Multiple presets may be combined in a single string with spaces in between each preset. Additionally, the image_url method accepts the variable expansion syntax which allows for even more dynamic arguments. After all of the arguments in this example are evaluated, the result will be the equivalent of {% image_url var img_path = entity.image preset:"transparent20" preset:"border10" preset:"thumb-small" preset:"border-red" %} and the final image url will be stored in the img_path variable.

{% img %}

Shortcut to output a <img> tag for an image, optionally wrapped in a link.

{% img image attributes %}

Parameters

value requiredobject

Image object, guid, or name

attributes optionalcollection

Key:value pairs. May use the variable arguments syntax. Additional options for the image URL, img tag, and anchor tag (if applicable)

Options

preset optionalvalue

Zero or more image presets; may repeat or include space-separated list

link optionalvalue

If string, wraps image with anchor to that URL. If true and image has a URL (page), wraps to the image URL

class optionalvalue

Class attribute for the img tag. If included multiple times all of the classes will be included, separated by spaces

link_class optionalvalue

Class attribute for the wrapping anchor tag, if applicable. If included multiple times all of the classes will be included, separated by spaces

link_attribute optionalvalue

Additional attributes for the wrapping anchor tag, if applicable. Each attribute must be prefixed with "link_", may only be included once, and must have a value to be included in the anchor tag

other optionalvalue

Additional attributes for img tag. Each additional attribute may only be included once and must have a value to be included in the img tag

Example Output an img element (and optional link) with the img shortcutUse the img shortcut to output an <img> element, optionally wrapped in a link, with presets and custom attributes.

Basic: image with default link

{%- img page.featured_image link:true -%}

<a href="https://www.domain.com/path/to/image/page"><img src="https://www.domain.com/path/to/img.jpg" alt="Image Alt Text" title="Image Title" width="Image Width" height="Image Height" /></a>

Outputs the image wrapped in a link to the image's default page.

Image without link

{%- img page.featured_image link:false -%}

<img src="https://www.domain.com/path/to/img.jpg" alt="Image Alt Text" title="Image Title" width="Image Width" height="Image Height" />

Outputs only the <img> element when link is false.

With presets and custom attributes

{%- img "Img for Homepage" preset:"thumb250" title:"Back to Home Page" other:"some other attribute" -%}

<img src="https://www.domain.com/path/to/altered/img.jpg" alt="Image Alt Text" title="Back to Home Page" width="Image Width" height="Image Height" other="some other attribute" />

Uses a preset to alter the image and sets title and other HTML attributes on the tag.

With custom link URL and link attributes

{%- img entity.link_img link:entity.link_destination.value link_class:"external_link" link_target="_blank" preset:"preview externallink" title:"Open In New Tab" -%}

<a href="https://www.domain.com/path/to/custom/destination" class="external_link" target="_blank"><img src="https://www.domain.com/path/to/altered/img.jpg" alt="Image Alt Text" title="Open In New Tab" width="Image Width" height="Image Height" /></a>

Uses a custom link URL and sets link class and target (e.g. for external links).

Dynamic attribute name with reference variable

{%- var property = 'data-attribute-x' -%}
{%- img page.featured_image link:false &property:'xyz' -%}

<img src="https://www.domain.com/path/to/img.jpg" alt="Image Alt Text" title="Image Title" width="Image Width" height="Image Height" data-attribute-x="xyz" />

Uses a reference variable (&property) to set an attribute whose name is determined at runtime.

{% query_param_link %}

Builds a link by combining the query parameters from the current request with the query parameters provided to this method as key:value pairs.

{% query_param_link output_to_template? [[var, set, or assign]? variable]? output_to_template? = attributes %}

Parameters

output_to_template optionalflag

If included the {% query_param_link %} will be output directly to the template.

var, set, or assign optionalkeyword

Optional. Specify either "var", "set" or "assign" to change which scope this {% query_param_link %} is stored on. "var" is the default behavior.

variable optionalvariable

output_to_template optionalflag

If included the {% query_param_link %} will be output directly to the template.

attributes requireddictionary

Key:value pairs with unique keys. May use the variable arguments syntax. The query parameters to set or unset in the resulting link. Attributes with a value of null will be ignored, and attributes with a value of false will be unset

Any query parameters from the current request that are not explicitly unset will be included in the resulting link, including "utm" parameters. Be sure to unset all parameters that you may reasonably expect to be present on the page but do not want to include in the resulting link.

Example How to use the query_param_link method to build URLs that add or replace query parameters

Basic: add or replace one parameter

{{request.url}} -> {% query_param_link = page:2 %}

https://www.domain.com/path/to/page -> https://www.domain.com/path/to/page?page=2

This example adds "?page=2" to the current request url. In the given example, the original request URL is https://www.domain.com/path/to/page.

Improved: add or replace one parameter and unset UTM parameters if present

{{request.url}} -> {% query_param_link = page:2 utm_source:false utm_medium:false utm_campaign:false %}

https://www.domain.com/promo/summer_sale?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale -> https://www.domain.com/promo/summer_sale?page=2

You can use the query_param_link method to modify multiple query parameters at once. Setting a query parameter to false in the query_param_link method removes it from the URL if it is present.

Multiple parameters and variable values

{%- var numLinks = 3 -%}
{%- query_param_link mylink = page:1 limit:numLinks topic:'Patriotism' -%}
{{-request.url}} -> {{ mylink | append:"#articletop" }}

https://www.domain.com/blog?page=2 -> https://www.domain.com/blog?page=1&limit=3&topic=Patriotism#articletop

This example adds the page, limit, and topic query parameters to the current request url and stores the result in the mylink variable.

Dynamic param names with reference variables

{%- var oldvarname = 'flat' -%}
{%- var newvarname = 'round' -%}
{{-request.url}} -> {% query_param_link = &oldvarname:false &newvarname:'true' -%}

https://www.domain.com/path/to/page?flat=true -> https://www.domain.com/path/to/page?round=true

This example uses reference variables to unset the query parameter stored in the oldvarname variable and set the query parameter stored in the newvarname variable to true and newvarname variables to false and true.