The Vend Developer Hub

Welcome to the Vend developer hub. You'll find comprehensive guides and documentation to help you start working with the Vend API as quickly as possible.

Theme filters

Introduction

Filters are simple methods that modify the output of numbers, strings, variables and objects. They are placed within an output tag {{ }} and are separated with a pipe character |.

Input

<!-- product.title = "Awesome Shoes" -->  

{{ product.title | upcase }}

Output

AWESOME SHOES

Money Filters

money

Returns money like NZ$10.20 or A$1.20 or $99.99 or €5.55. If value is passed to money filter (rather then object property ie "14.99" instead of variant.price) scale can be provided to override default scale value.

Input

<!-- USD 25.90 -->
{{ product.master_variant.price|money }}
<!-- AUD 25.90 -->
{{ product.master_variant.price|money }}
<!-- NZD 25.90 -->
{{ "2595000"|money }}
<!-- EUR 25.90 -->
{{ "2595000"|money: 100000 }}
<!-- RUR 25.90 -->
{{ "2595"|money: 100 }}

Output

$25.90
A$25.90
NZ$25.90
€25.90
RUR25.90

money_without_currency

Returns money like 10.20

Input

<!-- EUR 25.90 -->
{{ "2595000"|money }}

Output

25.90

String Filters

append

Appends characters to a string.

Input

{{ 'sales' | append: '.jpg' }}

Output

sales.jpg

camelcase

Converts a string into CamelCase.

Input

{{ 'coming-soon' | camelcase }}

Output

ComingSoon

capitalize

Capitalizes the first word in a string

Input

{{ 'capitalize me' | capitalize }}

Output

Capitalize me

title

Returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase

Input

{{ 'title me' | title }}

Output

Title Me

downcase / lower

Converts a string into lowercase.

Input

{{ 'I WANT THIS TO BE LOWER CASE' | downcase }}

Output

i want this to be lower case

escape

Escapes a string.

Input

{{ "<p>test</p>" | escape }}

Output

<!-- The <p> tags are not rendered, actual output is -->
&lt;p&gt;test&lt;/p&gt;

raw

Marks the value as being "safe", which means this variable will not be escaped if raw is the last filter applied to it

Input

{{ "<p>test</p>" | strip | raw }}
{{ "<p>test</p>" | strip }}

Output

<!-- The <p> tags are rendered, actual output is -->
<p>test</p>
 <!-- The <p> tags are not rendered, actual output is -->
&lt;p&gt;test&lt;/p&gt;

handle / handleize

Formats a string into a handle.

Input

{{ '100% M & Ms!!!' | handleize }}

Output

100-m-ms

md5

Converts a string into an MD5 hash.
An example use case for this filter is showing the Gravatar image associated with the poster of a blog comment:

Input

<img src="https://www.gravatar.com/avatar/{{ comment.email | remove: ' ' | strip_newlines | downcase | md5 }}" />

Output

 <img src="https://www.gravatar.com/avatar/2a95ab7c950db9693c2ceb767784c201" />

newline_to_br / nl2br

Inserts a
linebreak HTML tag in front of each line break in a string.

Input

{% capture var %}
One
Two
Three
{% endcapture %}
{{ var | newline_to_br }}

Output

One <br>
Two<br>
Three<br>

pluralize

Outputs the singular or plural version of a string based on the value of a number. The first parameter is the singular string and the second parameter is the plural string.

Input

{{ cart.item_count }}
{{ cart.item_count | pluralize: 'item', 'items' }}

Output

3 items

prepend

Prepends characters to a string.

Input

{{ 'sale' | prepend: 'Made a great ' }}

Output

Made a great sale

remove

Removes all occurrences of a substring from a string.

Input

{{ "Hello, world. Goodbye, world." | remove: "world" }}

Output

Hello, . Goodbye, .

remove_first

Removes only the first occurrence of a substring from a string.

Input

{{ "Hello, world. Goodbye, world." | remove_first: "world" }}

Output

Hello, . Goodbye, world.

replace

Replaces all occurrences of a string with a substring.

Input

<!-- product.title = "Awesome Shoes" -->
{{ product.title | replace: 'Awesome', 'Mega' }}

Output

Mega Shoes

replace_first

Replaces the first occurrence of a string with a substring.

Input

<!-- product.title = "Awesome Awesome Shoes" -->
{{ product.title | replace_first: 'Awesome', 'Mega' }}

Output

Mega Awesome Shoes

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.

Input

{{ "hello" | slice: 0 }}
{{ "hello" | slice: 1 }}
{{ "hello" | slice: 1, 3 }}

Output

h
e
ell

split

The split filter takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array filters.

Input

{% assign words = "Hi, how are you today?" | split: ' ' %}
{% for word in words %}
{{ word }}
{% endfor %}

Output

Hi,
how
are
you
today?

strip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the beginning and end of a string

Input

"{{ '   too many spaces      ' | strip }}"
"{{ '   too many dots...' | strip: "." }}"

Output

"too many spaces"
"   too many dots"

lstrip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the beginning of a string

Input

"{{ '   too many spaces           ' | lstrip }}"
"{{ '...too many dots.............' | lstrip: "." }}"

Output

"too many spaces           "
"too many dots............."

rstrip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the end of a string

Input

"{{ '              too many spaces      ' | rstrip }}"
"{{ '..............too many dots........' | rstrip: "." }}"

Output

"              too many spaces"
"..............too many dots"

strip_html

Strips all HTML tags from a string.

Input

{{ "<h1>Hello</h1> World" | strip_html }}

Output

Hello World

strip_newlines

Removes any line breaks/newlines from a string.

Input

{{ product.description | strip_newlines }}

truncate

Truncates a string down to 'x' characters, where x is the number passed as a parameter. An ellipsis (...) is appended to the string and is included in the character count.

Input

{{ "The cat came back the very next day" | truncate: 10 }}

Output

The cat...

truncatewords

Truncates a string down to 'x' words, where x is the number passed as a parameter. An ellipsis (...) is appended to the truncated string.

Input

{{ "The cat came back the very next day" | truncatewords: 4 }}

Output

The cat came back...

uniq

Removes any duplicate instances of an element in an array.

Input

{% assign fruits = "orange apple banana apple orange" %}
{{ fruits | split: ' ' | uniq | join: ' ' }}

Output

orange apple banana

upcase / upper

Converts a string into uppercase.

Input

{{ 'i want this to be uppercase' | upcase }}

Output

I WANT THIS TO BE UPPERCASE

url_escape

Identifies all characters in a string that are not allowed in URLS, and replaces the characters with their escaped variants.

Input

{{ "<hello> & <shopify>" | url_escape }}

Output

%3Chello%3E%20&%20%3Cshopify%3E

url_param_escape

Replaces all characters in a string that are not allowed in URLs with their escaped variants, including the ampersand (&).

Input

{{ "<hello> & <shopify>" | url_param_escape }}

Output

%3Chello%3E%20%26%20%3Cshopify%3E

reverse

Reverses a sequence, a mapping, or a string.

For sequences and mappings, numeric keys are not preserved. To reverse them as well, pass true as an argument to the reverse filter:

Input

{{ "reverse me"|reverse }}
{{ "1<2<3<4"|split:"<"|reverse|join:">"|raw }}

Output

em esrever
4>3>2>1

format

Formats a given string by replacing the placeholders (placeholders follows the sprintf notation)

Input

{{ "I like %s and %s."|format("apples", "oranges") }}

Output

I like apples and oranges.

Math Filters

abs

Returns the absolute value.

Input

{{ -4.6 | abs }}
{{ 6 | abs }}

Output

4.6
6

ceil

Rounds an output up to the nearest integer.

Input

{{ 4.6 | ceil }}
{{ 4.3 | ceil }}

Output

5
5

divided_by

Divides an output by a number. The output is rounded down to the nearest integer.

Input

<!-- product.price = 200 -->
{{ product.price | divided_by: 10 }}

Output

20

floor

Rounds an output down to the nearest integer.

Input

{{ 4.6 | floor }}
{{ 4.3 | floor }}

Output

4
4

minus

Subtracts a number from an output.

Input

<!-- product.price = 200 -->
{{ product.price | minus: 15 }}

Output

185

plus

Adds a number to an output.

Input

<!-- product.price = 200 -->
{{ product.price | plus: 15 }}

Output

215

round

Rounds the output to the nearest integer or specified number of decimals.

Input

{{ 4.6 | round }}
{{ 4.3 | round }}
{{ 4.5612 | round: 2 }}

Output

5
4
4.56

times

Multiplies an output by a number.

Input

<!-- product.price = 200 -->
{{ product.price | times: 1.15 }}

Output

230

modulo

Divides an output by a number and returns the remainder.

Input

{{ 12 | modulo: 5 }}

Output

2

HTML Filters

image_tag

Generates an image tag.

Input

{{ 'smirking_gnome.gif' | asset_url | img_tag }}

Output

<img src="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/39baaafe-97bf-11e5-b255-0a6afe88c81b.jpg" alt="" />

script_tag

Generates a script tag.

Input

{{ 'shop.js' | asset_url | script_tag }}

Output

<script src="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/350b7b27-8e01-11e5-b255-0a6afe88c81b.js" type="text/javascript"></script>

stylesheet_tag

Generates a stylesheet tag.

Input

{{ 'shop.css' | asset_url | stylesheet_tag }}

Output

<link href="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/2eecc09f-97c0-11e5-b255-0a6afe88c81b.css" rel="stylesheet" type="text/css" media="all" />

Internationalisation Filters

t

The translation filter retrieves the translated content from the locale file for the active language.
Passing count to the t filter allows custom pluralisation. Supported pluralization keys are:

  • zero
  • one
  • two
  • other

Input

{% if customer %}
<h1>{{ 'customer.orders.order_count' | t: count: customer.orders_count }}</h1>
{% endif %}

locales/en.default.json
{
    "customer": {
    "orders": {
        "order_count": {
            "zero": "Looks like you haven't made any orders yet",
            "one": "You've made one order with us",
            "other": "You've made {{ count }} orders with us"
        }
    }
  }
}

Output

// count = 1
<h1>You've made one order with us</h1>

// count = 12
<h1>You've made 12 orders with us</h1>

URL Filters

img_url

Returns the URL of an image. Accepts an image size as a parameter. The img_url filter can be used on the following objects:
product

Input

 {{ product | img_url: 'small' }}

Output

 https://s3.amazonaws.com/vend-images/product/ss/2/6/26c907f60c9fe73fb16effd3ffbeada94f767004.png

Parameters: image sizes

tiny:

Returns the image at a maximum size of 40 by 40 pixels.

small:

Returns the image at a maximum size of 50 by 50 pixels.

medium:

Returns the image at a maximum size of 100 by 100 pixels.

large:

Returns the image at a maximum size of 150 by 150 pixels.

thumb:

Returns the image at a maximum size of 160 by 160 pixels.

standard:

Returns the image at a maximum size of 350 by 350 pixels.

original:

Returns the image at a maximum size of 1920 by 1920 pixels.

within

Creates a collection-aware product URL by prepending /collections/collection-handle to a product URL, where collection-handle is the handle of the collection that is currently being viewed.

Input

<a href="{{ product.url | within: collection }}">{{ product.title }}</a>

Output

<a href="/collections/frontpage/products/alien-poster">Alien Poster</a>

asset_url

Returns the URL of a file in the "assets" folder of a theme.

Input

{{ 'shop.css' | asset_url }}

Output

https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/34f08c6c-8e01-11e5-b255-0a6afe88c81b.css

link_to

Generates an HTML link.

Input

{{ 'Vend' | link_to: 'https://www.vendhq.com' }}

Output

<a href="https://www.vend.hqcom">Vend</a>

Additional Filters

json

Converts a value into JSON format.

Input

{{ ["dog", "cat"]|json|raw }}
{{ product|json|raw }}

Output

["dog","cat"]
{"name":"Product One"}

default

Returns the passed default value if the value is undefined or empty, otherwise the value of the variable

Input

Dear {{ customer.name | default: "customer" }}

Output

<!-- If customer.name is nil -->
Dear customer

<!-- If customer.name is "" -->
Dear customer

<!-- If customer.name is "   " -->
Dear

date

Converts a timestamp into another date format. The format specifier is the same as supported by date. Timezone can be specified via second parameter, by default UTC timezone is used.

Input

{{ "now"|date:"m/d/Y H:i:s" }}
{{ "now"|date:"m/d/Y H:i:s", "Europe/Paris" }}

Output

01/05/2016 03:21:03
01/05/2016 04:21:55

date_modify

Modifies a date with a given modifier string

Input

{{ post.published_at|date:"m/d/Y" }}
{{ post.published_at|date_modify:"+1 day"|date:"m/d/Y" }}

Output

12/31/2015
01/01/2016

number_format

Formats numbers in a same was as number_format function.

Input

{{ 200.35|number_format }}
{{ 9800.333|number_format:"2", '.', ',' }}

Output

9,800
9,800.33

Array Filters

Also see article "Theme Objects \ Array" for dot notation in cases where it needs to be used inside a tag.

batch

The batch filter "batches" items by returning a list of lists with the given number of items. A second parameter can be provided and used to fill in missing items.

Input

{% for row in collection.products|batch:2 %}
  {% for product in row %}
      {{ product.name }}<br />
  {% endfor %}
  <hr />
{% endfor %}

Output

Product 1
Product 2
---------------------
Product 3
Product 4
---------------------

first

Returns the first element of an array.

Input

<!-- product.tags = "sale", "mens", "womens", "awesome" -->
{{ product.tags | first }}

Output

sale

last

Gets the last element passed in an array.

Input

<!-- product.tags = "sale", "mens", "womens", "awesome" -->
{{ product.tags | last }}

Output

awesome

join

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

Input

{{ [1, 2, 3]|join }}
{{ product.tags | join: ', ' }}

Output

123
tag1, tag2, tag3

keys

Returns the keys of an array. It is useful when you want to iterate over the keys of an array

Input

{{ "a":1,"b":2,"c":3}|keys|join }}

Output

123

length / size

Returns the size of a string or an array.

Input

{{ collection.products | size }}
{{ 'is this a 30 character string?' | size }}

Output

5
30

sort

Sorts an array.

Input

{{ ['a','c','A','b']|sort|join }}

Output

Aabc