Thing you should know about Toolbelt and Page templates
Toolbelt makes Page Templates a robust scripting language. This document provides basic information that you need to know to
avoid common mistakes and get the most out of Toolbelt and Merchant
1. Keep the
documentation open while you work. It fully documents Page Templates, MivaScript functions, and all Toolbelt commands. Use crtl-F to search the
documentation with your browser.
Laptop users may find the documentation in the admin does not fit their display. In the admin, right click on
Utility and select Open Link in new Tab to provide better viewing.2. Comment Out Items:
- Toolbelt items can be commented out using the # character directly in front of an item name. For example.
- <mvt:item name="ry_toolbelt" param="#assign|g.varname|expression" />
- Storemorph provides the <mvt:comment> </mvt:comment> tags that you can put around sections of code.
3. Variables: Variable names are not case sensitive, must start with a letter or underscore and can contain
numbers, a colon : (for structures) or brackets [ ] (for arrays). The can NOT contain hyphens.
These come have several prefixes:
- g.varname (global)
- l.settings:varname (used in storemorph items)
- l.all_settings:varname (used in Toolbelt and 3rd party modules)
- s.varname (system or environmental variables)
l.settings vs. l.all_settings: Internally Miva Merchant makes extensive use of a local data structure called l.settings. You will see it use in
template if expression. For example:
<mvt:if expr="l.settings:product:inv_level NE 'out'">
ONLY the Template language can use l.settings so Merchant makes copy of it called l.all_setttings: available to third
party modules like Toolbelt. Try to remember ALL Toolbelt items ALLways use l.all_settings. For example:
<mvt:item name="ry_toolbelt" param="assign|g.out|l.all_settings:product:inv_level" />
4. Varlist = The keys to the castle: This item opens a door to all the hidden variables, arrays and structures.
See the item documentation for complete details.
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products', l.all_settings)" />
5. Expressions: Toolbelt lets you use expressions nearly everywhere, so you can get more done with less
- variables: g.Category_Code
- literal text: 'string' always use single quotes.
- literal numbers: 3.1416
- operators: AND OR NOT IN EQ etc. The complete list operators is detailed in the documentation.
- The dollar sign $ is used to add strings together. 'John' $ ' ' $ 'Doe'
- You can normally use an expression where you see a variable name as a parameter.
- Literal strings and functions can all be used to create complex expressions. assign | g.alt_image|'/images/' $
l.all_settings:product;code $ '-1.jpg'
- Use Toolbelt and MivaScript Functions: PercentFormat(g.discount), file_read(g.filepath_name, 'script',
- Functions can be nested inside each other. Capitalize and replace ampersands with "and" in a product name.
eval | glosub(Capitalize(l.all_settings:product;name),asciichar(38),'and')
The foreach Item: This command loops through a structured array 1 item at a time. In the example below
the products array is a structure that looks like this l.all_settings:products[n]:fieldname
<mvt:foreach iterator="product" array="products"> Notice l.all_settings: has been removed and is implied.
Inside the loop each individual record is in a structure like this.
You can access and manipulate the data using Toolbelt.
In this example part of a product code is used to create an image filename.
assign|g.filename|tolower('/images/' $ substring(l.all_settings:product:code,1,6) $ '_1.jpg')
To print the page use &mvt:product:code;
The for Item: This command lets you create your own loop. You can step forwards,
backwards, or count by twos if you want. This example takes a comma separated list and creates a select
box. It also makes use of Toolbelts GettokenCount() function
<mvt:item name="ry_toolbelt" param="assign|g.list|'Sunday,Monday,Tuesday,Wednesday,Thrusday,Friday,Saturday'" />
<option value="">Select a day</option>
<mvt:item name="ry_toolbelt" param="for|j=1 to GettokenCount(g.list,',')" />
<mvt:foreach iterator="j" array="for_j">
<mvt:item name="ry_toolbelt" param="assign|g.day|gettoken(g.list,',',l.all_settings:j)" />
<mvt:if expr="g.day_of_week EQ g.day">
<option value="&mvt:global:day;" selected="">
7. Power Tools: If Assign is a bucket, Query is an excavator and Do is a tunnel boring machine. These power
tools give you complete access to the databases and the inner working of Merchant. Use caution when using these with
form data so that you don't open a security hole. Validate incoming form data and use the functions encodeentities()
with regular data and encodeattribute() for strings that are part of a URL to thwart hacking attempts.