Custom Themes

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.

Stay up to date! Be the first to hear about new features, updates, and resources for Big Cartel theme developers. Join our Developer Newsletter for updates »

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 »

design editor

Page Description
Layout The main store template.
Cart Where customers can see the contents of their cart and proceed to the checkout.
Checkout The page customers see while they’re redirected to PayPal Standard.
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.
Success The page customers see after a successful PayPal Standard purchase.

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:

<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>

{{ 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.

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.

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. View all variables »

My store is called {{ store.name }}

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

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

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' }}

Tags

Tags are the logic in your HTML, and are surrounded with a curly bracket and percent sign.

{% if product.on_sale %}

{% for item in cart.items %}

{% cycle 'odd', 'even' %}

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

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.

If your account is using our old PayPal Standard checkout, then these additional cart variables are also available. If not, they’ll return false or nil.

Variable Description
cart.country Returns the country the items are to be shipped. Only applicable if you have country based shipping.
cart.shipping.enabled Returns true or false based on whether the items in your cart are using Big Cartel’s shipping features.
cart.shipping.strict Returns true or false based on whether the items in your cart have specific shipping rates for different countries.
cart.shipping.pending Returns true or false based on whether your cart has strict shipping and customer user has selected their country.
cart.shipping.amount Returns the combined shipping amounts for all items in your cart.
cart.discount.enabled Returns true or false based on whether your store has discount codes.
cart.discount.pending Returns true or false based on whether your user has entered a discount code or not.
cart.discount.name Returns the name of the discount your customer is using.
cart.discount.amount Returns the amount your customer is saving by using the discount code.
cart.discount.code Returns the discount code your customer is using.
cart.discount.type Returns the type of discount that your customer is using: percent_discount, flat_rate_discount, or free_shipping.
cart.discount.percent_discount Returns the true or false depending on whether your customer is using a percentage-off discount.
cart.discount.flat_rate_discount Returns the true or false depending on whether your customer is using a flat-rate discount.
cart.discount.free_shipping Returns the true or false depending on whether your customer is using a free shipping discount.
cart.discount.percent Returns the discount percentage your customer is saving if they’re using a percentage-off discount, blank otherwise.

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.

Category

Used to retrieve information on a store’s categories or a specific category.

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.
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.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.url Returns the URL of your store. This will use your custom domain if you have it setup.
store.website Returns the URL of your store’s primary website.
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

Array

size(array)

Returns the size of an array.

{% assign my_array = 'Small|Medium|Large' | split: '|' %}
{{ my_array | size }} # => 3
join(array, connector)

Joins elements of an array with a connector.

Parameters

  • connector (‘ ‘ by default)
{{ options | join: ', ' }} # => "Small, Medium, Large"
sort(array)

Sorts the elements of an array.

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

Returns the first element of an array.

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

Returns the last element of an array.

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

Math

minus(number, number_to_subtract)

Subtracts two numbers.

{{ option.sold | minus: option.quantity }}
plus(number, number_to_add)

Adds two numbers.

{{ option.sold | plus: option.quantity }}
times(number, number_to_multiply)

Multiplies two numbers.

{{ 4 | times: 3 }} # => 12
divided_by(number, number_to_divide_by)

Divides a number by another number.

{{ 10 | divided_by: 2 }} # => 5
modulo(number, number_to_divide_by)

Calculates a remainder with division.

{{ 3 | modulo: 2 }} # => 1
num_lt(number, number_to_compare)

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

{{ 3 | num_lt: 2 }} # => false
num_lte(number, number_to_compare)

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

{{ 3 | num_lte: 3 }} # => true
num_gt(number, number_to_compare)

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

{{ 10 | num_gt: 2 }} # => true
num_gte(number, number_to_compare)

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

{{ 1 | num_gte: 2 }} # => false
num_eq(number, number_to_compare)

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

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

Money

money(number)

Formats a number into money format.

{{ 1 | money }} # => 1.00
{{ product.price | money }} # => 9.50
money_with_sign(number)

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

{{ 1 | money_with_sign }} # => $1.00
{{ product.price | money_with_sign }} # => $9.50
money_with_code(number)

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

{{ 1 | money_with_code }} # => 1.00 USD
{{ product.price | money_with_code }} # => 9.50 USD
money_with_sign_and_code(number)

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

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

Special

font_family(font)

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

Parameters

  • font (Ex: Arial, Helvetica, Times New Roman, or Verdana)
body { font-family: {{ theme.font | font_family }}; }
default_pagination(paginate, id, class_name, prev_label, next_label)

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

Parameters

  • id (“pagination” by default)
  • class_name (“pagination” by default)
  • prev_label (“« Previous” by default)
  • next_label (“Next »” by default)
{% 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(area, everywhere, everywhere_else)

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

  • everywhere (“Everywhere” by default)
  • everywhere_else (“Everyone else” by default)
{% for area in product.shipping %}
<p>{{ area | shipping_name }}</p>
{% endfor %}
hidden_option_input(option, id, class_name)

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

  • id (“option” by default)
  • class_name (blank by default)
{% if product.has_default_option %}
{{ product.option | hidden_option_input }}
{% endif %}
options_select(options, id, class_name)

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

Parameters

  • id (“option” by default)
  • class_name (blank by default)
{{ product.options_in_stock | options_select }}
options_radio(options, id, class_name)

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

Parameters

  • id (“option” by default)
  • class_name (blank by default)
{{ product.options_in_stock | options_radio }}
product_quantity_input(product, quantity, id, class_name)

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

Parameters

  • quantity (1 by default)
  • id (“quantity_product.id” by default)
  • class_name (blank by default)
Quantity: {{ product | product_quantity_input }}
item_quantity_input(options, id, class_name)

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

Parameters

  • id (“item_item.id_qty” by default)
  • class_name (blank by default)
Enter quantity: {{ item | item_quantity_input }}
country_select(country, label, id, class_name)

Returns a select box of all countries with the given country selected. To be used on the Cart page.

Parameters

  • label (“Select your country…” by default)
  • id (“country” by default)
  • class_name (blank by default)
Shipping: {{ store.country | country_select }}
discount_code_input(discount, id, class_name)

Returns a text input for the cart’s discount. To be used on the Cart page.

Parameters

  • id (“cart_discount_code” by default)
  • class_name (blank by default)
Enter discount: {{ cart.discount | discount_code_input }}
contact_input(contact, field, id, class_name)

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

Parameters

  • field (“name”, “email”, “subject”, “message”, or “captcha”)
  • id (matches field by default)
  • class_name (blank by default)
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' }}

String

size(string)

Returns the size of a string.

{% assign my_variable = 'Hello World' %}
{{ my_variable | size }} => 11
downcase(string)

Converts a string to lower case.

{% assign my_variable = 'Hello World' %}
{{ my_variable | downcase }} => hello world
upcase(string)

Converts a string to upper case.

{% assign my_variable = 'Hello World' %}
{{ my_variable | upcase }} => HELLO WORLD
capitalize(string)

Capitalizes words in a string.

{% assign my_variable = 'hello world' %}
{{ my_variable | upcase }} => Hello World
escape(string)

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

<a href="{{ product.url }}" title="View {{ product.name | escape }}">{{ product.name }}</a>
pluralize(string, count, singular, plural)

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

Parameters

  • count (the number of items)
  • singular (the singular name of the item, ex: “product”)
  • plural (the plural name of the item, ex: “products”)
You have {{ cart.item_count | pluralize: 'item', 'items' }} in your cart!
truncate(string, length, truncate_string)

Trims a string down to the length you specify.

Parameters

  • length (the number of characters to allow, 50 by default)
  • truncate_string (how to end a truncated string, “…” by default)
{{ product.name | truncate: 18 }} # => "Once upon a ti..."
truncatewords(string, length, truncate_string)

Trims a string down to the length you specify.

Parameters

  • length (the number of words to allow, 15 by default)
  • truncate_string (how to end a truncated string, “…” by default)
{{ product.name | truncatewords: 4 }} # => "Once upon a time..."
strip_html(string)

Removes all HTML tags from a string.

strip_newlines(string)

Removes all newlines (returns) from a string.

newline_to_br(string)

Converts newlines (returns) into
tags.

paragraphs(string)

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

replace(string, string_to_find, replacement_string)

Replaces all occurrences of a string with another string.

{{ product.description | replace: "hello", "goodbye" }}
replace_first(string, string_to_find, replacement_string)

Same as replace, but only replaces the first occurrence.

remove(string, string_to_remove)

Removes all occurrences of a given string.

remove_first(string, string_to_remove)

Same as remove, but only removes the first occurrence.

prepend(string, string_to_prepend)

Adds a string to the beginning of another string.

append(string, string_to_append)

Adds a string to the end of another string.

date(date, format)

Formats a 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

URL

link_to(item, text, title, id, class, rel)

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

Parameters

  • text (item’s name by default)
  • title (“View {{ item.name}}” by default)
  • id (blank by default)
  • class (blank by default)
  • rel (blank by default)
{{ page | link_to }}
{{ product | link_to: 'My Product' }}
{{ category | link_to: 'Tees', 'View tees category', 'tees_category', 'categories' }}
product_image_url(image, size)

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

  • size (“thumb” (75x75), “medium” (175x175), “large” (300x300), default is 1000x1000)
<img src="{{ product.image | product_image_url 'large' }}">
theme_js_url(name)

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

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

Returns the URL of your custom CSS StyleSheet.

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

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

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

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

  • url (the image URL to modify)
  • width (the desired image width, use - to skip)
  • height (the desired image height, leave blank or use - 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, and works perfectly with jQuery, Prototype, MooTools, Dojo, YUI, or any other flavor of JavaScript you can throw at it.

Adding it to your store

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>

Once that’s included, you have access to the following classes:

The following code sample (using jQuery) will display a list of products on a store page:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My Big Cartel Store</title>
  <script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
  <script src="{{ 'api' | theme_js_url }}"></script>
  <script>
    $(function() {
      Product.findAll({}, function(products) {
        $.each(products, function(i, product) {
          $('#products').append('<li><img src="' + Product.findImage(product.images[0].url, 'large') + '" /><br/><a href="' + product.url + '">' + product.name + '</a> - $' + Format.money(product.price) + '</li>');
        });
      });
    });
  </script>
</head>
<body>
  <ol id="products"></ol>
</body>
</html>

Product

Each of these methods (except where noted) support a custom callback function.

Returns a product based on the given permalink.

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

Returns an array of all products.

Optional Parameters

  • limit (default set on the Design > Theme page of the admin)
  • page (used for pagination, 1 by default)
  • category (permalink of a category)
Product.findAll({}, function(products) {
  console.log("I found " + products.length + " products!");
});

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

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

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!");
});
findImage(url, size)

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

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

Cart

Each of these methods returns a cart variable to a callback function.

refresh(callback, options)

Returns the current cart variable.

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

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

Cart.updateFromForm('cart_form', function(cart) {
  console.log("Cart updated!");
});
addItem(optionID, quantity, callback, options)

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

Cart.addItem(1234, 1, function(cart) {
  console.log("Item added!");
});
updateItem(itemID, quantity, callback, options)

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

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

Removes a given item.id from the cart.

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

Format

This is a helper class that allows you to format values.

money(number, withDelimiter, withSign, withCode)

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

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"
pluralize(count, singular, plural)

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

Format.pluralize(1, 'dog', 'dogs'); # => "1 dog"
Format.pluralize(2, 'dog', 'dogs'); # => "2 dogs"
queryString(hash)

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

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

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 new 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