PHPCart Template System

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

Overview

The PHPCart Template System (TS) was designed to allow webmasters and web designers to easily integrate the PHPCart Shopping Cart System into their websites. The PHPCart 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 you really only need to modify one template to get PHPCart up-and-running. The main template file (template.php) is the only file that really needs to me modified. You only modify the other template files if you don't like the default layout.

PHPCart comes with 2 templates to choose from. You can use either 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 "templates" directory and copy all of the files and folders from one template 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 PHPCart control panel.

There are 11 different template files that make up the PHPCart Template System. You can easily modify any of them to fit your needs. Below is a list of the template files and a description of when they are used:

Template	Type	Description
template.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.
cart.php	Page	This is used to create the cart template page. It defines the look of your shopping cart. The contents of this page are inserted into the template.php template when the shopping cart is displayed. The cart page displays all of the cart items and the cart totals. It also can display the coupon.
billing.php	Page	This is used to create the billing page. It defines the look of the billing page. The contents of this page are inserted into the template.php template when the billing page is displayed.
checkout.php	Page	This is used to create the checkout page. It defines the look of the customer checkout page. The contents of this page are inserted into the template.php template when the checkout page is displayed.
thankyou.php	Page	This template is displayed after payment has been approved. Not all gateways support returning customers to an "approved" page.
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.
offline.php	Page	This is the off-line/manual check display page. If you accept orders without an online payment then this page will display the instructions.
canceled.php	Page	This page is displayed if the customer goes to a gateway to make a payment and then chooses to cancel the order prior to completing the transaction. Not all gateways support returning the client to a cancel page.
declined.php	Page	This page is displayed if the customer's payment id declined. Not all gateways support returning the client to a declined page.
minicart.php	Page	This template is used to display the cart total on a page other than a PHPCart page.
email_admin.php	Email	Email template used to email the admin when an order is placed.
email_admin_ccinfo.php	Email	Email template used to email the admin when a manual credit card order is received.
email_customer.php	Email	Email template used to email the client once they have placed their order.
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.

Getting Started

The TS (PHPCart Template System) consists of files located in the templates directory and subdirectories. You can use any of the existing templates, modify them to fit your website, or completely design your own from scratch. Once you create a subdirectory under the templates directory you will be able to choose that template (based on the subdirectory name) from the configuration screen. You can change between templates at any time.

The TS (PHPCart 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.

TS Tags (PHPCart 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:

<tr>

<td align="right">Total: </td><td>%%TOTAL%%</td>

</tr>

</table>

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 foreground and background colors as well as the current template directory. Below is a chart of all of the TS Tags along with when they should be used.

TS Tag	Template	Where Used
Cart Specific TS Tags
%%ROW%%	Cart	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
%%NAME%%	Item	Displays the item name.
%%OPTIONS%%	Item	Displays the options, if any, for the item
%%PRICE%%	Item	Displays the item price
%%QUANTITY%%	Item	Displays the item quantity
%%WEIGHT%%	Item	Displays the item weight
%%TAX%%	Item	Displays the tax for the item
%%SHIPPING%%	Item	Displays the shipping charge per 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.
%%EXTRA1%%	Item	Displays the information passed in the extra1 variable
%%EXTRA2%%	Item	Displays the information passed in the extra2 variable
%%EXTRA3%%	Item	Displays the information passed in the extra3 variable
%%TOTAL%%	Item	Displays the item total
%%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
%%ORDERDATE%%	Checkout, Email	Displays the date/time of the order
%%ORDERID%%	Checkout, Email	Displays the order ID
Company Specific TS Tags (from admin configuration)
%%COMPANYNAME%%	All
%%COMPANYADDRESS%%	All
%%COMPANYWEBSITE%%	All
%%COMPANYPHONE%%	All
%%COMPANYEMAIL%%	All
%%HOMEPAGE%%	All
Font/Color Specific TS Tags (from admin configuration)
%%HEADERCOLOR%%	All
%% HEADERBGCOLOR %%	All
%%TEXTCOLOR%%	All
%%ROWCOLOR%%	All	Variable alternates between %%ROWCOLOR1%% and %%ROWCOLOR2%%
%%ROWCOLOR1%%	All
%%ROWCOLOR2%%	All
%%FONT%%	All
%%FONTSIZE%%	All
Customer Specific Tags
%%FIRSTNAME%%	Checkout
%%LASTNAME%%	Checkout
%%ADDRESS%%	Checkout
%%ADDRESS2%%	Checkout
%%CITY%%	Checkout
%%STATE%%	Checkout
%%STATES%%	Checkout	This tag is used to display the data from the states.php template file. Data is displayed as option values for the "state" field.
%%STATEOTHER%%	Checkout
%%ZIP%%	Checkout
%%COUNTRY%%	Checkout
%%PHONE%%	Checkout
%%COMPANY%%	Checkout
%%EMAIL%%	Checkout
%%COMMENTS%%	Checkout
Credit Card TS Tags
%%CCNUMBER%%	Checkout	Credit Card Number
%%CCTYPE%%	Checkout	Credit Card Type (Visa, MC, etc)
%%CVVCODE%%	Checkout	CVV Code (3 or 4 digit)
%%CCMONTH%%	Checkout	Expire Month
%%CCYEAR%%	Checkout	Expire 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.
%%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
%%FIRSTNAMEREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the firstname field fails validation
%%LASTNAMEREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the lastname field fails validation
%%ADDRESSREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the address field fails validation
%%CITYREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the city field fails validation
%%STATEREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the state field fails validation
%%ZIPREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the zip field fails validation
%%COUNTRYREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the country field fails validation
%%PHONEREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the phone field fails validation
%%EMAILREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the email field fails validation
%%CCTYPEREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the cctype field fails validation
%%CCNUMBERREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the ccnumber field fails validation
%%CCEXPIREREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the ccexpire field fails validation
%%CVVREQUIRED%%	Checkout	Displays the text of the PaymentMethodRequired variable in the language file if the cvvcode field fails validation
Miscellaneous TS Tags
%%MESSAGE%%	Cart	Displays the following messages when appropriate: Invalid Coupon Duplicate Item Not Added Empty Cart
%%PREVIOUSPAGE%%	Cart	URL to the previous page. This variable is used to link back to the referring page.
%%DATA%%	Template	Displays PHPCart in your main template file.
%%PAYMENTMETHODS%%	Checkout	Displays all of the payment options
%%PAYMENTTYPE%%	Checkout	Displays the selected payment method
%%TEMPLATEPATH%%	All	Displays the path to the template directory. Can be used to point to images in the template directory.
%%VALIDATION%%	Checkout	Displays the validation message(s) if any one or more fields fails validation

TS Comments (PHPCart Template System Comments)

TS Comments make setting up a template very easy. It was designed specifically for PHPCart. 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	Identifies a repeating html code block that will be used to display all items in the shopping cart.
MESSAGE	Cart, Checkout	Identifies an html code block that will be displayed if a message is generated.
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.
EXTRA1	Checkout	Identifies an area used to display the "extra1" variable, if used.
EXTRA2	Checkout	Identifies an area used to display the "extra2" variable, if used.
EXTRA3	Checkout	Identifies an area used to display the "extra3" variable, if used.

At first, using the TS Comments may seem confusing but using them is very straight forward.

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>
            <td align="right" class="text">Card Type : </td>
            <td align="left"><select name="cctype">
            <option value="">Select Credit Card Type</option>%%CCTYPES%%
            </select>%%CCTYPEREQUIRED%%
            </td>
</tr>
<tr>
            <td align="right" class="text">Credit Card Number : </td>
            <td align="left">
<input type="text" name="ccnumber" size="24" value="%%CCNUMBER%%">
            %%CCNUMBERREQUIRED%%</td>
</tr>
<tr>
            <td align="right" class="text">Expiration Date (mm/yyyy) : </td>
            <td align="left"><select name="ccmonth">
<option value="">Select Month</option>%%CCMONTHS%%
            </select>
            <select name="ccyear">
            <option value="">Select Year</option>%%CCYEARS%%</select>
            %%CCEXPIREREQUIRED%%
</tr>
<tr>
            <td align="right" class="text">CVV Code : </td>
            <td align="left">
<input type="text" name="cvvcode" size="5" value="%%CVVCODE%%">
            %%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:

<form action="phpcart.php" method="post" name="couponform">
<input type="hidden" name="action" value="coupon">Coupon 
<input type="text" name="couponcode"> 
<input type="image" src="%%TEMPLATEPATH%%images/validate.gif" border="0">
</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><a href="phpcart.php?action=delete&id=%%ROW%%">
            <img src="%%TEMPLATEPATH%%images/trashicon.gif" border="0"></a></td>
            <td>%%ID%%</td>
            <td>%%NAME%%</td>
            <td>%%PRICE%% </td>
            <td><input type="text" name="product[%%ROW%%]" value="%%QUANTITY%%"></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 colspan="2">><b>ID</b></td>
            <td><b>Description</b></td>
            <td><b>Price  </b></td>
            <td><b>Qty.</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 PHPCart 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.

Copy all of the files and subdirectories from one of the existing templates into a new template directory. This will be your starting point.
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.
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.
Insert the %%DATA%% tag in the main body area.
Make modifications to other pages as necessary.

That's it.