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 --]
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 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." 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 --]
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>
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.TotalQuantity --]
- Total Quantity
- [-- STORE.Back --]
- Back
- [-- STORE.URL --]
- Store URL:
- [-- STORE.YourIP --]
- Your IP Address is
- [-- 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.
1 The custom templates feature 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 page tags and product tags to find the possible values for each field.
