Before you start
v1
v1.1
v1.2
v1.3
v1.4
v1.5
New for v1.3
Change
;htmlconv= to ;strconv= as htmlconv is deprecated, now a newer TBS version is being used.
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.
Configuration
| File | Purpose |
|---|---|
 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.  By 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. |
|
| Below 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 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 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 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.
For 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.) For 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.
For 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 | |
|
New for v1.5
[var.paypal] has been changed to [var.paymentprocessoremail] | ||
| [var.paymentprocessoremail] | The email address to receive the payment. | |
|
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.Do not include this in the template, as it would be the wrong context for the page! |
|
| Below 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 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.
Now it's time for the sort of variables that loop inside a block.
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 |
| [products.quantity] shows the price, not the quantity. | ||
| Replace [product.photopath] with something like [product.photopath;ifempty='themes/[var.theme]/graphics/_noimg-m.png'] | ||
| Don'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 |
| [variation.attribute] means the variation name, and [variation.value] means the quantity. | ||
| Use [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 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.
| Don't forget to customise the code above so it fits in with your theme. | ||
| Don'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. | |
By 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 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.
For Heroes For Hire, made by desbest