PHP Super Cart Template System (TS)

For PHP Super Cart Version 2.0

This guide explains how to create and modify templates to use with the PHP Super Cart Shopping Cart System.

Overview

The PHP Super Cart Template System (TS) was designed to allow webmasters and web designers to easily integrate the PHP Super Cart Shopping Cart System into their websites. The PHP Super Cart Template System is fast, flexible and easy to use. Templates can be easily edited with your favorite html editor. Just add special “TS Tags” and “TS Comments” and your shopping cart will come to life.

The nice thing about the template system is that you really don’t need to modify any of the template files to get your cart up-and-running. Just upload your logo over the logo.jpg file associated with your site template (see more below). However, to customize your website, you’ll want to create your own template files. The main template file (index.php) is the only file that really needs to me modified to get a customized look. You only modify the other template files if you don’t like the default layout or to further integrate the existing templates.

PHP Super Cart comes with 5 main templates to choose from. You can use any of these templates immediately or you can customize them to your requirements. You can use them as the basis for a completely new template that you can create. Just create a new folder under the “template/site” directory and copy all of the files and folders from one of the other template/site folders into this new folder. You now have a new template that you can choose to display and modify. To pick your template, just select the template you want from the configuration area of the PHP Super Cart control panel.

Select the Site Template from the Layout Configuration screen

Template Files

At the heart of the PHP Super Cart Template System are the template files themselves. These files are standard html files with special TS Tags and TS Comments. They are easily edited to allow PHP Super Cart to match the exact look and feel of your website. There are several different template files that make up the PHP Super Cart Template System. You can easily modify any of them to fit your needs. Some areas, such as products or categories, allow you to have several different templates. This allows you to select a different template on a per product or per category basis. Other areas, such as emails or the site template, only have one template. You modify that one template to match the look/feel of your site. All templates are located in the “template” directory. See Appendix A for a complete list and description of all the template files.

Getting Started

The Template System consists of files located in the template directory and subdirectories. You can use any of the existing templates, modify them to fit your website, or completely design your own from scratch. Each template type has a special function and each template type has special TS Tags and TS Comments that work to bring the template to life.

The key template file is the index.php file. This file is located in a subdirectory of the “site” directory. The subdirectory is chosen from the Layout configuration screen. For example: If your Layout configuration is set to use the “Business” template then the main template file would be located in the “template/site/Business” directory. The full path would be “template/site/Business/index.php”. If you selected a different template from the Layout configuration screen, then the path to your template might be “template/site/Classic/index.php”. The directory that your template is located in is very important because all of the graphics and style sheets are located within the specific site template directory structure. If you create your own site template, be sure to use the same directory structure. Once you create a subdirectory under the template/site directory you will be able to choose that template (based on the subdirectory name) from the Layout configuration screen. You can change between templates at any time. When you change the site template, you must also choose a style sheet. Each site template may have one or more style sheets to choose from that matches the template.

Using TS Tags and TS Coments

The Template System uses special data tags referred to as “TS Tags” to define where in the template you want data to appear and uses html comment tags referred to as “TS Comments” to define the behavior of certain blocks of code including looping blocks and removing blocks when the cart is empty. There are TS Tags and TS Comments for both the shopping cart side and the catalog side of PHP Super Cart. Not all TS Tags and TS Comments are available on all template.

TS Tags ( PHP Super Cart Template System Tags)

TS Tags are easy to use. All TS Tags consist of an upper-case word surrounded by two sets of percent signs (e.x. %%TOTAL%%). You place these tags into your template right where you want the specific data to appear. Below is a snippet of code to show as an example:

The above example would create a table that looks like the following in your html editor:

Total:

%%TOTAL%%

However, in your web browser, the code would look like the following:

Total:

$285.94

There are TS Tags for displaying product data, messages and totals. There are also TS Tags for entering certain html values such as company information as well as for inserting the current template directory. Below is a chart of all of the TS Tags along with when they are available to be used.

TS Tag	Template		Where Used
Item Specific TS Tags (Items in the cart)
%%ROW%%	Item		Displays the row number of the product. This variable is used to track which item to delete and which item to change product quantity.
%%ID%%	Item		Displays the item ID. This is used when deleting an item from the cart. You typically do not display this to the customer. You use it to build the delete link for the product.
%%NAME%%	Item		Displays the item name.
%%OPTION%%	Item		Displays the current option selected
%%OPTIONPRICE%%	Item		Displays the price of the current option
%%OPTIONNAME%%	Item		Displays the name of the current option
%%PRICE%%	Item		Displays the item price including all options, qty 1. If configured, the price includes the tax.
%%QUANTITY%%	Item		Displays the item quantity
%%BASEPRICE%%	Item		Product price without options, qty 1 If configured, the price includes the tax.
%%FULLTOTAL%%	Item		Product price including tax and shipping for all quantities
%%TOTAL%%	Iterm		Displays the item price with options for all quantities. If configured, the price includes the tax. This does not include shipping
%%EXTRA1%%	Iterm		Displays any extra variable configured as ‘extra1’ passed to the cart.
%%EXTRA2%%	Iterm		Displays any extra variable configured as ‘extra2’ passed to the cart.
%%EXTRA3%%	Iterm		Displays any extra variable configured as ‘extra3’ passed to the cart.
%%WEIGHT%%	Item		Displays the item weight
%%TAX%%	Item		Displays the tax for the item
%%SHIPPING1%%	Item		Displays the shipping charge for the first item.
%%SHIPPING2%%	Item		Displays the shipping charge for each additional item after the first item.
%%THUMBIMAGE%%	Item		Displays a thumbnail image of the product.
%%PRODUCTURL%%	Item		Displays the product’s url back to the catalog.
%%PRODUCTCODE%%	Item		Displays the product code.
%%TOTAL%%	Item		Displays the item total
Cart Specific Tags
%%SUBTOTAL%%	Cart Checkout		Displays the cart subtotal.
%%DISCOUNT%%	Cart Checkout		Displays the total discount
%%COUPON%%	Cart Checkout		Displays the actual coupon used
%%TOTALSHIPPING%%	Cart Checkout		Displays the total shipping charge for this order.
%%TOTALTAX%%	Cart Checkout		Displays the total tax for this order.
%%GRANDTOTAL%%	Cart Checkout		Displays the shopping cart total
%%PREVIOUSPAGE%%	Cart		URL to the previous page. This variable is used to link back to the referring page.
%%MESSAGE%%	Cart		Displays the following messages when appropriate: Invalid Coupon Duplicate Item Not Added Empty Cart
%%ROWCOLOR%%	Cart Checkout		Variable alternates between the two colors configured in the admin control panel background colors (odd rows and even rows)
%%MAILINGLISTCHOICE%%	Confirm		Displays the correct text from the Language configuration screen based on the mailing list choice.
Order Specific Tags
%%ORDERDATE%%	Emails Tracking		Displays the date/time of the order.
%%SHIPPINGINFO%%	Tracking Emails		Displays the shipping information entered in the admin control panel.
%%STATUSMESSAGE%%	Tracking		Displays the status of the order.
%%INVOICE%%	Email Tracking		Displays the invoice number of the order.
%%AMOUNTDUE%%	Email Tracking		Displays the current amount due for the order.
Payment Specific Tags
%%PAYMENTDATE%%	Email, Tracking		Displays the date of the specific payment.
%%TRANSACTIONID%%	Email, Tracking		Displays the transaction id for the specific payment
%%PAYMENTTYPE%%	Email, Tracking		Displays the payment type for the specific payment.
%%PAYMENTAMOUNT%%	Email, Tracking		Displays the payment amount for the specific payment.
Company Specific TS Tags (from admin configuration)
%%COMPANYNAME%%	All		Name of the company
%%COMPANYADDRESS%%	All		Address of the company
%%COMPANYWEBSITE%%	All		Website of the company
%%COMPANYPHONE%%	All		Phone number of the company
%%COMPANYEMAIL%%	All		Email address of the company
%%HOMEPAGE%%	All		Home page of the company
Customer Specific Tags (billing/shipping)
%%FIRSTNAME%%	Billing Emails		Customer first name
%%LASTNAME%%	Billing Emails		Customer last name
%%ADDRESS%%	Billing Emails		Customer address
%%ADDRESS2%%	Billing Emails		Customer address line 2
%%CITY%%	Billing Emails		Customer city
%%STATE%%	Billing Emails		Customer state
%%STATES%%	Billing Emails		Specialty tag that displays all states/regions surrounded by “option” html tags. This is used to display the states/regions in a select box. States will be shown with their full name.
%%STATES2%%	Billing Emails		Specialty tag that displays all states/regions surrounded by “option” html tags. This is used to display the states/regions in a select box. States will be shown with their two-letter abbreviation.
%%STATEOTHER%%	Billing Emails		Customer state other (when not selected from the drop-down)
%%ZIP%%	Billing Emails		Customer zip code
%%COUNTRY%%	Billing Emails		Customer country
%%COUNTRIES%%	Billing Emails		Specialty tag that displays all countries surrounded by “option” html tags. This is used to display the countries in a select box.
%%PHONE%%	Billing Emails		Customer phone number
%%COMPANY%%	Billing Emails		Customer company name
%%EMAIL%%	Billing Emails		Customer email address.
%%COMMENTS%%	Billing Emails		Displays the user-entered comments for the order.
Credit Card TS Tags
%%CCNUMBER%%	Billing		Displays the masked credit card number. Credit card information is not displayed on the page.
%%CCTYPE%%	Billing		Displays the credit card type (visa, mc, etc).
%%CVVCODE%%	Billing		Displays the masked credit card CVV code. The CVV code is not displayed on the page.
%%CCMONTH%%	Billing		Displays the credit card month.
%%CCYEAR%%	Billing		Displays the credit card year.
%%CCTYPES%%	Checkout		Specialty tag that displays all credit card types surrounded by “option” html tags. This is used to display the credit card types in a select box.
%%CCMONTHS%%	Checkout		Specialty tag that displays the months of the year surrounded by “option” html tags. This is used to display the months of the year in a select box.
%%PAYMENTMETHODS%%	Checkout		Displays all of the payment options
%%PAYMENTTYPE%%	Checkout		Displays the selected payment method
%%CCYEARS%%	Checkout		Specialty tag that displays the next 10 years surrounded by “option” html tags. This is used to display the credit card types ina select box.
Validation Tags
%%VALIDATION%%	Checkout		Displays the validation message(s) if any one or more fields fails validation
%%XXXREQUIRED%%	Checkout		This is a very special form of a TS Tag. Any checkout form field that is entered into the Validation Rules table will have a special TS Tag associated with it’s name. This tag is only displayed if the field fails validation. For example: If you have a form field on the billing screen with a field name of “firstname” and you have a validation rule set up for the field then the system will automatically generate a TS Tag of %%FIRSTNAMEREQUIRED%%. This tag will then display the text associated with the validation rule. If the field does pass validation, then the TS Tag is removed. You can have as many special validation TS Tags as you have field validation rules set up in the admin control panel.
Miscellaneous TS Tags
%%DATA%%	Site Template		Displays The cart and catalog in your main template file.
%%TEMPLATEPATH%%	All		Displays the path to the template directory. Can be used to point to images in the template directory.
Catalog Tags
%%KEYWORDS%%		Catalog		This is the system generated list of keywords for the page.
%%DESCRIPTION%%		Catalog		This is the system generated description of the page.
%%TITLE%%		Catalog		This is the system generated title of the page.
%%CATALOGURL%%		All		This is the URL to the catalog home page.
%%SEARCHTERMS%%		Catalog		This is the list of words entered into the search box.
%%CARTURL%%		All		URL to the cart.
Block and Block Item Tags
%%BLOCKITEMSMALL%%		Block		This displays the information from the “small text” field of the block item.
%%BLOCKITEMURL%%		Block		This is the URL that links to the block item
%%BLOCKITEMTITLE%%		Block		This is the title of the block item.
%%BLOCKITEMLARGE%%		Block		This is the information from the “large text” field of the block item.
%%BLOCKITEMDATE%%		Block		This is the information displayed from the date field as formatted by the date configuration.
%%BLOCKITEMDATETIME%%		Block		This is the date field as formatted by the datetime configuration.
%%BLOCKITEMURL%%		Block		If the block item has an entry in the URL field, then that entry is displayed. Otherwise, the internally generated url to the block item is displayed.
%%BLOCKTITLE%%		Block		This is the title of the block (not the block item)
%%ITEMBIGTEXT%%		Block Item		This is the information from the “large text” field of the block item.
%%ITEMTITLE%%		Block Item		This is the title of the block item.
Sitewide Tags
%%CATEGORYURL%%		Site Template		This is the internally generated url to the category. This is used in breadcrumbs and the menu system.
%%CATEGORY%%		Site Template		This is the name of the category. It is used in breadcrumbs and the menu system.
%%KEYWORDS%%		Site Template		This displays the page keywords. Keywords are generated based on the item being displayed.
Product Tags
%%PRODUCTNAME%%		Product		Name of product
%%PRODUCTURL%%		Product		URL of the current product
%%MODELNUMBER%%		Product		Model number of product
%%SHORTDESCRIPTION%%		Product		This is the short description of the product
%%PRODUCTDESCRIPTION%%		Product		This is the long description of the product.
%%ITEMNUMBER%%		Product		This is the item number or SKU
%%PRICES%%		Category		Template to display multiple prices. Must fall within a <!-- BEGIN PRICES --> TS Comment.
%%SALEPRICES%%		Category		Template to display multiple sale prices. Must fall within a <!-- BEGIN SALEPRICES --> TS Comment.
%%PRICING%%		Category
%%MANUFACTURER%%		Category		Displays the manufacturer name.
%%IMAGESLINK%%		Product		Internally generated URL to the image gallery.
%%MANUFACTURERURL%%		Category		Displays the URL to the manufacturer page.
%%QUANTITY%%		Product		Displays the minimum quantity as configured in the admin control panel for the product.
%%WEIGHT%%		Product		Product weight, qty 1
%%SHIPPING1%%		Product		Shipping amount for qty 1
%%SHPPING2%%		Product		Shipping amount each additional product after first
%%PRICE%%		Product		This is the price of the product
%%AMOUNT%%		Product		This is the minimum amount that can be entered in a variable price field.
%%AMOUNTSAVED%%		Product		This shows the difference between the price and sale price.
%%SALEPRICE%%		Product		This is the sale price of the product
%%THUMBIMAGE%%		Product		Default thumb image url
%%SMALLIMAGE%%		Product		Default small image url
%%MEDIUMIMAGE%%		Product		Default medium image url
%%LARGEIMAGE%%		Product		Default large image url
%%IMAGEDESCRIPTION%%		Product		Default image description
%%IMAGESMALL%%		Product		Displays the small image in the gallery section of the product page.
%%GALLERYURL%%		Product		Displays the internally generated URL to the gallery page for the product.
%%OPTION%%		Catalog		Displays the current option
%%OPTIONS%%		Catalog		Displays the individual option items for the current option
%%TEXTITEM%%		Product		Displays the title text of the text item.
%%TEXTITEMURL%%		Product		Displays the internally generated URL of the text item.
%%TITLE%%		Text or Description Popup		Displays the title of the text item.
%%TEXT%%		Text or Description Popup		Displays the text of the text item.
%%BEGINQUANTITY%%		Product		Displays the starting price in a price range
%%ENDQUANTITY%%		Product		Displays the ending price in a price range
%%QUANTITYDIVISOR%%		Product		Displays the configured divisor character(s)
%%DESCRIPTIONS%%
%%CARTVARIABLES%%		Catalog		Hidden form variables needed to add the product to the cart.
Catalog Navigation Tags
%%FIRSTPAGE%%		Catalog		Link to the first page
%%PREVIOUSPAGE%%		Catalog		Link to the previous page
%%FIRSTRECORD%%		Catalog		Number of the first record being displayed on the current page
%%LASTRECORD%%		Catalog		Number of the last record being displayed on the current page
%%TOTALRECORDS%%		Catalog		Number of the total records for the current category
%%NEXTPAGE%%		Catalog		Link to the next page.
%%LASTPAGE%%		Catalog		Link to the last page.
%%PAGES%%		Catalog		Displays the numbers of all the pages as links to those pages.
Cart Information Tags (displayed on the catalog)
%%PRODUCTCOUNT%%		Catalog		This tag shows the current number of products in the cart.
%%ITEMCOUNT%%		Catalog		This tag shows the total number of items in the cart. If there are two products in the cart and one has a quantity of 5, then this will show 6.
%%TOTALSHIPPING%%		Catalog		Shows the current total shipping charges. Note: this may not be accurate due to unknown shipping zip code or unknown shipping method.
%%TOTALTAX%%		Catalog		Shows the current total tax for the order. Note: this may not be accurate due to unknown tax zone.
%%DISCOUNT%%		Catalog		Shows the discount as calculated by the coupon code.
%%GRANDTOTAL%%		Catalog		Shows the total of the cart items including tax, shipping and discounts.
%%FIRSTNAME%%		Catalog		Shows the first name of the shopper, if known
%%LASTNAME%%		Catalog		Shows the last name of the shopper, if known
Selected Attributes Tags (displayed on the catalog)
%%SELECTEDATTRIBUTEHEADER%%		Catalog		Shows the Attribute Header for the block.
%%ATTRIBUTETITLE%%		Catalog		Shows the title of the Attribute.
%%ATTRIBUTEITEM%%		Catalog		Shows the Attribute items. It will display all items within that Attribute.
%%ATTRIBUTEREMOVE%%		Catalog		Shows the name of the remove link.
%%ATTRIBUTEREMOVEURL%%		Catalog		The URL which will be used if someone press the remove link.
Attributes Tags (displayed on the catalog)
%%ATTRIBUTEHEADER%%		Catalog		Shows the Attribute Header for the block.
%%ATTRIBUTETITLE%%		Catalog		Shows the title of the Attribute.
%%ATTRIBUTEITEM%%		Catalog		Shows the Attribute items. It will display all the items within that Attribute as a link so that they can be activated.
%%ATTRIBUTEURL%%		Catalog		The URL which will be used if someone presses on the item.

TS Comments ( PHP Super Cart Template System Comments)

The TS Comments feature make setting up a template very easy. It was designed specifically for PHP Super Cart. It is fast, easy to use, and won’t break your HTML editor. You can now design the entire look of your site without having to break out sections into separate pages and try to guess how they will look or if they will even work. By using regular HTML comments you can easily tell the TS engine all that it needs to know to layout your shopping cart pages.

TS Comments look like this:

html code

In the above example, the XXX represents the specific type of TS Comment, such as MESSAGE, ITEM or EMPTY.

When the TS engine runs, it will know where to look for the various parts of the web page. This now frees you up to designing an entire page, complete with a message area, repeating table elements and even sections that will not display if the cart is empty. Below is a chart of TS Comments along with when they should be used.

CREDITCARD	Checkout	Identifies the credit card area of the billing/checkout page. If none of your gateways accept credit cards then this area is hidden
COUPON	Cart	Identifies an html code block that displays the coupon form. Hidden if a coupon is already entered or if the coupon system has been disabled.
DISCOUNT	Cart, Checkout, Emails	Identifies an html code block that displays the discount. Hidden if the coupon system is disabled or if there is no coupon entered.
CARTITEMS	Cart, Checkout, Emails Tracking	Identifies a repeating html code block that will be used to display all items in the shopping cart.
OPTIONS	Cart, Checkout, Emails Tracking	Identifies a repeating html code block that will be used to display all options for an item in the shopping cart. This TS Comment must be within the CARTITEMS TS Comment. If the item does not have any options, the area will be removed.
OPTION	Cart, Checkout, Emails Tracking	Identifies a repeating html code block that will be used to display all options for an item in the shopping cart. This TS Comment must be within the OPTIONS TS Comment.
MESSAGE	Cart, Checkout	Identifies an html code block that will be displayed if a message is generated. If no message is generated, the area will be removed.
EMPTY	Cart	Identifies an html code block that will be removed from the template if the shopping cart is empty.
VALIDATION	Checkout	Identifies an html code block that will be displayed if the checkout form does not pass validation. If the checkout form does pass validation, the area is removed
QUANTITY	Cart	Identifies an area used to display the “quantity” form field
THUMBIMAGE	Cart Catalog	Identifies an area used to display the “thumbimage” image tag area. If there is no thumb image, the area will be removed.
EXTRA1	Cart	Identifies an area used to display the “extra1” variable, if used. Hidden if there is no extra1 variable
EXTRA2	Cart	Identifies an area used to display the “extra2” variable, if used. Hidden if there is no extra2 variable
EXTRA3	Cart	Identifies an area used to display the “extra3” variable, if used. Hidden if there is no extra3 variable
INVALID	Tracking	Identifies the area to used to display when an invalid tracking code is used.
COMMENTS	Cart Tracking	Identifies the area used to display comments entered by the shopper. If there are no comments, the area is removed.
SHIPPING	Cart	Identifies the area used to display the shipping address fields. If the cart is configured to NOT display separate shipping addresses, the area is removed.
PAYMENTS	Email	Identifies a repeating html code block that will be used to display all payments made on the order.
CART	Catalog	Identifies the area used to build the hidden cart form variables.
OPTIONS	Catalog	Identifies the area to display the product options.
BLOCKXXX	Catalog	Identifies a block of html code to be used as a template when displaying a block. If the current page is configured to NOT display that specific block, the block will be removed. Example <!—BEGIN BLOCKREVIEWS -->.
BLOCKITEM	Catalog	Identifies a block of html code used as a template when displaying the individual block items. Must be contained inside a BLOCKXXX template.
BREADCRUMB	Catalog	Identifies a block of html code used as a template to create breadcrumbs.
SELECTEDATTRIBUTES	Catalog	Identifies a block of html code used as a template to list all the Attributes that have been selected by your visitor.
ATTRIBUTES	Catalog	Identifies a block of html code used to display all the active Attributes for each selected category.
PARENTMENU	Catalog	Identifies a block of html code used as a template to display the parent of the current menu.
CURRENTMENU	Catalog	Identifies a block of html code used as a template to display the current menu.
CHILDMENU	Catalog	Identifies a block of html code used as a template to display the child items of the current menu.
SIBLINGMENU	Catalog	Identifies a block of html code used as a template to display the siblings of the current menu.
SPECIALMENU	Catalog	Identifies a block of html code used as a template to display special categories.
MANUFACTURERMENU	Catalog	Identifies a block of html code used as a template to display manufacturers.
IMAGE	Image Popup	Identifies a block of html code used as a template to display all images in the image popup.
CURRENTTEXTITEM	Catalog	Identifies a block of html code used as a template to display the title of the current text item.
TEXTITEM	Catalog	Identifies a block of html code used as a template to display the title of each text item (not including the current text item).
SMALLIMAGE	Catalog	Identifies an area used to display the “smallimage” image tag area. If there is no small image, the area will be removed.
MEDIUMIMAGE	Catalog	Identifies an area used to display the “mediumimage” image tag area. If there is no medium image, the area will be removed.
LARGEIMAGE	Catalog	Identifies an area used to display the “large” image tag area. If there is no large image, the area will be removed.
MANUFACTURER	Catalog	Identifies an area used to display the manufacturer information. If there is no manufacturer, the area is removed.
ITEMNUMBER	Catalog	Identifies an area used to display the item number. If there is no item number, the area is removed.
MODELNUMBER	Catalog	Identifies an area used to display the model number. If there is no model number, the area is removed.
WEIGHT	Catalog	Identifies an area used to display the product weight. If there is no product weight, the area is removed.
SHIPPING1	Catalog	Identifies an area used to display the shipping for the first item. If there is no shipping charge for the first item, the area is removed.
SHIPPING2	Catalog	Identifies an area used to display the shipping for each additional item. If there is no shipping charge for the each additional item, the area is removed.
GALLERY	Catalog	Identifies an area used to display the image gallery. If there are no images, the area is removed.
IMAGES	Catalog	Identifies an area used to display the primary image of the product. If there is no primary image, the area is removed.
TEXTITEMS	Catalog	Identifies an area used to display the text items of the product. If there are no text items, the area is removed.
PRICE	Catalog	Identifies an area used to display the price. If the price field should be hidden, the area is removed. The price field is hidden if there are multiple prices for the product or if the pricing can be entered by the shopper.
SALEPRICE	Catalog	Identifies an area used to display the sale price. If the sale price field should be hidden, the area is removed. The sale price field is hidden if there are multiple sale prices for the product.
AMOUNT	Catalog	Identifies an area used to display the price when the shopper can choose the price.
PRICES	Catalog	Identifies an area used to display multiple prices. This area will be displayed or PRICE will be displayed but not both.
SALEPRICES	Catalog	Identifies an area used to display multiple sale prices. This area will be displayed or SALEPRICE will be displayed but not both.
PRICING	Catalog
CANCEL	Newsletter	Displays the html area used to ask the customer if they want to cancel the newsletter.
CANCELED	Newsletter	Displays the html area used to tell the customer that they have successfully canceled the newsletter.
CATEGORY	Catalog	Identifies the different product template areas within a category page. A category page can have multiple category blocks. Each block will be used in sequence to display the products.
FIRSTPAGE	Category	Identifies the html code used to display the first page link of a category
LASTPAGE	Category	Identifies the html code used to display the last page link of a category.
UNSUBSCRIBEURL	Newsletter	URL that allows the subscriber to unsubscribe from the newsletter.

At first, using the TS Comments may seem confusing but using them is very straight forward. Below are some examples of how to use TS Comments.

CREDIT CARD

Use the CREDITCARD TS Comment to surround the credit card area of the billing screen. If none of the active gateways support credit cards then this area will be hidden. If you do not accept credit card information locally then you can safely omit this.

<tr>

<td colspan=”2” align=”left”><strong>If you are paying via credit card please fill out the fields below</strong></td>

</tr>

<tr>

<option value=””>Select Credit Card Type</option>%%CCTYPES%%

</select>%%CCTYPEREQUIRED%%

</td>

</tr>

<tr>

<td align=”right” class=”text”>Credit Card Number : </td>

%%CCNUMBERREQUIRED%%</td>

</tr>

<tr>

<td align=”right” class=”text”>Expiration Date (mm/yyyy) : </td>

<option value=””>Select Month</option>%%CCMONTHS%%

</select>

<option value=””>Select Year</option>%%CCYEARS%%</select>

%%CCEXPIREREQUIRED%%

</tr>

<tr>

%%CVVREQUIRED%%</td>

</tr>

COUPON

Use the COUPON TS Comment to surround the coupon form. The form will not be displayed once a valid coupon is entered. If you do not use the coupon system you can safely omit this. If you do not want the coupon form to be hidden after a valid coupon is entered then do not use the COUPON TS Comment. Below is an example of use:

<input type=”hidden” name=”action” value=”coupon”>Coupon 

</form>

DISCOUNT

Use the DISCOUNT TS Comment to surround any area that you do not wish to have displayed if there is no coupon or if the coupon system has been turned off. Multiple areas may be defined. This is handy if you don’t want to show the “Discount” line item in the section that displays totals. Below is an example of use:

<tr>

<td colspan=2 align=right>Coupon (%%COUPON%%)</td>

<td>-%%DISCOUNT%%</td>

</tr>

CARTITEMS

Use the CARTITEMS TS Comment to surround the area that will be used as a template to display all of the cart items. Below is an example:

<tr >

<td>%%PRICE%% </td>

<td>%%TOTAL%%</td>

</tr>

MESSAGE

Use the MESSAGE TS Comment to surround the area that will display all system-generated messages. If there is no message to be displayed this area is removed. The system-genereated messages are as follows:

DuplicateMessage - Displayed when a duplicate item is already in the cart and AllowDuplicates is turned off.

EmptyCart - Displayed when the cart is empty.

<span class=”error”>%%MESSAGE%%</span>

EMPTY

Use the EMPTY TS Comment to surround any area that you do not want to display if the cart is empty. Items that you typically do not wan to display when the cart is empty include the “clear cart” button, “coupon” button, “item headings” area, “totals” area, “recalculate” button and the “checkout” button. Below is an example:

<tr>

<td><b>Description</b></td>

<td><b>Price  </b></td>

<td><b>Amount  </b></td>

</tr>

VALIDATION

Use the VALIDATION TS Comment to surround the area that will display the field validation messages during checkout. This area will be removed when the checkout form is first displayed since no field validation has taken place. Once the customer submits the form the validation script will run. If any fields fail validation the checkout form will be redisplayed with the validation block and validation message(s).

Validation text can be configured in the PHP Super Cart control panel. If a field fails validation then the message configured for that field will be displayed in place of the %%VALIDATION%% TS Tag. Below is an example:

<tr>

<td colspan=”2” class=”error”>The following fields must be filled out:<br>

%%VALIDATION%%</td>

</tr>

COMMENTS

Use the COMMENTS TS Comment to surround the comments area on the checkout form. This area will not display if “Display Comments Field” is set to “No”.

<tr>
<td align=”right”>Comments</td>
<td><div align=”left”>
<textarea name=”comments” cols=”50” rows=”3”>
%%COMMENTS%%
</textarea>
</div></td>
</tr>

Designing The Template

Here are the basic steps for designing your own template system.

1. Copy all of the files and subdirectories from one of the existing templates into a new template directory. This will be your starting point.

2. Use your existing website layout and overwrite the template.php file with your own website html code. You can just view your page in a browser and then view source to get the html code.

3. Remove all of the html code from the main body area of the template.php file and leave all the code that makes up your top and bottom (header/footer) area. This area is typically called the center well or center block.

4. Insert the %%DATA%% tag in the main body area.

5. Make modifications to other pages as necessary.

That’s it.

Appendix A

Template Files and Descriptions
(all files are located in the template directory)

Template	Type	Description
site/index.php	Main	This is the main template file. It should match the overall look of your website. All of the page templates are displayed using this template. In the main body of the template you insert a special Template System Tag (TS Tag) called %%DATA%% right where you want the shopping cart html code to be placed.
blocks/default.php	Page	This is the main file for displaying a block of text inside the main template file.
cart/billing.php	Page	This is used to create the billing page. The contents of this page are inserted into the template.php template when the billing page is displayed. The billing page displays the billing information form and credit card section (if required by an active gateway).
cart/billing-shipping.php	Page	This is used to create the billing page with shipping address information. The contents of this page are inserted into the template.php template when the billing page is displayed. The billing page displays the billing and shipping information form and credit card section (if required by an active gateway).
cart/canceled.php	Page	This is the canceled page that is displayed after a shopper cancels their order from a remote payment gateway. Not all remote gateways support sending a shopper back to a “canceled” page.
cart/cart.php	Page	This is used to create the cart page. The contents of this page are inserted into the template.php template when the shopping cart is displayed. The cart page contains the listing of your shopping cart (products) as well as the tax, shipping, discount and total.
cart/confirm.php	Page	This template displays the final order confirmation page. The products and totals are displayed along with all other cart information.
cart/declined.php	Page	This is the declined page that is displayed after a shopper cancels their order from a remote payment gateway or local credit card gateway. Not all gateways support sending a shopper to a “declined” page.
cart/manual_thankyou.php	Page	This is the thank you page that is displayed after the manual credit card information is supplied. If you do not accept credit card information manually then you do not need this page.
cart/offline_thankyou.php	Page	This is the off-line/manual check display page. It is displayed to show how to make payment arrangements offline.
cart/thankyou.php	Page	This template is displayed after payment has been completed. Not all gateways support returning customers to a “completed” page.
cart/tracking.php	Page	This page displays the order tracking information after an order is completed. It requires a special “key” in the url that is included in the order email.
cart/warning.php	Page	This is a warning that will be displayed if a product is added to the shopping cart from a referrer that is not defined in the PHPCart control panel configuration screen.
categories/category.php (plus others)	Page	Any template in the “categories” directory can be selected to display a particular category. Some category templates display one product per line, some display more. You can customize these files, make copies or create new ones. Each category can have their own category template file and category template files can be shared by multiple categories.
email/email_admin.php	Email	Email template used to email the admin when an order is placed.
email/email_customer.php	Email	Email template used to email the client once they have placed their order.
email/email_payment.php	Email	Email template used to email the customer that you received a payment.
email/email_shipping.php	Email	Email template used to email the customer any update about their shipping..
misc/popup.php	Page	This displays a popup browser window with additional product text.
misc/categorynotactive.php	Page	This message is displayed when a shopper lands on a category page that you have deactivated (such as from a search engine).
misc/gallery.php (located in the misc directory)	Inline Page	This template is displayed inside a product page when the image gallery is displayed. The template defines the look of the image gallery section.
misc/ipopup.php	Popup	This displays a popup browser window with additional product images.
misc/manufacturernotactive.php	Page	This message is displayed when a shopper lands on a manufacturer page that you have deactivated (such as from a search engine).
misc/newsletter.php	Page	This is displayed when cancelling a newsletter subscription..
misc/packingslip.php	Popup	This displays a popup browser window with a packing slip (available from the admin control panel).
misc/popup.php	Popup	This displays a popup when displaying text items or descriptions about a product (if popups are enabled in the admin control panel).
products/product.php	Page	There are several different product templates to choose from. These are used to display your products. Each product can have a separate template and each product template can be assigned to multiple products.

End of file.