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.

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.

Tags

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

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.

Case Statement

These tags let you handle multiple conditions.

For Loops

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

Cycle

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

Raw

You can disable tag processing by using the raw tag.

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.

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.

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.

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

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.

size

Returns the size of an array or string.

Parameters

None.

join

Joins elements of an array with a connector.

Parameters

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

sort

Sorts the elements of an array.

Parameters

None.

first

Returns the first element of an array.

Parameters

None.

last

Returns the last element of an array.

Parameters

None.

minus

Subtracts two numbers.

Parameters

Name Type Default Description
number_to_subtract integer nil Number to subtract.

plus

Adds two numbers.

Parameters

Name Type Default Description
number_to_add integer nil Number to add.

times

Multiplies two numbers.

Parameters

Name Type Default Description
number_to_multiply integer nil Number to multiply.

divided_by

Divides a number by another number.

Parameters

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

modulo

Calculates a remainder with division.

Parameters

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

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.

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.

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.

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.

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.

money

Formats a number into money format.

Parameters

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

money_with_sign

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

Parameters

None.

money_with_code

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

Parameters

None.

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.

font_family

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

Parameters

None.

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.

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.

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.

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.

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

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.

country_select

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

Parameters

Name Type Default Description
label string “Select your country…” First select option text.
id string “country” Element id.
class_name string ”” Element class name.

discount_code_input

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

Parameters

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

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.

downcase

Converts a string to lower case.

Parameters

None.

upcase

Converts a string to upper case.

Parameters

None.

capitalize

Capitalizes words in a string.

Parameters

None.

escape

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

Parameters

None.

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.

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.

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.

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.

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.

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

theme_js_url

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

Parameters

None.

theme_css_url

Returns the URL of your custom CSS StyleSheet.

Parameters

None.

theme_image_url

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

Parameters

None.

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.

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.

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

Cart.refresh

Returns the current cart variable.

Parameters

Name Type Default Description
callback function null Your callback function.

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

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.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.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.
Heads up! You're using an unsupported older browser. Click to learn how to update it.