Heroes For Hire logo Cartcake
Theming Guide
Before you start
v1
v1.1
v1.2
v1.3
v1.4

new New for v1.3
Change ;htmlconv= to ;strconv= as htmlconv is deprecated, now a newer TBS version is being used.
This guide tells Heroes For Hire, how to make themes for Cartcake. Once you've designed and sliced a theme, you're ready to go.

To make use of this tutorial, you must know the following things... By the end of this tutorial, you should know... Cartcake uses a templating engine called Tinybutstrong, and throughout this tutorial, you will learn some of that. Knowing TBS is a requirement of completing this tutorial, so if you need extra help you can use their website.

Cartcake being a custom coded script, rather than a free open source script, you may get the idea that any design can be made into a theme, without limitations. That is not the case. Yes, Cartcake has less design limitations than other alternatives, but all scripts have limitations, in how they can be templated. Reasons being... In TBS, a variable is called a field; and a loop is called a block.
Theme Structure
A typical Cartcake theme has this directory structure. This theme in particular is called Panorama, Cartcake's 1st ever theme.
In each theme, the graphics/ folder is required, as there are required images in this folder. More about that, later on.
Files that begin with an underscore _ are either required images or configuration files.
directory listing of the Panorama Cartcake themedirectory listing of the graphics/ folder in the Panorama Cartcake theme
Configuration
File Purpose
information The word variation, depending on the context, it might be referring to a variation of your theme, or a variation of a product. If it's referring to a theme variation, it may more specifically be referring to a stylesheet.
You can use [var.variation] in your header.html, to make a variation point to a specific variation stylesheet, (or images).
_config.xml Settings for your theme.
ordernumber is to number whether it's your 1st 2nd 3rd theme. Example:
_countries.html Contains all the <option> tags for the countries. This will be used on the checkout.

The download link for this is here.     Deprecated country code version.

warningBy default on the checkout, the country is set at United Kingdom and not allowed to be changed. To change this, load up _countries.html and remove the selected attribute from the UK option tag.
If you would like to set it to all countries, move the selected attribute to the top
_preview.html A html mockup page with no TBS, showing a preview page of your theme.
graphics/_thumbnail-m_variation.png 292x164
A snapshot of your theme for each variation you have.
Variations are defined in _config.xml
graphics/_thumbnail-s_variation.png 200x150
A snapshot of your theme for each variation you have.
Variations are defined in _config.xml
graphics/_add.png Add icon, to increase quantity in basket.
graphics/_minus.png Minus icon, to decrease quantity in basket.
graphics/_defaultlogo_variation .png Shows a default logo in case it's undefined..
graphics/_noimg-l.png 250x250
Shown when a product has no image.
graphics/_noimg-m.png 175x175
Shown when a product has no image.
graphics/_noimg-s.png 125x125
Shown when a product has no image.
graphics/_noimg-xs.png 75x75
Shown when a product has no image.
Your stylesheet Make 4 div classes in your stylesheet called .notice. .rednotice .ambernotice and .greennotice.

Global Variables
Its always a good idea to create header and footer files, and include them on all pages. To include a file into your template, use [onload;file='header.html']

Create the files below, as you will be templating them later on. You should make the 404.html page now. It should display when a Error #404 File Not Found error happens. Because of a limitation of Apache server's mod_rewrite, it will only show once Cartcake is installed in the root directory.

Below are some valuable template tags, to put into your files. These are global variables, so they work on all pages.
Variable Purpose
[var.theme] Current theme
[var.themevariation] Theme variation
Good for selecting stylesheets.
[var.currencysign] Currency symbol
Always shows £ in v1.
[var.businessname] Business name
Put this inbetween <title> tags.
[var.tracking;htmlconv=no] Tracking html code, as defined in the admin cp.
Good for collecting website statistics.
Put this in the footer before the </body> tag.
Keep the htmlconv parameter as it is to print HTML.
[var.sitelogopath] Website logo
Prints nothing if it's blank
[var.pagemode] Reads shop, account, help or basket, depending on the page you're on.
This is useful for displaying html tags, depending on the outcome.
To make use of this variable, learn about conditional variables.
Manual

It may be useful to learn about conditional display (if/else/ifempty), and about block parameters and operators.
informationBelow is code to use for the <title> tags.

Below is some example code taken from the Panorama theme need for header.html
You can use this for SEO purposes.
new New for v1.3
New global variable.
[var.welcome;htmlconv=yes] Welcome message, as defined in the admin cp.
Keep the htmlconv parameter as it is, to disable html.
Local Variables
Page Variable Purpose
new New for v1.3
index.html has new variables you might find useful.
index.html [var.welcome;htmlconv=yes] Welcome message, as defined in the admin cp.
Keep the htmlconv parameter as it is, to disable html.
[var.homesort] The method of sorting the products on a page. This is either recent or alphabetised.
Works best used as a conditional, for a header that displays text.
[var.homelist] The number of products to display on the home page.
[var.allitems] The amount of items for sale.
This includes items that are out of stock.
You will find this useful along with homelist for auto pagination.
account.html [var.today] Today's date.
yyyy-mm-dd format
[var.domainname] The domain name of the current website, stripped of the http:// prefix.
new New for v1.1
account.html has new code for you to add.
Here's the html code for account.html, taken from the Panorama theme.


If you want breadcrumbs in account.html, use this code.
basket.html
checkout.html
[var.domainname] The root domain name without the http://www. prefix.
More accurately called the host name.
[var.currencycode] Currency code in three letters
[var.datenumber] The current date in yyyy-mm-dd format.
[var.deliverycost] Delivery cost
[var.grandtotal] Total cost of the basket/order.
[var.ip] The user's ip address.
warningFor security reasons, do not show this! IP Addresses are recorded to give the webmaster/merchant a means to detect whether a purchase really was fraudulent, in the rare case of PayPal holding funds on suspicion of fraud.
[var.ordernumber]
[var.orderid]
The order number of the current order which is pending.
(orderid is passed to the payment processor, to make the order processed once done, whereas ordernumber is for other backend purposes.)
warningFor obvious reasons, do not show this!
[var.paymentprocessor] Payment processor
[var.websiteurl] Website url
category.html [var.category] Category name
[var.categoryid] Category id
checkout.html [var.currencycode] Currency code
[var.checkoutmode] Prints userinput when directly on the checkout page.
Prints confirm when the user confirms the order, to start paying.
This feature makes use of conditional blocks.
[var.emailsubject] The subject of the email, pending to be sent to the customer, upon order completion.
warningFor obvious reasons, do not show this!
[var.paymentprocessor] A list of the products in the basket to be brought, and at what price.
[var.paymentprocessor] Payment processor
[var.paymentfunction] This file is included in the checkout
[var.paypal] The email address to receive the payment.
new New for v1.1
You can show your chosen delivery cost.
help.html [var.address;htmlconv;yes] Postal address
htmlconv as in the manual
[var.deliverycost] Shows the delivery cost as a number.
If the basket only has virtual items, the value is n/a
[var.phone] Phone number
[var.customhelp;htmlconv=yes] Custom help, as defined in the admin cp.
htmlconv as in the manual
Keep htmlconv as it is to disable HTML.

ordercomplete.html [var.paymentfunction] The file the page uses to check the payment status of the recent payment.
ordercomplete.html [var.paymentprocessor] Payment processor
[var.paymentstatus] The status response of the payment. It's likely to be Completed or Pending.
[var.payment] Provided that the user has attempted to make a payment, this variable will prints true when the payment was successful, and fail when it isn't.
If the user has accessed this page directly, it will print unnecessary, as no payment has been attempted.
[var.orderid] The orderid that gets looked up in the backend, to check the status of the payment.
warningDo not include this in the template, as it would be the wrong context for the page!
informationBelow is the code you'll need for ordercomplete.html, taken from the Panorama theme. It includes graphics, so replace them or take them out.
new New for v1.1
ordercomplete.html has a new sentence to add to your template.
category.html
products.html
[var.shopmode] Reads category, home or product, depending on what page you're on.
Use in conjuction with [var.pagemode], inbetween <title> tags.
To make use of this variable, learn about conditional variables.
Manual

It may be useful to learn about conditional display (if/else/ifempty), and about block parameters and operators.
[var.categoryname] Category name
Put this inbetween <title> tags.
To make use of this variable, learn about conditional variables. Manual

If you want breadcrumbs, the code below provides what should go on product.html The relevant CSS code is here.
basket.html
checkout.html
ordercomplete.html
[var.basketmode] Reads basket, checkout or ordercomplete, depending on what page you're on.
Use in conjuction with [var.pagemode], inbetween <title> tags.
To make use of this variable, learn about conditional variables.
Manual

It may be useful to learn about conditional display (if/else/ifempty), and about block parameters and operators.
product.html
account.html
checkout.php
<div class="notice">[onshow;block=div;when [var.shownotice]=yes][var.notice]</div>
<div class="rednotice">[onshow;block=div;when [var.showrednotice]=yes][var.rednotice]</div>
<div class="ambernotice">[onshow;block=div;when [var.showambernotice]=yes][var.ambernotice]</div>
<div class="greennotice">[onshow;block=div;when [var.showgreennotice]=yes][var.greennotice]</div>
Shows a notice, whilst using conditional blocks to make the div appear, depending on whether the variable in question, is blank or not.

The [var.show___notice] variables print either yes or no.
[var.productname] Product name
Put this inbetween <title> tags.
To make use of this variable, learn about conditional variables. Manual
Loops
Here's some background information on how Cartcake works.

The code from the products section came from a script called StockClaw, so that's why quantity really means price; because the database field wasn't renamed. That's the same reason why variation's attribute and value will mean value and quantity. This paragraph will make more sense to you later on, if you don't understand.

Other shopping cart scripts allow variations (of products, think catalogue fashion stores) to have different images, different prices, but the same product description, for the same product. Cartcake doesn't. With Cartcake, variations aren't anything but a word. If there is only one variation, the product is treated as having none. Also, a product must have a variation to be sold. Below are some images to illustrate this.
listing of products on Cartcake
a product with more than 1 field shows the variations on the product page, so someone can choose variation to put in the basket
a product with 1 variation can be added to the basket, but no variations are shown, because it's treated as having none.
an item with no variations is out of stock

Now it's time for the sort of variables that loop inside a block.
new New for v1.1
account.html now accepts template tags from "Loops".

For example, a <table> in category.php may show only 5 products, with each product taking up a <tr>, when a person is browsing the shop website. But the product's variables are only entered once inside index.html. What happens, is that the <tr> block is looped 5 times. Here is where you learn to use blocks with TBS. Blocks do not do anything unless they are merged. To learn about that, use the example and manual.

Page Variable Purpose
Global [category.id]
[category.title]
Listing categories
basket.html
index.html
category.html
product.html
account.html
[product.id]
[product.title]
[product.photopath]
[product.quantity]
[product.description]
index.html        Displaying 6 latest products
category.html        Listing products in category
product.html        Listing active product
warning[products.quantity] shows the price, not the quantity.
informationReplace [product.photopath] with something like [product.photopath;ifempty='themes/[var.theme]/graphics/_noimg-m.png']
informationDon't forget to use the nodata field parameter to display a notice for in case the product and category doesn't exist. They are both GET variables taken from the address bar.
basket.html
category.html
product.html
account.html
[variation.id]
[variation.attribute] variation!
[variation.value] quantity!
category.html        Listing the product from the outer block
product.html        Listing active product
warning[variation.attribute] means the variation name, and [variation.value] means the quantity.
warningUse [variation] on category.html with caution, as exclusive product.html variables cannot be used on category.html.
products.html [var.variationcount] The amount of variations the active product has.
new New for v1.1
You can show your chosen delivery cost.
basket.html
checkout.html
[var.deliverycost] Shows the delivery cost as a number.
If the basket only has virtual items, the value is n/a
There is new template code for both pages, so check below for them.


Here is the code required to add a product to the basket, and to show whether it's out of stock, taken from the Panorama theme.
It makes use of conditional and operator parameters for the blocks. Make sure you understand the TBS code, to avoid being a noob.

Below is the code Panorama uses on basket.html for the shopping basket. Customise it as you wish.
new New for v1.3
Users can now specify what country they're from on the checkout.
warningDon't forget to customise the code above so it fits in with your theme.
warningDon't forget to change graphics/_add.png and graphics/_minus.png to your own images.
[var.recipname;noerr]
[var.roadname;noerr]
[var.secondline;noerr]
[var.city;noerr]
[var.postcode;noerr]
[var.country;noerr]
[var.custname;noerr]
[var.custname;noerr]
[var.phonenumber;noerr]
Variables in a form which are to be posted through text input fields, which have those variables as their value.
warningBy default on the checkout, the country is set at United Kingdom and not allowed to be changed. To change this, load up _countries.html and remove the selected attribute from the UK option tag.
If you would like to set it to all countries, move the selected attribute to the top
Below is the code you'll need for the checkout. It's taken from Panorama theme, as always. You might want to modify the design.


new New for v1.3
Change ;htmlconv= to ;strconv= as htmlconv is deprecated, now a newer TBS version is being used.
Auto Pagination

This is the section that teaches you how to implement auto pagination for your Cartcake theme. Make sure you that you have completed your theme, especially the home and category pages, before continuing.

Auto pagination is that thing where people can scroll down forever and have new listings appear. It's been around for a long time, but has been popularised into the mainstream by Pinterest.

Auto pagination only works on v1.3, and there is no setting for people to enable or disable it. If you enable it for your theme, it will 100% be enabled.

Right now you can only auto paginate products, so you can only use it for the index.html and products.html page.

To start enabling up auto pagination for your theme, you must first make a file called ajaxcontrols.php inside your theme, and have it looking something like this.

To edit the hooks.php correctly, you must edit what is inbetween the EOF lines. This will be the the result of 1 product. It should match your theme. You already know how to do this.

The next step is to use an auto pagination javascript plugin. There are loads of them on the internet. It doesn't matter if you use jQuery or Prototype. Once you have a plugin setup, you'll need to use these variables.

Usage Javascript code
Insert this before the pagination function var offset = [var.homelist;noerr];
Insert this after the pagination function has occured offset = offset + [var.homelist;noerr];
Load up this page themes/[var.theme]/ajaxcontrols.php?page=products&offset=' + offset
If the element's children goes higher than this, stop pagination [var.homelist;noerr] * [var.maxpages;noerr]

Pinterest-eque Example

Here is an example that uses the Image Resize and Masonry jQuery plugins, to create a Pinterest-eque layout.

Don't be a noob, and learn what Fluid columnWidth and imagesLoaded parameters do for Masonry.

Troubleshooting
HTML
Why do my sliced tables or css grids look bad?
   Use a HTML4 Transitional or HTML5 doctype.
   If you're looking for IE compatibility, no doctype will force quirks mode, so use a UX-A Compatible header, to force IE7, IE8 or IE9 rendering, but only as a last resort because you're noobish and am too lazy so you're forcing an old version of IE rather than fix up your css. The Developer Tools will help you out, if you press F12.

Where can I learn HTML5?
   By going to HTML5 Rocks. Beware of Google propaganda.

CSS
Where can I learn CSS?
   Ask desbest for his super-easy learn CSS tutorial.

I need help with CSS
   If Google fails, use webmaster forums such as Sitepoint and StackExchange.

How do I get vertical-align to work?
   Refer to this link

How do I position things in CSS?
   Refer to this link (the "display" attribute is not included)

How can I get colour themes for my CSS?
   Use Less.js

How to I make a list?
   Listamatic is a good starting point

How do I make a grid layout?
   Maxdesign layouts is a good starting point. They've now got new layouts for bootstrap. [link two]

What css grid frameworks do you recommened?
    1KB Grid     Tiny Fluid Grid     Semantic Grid System     Variable Grid System     Elastic Framework    

How do I use floats, menus or selectors in CSS?
    Float tutorial, list tutorial and select tutorial will help you.

I have a fixed position navigation bar obscuring the anchors. How do I fix this?
   Refer to this page.

What are some good resources for making websites responsive?
   Google Developers has a page up, but it's not recommended. Learning about the viewport tag and max-width and max-device-width. More clarification is here and here.

I've used media queries to make my website responsive. Now how can I have it iPhone compatible?
   Refer to this guide.

Where can I learn some cutting edge HTML5 style CSS3?
   By going to CSS Tricks.

Javascript
Where can I get some fancy JQuery plugins from?
   By browsing the JQuery plugins.

Tinybutstrong
Where can I get help on TBS?
   Use the TBS forum.

Miscellaneous
Where can I find something interesting to do with web developing?
   Browse desbest's bookmarks or use Delicious.
footer Heroes For Hire - design agency