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 page templates.

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

  • 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', g.filedata)
  • 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')

6. Loops:
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.
  l.all_settings:product:fieldname
 
  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; </mvt:foreach>

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'" />
<select name="day_of_week">
  <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="">
    <mvt:else>
      <option value="&mvt:global:day;">
    </mvt:if>
    &mvt:global:day;</option>
  </mvt:foreach>
</select>

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.