Introduction

Looking to customize a Big Cartel store or build a custom theme? You’re in the right place! Whether you’re just getting started or an experienced coder, we’ve got everything you need here to build a great theme and make your vision a reality: the basic anatomy of a theme, how our template language works, complete variable and filter documentation, and some sample code to get you on the right track.

Getting Started

A Big Cartel theme consists of 9 built-in pages and is made up of HTML, CSS, Javascript, and a combination of filters and variables. All changes to a store’s theme will need to be made in the Customize Design section of the admin, but if you’re a more advanced coder we’d love for you to check out Dugway to develop and test your theme locally.

Not a coder? If you’re looking for themes to install in your store, or general theme customization tips, check out our customization article »

Page	Description
`Layout`	The main store template.
`Cart`	Where customers can see the contents of their cart and proceed to the checkout.
`Contact`	A built in contact page.
`Home`	The store’s Home page.
`Maintenance`	The page visitors will see when a store is in Maintenance Mode.
`Product`	The individual product page.
`Products`	The page where visitors can see all products and categories.

The Layout page is the most important of all of these, and you can think of it as a master template that all store pages live inside. Any content that you need displayed throughout the entire store — a header, navigation, logo, etc will go in here. We also require that you include some important variables to make sure your store functions properly: {{ head_content }}, which goes inbetween the <head> HTML tags, and {{ page_content }} inside <body>. Here’s what that looks like inside a simple, stripped down HTML template:

{{ head_content }} loads important system code from our server, while {{ page_content }} will display the content for the current page being viewed - such as product details on the individual Product page.

You’ll also notice there’s a line in the above code to load a CSS file. We’ll take care of hosting your theme’s CSS, which can be edited in Customize Design > Advanced > CSS. You’ll then want to make sure you call this in the <head> HTML tags like the example above.

We don’t offer hosting for any separate javascript files though, so if your theme requires any javascript you’ll need to have load it from an external website or include it directly inside your page content.

<html>
  <head>
    <title>{{ page.name }} | {{ store.name }}</title>
    <link href="{{ theme | theme_css_url }}" media="screen" rel="stylesheet" type="text/css">
    {{ head_content }}
  </head>
  <body>
    <h1>{{ page.name }}</h1>
    <div>{{ page_content }}</div>
  </body>
</html>

Dugway

If you’re building a new theme or doing a major overhaul to your existing theme, you should definitely check out Dugway. This fancy little tool allows you to build a Big Cartel theme (or run any of our default themes) locally on your computer, test it in any browser, and you can make changes to a theme using your favorite code editor. It also supports tools like CoffeeScript, Sass, and LESS. We’ve got more information on how to install Dugway and start creating a theme over at: github.com/bigcartel/dugway

Theme Help

Have a question about building a Big Cartel theme, how to use certain variables/filters, or stuck with a tricky coding issue? Head over to Stack Overflow – it’s a great question and answer site for programmers. Just be sure to include the bigcartel tag when asking a question to get answers from programmers and members of the Big Cartel team: http://stackoverflow.com/questions/tagged/bigcartel

Syntax

Our theme template language consists of variables and filters. Variables are the individual pieces of data about different aspects of your store, like product details and cart information. Filters are simple methods to format or manipulate output, like capitalizing words or modifying the size of an image. We’ve provided complete documentation for filters and variables below.

If, Else, and Elsif

These tags show output for different conditions. The opposite of if is unless. You can use and and or to combine conditions.

{% if store.website != blank %}
  <a href="{{ store.website }}">Back to Site</a>
{% endif %}

{% if product.on_sale %}
  On Sale!
{% else %}
  Regular price
{% endif %}

{% if product.images == empty %}
  Just use your imagination
{% endif %}

{% if product.price > 100 %}
  This is pretty expensive
{% elsif product.price > 50 %}
  This is a little expensive
{% endif %}

{% if cart.shipping.enabled %}
  Shipping: {{ cart.shipping.amount | money_with_sign }}
{% endif %}

{% unless cart.item_count == 0 %}
  Start shopping!
{% endunless %}

# colors = ['red','blue','green']
{% if colors contains 'blue' %}
   It's blue!
{% endif %}

{% if page.full_url contains '/category/mens' %}
   Men's wear!
{% endif %}

Case Statement

These tags let you handle multiple conditions.

{% case product.status %}

{% when 'active' %}
  Buy me!
{% when 'coming-soon' %}
  Buy me soon!
{% when 'sold-out' %}
  You already bought me!
{% endcase %}

For Loops

These tags allow you to loop over collections, like a list of products or items in the cart.

{% for product in products.featured %}
  Product: {{ product.name }}
{% endfor %}

{% for item in cart.items %}
  Item: {{ item.name }}
{% endfor %}

During every for loop there are a few helper variables available.

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

Narrow down the items inside your loop with limit and offset.

{% for image in product.images limit:2 %}
  Show two images: {{ image.url }}
{% endfor %}

{% for product in products offset:1 %}
  Skip first product: {{ product.name }}
{% endfor %}

Loop over a range of both literal or variable numbers.

{% for i in (1..cart.item_count) %}
  Item number {{ i }}
{% endfor %}

Use the else tag when nothing exists in the collection.

{% for product in products.all %}
  <div {% if forloop.first %}class="first"{% endif %}>
    Product {{ forloop.index }}: {{ product.name }}
  </div>
{% else %}
  No products were found.
{% endfor %}

Cycle

These tags let you alternate between a set of values. Commonly used to alternate between colors to zebra stripe rows.

{% cycle 'one', 'two', 'three' %}

{% for item in cart.items %}
  <li class="{% cycle 'odd', 'even' %}">{{ product.name }}</li>
{% endfor %}

Raw

You can disable tag processing by using the raw tag.

{% raw %}
  Display text inside curly brackets like {{ this }} on a page with `raw`
{% endraw %}

Variable Assignment

These tags let you store data in your own variables to be used in output or other tags. The easiest way is with the assign tag.

{% assign looking_for = 'Tees' %}
{% for category in categories.all %}
  {% if category.name == looking_for %}
    It's a match!
  {% endif %}
{% endfor %}

Combine a number of strings into one variable by using the capture tag. These are blocks that “capture” whatever is rendered inside and assign it to the given variable.

<ul>
  {% for category in categories %}
    {% capture css_id %}category_{{ category.permalink }}_{{ forloop.index }}{% endcapture %}
    <li id="{{ css_id }}" class="{{ css_id }}">{{ category.name }}</li>
  {% endfor %}
</ul>

Variables

Variables are the individual pieces of data about different aspects of your store. You can use these variables in your code to display specific information. To use variables, wrap them in two curly brackets on either side.

My store is called {{ store.name }}

This image is {{ image.width }} pixels wide

<a href="{{ page.url }}">My Page</a>

Cart

Used to display information about the buyer’s cart.

Variable	Description
`cart.item_count`	Returns the number of items in the cart.
`cart.subtotal`	Returns the combined price for all items in your cart, before shipping, tax, or discounts.
`cart.total`	Returns the combined price, shipping, tax, and discounts for all items in your cart.
`cart.items`	Returns all of the items in your cart.

Cart Item

Used to display information on each item in the cart. Iterate through them with a for loop.

Variable	Description
`item.id`	Returns the id of an item.
`item.name`	Returns the name of an item. This is done by combining the name of the product and name of the option, unless it’s a default option.
`item.price`	Returns the price of an item multiplied by it’s quantity.
`item.unit_price`	Returns the price of for one of an item.
`item.shipping`	Returns the shipping amount of an item, if you’re using Big Cartel’s shipping features.
`item.total`	Returns the total price and shipping amount of an item.
`item.quantity`	Returns the quantity in the cart for an item.
`item.product`	Returns the product of an item.
`item.option`	Returns the option of an item.

Variable	Description
`category.id`	Returns the id of a category.
`category.name`	Returns the name of a category.
`category.permalink`	Returns the permalink of a category.
`category.url`	Returns the URL of a category.
`category.products`	Returns all of the products of a category.
`categories.all`	Returns all of the categories in your store.
`categories.active`	Returns all of the categories that are currently in use by one or more products.
`categories.permalink`	Returns a specific category based on it’s permalink.

Contact

Used on a store’s built-in Contact page to build your contact form, and display a message after the form is submitted.

Variable	Description
`contact.name`	Returns the name entered in the contact form.
`contact.email`	Returns the email address entered in the contact form.
`contact.subject`	Returns the subject entered in the contact form.
`contact.message`	Returns the message entered in the contact form.
`contact.captcha`	Returns a unique captcha to fight spam for the contact form. Note: deprecated in favor of contact.recaptcha
`contact.recaptcha`	Inserts javascript code for Google reCAPTCHA, CSS to hide the badge, and a required message indicating the contact form is protected by Google reCAPTCHA.
`contact.sent`	Returns true or false based on whether the the contact form was successfully sent.

Country

Used to retrieve information about countries from the Big Cartel shipping settings.

Variable	Description
`country.name`	Returns the name of a country.
`country.code`	Returns the code of a country.

Image

Used for retrieving information on theme or product images.

Variable	Description
`image.url`	Returns the URL of an image.
`image.width`	Returns the width of an image.
`image.height`	Returns the height of an image.

Page

Used for retrieving information on custom pages.

Variable	Description
`page.id`	Returns the id of a page.
`page.name`	Returns the name of a page.
`page.content`	Returns the content of a page.
`page.category`	Returns the type of page. “custom” or “theme”.
`page.permalink`	Returns the permalink of a page.
`page.url`	Returns the URL of a page.
`page.full_url`	Returns the absolute URL of a page.
`page.full_path`	Returns the path as well as any query parameters of the page.
`pages.all`	Returns all of the custom pages in your store.
`pages.permalink`	Returns a specific page based on it’s permalink.

Product

Used to retrieve all details on a given product.

Variable	Description
`product.id`	Returns the id of a product.
`product.name`	Returns the name of a product.
`product.permalink`	Returns the permalink of a product.
`product.url`	Returns the URL of a product.
`product.edit_url`	Returns the URL to edit a product in the admin.
`product.position`	Returns the position of a product in your product list.
`product.description`	Returns the description of a product.
`product.status`	Returns the status of a product. “active”, “sold-out”, or “coming-soon”.
`product.created_at`	Returns the date the product was first created.
`product.categories`	Returns all of the categories of a product.
`product.css_class`	Returns the css_class of a product. “product”, “product sold”, “product soon”, or “product sale”.
`product.default_price`	Returns the default price of a product.
`product.variable_pricing`	Returns true if any option has a price that differs from the default price, false otherwise.
`product.min_price`	Returns the minimum price of a product and it’s options.
`product.max_price`	Returns the maximum price of a product and it’s options.
`product.on_sale`	Returns true or false based on whether the product is marked as on sale.
`product.has_default_option`	Returns true if the product has no custom options configured. False otherwise.
`product.has_option_groups`	Returns true if the product has option groups.
`product.option`	Returns the default option of a product.
`product.options`	Returns all of the options of a product whether they are sold out or not.
`product.options_in_stock`	Returns all of the options of a product that are in stock. If you’re not using Big Cartel’s inventory tracking, then this is the same as calling product.options.
`product.shipping`	Returns all of the shipping areas of a product.
`product.image`	Returns the default image of a product.
`product.images`	Returns all of the images of a product.
`product.image_count`	Returns the number of images a product has.
`product.previous_product`	Return the previous product in your list.
`product.next_product`	Return the next product in your list.
`products.all`	Returns all of the products in your store.
`products.current`	Returns all of the products for the current Products page.
`products.on_sale`	Returns all of the products in your store that are marked “on sale”.
`products.permalink`	Returns a specific product based on it’s permalink.

Product Option

Used for retrieving options that have been added to a given product.

Variable	Description
`option.id`	Returns the id of an option.
`option.name`	Returns the name of an option.
`option.price`	Returns the price of the product option, if set, or the price of the parent product.
`option.has_custom_price`	Returns true if this product option has a price set that’s different than the parent product, false otherwise.
`option.position`	Returns the position of an option in a product’s option list.
`option.sold`	Returns the number of times an option has been sold.
`option.sold_out`	Returns true or false based on whether the option is sold out. If you’re not using Big Cartel’s inventory tracking, then this is always true.
`option.quantity`	Returns the quantity left in stock for an option.
`option.inventory`	Returns the remaining inventory percentage of an option.
`option.default`	Returns true or false based on whether the option is the product’s default option.

Product Shipping Area

Used for retrieving information on shipping areas from the Big Cartel shipping settings.

Variable	Description
`area.name`	Returns the name of a shipping area. Must be used with the shipping_name filter.
`area.amount_alone`	Returns the shipped alone amount of a shipping area.
`area.amount_with_others`	Returns the with others amount of a shipping area.
`area.country`	Returns the country of a shipping area. Only applicable if you have country based shipping.

Store

Used for retrieving store information that’s set on the Settings page of your admin.

Variable	Description
`store.name`	Returns the name of your store.
`store.description`	Returns the description of your store.
`store.host`	Returns the hostname of your store (e.g. `myshop.bigcartel.com`). This will use your custom domain if you have it setup.
`store.url`	Returns the URL of your store (e.g. `https://myshop.bigcartel.com`). This will use your custom domain if you have it setup.
`store.website`	Returns the URL of your store’s primary website that you’ve added to your shop info.
`store.currency.name`	Returns the name of the currency used for your store.
`store.currency.code`	Returns the code of the currency used for your store.
`store.currency.sign`	Returns the sign of the currency used for your store.
`store.country`	Returns the country of your store.

Filters

Filters are simple methods to format or manipulate output. The first parameter is your starting value, and it runs from left to right through one or more filters separated by bars.

{{ product.price | money_with_sign }}

{{ page.name | capitalize | truncate }}

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

size

Returns the size of an array or string.

Parameters

None.

{% assign my_array = 'Small|Medium|Large' | split: '|' %}
{{ my_array | size }} # => 3

join

Joins elements of an array with a connector.

Parameters

Name	Type	Default	Description
`connector`	string	” “	String to connect items with.

{{ options | join: ', ' }} # => "Small, Medium, Large"

sort

Sorts the elements of an array.

Parameters

None.

{% assign my_array = '1|3|2|4' | split: '|' %}
{{ my_array | sort | join: ', ' }} # => 1, 2, 3, 4

first

Returns the first element of an array.

Parameters

None.

{% assign my_array = 'Small|Medium|Large' | split: '|' %}
{{ my_array | first }} # => Small

last

Returns the last element of an array.

Parameters

None.

{% assign my_array = 'Small|Medium|Large' | split: '|' %}
{{ my_array | last }} # => Large

minus

Subtracts two numbers.

Parameters

Name	Type	Default	Description
`number_to_subtract`	integer	nil	Number to subtract.

{{ option.sold | minus: option.quantity }}

plus

Adds two numbers.

Parameters

Name	Type	Default	Description
`number_to_add`	integer	nil	Number to add.

{{ option.sold | plus: option.quantity }}

times

Multiplies two numbers.

Parameters

Name	Type	Default	Description
`number_to_multiply`	integer	nil	Number to multiply.

{{ 4 | times: 3 }} # => 12

divided_by

Divides a number by another number.

Parameters

Name	Type	Default	Description
`number_to_divide_by`	integer	nil	Number to divide by.

{{ 10 | divided_by: 2 }} # => 5

modulo

Calculates a remainder with division.

Parameters

Name	Type	Default	Description
`number_to_divide_by`	integer	nil	Number to divide by.

{{ 3 | modulo: 2 }} # => 1

num_lt

Returns true or false if a number is less than the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

{{ 3 | num_lt: 2 }} # => false

num_lte

Returns true or false if a number is less than or equal to the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

{{ 3 | num_lte: 3 }} # => true

num_gt

Returns true or false if a number is greater than the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

{{ 10 | num_gt: 2 }} # => true

num_gte

Returns true or false if a number is greater than or equal to the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

{{ 1 | num_gte: 2 }} # => false

num_eq

Returns true or false if a number is equal the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

{{ 10 | num_eq: 2 }} # => false

money

Formats a number into money format.

Parameters

Name	Type	Default	Description
`format`	string	nil	Can be “sign”, “code”, or “sign_and_code”

{{ 1 | money }} # => 1.00
{{ product.price | money }} # => 9.50
{{ product.price | money: 'sign' }} # => $9.50
{{ product.price | money: 'code' }} # => 9.50 USD
{{ product.price | money: 'sign_and_code' }} # => $9.50 USD

money_with_sign

Formats a number into money format, and adds your currency sign. Set on the Settings page of the admin.

Parameters

None.

{{ 1 | money_with_sign }} # => $1.00
{{ product.price | money_with_sign }} # => $9.50

money_with_code

Formats a number into money format, and adds your currency code. Set on the Settings page of the admin.

Parameters

None.

{{ 1 | money_with_code }} # => 1.00 USD
{{ product.price | money_with_code }} # => 9.50 USD

money_with_sign_and_code

Formats a number into money format, and adds your currency sign and code. Set on the Settings page of the admin.

Parameters

None.

{{ 1 | money_with_sign_and_code }} # => $1.00 USD
{{ product.price | money_with_sign_and_code }} # => $9.50 USD

font_family

Returns the full font family for a given base font. Ex: “Verdana” returns “Verdana, Arial, Helvetica, sans-serif”.

Parameters

None.

body { font-family: {{ theme.font | font_family }}; }

default_pagination

Creates pagination links (1 2 3 … 5) for the given paginate object.

Parameters

Name	Type	Default	Description
`id`	string	“pagination”	Element id.
`class_name`	string	“pagination”	Element class name.
`prev_label`	string	“« Previous”	Text of previous link.
`next_label`	string	“Next »”	Text of next link.

{% paginate products from products.current by 10 %}
  {% if products != blank %}
    <ul class="product_list">
      {% for product in products %}
        <li class="product">
          <a title="{{ product.name }}" href="{{ product.url }}">{{ product.name }}</a>
        </li>
      {% endfor %}
    </ul>
    {{ paginate | default_pagination, 'paginate_id' , 'paginate_class' , 'previous page' , 'next page'  }}
  {% else %}
    <p>No products found.</p>
  {% endif %}
{% endpaginate %}

shipping_name

Returns the name of a shipping area. If the shipping area is a for a country, it will use the country’s name. Otherwise it will use everywhere if it’s the only shipping option, and everywhere_else if there are multiple shipping areas.

Parameters

Name	Type	Default	Description
`everywhere`	string	“Everywhere”	Text for “everywhere” case.
`everywhere_else`	string	“Everyone else”	Text for “everywhere else” case.

{% for area in product.shipping %}
<p>{{ area | shipping_name }}</p>
{% endfor %}

hidden_option_input

Returns a hidden form input for the given option to be added to the cart. Useful for when there is only one default option.

Parameters

Name	Type	Default	Description
`id`	string	“option”	Element id.
`class_name`	string	””	Element class name.

{% if product.has_default_option %}
{{ product.option | hidden_option_input }}
{% endif %}

options_select

Returns a select combobox for the given options to be added to the cart.

Parameters

Name	Type	Default	Description
`id`	string	“option”	Element id.
`class_name`	string	””	Element class name.

{{ product.options_in_stock | options_select }}

options_radio

Returns an unordered list of radio buttons for the given options to be added to the cart.

Parameters

Name	Type	Default	Description
`id`	string	“option”	Element id.
`class_name`	string	””	Element class name.

{{ product.options_in_stock | options_radio }}

product_quantity_input

Returns a text input for the given product to specify what quantity to add to the cart.

Parameters

Name	Type	Default	Description
`quantity`	integer	1	Quantity to add to cart.
`id`	string	“quantity_product.id”	Element id.
`class_name`	string	””	Element class name.

Quantity: {{ product | product_quantity_input }}

item_quantity_input

Returns a text input for the given option to update it’s quantity on the Cart page.

Parameters

Name	Type	Default	Description
`id`	string	“item_item.id_qty”	Element id.
`class_name`	string	””	Element class name.

Enter quantity: {{ item | item_quantity_input }}

contact_input

Returns a text input for the given contact field. Note: these filters will only work on the built-in Contact page.

Parameters

Name	Type	Default	Description
`field`	string	nil	Must be “name”, “email”, “subject”, “message”, or “captcha”.
`id`	string	matches field	Element id.
`class_name`	string	””	Element class name.

Name: {{ contact | contact_input: 'name' }}
Email: {{ contact | contact_input: 'email' }}
Subject: {{ contact | contact_input: 'subject' }}
Message: {{ contact | contact_input: 'message' }}
Spam Check: {{ contact.captcha }}
Enter the letters from the above image: {{ contact | contact_input: 'captcha' }}

downcase

Converts a string to lower case.

Parameters

None.

{% assign my_variable = 'Hello World' %}
{{ my_variable | downcase }} => hello world

upcase

Converts a string to upper case.

Parameters

None.

{% assign my_variable = 'Hello World' %}
{{ my_variable | upcase }} => HELLO WORLD

capitalize

Capitalizes words in a string.

Parameters

None.

{% assign my_variable = 'hello world' %}
{{ my_variable | upcase }} => Hello World

escape

Removes special characters from a string. Useful for outputting attributes in HTML.

Parameters

None.

<a href="{{ product.url }}" title="View {{ product.name | escape }}">{{ product.name }}</a>

pluralize

Returns the singular version of a word if there are one, and the plural version otherwise.

Parameters

Name	Type	Default	Description
`count`	integer	nil	The number of items.
`singular`	string	nil	The singular name of the item.
`plural`	string	nil	The plural name of the item.

You have {{ cart.item_count | pluralize: 'item', 'items' }} in your cart!

truncate

Trims a string down to the length you specify.

Parameters

Name	Type	Default	Description
`length`	integer	50	The number of characters to allow.
`truncate_string`	string	“…”	How to end a truncated string.

{{ product.name | truncate: 18 }} # => "Once upon a ti..."

truncatewords

Trims a string down to the length you specify.

Parameters

Name	Type	Default	Description
`length`	integer	15	The number of words to allow.
`truncate_string`	string	“…”	How to end a truncated string.

{{ product.name | truncatewords: 4 }} # => "Once upon a time..."

strip_html

Removes all HTML tags from a string.

Parameters

None.

strip_newlines

Removes all newlines (returns) from a string.

Parameters

None.

newline_to_br

Converts newlines (returns) into <br /> tags.

Parameters

None.

paragraphs

Converts newlines (returns) into <br /> tags and consecutive newlines into <p> tags.

Parameters

None.

replace

Replaces all occurrences of a string with another string.

Parameters

Name	Type	Default	Description
`string_to_find`	string	nil	The string to search for.
`replacement_string`	string	nil	The string to replace it with.

{{ product.description | replace: "hello", "goodbye" }}

replace_first

Same as replace, but only replaces the first occurrence.

Parameters

Name	Type	Default	Description
`string_to_find`	string	nil	The string to search for.
`replacement_string`	string	nil	The string to replace it with.

remove

Removes all occurrences of a given string.

Parameters

Name	Type	Default	Description
`string_to_remove`	string	nil	The string to remove.

remove_first

Same as remove, but only removes the first occurrence.

Parameters

Name	Type	Default	Description
`string_to_remove`	string	nil	The string to remove.

prepend

Adds a string to the beginning of another string.

Parameters

Name	Type	Default	Description
`string_to_prepend`	string	nil	The string to prepend.

append

Adds a string to the end of another string.

Parameters

Name	Type	Default	Description
`string_to_append`	string	nil	The string to append.

date

Formats a date.

Parameters

Name	Type	Default	Description
`format`	string	nil	The date format to use.

%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

link_to

Creates a link to any page, product, or category.

Parameters

Name	Type	Default	Description
`text`	string	item’s name	The link’s text.
`title`	string	“View {{ item.name}}”	The link’s title attr.
`id`	string	nil	The link’s title attr.
`class`	string	nil	The link’s class attr.
`rel`	string	nil	The link’s rel attr.

{{ page | link_to }}
{{ product | link_to: 'My Product' }}
{{ category | link_to: 'Tees', 'View tees category', 'tees_category', 'categories' }}

product_image_url

Returns the URL of the specified product image and size. Pro-tip: instead of using the pre-made sizes, use the constrain filter for a custom image size.

Parameters

Name	Type	Default	Description
`size`	string	nil	Can be “thumb” (75x75), “medium” (175x175), “large” (300x300), or blank (1000x1000).

<img src="{{ product.image | product_image_url 'large' }}">

theme_js_url

Returns the URL of a JavaScript file used by a specific theme. Use this over calling the URLs directly.

Parameters

None.

<script src="{{ 'prototype' | theme_js_url }}" type="text/javascript"></script>
<script src="{{ 'api' | theme_js_url }}" type="text/javascript"></script>

theme_css_url

Returns the URL of your custom CSS StyleSheet.

Parameters

None.

<link href="{{ theme | theme_css_url }}" media="screen" rel="stylesheet" type="text/css">

theme_image_url

Returns the URL of an image file used by a specific theme. Use this instead of direct URLs.

Parameters

None.

#website_back {
  background-image: url({{ 'btn_website.png' | theme_image_url }});
}

constrain

Modifies the URL of any product or theme image to constrain the size to any width and/or height. When constraining an image using both width and height, the image is scaled down to the largest possible width and height that will fit the dimensions you provided while maintaing its aspect ratio.

Parameters

Name	Type	Default	Description
`width`	string	nil	The desired image width. Use “-“ to skip.
`height`	string	nil	The desired image height. Use “-“ or leave blank to skip.

Constrain an image based on width only:

<img src="{{ product.image | product_image_url | constrain: '800' }}">
background-image: url("{{ theme.background_image.url | constrain: '100' }}");

Constrain an image based on height only:

<img src="{{ product.image | product_image_url | constrain: '-', '800' }}">
background-image: url("{{ theme.background_image.url | constrain: '-', '100' }}");

Constrain an image based on width AND height:

<img src="{{ product.image | product_image_url | constrain: '800', '800' }}">
background-image: url("{{ theme.background_image.url | constrain: '100', '100' }}");

JavaScript API

Our JavaScript API returns variables in JSON format, allowing you to use Ajax requests to update/retrieve store data. Our API is 100% standalone and requires no other libraries.

Just drop the following line of code into your store’s HTML. Keep in mind that this code will only work in your store, and not any external websites.

<script src="{{ 'api' | theme_js_url }}"></script>

Product.find

Returns a product based on the given permalink.

Parameters

Name	Type	Default	Description
`permalink`	string	null	The product permalink.
`callback`	function	null	Your callback function.

Product.find('my-tee', function(product) {
  console.log("I found " + product.name + "!");
});

Product.findAll

Returns an array of all products.

Parameters

Name	Type	Default	Description
`params`	object	{}	Can contain `limit` count, `page` number, and `category` permalink.
`callback`	function	null	Your callback function.

Product.findAll({}, function(products) {
  console.log("I found " + products.length + " products!");
});

Product.findAll({ category: 'tees' }, function(products) {
  console.log("I found " + products.length + " tees!");
});

Product.search

Returns an array of all products that match the specified search term. Most of the parameters from findAll will work as well.

Parameters

Name	Type	Default	Description
`term`	string	null	The search term.
`params`	object	{}	Can contain `limit` count, `page` number, and `category` permalink.
`callback`	function	null	Your callback function.

Product.search('shirt', {}, function(products) {
  console.log("I found " + products.length + " products!");
});
Product.search('shirt', { limit: 5 }, function(products) {
  console.log("I found " + products.length + " shirts!");
});

Product.findImage

Returns the URL of an image with the given size. Works just like the product_image_url filter.

Parameters

Name	Type	Default	Description
`url`	string	null	The image URL.
`size`	string	null	Can be “thumb” (75x75), “medium” (175x175), “large” (300x300), or blank (1000x1000).

Product.findImage(product.image, 'thumb');

Cart.refresh

Returns the current cart variable.

Parameters

Name	Type	Default	Description
`callback`	function	null	Your callback function.

Cart.refresh(function(cart) {
  console.log("I've got " + cart.item_count + " items in the cart!");
});

Cart.updateFromForm

Submits a specific form ID to add, update, or remove items from the cart.

Parameters

Name	Type	Default	Description
`form_id`	string	null	The id of your form element.
`callback`	function	null	Your callback function.

Cart.updateFromForm('cart_form', function(cart) {
  console.log("Cart updated!");
});

Cart.addItem

Adds a particular option.id to the cart with the desired quantity (1 by default).

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`quantity`	integer	1	The number to add to the cart.
`callback`	function	null	Your callback function.

Cart.addItem(1234, 1, function(cart) {
  console.log("Item added!");
});

Cart.updateItem

Updates a particular item.id in the cart with the desired quantity.

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`quantity`	integer	1	The number to update the cart with.
`callback`	function	null	Your callback function.

Cart.updateItem(1234, 10, function(cart) {
  console.log("Item updated!");
});

Cart.removeItem

Removes a given item.id from the cart.

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`callback`	function	null	Your callback function.

Cart.removeItem(1234, function(cart) {
  console.log("Item removed!");
});

Format.money

Formats a number into the proper format for a store’s currency, similar to the money filters. The sign and code will be wrapped in <span> tags.

Parameters

Name	Type	Default	Description
`number`	integer	null	The number to convert.
`with_delimiter`	boolean	false	Whether to include a delimiter.
`with_sign`	boolean	false	Whether to include a sign.
`with_code`	boolean	false	Whether to include a code.

Format.money(9.3); // "9.30"
Format.money(1000); // "1000.00"
Format.money(1000, true); // "1,000.00"
Format.money(1000, true, true); // "$1,000.00"
Format.money(1000, true, true, true); // "$1,000.00 USD"

Format.pluralize

Returns the singular version of a word if there is one, and the plural version otherwise.

Parameters

Name	Type	Default	Description
`count`	integer	nil	The number of items.
`singular`	string	nil	The singular name of the item.
`plural`	string	nil	The plural name of the item.

Format.pluralize(1, 'dog', 'dogs'); // "1 dog"
Format.pluralize(2, 'dog', 'dogs'); // "2 dogs"

Format.queryString

Returns a URL-encoded string containing the hash’s contents as query parameters.

Parameters

Name	Type	Default	Description
`params`	object	nil	The object to convert.

Format.queryString({ one: 'uno', two: 'dos' }); // "one=uno&two=dos"

Changelog

This changelog represents the evolution of our Theme API. All changes are automatic and fully backwards-compatible, unless stated otherwise.

2024-03-30

Added store.host variable to get shop’s hostname which compliments the existing store.url

Introduction

Getting Started

Dugway

Theme Help

Syntax

Tags

If, Else, and Elsif

Case Statement

For Loops

Cycle

Raw

Variable Assignment

Variables

Cart

Cart Item

Category

Contact

Country

Image

Page

Product

Product Option

Product Shipping Area

Store

Filters

size

Parameters

join

Parameters

sort

Parameters

first

Parameters

last

Parameters

minus

Parameters

plus

Parameters

times

Parameters

divided_by

Parameters

modulo

Parameters

num_lt

Parameters

num_lte

Parameters

num_gt

Parameters

num_gte

Parameters

num_eq

Parameters

money

Parameters

money_with_sign

Parameters

money_with_code

Parameters

money_with_sign_and_code

Parameters

font_family

Parameters

default_pagination

Parameters

shipping_name

Parameters

hidden_option_input

Parameters

options_select

Parameters

options_radio

Parameters

product_quantity_input

Parameters

item_quantity_input

Parameters

contact_input