Screen: ShopSite > Merchandising > Custom Templates
Custom Template Tag Specification
Global Tags
Most global tags can be used in any type of custom template.
INCLUDE
- [-- INCLUDE filename {PROCESS} --]
- Places the contents of filename into the output file.
With the optional PROCESS parameter, any custom template tags in contents of filename are replaced with their database values before the contents are placed into the output file.
VAR
- [-- VAR.name value --]
[-- VAR.name --]
[-- VAR.name {INC} {DEC} --]
- Sets or retrieves a variable value, or increments/decrements a numeric 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!" --]
If the value stored is numeric, you can increment or decrement the value by 1 with the INC and DEC parameters, like this:
[-- VAR.t2 INC --]
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 --]
FLAGS
Many tags can accept special flags as part of the tag to add special rules for processing the tag. The following flags are "general", and can be used in a variety of different places:
- [-- FIELD.Name JS_ENCODE --]
- The JS_ENCODE flag gan be used on PRODUCT or PAGE tags to escape reserved characters (e.g. /, ’, ", etc.). This will prevent the reserved characters from unintentionally altering the JavaScript function, such as customized Customer Registration links, a custom MiniCart, or ANALYTICS_MULTI_DOMAIN code. For example:
<script type="text/javascript" language="JavaScript">
document.write('<a href="javascript:__utmLinker(\'[-- PRODUCT.MoreInfoURL --]\');">[-- PRODUCT.Name JS_ENCODE --]</a>');
</script>
- [-- FIELD.Name REMOVE_HTML --]
- The REMOVE_HTML flag can be used with any field which could contain HTML tags or with graphic tags (e.g. [-- PAGE.Graphic --]).
When used in a text field, any HTML tags will be stripped out of the field, leaving only the unformatted text. This could be used to use the field within an HTML element. For example:
<a href="[-- PRODUCT.MoreInfoURL --]" title="[-- PRODUCT.Name REMOVE_HTML --]">[-- PRODUCT.Name</a>
When used with a graphic tag, the flag will cause the beginning <img and closing > to be removed from the image tag, allowing you to customize the tag. NOTE: ShopSite Version 8.2 and later allow the merchant the option to customize image tags, so use of REMOVE_HTML for graphic tags may not be desirable.
IF
- [-- 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 value1, 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." Strings must be enclosed in quotation marks, and string comparisons are case sensitive.
- If an IF or ELSE_IF tag only contains one parameter, the ShopSite parser checks to see if the parameter has a value (that is, if the merchant has entered a value for that field). If there is a value, the parser adds the contents before the next ELSE/ELSE_IF/END_IF tag to the page that is currently being generated. If the parameter has no value, the parser skips to the next such tag.
- If an IF or ELSE_IF tag contains two parameters, the parser compare the values to see if they are equal (string compare). If they are equal, the parser adds the contents before the next tag to the page that is currently being generated. If the parameters are not equal, the parser skips to the next 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 tests whether the merchant has checked the box to display the page name, and inserts the contents of the PAGE.Name field if it checked:
[-- IF PAGE.DisplayName --]
<H1>[-- PAGE.Name --]</H1>
[-- END_IF --]
This example tests whether the page name matches a string, and inserts the contents of the PAGE.Field1 field if it matches:
[-- IF PAGE.Name "About Us" --]
<H1>[-- PAGE.Field1 --]</H1>
[-- END_IF --]
- [-- IF ANALYTICS_MULTI_DOMAIN --]
This is a specific IF call you can use to test whether or not to create special URLs for Google Analytics tracking cross-domain links. It will return true if Google Analytics is enabled and either the shopping cart or secure domain name is different from the store domain name.
For example, if a store were using Google Analytics, and the store used the domain name www.mystore.com, but the shopping cart used www.checkout.com, you would need to make sure links and forms that went from the store pages to the shopping cart pages (such as an Add To Cart button) sent the correct information for Google Analytics.
The following is an example of using this tag for a View Cart button:
[-- IF ANALYTICS_MULTI_DOMAIN --]
<script type="text/javascript" language="JavaScript">
document.write('<a href="javascript:__utmLinker(\'[-- SHOPPING_CART_URL --]\');">[-- ViewText --]</a>');
</script>
<noscript>
<a href="[-- SHOPPING_CART_URL --]">[-- ViewText --]</a>
</noscript>
[-- ELSE --]
<a href="[-- SHOPPING_CART_URL --]">[-- ViewText --]</a>
[-- END_IF --]
You could also use the tag to make sure a FORM tag, such as the search form below, gets handled right:
[-- IF ANALYTICS_MULTI_DOMAIN --]
<form action="[-- SHOPPING_CART_URL BASE --]/productsearch.cgi?storeid=[-- STORE.ID --]" method="post" onSubmit="javascript:__utmLinkPost(this)">
[-- ELSE --]
<form action="[-- SHOPPING_CART_URL BASE --]/productsearch.cgi?storeid=[-- STORE.ID --]" method="post">
[-- END_IF --]
CALL External Program
- [-- 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.
If a CALL tag is used in a page or product template, the user-supplied program must be in the ShopSite CGI directory. If a CALL tag is used in a shopping cart or registration template, the program must be located in the shopping cart 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
- PRODUCT.MoreInfoURL - the path of the product's More Information page
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.
Debugging Tag
When designing custom templates, it can be useful to know what values are being used for specific things. The GENERATE_MESSAGE tag will display a specific message and the value of a VAR, PAGE, or PRODUCT tag on the page generation screen in the back office.
- [-- GENERATE_MESSAGE "message" {VAR.name} --]
- Display message and (optionally) the value of VAR.name on the page generation screen in the back office.
Store Tags
Most store tags can be in all templates, and can be used with the REMOVE_HTML parameter.
Store Identification
- [-- STORE.ID --]
- The encrypted store ID.
- [-- STORE_Serial_Number --]
- The store serial number.
- [-- STORE.Type --]
- The store product level: PROFESSIONAL, MANAGER, STARTER, or EXPRESS. Use this tag to test for features that are not available in all products, such as product search, which is only available in Pro and Manager stores.
Store URLs
- [-- MyStoreURL --]
- Returns the full URL to the store's output directory.
- [-- STORE.Output_URL --]
[-- Output_Directory_URL --]
- Returns the full URL to the store's output (HTML) directory.
- [-- 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>
- [-- ShopSite_Images --]
- Returns the URL to the store's ShopSite Images directory
E-Mail Addresses
- [-- STORE.Email --]
- The merchant's e-mail address.
- [-- STORE.EmailTo --]
- The merchant's e-mail address in a full mailto: HTML tag.
Date and Time
- [-- STORE.Date --]
- Server date when the page was generated.
- [-- STORE.Time --]
- Server time when the page was generated.
Text Field Tags
The default values for these fields are shown here, but the merchant can change the text.
- [-- STORE.Name {Remove_HTML} --]
- The store's name.
- [-- STORE.Product --]
- Product
- [-- STORE.ProductName --]
- Product Name
- [-- STORE.Product --]
- Product
- [-- STORE.Price --]
- Price
- [-- STORE.OnSaleText {Remove_HTML} --]
- The text of the On Sale field, set in the Preferences > Store Text > Store Pages screen.
- [-- STORE.Sku --]
- SKU
- [-- STORE.Item --]
- Item
- [-- STORE.Items --]
- Items
- [-- STORE.Contains --]
- Contains
- [-- STORE.Subtotal --]
- Subtotal
- [-- STORE.Qty --]
- Qty
- [-- STORE.Quantity --]
- Quantity
- [-- STORE.TotalQuantity --]
- Total Quantity
- [-- STORE.Back --]
- Back
- [-- STORE.URL --]
- Store URL:
- [-- STORE.YourIP --]
- Your IP Address is
- [--STORE.Home--]
- Home
- [--STORE.OrderQuantity--]
- Order Quantity
- [-- Store.MoreDetails --]
- More Details
- [-- Store.RelatedProducts --]
- Related Products
- [-- Store.Inventory --]
- Inventory
- [-- STORE.AddToCart --]
- The text or image defined for the Add to Cart button in the store. ShopSite Pro stores can also use the [-- PRODUCT.AddToCartButton --] tag.
- [-- STORE.DisplayAddToCartText --]
- returns checked if [-- STORE.AddToCart --] is text, unchecked indicates that [-- STORE.AddToCart --] contains the filename for the image to be used.
- [-- STORE.ViewCart --]
- The text or image defined for the View Cart button in the store. ShopSite Pro stores can also use the [-- PRODUCT.ViewCartButton --] tag.
- [-- STORE.DisplayViewCartText --]
- returns checked if [-- STORE.ViewCart --] is text, unchecked indicates that [-- STORE.ViewCart --] contains the filename for the image to be used.
- [-- STORE.SearchImage --]
- The Search button image name.
1 Several fields have default values and will never return null, and thus cannot be used in an IF statement. See the page tags and product tags to find the possible values for each field.
