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.

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 database, 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:

Tags are not case-sensitive.

A tag may not extend over more than one line. That is, there cannot be any carriage returns or line feeds within a tag.

The following tags must appear on lines by themselves; all other tags can be placed on lines that contain other text, other tags, and HTML.

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 --]

Inserts the full URL to the shopping cart link.

Note that if you use this tag outside of a custom 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:

[-- 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:

Database fields, in the same form as defined for pages and products, such as PAGE.Name or PRODUCT.Graphic

STORE_ID - the store's StoreID

OUTPUT_DIRECTORY_URL - the URL of the store's HTML directory

OUTPUT_DIRECTORY_PATH - the path of the store's output directory

SHOPPING_CART_URL - the URL of the store's shopping cart

DATA_DIRECTORY_PATH - the path of the store's data directory

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 field-A --] [-- ELSE_IF field-B --] [-- ELSE --] [-- END_IF --]

Tests whether field-A has a value2.

If field-A has been set, the ShopSite parser adds the contents before the [-- ELSE_IF --] tag to the page that is currently being generated.

If field-A has no value, the parser tests whether field-B has a value. If it does, the parser adds the content before the [-- ELSE --] tag.

If neither field-A nor field-B have values, the parser adds the contents after the [-- ELSE --] tag.

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:

PAGE.LinkName
PAGE.LinkGraphic
PAGE.LinkText
PAGE.FileName
[-- OUTPUT_DIRECTORY_URL --]

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:

FileName - returns "Page#.html" if the field is blank, where # is the record number of the page.
Colors - all color fields returns a hex color value, preceded by the pound sign (#). This includes PAGE.BackgroundColor, PAGE.LinkColor, etc.

Graphic and LinkGraphic - return a full <img src> tag with all formatting information, including size and alt values, as defined in the images section of ShopSite. For example:
[-- PAGE.Graphic --]

returns a tag in this format:
<img src="http://www.store.com/media/graphic.gif" width=50 height=40 alt="Example" hspace=3 vspace=3 border=0>

[-- 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:

PAGE.Columns, which uses the number of columns set by the merchant for the page
A number, to define a fixed number of columns
VAR.xxx, to use a variable value set previously in the template

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:

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.
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.
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.
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:

FileName - returns "Product#.html" if the File Name field for a more info page is blank, where # is the record number of the page.
Graphic - returns a full <img src> tag with all the formatting information, including size and alt values, as defined in the images section of ShopSite. For example:
[-- PRODUCT.Graphic --]

returns a tag in this format:
<img src="http://www.store.com/media/productgraphic.gif" width=50 height=40 alt="Example" hspace=3 vspace=3 border=0>

[-- 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:

[-- 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.

[-- 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. These tags must come outside the [-- DEFINE PRODUCT --] and [-- END_DEFINE PRODUCT --] tags in a product template.

[-- 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:

[-- 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.0 cannot be used to create all of the features that are present in the built-in 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
February 22, 2002
Give Feedback