Custom Template Specification

Custom templates are text files that contain standard HTML tags and custom template tags that define where information from the ShopSite databases is to appear. You can use these tags to define page templates, page links, product templates, and more info page templates1. Use this help page as a custom tag reference, and look at the example page template and example product template for ideas on using the tags. (You can download a zip file here that contains these custom page and product templates, simple page and product databases, and the images required for the store. Upload them all to a test store and publish the store to see a working example of custom templates. Note that it will overwrite part of your existing store, so be sure to back up your databases first or use a test store.)

Template Tag Format

All ShopSite custom template tags have the same basic format:

[-- TAG INFO --]

When a store that uses a custom template is published, ShopSite searches the template for tags with the above syntax and replaces them with information from the pages and products databases, based on the instructions in TAG INFO. ShopSite publishes all standard HTML tags just as they appear in the templates.

HTML authoring programs and browsers should display the ShopSite tags as regular text. This helps while developing and debugging templates by letting you see a template with the tags as placeholders.

Other notes on formatting tags:

Template Tag Definitions

A parameter in curly braces, like this: {parameter} is optional; do not include the braces when using these parameters. A parameter in italics is a placeholder showing where you need to provide a real value.

Global Tags

You can use these tags in both page and product templates.

[-- HEADER --]
Inserts the page header.

 

[-- FOOTER --]
Inserts the page footer.

 

[-- STORE_ID --]
The store's StoreID.

 

[-- OUTPUT_DIRECTORY_URL --]
Returns the full URL to the store's output directory.

 

[-- SEARCH_FORM --]
Inserts the product search form (ShopSite Pro stores only).

 

[-- SHOPPING_CART_URL {BASE} --]
Inserts the full URL to the shopping cart link.

 

With the optional BASE parameter, this tag returns the URL to the shopping cart CGI directory (as set in Preferences > Hosting Service). You can use this tag in your own forms which can be for a multi-product [Add to Cart] button, single-product [Add to Cart] buttons that require a form for specifying quanitity or pull-down options, and for creating your own search box.

 

Note that if you use this tag in a custom page template (not a product template), you cannot use the [--PRODUCT.ViewCartButton--] tag for the link text or graphic. You must specify the link text or graphic, such as:

<a href="[--SHOPPING_CART_URL--]"><img src="media/view_cart1.gif"></a>

 

[-- CALL program.cgi{(parameter1, parameter2, parameterN)} --]
Calls a user-supplied program and replaces the tag with any output from the program. Parameters can be passed to the program by including them as a comma-separated list within parentheses after the program name. If the program does not require any parameters, you do not need to include the parentheses. The user-supplied program must be in the ShopSite CGI directory.

You can include any of the following, which will be substituted before the program is called:

Example:

[-- CALL createthumbnail.pl(20,20,PRODUCT.Graphic) --]

The above example would call a program called createthumbnail.pl in the ShopSite CGI directory, and pass in the values 20, 20, and a full <img> tag for the graphic of the current product. This program might return an <img> tag to a newly-created 20x20 thumbnail of the product graphic.

 

[-- IF param1 {param2} --]
  HTML, text, and custom template tags
[-- ELSE_IF param3 {param4} --]
  HTML, text, and custom template tags
[-- ELSE --]
  HTML, text, and custom template tags
[-- END_IF --]
Tests whether param1 has a value2, or if param1 is equal to param2. Param1 can be any product or page field, such as PRODUCT.DisplayName. Param2 can be any field or a string, such as "Checked."

 

You can nest [-- IF --] tags, and you can use multiple [-- ELSE_IF --] tags. The [-- ELSE_IF --] and [-- ELSE --] tags are optional.

Any custom template tags within the conditional content are replaced with information from the pages and products databases before the content is added to the current page.

The following example inserts the contents of the PAGE.Name field if the merchant has checked the box to display the page name:

[-- IF PAGE.DisplayName --]
  <H1>[-- PAGE.Name --]</H1>
[-- END_IF --]

[-- VAR.name value --]
[-- VAR.name --]
Sets or retrieves a variable value. Use the first format to assign a value to a variable, and use the second format to retrieve the value. For example, this command stores the contents of the current page's Text2 field in a variable named t2:

[-- VAR.t2 PAGE.Text2 --]

You could later retrieve that value with this command:

[-- VAR.t2 --]

You can store almost any value in a VAR variable. These two commands store a numeric value and a string value, respectively:

[-- VAR.numcolumns 2 --]
[-- VAR.bargain "Bargain of the day!" --]

Once a VAR is defined, it's value is available during the rest of the store generation process and can be called from both page and product templates. It can also be used in LOOP and CALL statements, like this:

[-- LOOP PRODUCTS VAR.numcolumns --]
[-- CALL program.cgi VAR.xxxx --]

Page Tags

You can only use these tags in page templates.

[-- DEFINE LINK_TO_PAGE --]
[-- END_DEFINE LINK_TO_PAGE --]
Marks the beginning and end of the HTML that defines the link that other pages will use to link to this page. These tags must come before the [-- DEFINE PAGE --] tag in a template.
Note:
These tags are not required if you are building all page links into your template. However, you must use these tags to define the links to this page if you are letting ShopSite link pages automatically.

You can use any page tags and fields in the LINK_TO_PAGE section, but the tags and fields most commonly used are:

Look at the LINK_TO_PAGE section in the example page template for an example of how to use these tags to create page links.

 

[-- DEFINE PAGE --]
[-- END_DEFINE PAGE --]
Marks the beginning and end of the HTML for the page template. Most of the template will be contained between the [-- DEFINE PAGE --] and [-- END_DEFINE PAGE --] tags.

 

[-- PAGE.Field {REMOVE_HTML} --]
Inserts the contents of Field, which must be the name of a field in the pages database. For example, [-- PAGE.Text1 --] returns the contents of the page's Text 1 field. See the list of database fields for a listing of fields that you can use in page templates.

The optional REMOVE_HTML parameter removes any HTML from the field before displaying it. This can be useful if, for example, you have put HTML tags in the page name field to format how the name is displayed, but also want to use the page name in the <title> tag, which does not allow formatting.

Four fields return their contents in specific formats and do not take the REMOVE_HTML parameter:

 

[-- LOOP PRODUCTS {numcolumns} --]
[-- END_LOOP PRODUCTS --]
Marks the beginning and end of a loop to insert product information on a page. Everything within the loop is repeated for each product assigned to the current page. The loop will insert products on the page in the order specified on the Arrange Items screen, or according to the rules set in the Page Arrangement Settings, or in the order in which they were added to the page if no arrangement was specified.

The optional numcolumns parameter lets you present products in rows in a table, which produces a multi-column layout. You can specify the number of columns in three ways:

When used with the numcolumns parameter, the LOOP tag will be replaced with a <TR> tag and the END_LOOP tag will be replaced with a </TR> tag when the page is generated, so you should not include those tags in your template. Study the example multi-column page template to see how this works. There is also an example multi-column product template designed to work with the page template. The product template does not contain any tags that are explicitly for multi-column layouts, but it must work with the page template to produce correct HTML.

 

[-- PRODUCT --]
Inserts the fields for the next product within a [-- LOOP PRODUCTS --] loop. This tag must appear on a line by itself between a [-- LOOP PRODUCTS --] and an [-- END_LOOP PRODUCTS --] tag.

The product fields that are inserted are defined by these rules:

  1. If the product template includes the tag for a field and the current product has a value for that field, the value will be inserted.

     

  2. If the template tag for a field is not included in the product template, the field value will never be displayed, regardless of whether it is set in the database.

     

  3. If the product template uses a tag, such as [-- PRODUCT.SKU --], but the SKU field has no entry, the ShopSite parser will insert an HTML comment tag indicating that the field was empty.

     

  4. If the "Toggle" fields for a product are set to not display certain fields, but the template includes tags for those fields, the field values will be inserted in the page. For example, if the SKU Toggle field is set to not display, but the template includes the [-- PRODUCT.SKU --] tag, the SKU will be inserted.

 

[-- LOOP LINKS {numcolumns} --]
[-- END_LOOP LINKS --]
Marks the beginning and end of a loop to insert links to other pages on the current page. Everything within the loop is repeated for each page link assigned to the current page. The loop will insert links on the page in the order specified on the Arrange Items screen, or according to the rules set in the Page Arrangement Settings, or in the order in which they were added to the page if no arrangement was specified.

The optional numcolumns parameter lets you present links in rows in a table, which produces a multi-column layout. See the LOOP PRODUCTS tag for more information.

 

[-- LINK --]
Inserts the next page link within the [-- LOOP LINKS --] loop. This tag must appear on a line by itself between a [-- LOOP LINKS --] and an [-- END_LOOP LINKS --] tag. Page link information is defined in the [-- DEFINE LINK_TO_PAGE --] section, based on the Link Info fields in the pages database.

 

[-- LOOP ITEMS {numcolumns} --]
[-- END_LOOP ITEMS --]
Marks the beginning and end of a loop to insert Items on a page. Everything within the loop is repeated for each item. Use the ITEM tags to insert product information and links to other store pages. The loop will insert items on the page in the order specified on the Arrange Items screen, or according to the rules set in the Page Arrangement Settings, or in the order in which they were added to the page if no arrangement was specified.

The optional numcolumns parameter lets you present items in rows in a table, which produces a multi-column layout. See the LOOP PRODUCTS tag for more information.

 

[-- ITEM --]
Inserts the next product or page link within the [-- LOOP ITEMS --] loop. This tag must appear on a line by itself between a [-- LOOP ITEMS --] and an [-- END_LOOP ITEMS --] tag.

Product Tags

These tags can only be used in product templates.

[-- DEFINE PRODUCT --]
[-- END_DEFINE PRODUCT --]
Marks the beginning and end of the HTML for the product template. Most of the template will be contained between the [-- DEFINE PRODUCT --] and [-- END_DEFINE PRODUCT --] tags.

 

[-- PRODUCT.Field {REMOVE_HTML} --]
Inserts the contents of Field, which must be the name of a field in the products database. The optional REMOVE_HTML parameter removes any HTML from the field before displaying it. See the list of database fields for a listing of fields that you can use in product templates.

For example, [-- Product.Name --] returns the contents of the product's Name field.

Two fields return their contents in specific formats:

 

[-- PRODUCT.RecordNumber --]
Inserts the record number of the product. You can use this tag to create HTML anchor tags to link directly to a specific product, such as <a name="#[-- PRODUCT.RecordNumber --]">

 

[-- PRODUCT.AddToCartURL --]
Inserts the URL needed to create a link to the shopping cart and add the current product. Note that the template must provide the HTML tags and the text or graphic for the link. For example, an AddtoCartURL tag that uses a graphic might look like this:

<a href="[-- PRODUCT.AddToCartURL --]"><img src="buynow.gif"></a>

 

[-- PRODUCT.OrderCheckout --]
Returns a complete set of FORM tags to present the [Add to Cart] and [View Cart] buttons, as defined for the product. If the product has the display of ordering options and/or quantity enabled, they are included as parts of the form.

 

[-- ORDER_OPTION_MENU COLUMN --]
[-- ORDER_OPTION_MENU LINE --]
Returns a complete HTML table to present the ordering options for a product, either all on one line or all in one column. This tag must be placed inside a FORM tag.

 

[-- LOOP SUBPRODUCTS {numcolumns} --]
[-- END_LOOP SUBPRODUCTS --]
Marks the beginning and end of a loop to insert subproduct information on a page. Everything within the loop is repeated for each subproduct assigned to the current product.

The optional numcolumns parameter lets you present subproducts in rows in a table, which produces a multi-column layout. You can specify the number of columns in two ways:

When used with the numcolumns parameter, the LOOP tag will be replaced with a <TR> tag and the END_LOOP tag will be replaced with a </TR> tag when the page is generated, so you should not include those tags in your template.

 

[-- SUBPRODUCTS --]
Inserts the fields for the next subproduct within a [-- LOOP SUBPRODUCTS --] loop. This tag must appear on a line by itself between a [-- LOOP SUBPRODUCTS --] and an [-- END_LOOP SUBPRODUCTS --] tag.

 

[-- DEFINE SUBPRODUCT --]
[-- END_DEFINE SUBPRODUCT --]
Marks the beginning and end of the HTML that defines the presentation of a subproduct in this product template. These tags must come before the [-- DEFINE PRODUCT --] tag in a product template.
You can use all global and product tags within a subproduct definition, but note that product tags will produce information about the subproduct, not about the parent product.
More Info Page Tags

These tags can be used to create product More Info pages and can only be used in product templates. These tags must come outside the [-- DEFINE PRODUCT --] and [-- END_DEFINE PRODUCT --] tags within a product template.

[-- PRODUCT.MoreInfoURL --]
Inserts the URL of the product's More Info page, assuming one is defined.

 

[-- DEFINE MORE_INFO_PAGE --]
[-- END_DEFINE MORE_INFO_PAGE --]
Marks the beginning and end of the HTML that defines a More Info page for this product.

 

[-- MORE_INFO.DisplayPageHeader --]
Returns checked if the store's page header is to be displayed. Use an IF statement to determine the value:

[-- IF MORE_INFO.DisplayPageHeader --]
<P>[-- HEADER --]</P>
[-- END_IF --]

 

[-- MORE_INFO.DisplayPageFooter --]
Returns checked if the store's page footer is to be displayed. Use an IF statement to determine the value:

[-- IF PAGE.DisplayPageFooter --]
<P>[-- FOOTER --]</P>
[-- END_IF --]

 

[-- MORE_INFO.BackgroundColor --]
Inserts a pound sign (#) and the hex value of the background color of the More Info page.

 

[-- MORE_INFO.BackgroundImage --]
Inserts the file name of the background image for the More Info page. Note that the template must include the rest of the tag to use the image, such as:

<BODY BACKGROUND="[-- MORE_INFO.BackgroundImage --]">

 

[-- MORE_INFO.TextColor --]
Inserts a pound sign (#) and the hex value of the text color of the More Info page.

 

[-- MORE_INFO.LinkColor --]
Inserts a pound sign (#) and the hex value of the unvisited link color of the More Info page.

 

[-- MORE_INFO.VisitedColor --]
Inserts a pound sign (#) and the hex value of the visited link color of the More Info page.

 

[-- MORE_INFO.ActiveColor --]
Inserts a pound sign (#) and the hex value of the active link color of the More Info page.

1 The custom templates feature in ShopSite 6.1 cannot be used to create all of the features that are present in the built-in ShopSite templates.

2 Several fields have default values and will never return null, and thus cannot be used in an IF statement. See the list of database fields to find the possible values for each field.

ShopSite Help and Resource Center
July 5, 2002
Give Feedback
Copyright © ShopSite, Inc.
http://www.shopsite.com