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