Welcome to the Instantcart Template wiki

Welcome to Instantcart Wiki. This is an information source covering Instantcart Products, including technical wiki entries to assist developers in understanding and using the Instantcart Template Framework.

Introduction

Instantcart uses the Twig templating engine from SensioLabs a secure, fast and flexible templating system to allow you to easily edit and customise your website.

To get an overview of how Twig works, please see the Twig for Template Designers documentation from Sensiolabs. There is also a short tutorial from Sebastien Giroux here.

If you wish to jump straight to a particular template, please choose from the menu below.

Folder Structure

Instantcart uses a template structure that is fairly simple to understand. Each template folder contains a number of subfolders know as “page content” folders. Each folder is descriptive of particular area of your Instantcart webstore, and follows the following format.

|- public_html
    |- templates
    |    |-- main
             |--- snippets
                    |- {Snippets of code used for displaying the contents of loops of data}
                    |- products.snippet.html
             |--- account
             |      |- forgotPassword.template.html
             |      |- loginBox.template.html
             |      |- loginError.template.html
             |      |- myaccount.template.html
             |      |- myledger.template.html
             |      |- myOrdersOrder.template.html
             |      |- myOrdersOrderDetail.template.html
             |      |- myreturns.template.html
             |      |- password.template.html
             |      |- signup.template.html
             |      |- signupMoreInformation.template.html
             |      |- signupSuccess.template.html
             |      |- tickets.template.html
             |      |- tickersDetail.template.html
             |
             |--- basket
             |      |- basketContents.template.html
             |      |- basketEmpty.template.html
             |
             |--- brands
             |      |- brands.template.html
             |
             |--- checkout
             |      |- checkoutPayment.template.html
             |      |- checkoutShipping.template.html
             |      |- success.template.html
             |
             |--- content
             |      |- content.template.html
             |      |- news.template.html
             |
             |--- error
             |      |- error404.template.html
             |  
             |--- index
             |      |- brand.template.html 
             |      |- category.template.html 
             |      |- home.template.html
             |      |- search.template.html
             | 
             |--- product
             |      |- productdetail.template.html
             | 
             |--- index.html
             |--- template.html (can be any name)

About Reference Tables

Instantcart uses a series of variables that call data into your template files. The following tables contain variables Instantcart supports for each template. Some variables are global and can be used accross your site in any template file, and some are private and can only be used for a specific template.

Global Variables

The following table contains variables you can use in any .html template file.

Term Data Type Typical Output Description
page_title varchar The title of your site Outputs the title for your site
description varchar Text Output describing site Outputs the meta description for the site
meta_keywords varchar keyword1, keyword2 Outputs keywords for the current page
meta_noindex boolean false Meta Tag No Index
show_advert boolean false Shows advert
advert_image boolean false Shows image
ad_bottom boolean false Displays add at bottom of the website
ssl boolean false Defines if SSL is required
logged_on boolean false Defines if the customer is logged in or not
show_columns boolean false control to show columns
messages array (See Messages)
current_year varchar 2011 The current year in full
store_name varchar My Instantcart store The name of your store
product_url varchar product
facebook array array Fetches array of facebook data, ie facebook.page_id
dept_url varchar dept
base_url varchar http://www.yourstore.co.uk/ The full url of your store, with https or http depending if ssl is true
http_type varchar (http: or https:)
categories array (See categories)
menu_drop_down html Outputs the dropdown menu in html using html UL list formatting
menu_vertical html Outputs the a menu in html using html DL DT list formatting
store_url varchar www.yourstore.co.uk Your store url without the preceeding http://.. prefix
current_uri varchar product/my_product_2.html The current path being executed
current_path varchar http://www.yourstore.co.uk/product/my_product_2.html The full path of the page displayed
http_referrer varchar http://www.yourstore.co.uk/?ref=id The prevoius page/url that referred you to the current page
template_server_url varchar http://code.instantcart.com/templates/tekkie_twig/ Url location of the Template CDN server
template_images_url varchar http://code.instantcart.com/templates/tekkie_twig/pics/ Url location of the Template CDN server
template_css_url varchar http://code.instantcart.com/css/ Url location of the CDN server with trailing folder
template_code_url varchar http://code.instantcart.com/js/ Url location of the CDN server with trailing folder
cdn_url varchar http://code.instantcart.com/ Url location of the CDN server
setting array (See settings)
open_graph_image html <meta property=“og:title” …
help_box html Predefined Help box html
ssl_box html Predefined SSL Box html
page_tabs array (See page tabs)
banners.top array (See Banners)
banners.left array (See Banners)
banners.right array (See Banners)
form_field_seed html <form id=“seed” value=“sdf0787s8BHUBJ8890” /> Seed form input for a html form, used for verication to stop XSS attacks
login_for_price boolean 1 Users have to login to order or see prices
tax_number varchar GB772 2356 45 Tax or VAT number for the store
seed varchar sdf0787s8BHUBJ8890 The Raw seed value used in form_field_seed
news array (See News)
latest_products array (See Latest products)
recent_products array (See recent products)
special_offers array (See special offers)
reviews array (See reviews)
best_sellers array (See best sellers)
css_filenames html <style type=“text/css” media=“all”>@import “http://code.inst Outputs a list of html formatted CSS filenames
js_filenames html <script language=“javascript” type=“text/javascript” src=“http://code Outputs a list of html formatted js filenames
js_code html <script… Outputs a block of JS code relavent to the page in question for inbuilt functionality
image_path array (See image path)
footer_content html <script… Predefined footer content such as Google Analytics Code etc
agree_terms boolean 1 Returns 1 or 0
breadcrumb array (See Breadcrumb)
get_var array array Returns an array of GET url variables. You can access the PHP var $_GET['show'] by using get_var.show

breadcrumb (array)

The breadcrumb array allows you to access the historic navigation path for a category or product. For example:-

Home » Category One » Sub Category » Product Code

Term Data Type Typical Output Description
name varchar Category One The name of the category
url varchar /category_one_1.html The url of the category
last boolean 1 A true / false indication to state that the array value is the last one in the array or is currently viewed

Usage:

<div class="navigation">
  <h1>{{ category.name }}</h1>
    <p><a href="/">Home</a> >> {% for cat in breadcrumb %}<a href="{{ cat.url }}">{{ cat.name }}</a> {% if cat.last == false %} >> {% endif %} {% endfor %}</p>
</div>

user (array)

Term Data Type Typical Output Description
is_logged_on boolean True/false Boolean if the user is logged on or off
firstname string John Smith prints the first name of the customer if logged in
name string John prints the full name of the customer if logged in

Usage:

{% if user.is_logged_on %}
  Welcome back {{ user.firstname }}
  <a href="/account.php" title="My Account">My Account</a>
{% else %}
  <a href="/login" title="Sign In">Sign In</a>
{% endif %}

basket (array)

Term Data Type Typical Output Description
total varchar £543.00 Outputs the current basket total formatted to the currency set
count int 8 Outputs the total number of items in the basket

Useage:

<a href="/basket"> Basket {{ basket.total|raw }} ({{basket.count}})</a>

setting (array)

The setting array contains references to data set in the Intstantcart control panel. This can be anything from color settings to the logo used on your website. Each reference can be accessed as listed from the table below.

Term Data Type Typical Output Description
setting.color_tab varchar The title of your site Outputs the title for your site
setting.color_h1 varchar The title of your site Outputs the title for your site
setting.color_p varchar The title of your site Outputs the title for your site
setting.color_bg varchar The title of your site Outputs the title for your site
setting.image_bg varchar The title of your site Outputs the title for your site
setting.color_tab_on varchar The title of your site Outputs the title for your site
setting.color_tab_off varchar The title of your site Outputs the title for your site
setting.color_tab_title varchar The title of your site Outputs the title for your site
setting.color_tab_title_off varchar The title of your site Outputs the title for your site
setting.height_header varchar The title of your site Outputs the title for your site
setting.color_button_buy varchar The title of your site Outputs the title for your site
setting.color_button_more varchar The title of your site Outputs the title for your site
setting.id_google_site varchar The title of your site Outputs the title for your site
setting.image_logo varchar The title of your site Outputs the title for your site

As an example, you would use the following syntax to display your store logo.

<div class="headerLogo">
    {% if setting.image_logo %}
    <a href=""><img src="pics/{{ setting.image_logo }}" border="0" alt="{{ store_name }}" /></a>
    {% else %}
    <h3><a href="/">{{ store_name }}</a></h3>
    {% endif %}
</div>

categories (array)

The categories array contains references to the categories for your site.

Term Data Type Typical Output Description
category.id int 4 The ID of the category
category.url varchar /cat_name_353.html Outputs the category url
category.name varchar My Category The name of the category
category.parent_id int 2 Parent Id for this category array
category.children array A child array in the same format as this parent

As an example, you would use the following syntax to display your store logo.

<ul>
  {% for category in categories %}
  <li><a href="{{ category.url }}">{{ category.name }}</a></li>
  {% endfor %}
</ul>

page_tabs (array)

Page tabs allow you to use the functionality of the page tabs section (under the control panel) within your website. The page_tabs reference is a recursive array containing the following references within each sub array of page_tabs.

Term Data Type Typical Output Description
tabs_new_window boolean 1/0 If true, can be used to launch link into a new window
tabs_name varchar My Page Outputs the title for your site
tabs_url varchar /mypage.html The link to the new page for the page tab, can be local or external

To access these varables using Twig, you would use the following syntax

{% for tab in page_tabs %}
{% if tab.tabs_new_window %}
{% set new_window = "target=\"_blank\"" %}
{% endif %}
{% if current_uri in tab.tabs_url or current_path in tab.tabs_url %}
{% set tabs_class = "class=\"on\"" %}
{% endif %}
<li {{ tabs_class }}><a href="{{ tab.tabs_url }}" {{ new_window }}>{{ tab.tabs_name }}</a></li>
{% endfor %}

You can also use sub page tabs too. This is a new feature we have added so you can create tabs within tabs.

Here's and example:-

                <div class="navigation">
                    <ul class="nav">
                        {% set count = 0 %}
                        {% set length = page_tabs|length %}
                        {% for tab in page_tabs %}
                        {% set count = count + 1 %}
                        {% if tab.new_window %}
                        {% set new_window = "target=\"_blank\"" %}
                        {% endif %}
                        <li class="{% if length == count %}last{% elseif count == 1 %}first{% endif %}{% if current_uri == tab.url %} active{% else %}{% for tab in tab.sub_tabs %}{% if current_uri in tab.url %} active{% endif %}{% endfor %}{% endif %}"><a class="tab_{{ tab.id }}" {% if tab.url != '#' %}href="{{ tab.url }}"{% endif %}{{ new_window }}> {{ tab.name }} <b class="caret {% if count == 1 %}on{% else %}off{% endif %}">&nbsp;</b></a> 
                         <ul>
                                {% set sub_count = 0 %}
                                {% set sub_length = tab.sub_tabs|length %}
                                {% for tab in tab.sub_tabs %}
                                {% set sub_count = sub_count + 1 %}
                                <li {% if current_uri in tab.url %}class="active"{% endif %}><a href="{{ tab.url }}" {{ new_window }}> {{ tab.name }} &nbsp;&nbsp;{% if sub_count < sub_length %}&bull;{% endif %} </a></li>
                                {% endfor %}
                        </ul>
                        </li> 
                        {% endfor %}
                    </ul>
                </div>

banners (array)

Banners allows you to access banners added via the control panel. You can access left, top, and right banners using the same format as below:-

Term Data Type Typical Output Description
link varchar /mypage.html The link to the new page for the banner can be local or external
title varchar My Advert The alt tag for the banner
file varchar banner.jpg The filename of the banner

To access these varables using Twig, you would use the following syntax

<div class="banners">
    {% for banner in banners.right %}
    <a href="{{ banner.link }}" title="{{ banner.title }}"><img src="pics/adverts/{{ banner.file }}" border="0" alt="{{ banner.title }}" /></a>
    <br /><br />
    {% endfor %}
</div>

news (array)

The news reference allow you to display top news story summaries on your site. The news reference is a recursive array containing the following references within each sub array of news.

Term Data Type Typical Output Description
id int 3 The ID of the news item
url varchar news/#3 The local url of the news item
title varchar My News Item The title of the news item
date varchar 8th June 2011 Formatted date

To access these varables using Twig, you would use the following syntax

{% for item in news %}
<h2>{{ item.title }}</h2>
<p>Posted on {{ item.date }}</p>
{% endfor %}

You can of course manipulate this data in any way you like, for example you could create a scrolling news ticker in ajax or Jquery based on the news array.

latest_products (array), special_offers (array), recent_products (array) & best_sellers (array)

The recent_products, special_offers, recent_products & best_sellers references allow you to display products that have recently been viewed by a user. These references are recursive arrays containing the following references within each sub array contained within.

Term Data Type Typical Output Description
image_mini varchar http://www.yourstore/images/product_images/mini/product_image.jpg Mini Image URL & Path
image_small varchar http://www.yourstore/images/product_images/small/product_image.jpg Small Image URL & Path
image_thumb varchar http://www.yourstore/images/product_images/thumb/product_image.jpg Thumb Image URL & Path
image_main varchar http://www.yourstore/images/product_images/main/product_image.jpg Main Image URL & Path
link varchar http://www.yourstore/product/product_name_1.html Link to the product
name varchar Product Name Title of the product
name_short varchar Product Na.. An abbreviated title of the product
tax_rate varchar 20 Tax rate in percent
id int 4 The product id
price_ex_tax varchar £5.00 The price excluding tax formatted to the local currency
price_inc_tax varchar £5.90 The price including tax formatted to the local currency
login_for_price boolean true/false User has to log in to view price if true

Usage syntax example using a snippet (snippet/right.snippet.html):

<h3>What's New?</h3><p>Find out whats new at our store</p>
<div id="latestProducts"><ul>
        {% for product in latest_products %}
        {% include "snippets/latestProducts.snippet.html" %}
        {% endfor %}  
    </ul>
</div>
{% if recent_products %}
<h3>What I've just Seen</h3><p>Catch up on items you have previously seen</p>
<div id="recentBox"><ul>
        {% for product in recent_products %}
        {% include "snippet/latestProducts.snippet.html" %}
        {% endfor %}  
    </ul>
</div>
{% endif %}
{{ banners_right }}

To display these products, we use a snippet that we have named latestProducts.snippet.html, however this snippet can be used to display any product reference, such as recent_products, special_offers & best_sellers or any reference that uses the supported terms listed in the above table.

Useage syntax example for (snippets/latestProducts.snippet.html)

<li>
    <a href="{{ product.link }}"><img src="{{ product.image_thumb|raw }}"  width="100" height="100" border="0" alt="{{ product.name }}" /></a><br />
    <p><a href="{{ product.link }}">{{ product.name }}</a></p>
    <span class="price">{{ product.price_inc_tax|raw }}</span>
</li>

reviews (array)

The reviews reference allow you to display top product reviews summaries on your site. The reviews reference is a recursive array containing the following references within each sub array of news.

Term Data Type Typical Output Description
id int 3 The Product ID for the review
content varchar Review Content The content for the review
rating varchar 5 Rounded rating between 1 and 5
name varchar Product Product Name
image varchar product.jpg Formatted date

To access these varables using Twig, you would use the following syntax

{% for review in reviews %}
<h2>Review for {{ review.name }}</h2>
<p>User rating of {{ review.rating }} out of 5</p>
{% endfor %}

image_path (array)

Image paths can be accessed directly by using the references in the table below.

Term Data Type Typical Output Description
image_path.product.mini varchar http://www.yourstore/images/product_images/mini/ Mini Image URL & Path
image_path.product.small varchar http://www.yourstore/images/product_images/small/ Small Image URL & Path
image_path.product.thumb varchar http://www.yourstore/images/product_images/thumb/ Thumb Image URL & Path
image_path.product.main varchar http://www.yourstore/images/product_images/main/ Main Image URL & Path
image_path.product.large varchar http://www.yourstore/images/product_images/large/ Large Image URL & Path
image_path.product.brand varchar http://www.yourstore/images/brands/ Brand Image URL & Path
image_path.product.dept varchar http://www.yourstore/images/depts/ Dept Image URL & Path

To access these varables using Twig, you would use the following syntax. Please note, this example is based on an additional reference used in productdetail.template.html which is a local reference to this file.

<img src="{{ image_path.product.thumb }}{{ product.image.one_thumb }}" title="My Image" />

messages (array)

Messages accesses the error message system, so you can print any pending messages to your template. The messages reference is a recursive array containing the following references within each sub array of messages.

To access these varables using Twig, you would use the following syntax.

Term Data Type Typical Output Description
type varchar success / error The type or message ie success or error
body varchar Error message in plain text The success or error message
{% for message in messages %}
{# Type is error or success #}
<div id="message_banner_{{ message.type }}"><p>{{ message.body }}</p></div>
{% endfor %}

Local References

Local references can only be used for a specified template or alternatively a snippet that is used within the specified template, unlike global references that can be used anywhere on any page.


** Important Notice **

It is adivsed that you are proficient with HTML and get to grips with the Twig templating engine before you begin to edit store templates. Techical support is not provided for template assistance to end users, however this guide will be self explanitary to developers. Please edit templates at your own risk, and remember to backup any template files prior to making changes. If you use your own template, you will be required to make any updates and changes that we may issue from time to time.