E-Commerce, Web Design, Custom Solutions.

Tool Belt Docs

Tool Belt Docs

Code: toolbelt_docs

To see the actual module Click here.

Index
Last Update: 9/28/2010

PCI Net ToolbeltTM Overview

What is Toolbelt?

Toolbelt is an add on module for Miva Merchant 5TM web stores that dramatically extends the page template language, Store Morph TM, adding hundreds of new functions and commands. It gives store owners and developers the ability to create store pages that were impossible before. Additional page templates included in the zip file show many fully commented, real world examples of how you can script your pages to do things that once required external modules. Toolbelt turns page templates into a robust scripting environment.

Index

What's in this guide?

Rather than assume you know all about Page, Items, and Functions and programming, this guide provides the core information you need in a single resource as well as serving as a complete function reference guide.

Store Morph is easy to learn. All you need is a basic knowledge of HTML and a few programming concepts. Toolbelt makes Store Morph a more complete scripting language and a knowledge of programming, while not essential will make the concepts presented here easier to understand.

Parts of this document are excerpts from the Miva Merchant 5 Documentation and MivaScript Guide 4.0x. They are reproduced here with the permission of Miva Merchant.

Toolbelt Examples:

I recommend that you set up a new Page Template with a page code called TEST, where you can try out the many examples presented here, without interfering with your store. You will be able to view the test page by navigating to http://www.YourStoreName.com/mm5/merchant.mvc?page=TEST. Make sure you click the Items tab, find ry_toolbelt and assign it to the page by clicking the checkbox and clicking [Update]

Index

Installation:

  1. After you have downloaded and unpacked the zip file to your hard drive, login to the Miva Merchant admin.
  2. Under Global Settings, click on the "Modules [Add]" link in the left navigation.
  3. The "Add Module" screen will be displayed. Click the [Upload] button.
  4. The "Upload File" window will be displayed. Click on the [Browse] button and locate and the module's ry_toolbelt.mvc file on your hard drive and click [Open], then click on the [Upload] button.
  5. The file will be uploaded, and the file name and path displayed in the "Module" field of the main admin frame. Click the [Add] button.
  6. The module will be installed, and the information screen displayed.
  7. Click on the "Utilities" link in the left navigation.
  8. On the Utility Modules screen, check the box next to PCI Net Tool Belt and click the [Update] button.
  9. A tab called PCI Net Tool Belt will appear. Click the tab and enter your license key checkbox, then click [Update].
  10. The modules will add itself as an item to every page in the store. Browse the list of functions.
Index

Upgrading:

  1. After you have downloaded and unpacked the zip file to your hard drive, login to the Miva Merchant admin.
  2. Under "Global Settings", click on the "Modules" link in the left navigation.
  3. On the Modules screen, search for Toolbelt. On the right site click the [Edit] button.
  4. The "Edit Module" screen will be displayed. Click the "Files" tab then Click the [Upload] button.
  5. The "Upload File" window will be displayed. Click on the "Overwrite" checkbox then [Browse] button and locate and the module's ry_toolbelt.mvc file on your hard drive and click [Open], then click on the [Upload] button.
  6. The file will be uploaded, and the file name and path displayed in the "Module" field.
  7. IMPORTANT: Click the [Update] button. You're finished.
Index

How to:

If you have never edited a Store Morph Page Template before you should review the Miva Merchant 5 documentation and browse to UI/Store Design/Store Morph Technology. If that looks like too much reading, let's just jump in.

How to add Items to a page

Let's add a few useful buttons to the basket page. The normal process of editing pages will go something like this. In the Admin, click the "Pages" link to display the User Interface. Don't worry. Merchant will allow you to undo your changes and go back to a previous version. See Working with Version History for details.

  1. Find the page BASK and click the [Edit] button.
  2. Copy the template to notepad (or other plain text editor). Click in the Template: area and press ctrl-A then ctrl-C to copy the template
  3. Select notepad and press ctrl-V to paste the template text. You can save your work if you wish.
  4. After you make changes (more on this below), in notepad press ctrl-A then ctrl-C to copy your changes.
  5. Click in the Template: area again and press ctrl-A, delete then ctrl-V to paste your changes; Click [Update]
  6. In a new browser window or tab go to the basket page and review your update.

Add the buttons [Continue Shopping] and [Checkout] to your Basket page.

In notepad change this...
<tr><td align="left" valign="top" width="100%">
<br>
<mvt:item name="basket" />
</td></tr>

to this...
<tr><td align="left" valign="top" width="100%">
<br>
<mvt:item name="basket" />
<mvt:if expr="NOT l.settings:basket:empty">
<div style="float: right">
<mvt:item name="ry_toolbelt" param="basketbuttons|checkout|Checkout|mybtn" />
</div>
<div>
<mvt:item name="ry_toolbelt" param="basketbuttons|continue_lastprod|Continue|mybtn"/>
</div>
</mvt:if>
</td></tr>
Click [Update]. In your store add a product to the basket, then browse to the basket page. Right click on the page and select View Source, to examine the html.

On the Admin Edit Page, click the tab PCInet Tool Belt*, click the BasketButtons link and read more about this item.

Index

Where to:

Where can you use the PCI Net Toolbelt? Almost anywhere you find a text box in Merchant Admin, IF you have it assigned to every page template. Edit the BASK Page then click the Items tab. You will find every item assigned to the page has a checked box. Each Item adds functionality to the page and normally has an associated <mvt:item /> tag in the template. For Example: the basket item, when checked adds the Basket Contents tab which lets you edit the way the basket displays. In the page template you should see the item as <mvt:item name="basket" />.

Likewise you should check the box next to ry_toolbelt to assign it to the page.

Toolbelt items/functions work the same way. For example: On the product page you will find the entity &mvt:product:name; (see entities below). This corresponds to the variable l.all_settings:product:name. If you always wanted to make sure product names were capitalized regardless of what was entered in the database, you can use the eval item and the capitalize() function.

<mvt:item name="ry_toolbelt" param="eval|capitalize(l.all_settings:product:name, ' ')" />

You can use Toolbelt items on any page template, category tree, global header / footer, category and product header or footer and more.

Toolbelt will NOT work in some third party module text areas or text areas that have nothing to do with page display, like shipping settings.

Index

Store Morph Items:

Page items are the methods you will use to access the features of Store Morph and Toolbelt. An item is a single element in a template that makes up a distinct part of the page. It can be as simple as assigning a variable...

<mvt:item name="ry_toolbelt" param="assign|g.ProdName|l.all_settings:product:name" />

OR can call up an entire section of the page where the settings are configured in another tab.

For example, when the basket item is assigned to a page, a new tab is displayed call Basket Contents. This tab provides a sub-template where you can configure the basket layout. To use the item, you add the item command to the template.

<mvt:item name="basket" />

Open and Close Items: Some Store Morph items come in pairs just like HTML tags, with (e.g. <b>This is Bold</b>). Omitting a closing tag will cause the page compiler to report an error when you save the page. For Example:

<mvt:item name="body">
...Page content...
</mvt:item>

Empty Items are stand alone commands in that they perform a single operation. These items all end with a closing right slash (e.g. />) Note the difference in the Basket and Body items above.

Toolbelt Items are all empty items that perform a single operation.

Index

Entities:

These badly named language elements represent the combination of an output statement and variable having the syntax of &mvt:product:code; or &mvt:global:product_code;  This would be roughly equivalent to JavaScript's document.write(product:code).

These two forms represent the scope of the variable where the former is stored internally as a local variable l.settings:product:code and the latter is stored globally as g.Product_code. There is however a third form of the variable that is used by all third party modules like Toolbelt (i.e. l.all_settings:product:code).

For now all you need to know is that &mvt:variableName; is how you write the variable to the page.

For more information, see the section on variables.

Index

Comments

You can add comments or comment out sections of the page using <mvt:comment> and </mvt:comment>, however there is a bug in the page compiler which lets certain items "leak" through to the screen. This usually occurs when the commented section contains an entity representing a URL or a third party module. In those cases add html comments to hide the leak from display as shown.

<!-- <mvt:comment>
...hidden content...
</mvt:comment> -->
Index

Variables:

Do you remember algebra from school? x=4, y=6, z=x+y

The letters in the equations above are variables (like x) that hold a value (like 4) that you can use to hold information to calculate the value of another variable (like z= 4 + 6). The equation above is called an expression (like x+y).

As with algebra, Store Morph variables are used to hold values which can be strings, numbers, or other variables. Variables can be populated by a simple assignment (like x=5 or tree="oak") or by the result of an expression (like z=x+y). T

Toolbelt gives you access to variables via the assign and eval items.

Variable Names:

A variable can have a short name, like g.x, or a more descriptive name, like l.settings:product:code, but all variable names follow these rules:

  • Names start with a prefix as defined below.
  • Names are case In-sensitive (g.y and g.Y are the same variable).
  • After the prefix, Names must begin with a letter or the underscore character.

Prefixes in the variable name define its scope in the current page. The prefixes are:

  • Local: (Prefix l.settings): Local variables available only to Store Morph language elements.
    e.g <mvt:if expr="NOT l.settings:basket:empty">
  • Local: (Prefix l.all_settings:) Local variables available to modules like Toolbelt.
    e.g <mvt:item name="ry_toolbelt" param="assign|g.isEmpty|l.all_settings:basket:empty" />
  • Global: (Prefix g.): Scope is the entire program.
  • System: (Prefix s.): Used to access built-in system variables. See System Variables below.
  • Dynamic: (Prefix dyn_): Used to store dynamically generated time values. See Time Variables below.

The variables starting with  l.settings contain Merchant data structures used internally by Store Morph. They can only be used inside if expressions. The variables starting with l.all_settings, are a copy (by reference. see below) of l.settings. Merchant makes this variable available to third party modules. Toolbelt always uses this form.

Data Types and Type Checking: Store Morph data types are loosely defined and can be easily interchanged. This can lead to unexpected errors. In the example below the variable g.value can be treated as a string or a number.

assign|g.value|'100'

  • (2 * g.value) returns 200
  • 'Shirt' $ g.value $ '.jpg' returns Shirt100.jpg
  • 'Shirt' $ (2 * g.value) generates an error

The Varlist Item: What was that variable name?

It is impossible to remember all of the entities available to a Store Morph page so Toolbelt provides a powerful inspection tool for debugging variables called varlist. Simply add the lines of code below to the bottom or your page templates before the last </mvt:item></html> tags.

Display Local Variables: <mvt:item name="ry_toolbelt" param="varlist|local" />

All local variables will be de-constructed, sorted and displayed in human readable form showing the variable name, entity name and variable contents. To disable the item without removing it from the page, simply put an X in front of the last parameter and it will be ignored.

Don't display: <mvt:item name="ry_toolbelt" param="varlist|Xlocal" />

HINT: Place all three commands in a conditional using your IP address and ONLY YOU will see the results.

<mvt:if expr="s.Remote_Addr EQ '66.123.45.678'">
<mvt:item name="ry_toolbelt" param="varlist|local" />
<mvt:item name="ry_toolbelt" param="varlist|global" />
<mvt:item name="ry_toolbelt" param="varlist|Xsystem" />
</mvt:if

Disable the entire output by putting an X in the IP address. Disable the individual items by putting and X in front of the keyword (e.g. local becomes Xlocal)

The Varlist() Function: As of version 5.34 a new function has been added that provides a search parameter, reducing the size of the output. Scope = 'l', 'g', or 's'. search = variable(s) to display, l.all_setting = required.

<mvt:item name="ry_toolbelt" param="eval|varlist('scope', 'search', l.all_setting)" />

<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'store', l.all_settings)" />
<mvt:item name="ry_toolbelt" param="eval|varlist('g', 'module', l.all_settings)" />

Variables by Reference ( VAR or var ):

When using functions, variables are often passed as parameters. But, in some functions, a parameter may be defined internally using an optional "VAR" or "var" statement after the variable name. This signifies that the parameter variable would be passed by reference.

Any changes to the variable within the function will be applied in the variable when the function returns. This means string, numbers or entire arrays and structures can be returned inside the variable used in the function.

Example: file_read(filepath, location, data var)

"assign|g.length|file_read('/mm5/teamnames.txt', 'script', g.baseball_teams)"

g.length contains length of the files and  g.baseball_teams contains the file data.

Toolbelt makes extensive use of the feature. You pass an empty variable and Toolbelt returns the results in the same variable as a structured array. Some of the functions detailed below also use this feature.

Assign by Reference { }: The assign item has a special syntax that allows you to construct a string representation of a new variable name using expressions.  After assigning the string to a variable, you can then assign value to the constructed reference variable. The implication is that it becomes easy script complex variable names and then assign values to them; in short, dynamic variable names.

<mvt:item name="ry_toolbelt" param="assign|g.refvar|'g.url'" />;
<mvt:item name="ry_toolbelt" param="assign|{ g.refvar }|'http://www.pcinet.com/'" />;
&mvt:global:url; displays http://www.pcinet.com/
Index

Expressions:

Expressions can contain variables, literal values (text or numbers), functions, and operators, which indicate how the other components in the expression are to be evaluated. Expressions are evaluated and return a result that can be assigned to a variable using the assign item or output to the page using the eval item. They can evaluate a condition as false (0 or null) or true (not 0 or null). You can then take action on the results. See the MivaScript 4.0x Reference Guide. It's badly out of date but is a prime reference resource.

Syntax: Spaces in an expression are not evaluated unless the spaces are an intrinsic part of the data being evaluated. Spaces are simply separators between parts of the expression.

In Toolbelt, nearly every parameter can be evaluated as an expression. Some functions however accept specific keywords. Using the assign statement below expression can consist of many things.

<mvt:item name="ry_toolbelt" param="assign|g.varname|expression" />

Expression Examples:

Strings: String literals are always enclosed in single quotes; the $ operator is used to add strings together.
'PCI Net' $ ' E-commerce'

String functions: Literals and variables can be combined.
tolower('/images/' $ l.all_settings:product:code $ '_1.jpg')

Null Strings: Remove all colons from a string by replacing them with a null string (two single quotes e.g. '').
glosub(g.prompt,':','')

Nested Functions: Trim leading spaces, get the characters before the first hyphen and convert to uppercase.
toupper(left(ltrim(g.Category_code),'-'))

Numeric Expression:
(g.row * 6) -1

(l.all_settings:product:cost * g.markup) ROUND 2

Special characters: Store Morph has trouble with certain characters like the ampersand & single and double quotes in expressions.

The ampersand causes a compiler error:
<mvt:item name="ry_toolbelt" param="assign|g.url|g.sessionurl $ '&screen=BASK" />

Alternative:
<mvt:item name="ry_toolbelt" param="assign|g.url|g.sessionurl $ asciichar(38) $ 'screen=BASK'" />

While using asciichar(38) instead of & works, it a bit cumbersome in a long URL with lots of parameters.

In this example the ampersand & was replaced with the tilde ~. Assuming there were lots of tildes, they can all be replaced at once using the glosub() function. The same technique can be used with embedded quotes and apostrophes.

Better solution:
<mvt:item name="ry_toolbelt" param="assign|g.url|g.sessionurl $ '~screen=BASK' $ more..." />
<mvt:item name="ry_toolbelt" param="assign|g.url|glosub(g.url,'~',asciichar(38))" />

A chart of ascii character codes can be found here.

Index

If elseif else:

In all programming languages comparisons form the basis for flow control, determining code to execute and what code to skip. Store Morph has a single language construct for flow control, the opening if, elseif, else and closing /if statements.

<mvt:if expr=" condition ">
do this...
<mvt:elseif expr=" condition ">  (optional)
do this
<mvt:else> (optional)
do this...
<mvt:if expr=" condition ">
do this
</mvt:if>
</mvt:if>

The else if and else portions are optional but a closing tag </mvt:if> must be used. As shown in the example above, conditionals may be nested. The expr parameter must evaluate as a valid expression where false is defined as zero or null and true is defined as not zero or not null. The Operators section below provides example of conditional expressions.

Index

Operators:

Operators are a symbol or symbols used to operate on data, most often in an <mvt:if> statement. Store Morph provides a reasonable set of operators but Toolbelt provides access to the rest of them defined in MivaScript. Every operatory is not listed here. See the MivaScript Reference Guide for full details.

Comparison:
  • EQ -- Equal To
  • GT -- Greater Than
  • LT -- Less Than
  • NE -- Not Equal To
  • GE -- Greater Than or Equal To
  • LE -- Less Than or Equal To
<mvt:if expr="g.Basket:cust_id EQ 0">
Customer is not logged in
</mvt:if>
Logic:
  • AND -- Logical AND
  • OR -- Logical OR
  • NOT -- Logical NOT
  • ISNULL -- variable is empty
  • NOT ISNULL -- variable is not empty
<mvt:if expr="NOT ISNULL l.settings:product:image">
<img src="&mvt:product:image;" alt="&mvt:product:name;">
</mvt:if>
Text String
  • $ -- String concatenation
  • IN -- Starting position a string is IN another string
  • CIN -- Case Insensitive version if IN
  • EIN -- Ending position a string is IN another string
  • ECIN -- Case Insensitive version if EIN
<mvt:if expr="',' $ g.Screen $ ',' IN ',OUS1,OUSM,OSEL,OPAY,OPRC,OINF,OCST,ORDL'">
This is a checkout page.
</mvt:if>
Arithmetic
  • + Addition
  • - Subtraction
  • * Multiplication
  • / Division
  • POW -- Power
  • MOD -- Modulo
  • ROUND -- Number rounding
<mvt:if expr = "(pos1 MOD 3 ) EQ 0">
This is the third item.
</mvt:if>
Operator Precedence: From highest to lowest MivaScript Operators:
  • NOT
  • ROUND, CRYPT, MOD, SUBSTR, POW
  • /, *
  • +,-,$
  • IN, CIN, EIN, ECIN, EQ, NE, GE, LE, LT, GT
  • AND, OR
Index

Exit:

The <mvt:exit /> tag causes the code to terminate the current page or process, rather than continuing through the rest of the code on the page.

<mvt:if expr="l.settings:basket:empty">
Your shopping basket is currently empty.<br>
<mvt:exit />
</mvt:if>
Index

About Your Data

It's your store. It's your data. Why shouldn't you have access to it. This section will explain how Merchant stores and presents data, and how you can use Toolbelt to use it.

Index

Arrays:

Store Morph items very often return results from Merchant databases in the form of structured arrays. The Toolbelt varlist|local item will display all arrays loaded into memory. For instance, the basket total is stored in the variable l.all_settings:basket:total. While the first product code in the basket is stored in l.all_settings:basket:items[1]:code and the first attribute option for the first item is stored in l.all_settings:basket:items[1]:options[1]:opt_code.

This type of structure (l.all_settings:table[n]:fieldname) is used throughout Merchant. Normally you won't need to create arrays or access them directly but will constantly need to read and output them. The Array functions are listed below.

NOTE: All Store Morph arrays are 1 based. That is they start with [1]. There is no [0] element. Attempting to access a zero or negative array element will generate a runtime error.

Use the function miva_array_max(array_name) to return the size of an array.

Index

Foreach loop:

The foreach statement gives you a way to step through a collection of data stored in an structured array.

<mvt:foreach iterator="product" array="products">
<mvt:comment> Display the code and name. </mvt:comment>
&mvt:product:code;<br>
&mvt:product:name;<br>
</mvt:foreach>

Notice the first line <mvt:foreach iterator="product" array="products"> where products (with an s) is the name of the array we are looping through and product (no s) contains the current item. (i.e. &mvt:product:code; does not have an s). Internally the template is looping through the array products[n]:fieldname and presenting a copy of the data record as product:fieldname.

Unlike other languages Store Morph does NOT provide an &mvt:break; command to exit the loop early. All foreach loops continue to the end of the data. To overcome this problem, conditional statements can be added inside the loop so that selected records can be skipped.

Index

For loop:

Where the foreach loop operates exclusively on array data, Toolbelt provides a way to create your own loop by preceding a foreach item with the for item.

<mvt:item name="ry_toolbelt" param="assign|g.bigST|'CA|TX|FL|IL|NY'" />
<mvt:item name="ry_toolbelt" param="for|j=1 to 5 step 1" />
<mvt:foreach iterator="j" array="for_j">
   &mvt:j;: <mvt:item name="ry_toolbelt" param="eval|gettoken(g.bigST,'|',l.all_settings:j)" /><br>
</mvt:foreach>

For loops are not limited to positive increments. The value of the start, end and step expressions can be positive or negative numbers. The step parameter is optional and defaults to 1 if omitted. This makes it possible, for example, to display an array in reverse order or skip every other line.

<mvt:item name="ry_toolbelt" param="for|counter=start_exprsn to end_exprsn step incr_exprsn" />
Index

Query Your Stores Data:

Your stores data is kept in a MySQL database called Merchant. Within the Merchant database are all the tables that hold the domain settings and your store data. Your domain host will likely provide you with a control panel application that lets you view the databases. Store tables are easy to spot. They all start with "s01_" If you have a second store, its tables will begin with "s02_"  and so on. The products table for exampe will be s01_Products and the Orders will be s01_Orders.

The Query item lets you construct and run MySQL queries. It will execute any well formed query so use extreme caution with any query that directly modifies data. Backup your data first. SELECT queries normally won't cause problems but it is possible to construct a query that returns so much data that Merchant times out. Use LIMIT in your queries until you are sure you are getting the correct data.

This example uses returns the customers last 10 orders using their email address.

<mvt:item name="ry_toolbelt" param="query|query_string|array_name" />

Example:
<mvt:item name="ry_toolbelt" param="assign|g.sql|'
SELECT * FROM s01_Orders
WHERE (ship_email = `' $ g.Customer_ShipEmail $ '`)
ORDER BY id DESC
LIMIT 0, 10' " />
<mvt:item name="ry_toolbelt" param="query|g.sql|PastOrders" />

Notice that the query spans several lines. This is for readability only. If you look closely you will find a single quote before and after the query string. Embedded within the string you will find the right quote character ` has been used to enclose the string variable g.Customer_ShipEmail. Print the string to the page with &mvt:global:sql; and you will see the following.

SELECT * FROM s01_Orders
WHERE (ship_email = `emailaddress@domain.com`)
ORDER BY id DESC
LIMIT 0, 20 

Toolbelt will change the right quote to a single quote for you before executing the query.

The Query item returns a view of the data in a structured array. In the example above, this would be in the array l.all_settings:pastorders. Temporarily use Toolbelts varlist function at the bottom or you page template to quickly see exactly what it returned.

View Returned Values: 
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'PastOrders', l.all_settings)" />
Index

External Data:

There are already built in functions for retrieving and writing external data, so Toolbelt does not provide Import or Export items. Review the File System functions for more information, but a few of these are:

  • file_create(filepath, location, data)
  • file_read(filepath, location, data var)
  • file_append(filepath, location, data)
  • wget(url, filepath, location)

This example determines if a banned name was entered by the user. By using Ajax like techniques, user input was validated against an external list without refreshing the screen.

The example below uses file_read() to load a test file, calculate the number of lines, create a loop, parse each name and compares it with g.name. It then outputs JavaScript variables.

<mvt:item name="ry_toolbelt" param="assign
|g.length|file_read( '/mm5/banned_names.txt', 'script', g.banned )" />
<mvt:item name="ry_toolbelt" param="assign|
g.linecount|GettokenCount(g.banned,asciichar(10)" />

<mvt:item name="ry_toolbelt" param="for|i=1 to g.linecount" />
<mvt:foreach iterator="i" array="for_i">
<mvt:item name="ry_toolbelt" param="assign
|g.linein|trim(gettoken(g.banned,asciichar(10),l.all_settings:i))" />
<mvt:if expr="g.linein">
<mvt:item name="ry_toolbelt" param="assign
    |g.bannedname|trim(gettoken(g.linein,asciichar(9),1))" />
<mvt:if expr="g.name EQ g.bannedname">
 var ban_found = true;
 var ban_error = "The name you selected is prohibited by Major League Baseball.";
 <mvt:exit />
</mvt:if>
</mvt:if>
</mvt:foreach>

 

Index

Loading Sub-Screens:

Given a screen code, the screen item retrieves the contents of any page template and either displays it or stores the results in a variable. This means you can display a template at any location inside another page template. You can create re-usable sub-screens (i.e. mini basket, featured products) and display them as needed.

<mvt:item name="ry_toolbelt" param="screen|screen_code" />
<mvt:item name="ry_toolbelt" param="screen|screen_code_exprsn|g.variable" />

The fact that you can store the results in a variable opens up many other possible uses. Toolbelt provides a number of extra Page Templates that make use of this feature.

  • Use a screen as a program sub-routine.
  • Create special purpose screens that you can send as email using SendEmail.
    • Request for Quote.
    • Merchant HTML Email
    • Today's Order Summary.
    • Thank You for Registering
  • Create a wholesale product screen then use conditionals to switch displays.

More information can be found in the Screen Section below

Index

Calling Web Pages:

Given a URL expression, the Call_Get item returns the contents of any web page as a variable. Once loaded the variable can be displayed as is or modified via script. Alternatively use Call_Post, data can be posted to another web page. This provides a mechanism for transmitting form data to another site.

<mvt:item name="ry_toolbelt" param="call_get|g.webpage|url_exprsn" />

More information can be found in the Call Section below

Index

Do External Functions:

Call any external function within any compiled MivaScript file with the Do item. Like MivaScripts MvDO tag or OpenUIs DOFUNC token, you can use this to directly access your own compiled MivaScript functions without having to write an entire module. You can even tap into Miva Merchants API if you can determine the correct call.

<mvt:item name="ry_toolbelt" param="do|g.file_exprsn|g.result|Function_Name(var1,var2)" />
Index

Function Reference

MivaScript is the web language Miva Merchant and Store Morph is written in. As such, there are many functions built into the language that are not available to Store Morph templates without the help of Toolbelt. Toolbelt also adds many new functions of its own. There are two types of Toolbelt functions; Items like assign...

<mvt:item name="ry_toolbelt" param="assign|g.var|expression" />
and expression functions like capitalize().
<mvt:item name="ry_toolbelt" param="assign|g.var|capitalize(string, separator)" />

Review the section on expressions if the difference is not clear. Any Toolbelt item that can accept an variable or expression as a parameter will accept a function as a parameter.

This section is devoted the later and includes additional functions added by Toolbelt.

Passing Variables by Reference ( VAR or var ):

When using functions, variables are often passed as parameters. But, in some functions, a parameter may be defined internally using an optional "VAR" or "var" statement after the variable name. This signifies that the parameter variable would be passed by reference.

Any changes to the variable within the function will be applied in the variable when the function returns. This means string, numbers, or entire arrays and structures can be returned inside the variable used in the function.

Example: file_read(filepath, location, data var)

"assign|g.length|file_read('/mm5/teamnames.txt', 'script', g.baseball_teams)"

g.length contains length of the files and  g.baseball_teams contains the file data.

Toolbelt makes extensive use of the feature. You pass an empty variable and Toolbelt returns the results in the same variable as a structured array. Some of the functions detailed below also use this feature.

Some of the functions below are hi-lighted in red. These functions are not part of MivaScript but have been added by Toolbelt.

Index

Debugging:

Varlist Item and the Varlist() functions are provided to allow you to easily see the underlying variables and data structures.  See Varlist Above. See Live Example here and Search Example here.

Trace Item is provided as an aid in debugging complex page templates. It outputs trace code directly to the screen. See Trace

Page Compiler popup errors are those frustrating Merchant message you get when trying to save a page template. Most of these errors are introduced while trying to edit third party page items like Toolbelt, but the template compiler produces an error message that is completely misleading. For example the compiler tells you you have a missing </mvt:if> tag leading you on a goose chase trying to figure out where you left one off, when the real error was an extra double quote or missing semi-colon 10 lines earlier.

Use <mvt:comment> </mvt:comment> to block out whole sections of the page will save correctly, then moving the comments around a few lines or sections at a time till you locate the offending line.

Compiler Bugs: When creating Toolbelt expressions, Care must be taken with these characters.
Ampersand &, Single Quote , Double Quote , Pipe |, and semicolon ;

These have special meaning to the template compiler, sometimes forcing you to use the
asciichar() function. Also some characters can cause problems if the follow immediately after a closing item bracket />

Index

Strings:

String Function Reference. Red indicates a Toolbelt function.
function(parameters) Description
asciichar(number) Returns the character corresponding to number (number must be less than 255).
asciivalue (character) Returns the ASCII numeric value for character (character must be a single character).
body_InnerHTML(string) Returns the portion of a web page between the <body> tags. After reading a webpage into a string using the Call item, Screen item, or the fileread() function, this function will strip out the html and head sections.
capitalize(string, separator) Returns a copy of string with the leading character of each word capitalized. Separator is normally a space but can be any character like a comma or pipe.
compress(string) Returns a copy of string after removing tabs, leading and trailing spaces and blank lines.
decodeattribute (string) Returns a copy of string (which is usually a URL) converted from URL-encoded format to ordinary text. This function is the opposite of encodeattribute.
decodeentities (string) Returns a copy of string in which all HTML entities have been converted to their plain text equivalents (for example, '&lt;' is converted to '<'). This function is the opposite of encodeentities.
decodehtml(string) Reverses EncodeHtml(); Decodes each html character string &#nnn; where nnn is the ascii character code.
encodeattribute (string) Returns a copy of string (which is usually a URL) in URL-encoded format. Special characters such as space, tilde (~), and the plus sign are converted to hexadecimal %nn format. This function is the opposite of decodeattribute.
encodeentities (string) Returns a copy of string in which all characters have been converted to their HTML entity equivalents, where applicable (for example, '<' is converted to '&lt;'). This function is the opposite of decodeentities.
encodehtml(string) Returns string with each character encoded as html character codes (e.g. &#nnn;) where nnn is the ascii character code.
gettoken(string, separators, n) Tokenizes string, using any of the characters in separators as token separators, and returns the nth token. A null string is returned if there is no nth token.
gettokenCount(string, separators) Returns the number of items (tokens) in a delimited list. For example: Number of items in a comma separated list: gettoken_count(g.CSVstring, ',') or
Number if lines in a text file: gettoken_count(g.datafile, asciichar(10))
glosub_array( string, search, replace ) Works like glosub(), but search and replace are arrays that are iterated through, each value in the search array found in the string is replaced by the corresponding replace array value.
glosub(string, search, replace) Global substitution; returns a copy of string in which all instances of string search have been replaced by string replace. (Note: to represent a backslash (\) in replace, use '\\').
hardbreak(string) This function converts every space in a string (i.e. ascii char 32) into a break tag <br> letting you display text in a column.
left(string, [number] or [search_string]) Returns the left portion of string up to the number of characters OR first occurrence of search_string; must be an exact match.
len(string) Returns the number of characters in string.
ltrim(string) Returns a copy of string with all space characters removed from the left end.
padl(string, length, padcharacter) Returns a string length characters long, consisting of string padded on the left with as many instances of padcharacter as are needed to make up the full length.
padr(string, length, padcharacter) Returns a string length characters long, consisting of string padded on the right with as many instances of padcharacter as are needed to make up the full length.
rtrim(string) Returns a copy of string with all space characters removed from the right end.
removeChars(string, characters) Returns the source string with each character in the list removed. This example strips all formatting characters from a phone number.
RemoveChars(g.ship_phone, '( )-.,')
replace(string, search, replace, start var) Replace some characters with other characters in a string. start_var MUST be a variable (defaults to 1) and will be set to the next character position after the replace when the function returns.
right(string, [number] or [search_string]) Returns the right portion of string up to the number of characters OR last occurrence of search_string; must be an exact match.
striphtml(string) Returns a copy of a string with all html stripped out.
substring(string, start, length) Returns the substring of string, beginning at position start, length characters long.
tokenize( string, replacements ) Returns the string, concatenated with the value of each token contained in replacements. Replacements is an array of structures, each with a token and a value. 
tolower(string) Returns a copy of string in lower case.
toupper(string) Returns a copy of string in upper case.
trim(string) Returns the value of string with leading and trailing spaces removed

 

Index

Arrays:

function(parameters) Description
miva_array_collapse(array) Returns a copy of the array with the indices sequential from one to the number of elements in the source array. (
So, array[1], array[50], array[100] would be resultarray[1], resultarray[2], resultarray[3].)
miva_array_elements(array) This function returns the number of elements in the array that were actually used.
miva_array_max(array) This function will return the maximum array element used.
miva_array_serialize(array)
miva_array_deserialize(array)
miva_array_serialize returns a string representation of the array and any subarrays. This is useful for outputting an array to file or a database record as an aggregate.
miva_array_deserialize is passed a string in the format returned from miva_array_serialize, and returns an aggregate repopulated to match the original aggregate.

 

Index

Numbers:

The arguments of the trigonometric functions sin, cos, tan, sinh, cosh, and tanh should be expressed in radians; the results of asin, acos, atan, and atan2 are expressed in radians. Function arguments in radians can be given in the range 0 to 2pi, or -pi to pi.

function(parameters) Description
acos(number) Returns the arccosine of number.
asin(number) Returns the arcsine of number.
atan(number) Returns the arctangent of number.
atan2(y,x) Returns the arctangent of y/x. This is similar to atan(), but the signs of y and x are taken into account when computing the quadrant of the result.
ceil(number) Returns the smallest integer greater than or equal to number
cos(number) Returns the cosine of number.
cosh(number) Returns the hyperbolic cosine of number.
exp(number) Returns the constant e (approximately 2.71828) raised to the power number.
floor(number) Returns the largest integer less than or equal to number
fmod(number1,number2) Returns the remainder of number1/number2; number1, number2, and the result are all floating point numbers.
int(number) Returns integer portion of number (removes the decimal and any digits to the right of it)
log(number) Returns the natural logarithm (base e, approximately 2.71828) of number.
log10(number) Returns the base 10 logarithm of number
NumberFormat(number, number_of_places) Returns the number formally formatted.
307006550.796 becomes 307,006,550.80
power(number, power) Raises number to a power (for example, power(12,2)=144)
PercentFormat(number, number_of_places) Returns the number as a percent.

0.1551 becomes 15.51%.

random(maximum) Returns a random number less than or equal to maximum
rnd(number, number_of_places) Works like the ROUND operator, rounding number up or down to number_of_places after the decimal
sin(number) Returns the sine of number.
sinh(number) Returns the hyperbolic sine of number.
sqrt(number) Returns the square root of number.
tan(number) Returns the tangent of number.
tanh(number) Returns the hyperbolic tangent of number.

 

Index

File System:

In all of these functions, location is designated as one of the string literals 'data' or 'script'; where data refers to the mivadata folder and script refers to the html (web site) folder.

For all file function:

  • Literal filenames and paths must be surrounded by single quotes.
  • Forward slash (on Windows and Unix) separates folders/directories.
  • Except as indicated, all file system functions return a value of '1' (true) if they succeed and '0' (false) if they fail.
File system functions. Red indicates a Toolbelt function.
function(parameters) Description
dir(filepath, location, entries var) Reads a directory where filepath = The path to a directory relative to the location, location = 'data' or 'script', and entries = array of resultant file names.
file_append(filepath, location, data) Appends data to the file in path where location is 'data' or 'script'. Returns length of data or -1 if fails.
file_create(filepath, location, data) Creates and appends data to the file in path where location is 'data' or 'script'. Returns length of data or -1 if fails or file does not exist.
file_read(filepath, location, data var) Reads a file where: filename = target input file, location = 'data' or 'script', data = variable by reference to contain the file.
miva_lockfile(filename, location) Creates and locks a lockfile where: filename = target file, location = 'data' or 'script'.
table_exists(mysql_tablename) Return 1 if the tablename is found in the Merchant MySQL database else returns 0.
tar_create(filepath, location, dir, dir_loc, flags) Creates a tar file, Return 1 on success 0 on failure where: file = target output file, location = 'data' or 'script', dir = Directory to create a tarball of, dir_loc = 'data' or 'script', defaulting to data, flags = comma-separated list of qualifiers, consisting of: 'compress' - The resultant file will be compressed in bzip2 format.
tar_directory( filepath, location , desc ) Retrieves information about a tar file as a structure in the variable desc. The function returns the number of files in output array or 0 on error, where: filepath = the path and file name, location = 'data' or 'script', and desc is an array of structures as shown below.


NAME: Text, File name.
MODE: Integer, file protection mode of file.
UID: Integer, User ID of file.
GID: Integer, Group ID of file.
SIZE: Integer, Size of file.
TIMESTAMP: Integer, Timestamp (time_t format)
TYPE: Integer, Type of file; 0 = normal, 1 = link, 2 = symbolic link, 3 = directory, 4 = unsupported
LINK: Text, Link target (if link)
USER: Text, Name of user
GROUP: Text, Name of group
MAJORDEV: Integer, Major version number (if a device file)
MINORDEV: Integer, Minor version number (if a device file)

tar_extract( file, tar_location , dir , dir_location ) Unpacks a tar file to a specified directory. Returns 1 on success, 0 on failure where: file = the path and file name, tar_location = 'data' or 'script', dir = directory to extract the tar file to dir_location = 'data' or 'script'.
wdownload(url, filepath, location,
   functionname(size, total, data var), data)
Downloads a file where : url = file to retrieve, filepath = where file should be stored, location is 'data' or 'script', function = name of callback function in current script data = 1 to continue, 0 to abort.
wget(url, filepath, location) Downloads a file where : url = file to retrieve, filepath = where file should be stored, location is 'data' or 'script'.
xml_parse(filepath, location, output var) Parces and XML file where: filepath = Location of the file to parse, location = 'data' or 'script', output = xml file parsed into an aggregate.
xml_parse_section_init( filepath, location, level )  
xml_parse_section( output var, eof var )  
xml_parse_section_getstate( target var )  
xml_parse_section_setstate( source var )  
xml_parse_error( lineno var, error var )  

 

Index

Mivadata Folder:

These functions all operate on the mivadata folder.

Data Folder functions.
function(parameters) Description
fchmod(source_path, mode_number) fchmod() works like UNIX chmod and changes permissions to mode_number on the file named by source_path in the data directory. The mode number must be in the format nnnn (decimal) or 0nnnn (octal). Literal Octal requires single quotes.
fcopy(source_path, destination_path) fcopy() work like UNIX cp to copy the file named by source_path to the file named by destination_path, both within the data directory;
fscopy(source_path, destination_path) fscopy() works like UNIX cp to copy the file named by source_path in the data directory to the file named by destination_path in the script directory.
fdelete(path), fdelete() works like UNIX rm to delete the file named by path in the data directory.
fexists(path), fexists() returns a boolean true (1) or false (0) testing if the file named by path exists in the data directory.
fmkdir(path), fmkdir() works like UNIX mkdir to create a directory specified by path in the data directory
fmode(path), Returns the permissions mode of the file named by path in the data directory (returns -1 if the file does not exist). 
frename(source_path, destination_path), frename() works like UNIX mv to rename the file named by source_path to be the file named by destination_path, both within the data directory.
fsrename(source_path, destination_path),
 
fsrename() works like UNIX mv to rename the file named by source_path in the data directory to be the file named by destination_path in the script directory.
fsize(path) fsize() returns the number of bytes in the file named by path in the data directory (returns -1 if the file does not exist). 
fsymlink(file, lnk) (Unix only) Creates a symbolic link to the file in the data directory.
file - path name of the file relative to the Miva Merchant data directory.
lnk - path name of the link relative to the Miva Merchant data directory.

 

Index

HTML Folder:

These functions all operate on the html (web site) folder.

Script Folder functions.
function(parameters) Description
schmod(source_path, mode_number) schmod() works like UNIX chmod and changes permissions to mode_number on the file named by source_path in the data directory.
The mode number must be in the format nnnn (decimal) or 0nnnn (octal). New in 4.01: Literal Octal requires single quotes.
scopy(source_path, destination_path) scopy() work like UNIX cp to copy the file named by source_path to the file named by destination_path, both within the script directory.
sfcopy(source_path, destination_path) sfcopy() works like UNIX cp to copy the file named by source_path in the script directory to the file named by destination_path in the data directory.
sdelete(path) sdelete() works like UNIX rm to delete the file named by path in the script directory.
sexists(path) sexists() returns a 1 (true) or 0 (false) testing if the file named by path exists in the script directory.
smkdir(path) smkdir() works like UNIX mkdir to create a directory specified by path in the script directory.
smode(path) Returns the permissions mode of the file named by path in the data directory (returns -1 if the file does not exist). smode() does the same in the script directory.
srename(source, destination) srename() works like UNIX mv to rename the file named by source_path to be the file named by destination_path, both within the script directory.
sfrename(source_path, destination_path) sfrename() works like UNIX mv to rename the file named by source_path in the script directory to be the file named by destination_path in the data directory.
ssize(path) ssize() returns the number of bytes in the file named by path in the script directory. Returns -1 if the file does not exist.
ssymlink(file, lnk) (Unix only) Creates a symbolic link to the file in the scripts directory.
file - path name of the file relative to the Miva Merchant scripts directory.
lnk - path name of the link relative to the Miva Merchant scripts directory

 

Index

System Functions:

 

System functions.
function(parameters) Description
makesessionid() Returns a 128-bit unique ID.
miva_getvarlist (scope) Returns a comma-separated list of the names of all currently defined variables with the given scope. scope must be a literal string: 'l', 'local', 'g', 'global', 's', 'system'.
miva_output_flush() Writes the HTTP headers and any other output to the browser. Second and subsequent calls will write the output, but not rewrite the headers.
miva_output_header( name, value) Sets an HTTP header name-value pair.
miva_variable_value(varname) Takes a variable name and returns the value of the variable to which the value of varname is referring.
varlist(scope, search, l.all_settings) Like the Toolbelt Varlist item, this function reports an exploded, sorted list of global, local, and system variables, where Scope is one of these string literals 'l', 'g', 's', search is an optional variable name and l.all_settings is required.

 

Index

System Variables:

Accessibility Codes

Origin:
  • S: generated by Miva Merchant Virtual Machine, Miva Merchant Mia
  • E: if available, inherited from environment
  • H: if available, inherited from HTTP header (via the environment)
Platform:
  • C: accessible with CGI version of Miva Merchant Virtual Machine
  • N: accessible with NSAPI version of Miva Merchant Virtual Machine
  • P: accessible with Miva Merchant Mia

For example, E: C,N means that the variable in question is inherited from the environment and is accessible in the CGI and NSAPI versions of Miva Merchant Virtual Machine.

System Variables.
Variable Return Value Accessibility
apitype Platform: 'CGI', 'NSAPI', or 'Mia' (Miva Merchant Mia) S: C,N,P
argN If a list of values is passed to a MivaScript program, argN is the value of the Nth argument on the URL used to call the script. arg1 always contains the program file name. The first argument after the file name will be arg2, and so forth. S: C,N,P
auth_type Authentication method user by the server E: C,N
callerid Each time a cookie-enabled browser accesses a MivaScript document, MivaScript creates a 32-character cookie that is unique to that browser and URL. The cookie lasts for one year after being set. Cookies can be turned off in Miva Merchant Virtual Machine; contact your server administrator. S: C,N,P
content_length Length of any attached (POST) information E: C
content_type Type of data for POST E: C
documenturl Contains URL of the currently running MivaScript program. This URL also contains the character between the program name and the command line arguments ('+' for NSAPI and Miva Merchant Mia, and '?' for CGI). S: C,N,P
gateway_interface Version of CGI used E: C
globaltimeout Maximum total number of seconds that this script can execute. S: C,N,P
http_accept Comma-separated list of MIME types (type/subtype) that the browser will accept. This list is very incomplete on most browsers. H: C,N,P
http_accept_charset Character sets preferred by the browser (other than the default ASCII or ISO Latin-1) H: C,N,P
http_accept_language ISO codes for the languages preferred by the browser H: C,N,P
http_connection String that browser sends to the server to preserve a TCP connection (also called a "keep-alive" string). Not supported by all browsers and servers. H: C,N,P
http_cookie Contents of all the cookies set for the document. H: C,N,P
http_host Remote host name (usually same as server_name) H: C,N,P
http_pragma Mode client is running under H: C,P
http_referer The document that the current document was accessed from. H: C,P
http_user_agent Browser name, platform, version, and library H: C,N,P
mivaversion Version of the MivaScript language preprocessor
(Replaces the previous s.version)
S: C,N,P
miva_defaultlanguage Retrieves the current default language setting
 
miva_language Retrieves the current language setting
 
miva_sslavailable Whether OpenSSL is available for use by <MvCALL> S: C,N,P
nargs If a list of values is passed to a MivaScript program, nargs is the number of arguments on the URL, including the program file name. S: C,N,P
path_info Extra path information in the URL (a directory path that occurs immediately after the name of the CGI program in the URL) E: C,N
path_translated path_info, translated to a physical location by prepending the server document directory to its value E: C
process_id Currently running process number S: C,N,P
query_string Information passed after a URL and a "?" via the GET method E: C
remote_addr IP address of remote host E: C,N,P
remote_host The domain name of the remote host E: C,N,P
remote_ident Remote user name, from servers that support RFC 931 identification E: C
remote_user User name associated with protected script, on servers that support user authentication E: C,N
request_method GET, POST, or HEAD E: C,N,P
script_name Virtual path to CGI script; not mapped locally to actual path E: C
server_hostname The name of the server E: C,N
server_name Same as server_hostname E: C,N,P
server_port Port under which server is running E: C,P
server_port_secure Whether the port is secure (boolean) E: C
server_protocol Name and revision of protocol used E: C,N,P
server_software HTTP server and version number that processed the request E: C,P
server_url server_hostname, in URL format E: C,N
server_version Version of the server E: C,N
user_agent Same as http_user_agent

 

Index

Time Functions:

Note: These functions cannot be used to process dates earlier than January 1, 1970, or later than January 19, 2038.
function(parameters) Description
ftime ( path ) Returns time_t since a file in the data directory was last modified. See "Time Variables" for time_t definition.
stime( path ) Returns time_t since a file in the script directory was last modified. See "Time Variables" for time_t definition.
time_t_month(time_t, time_zone) Returns the current month as a number
time_t_year(time_t, time_zone) Returns the current year
time_t_hour(time_t, time_zone) Returns current hour (using a 24-hour clock)
time_t_min(time_t, time_zone) Returns the current minute in the hour
time_t_sec(time_t, time_zone) Returns the current second in the minute
time_t_dayofmonth(time_t, time_zone) Returns the current day of the month
time_t_dayofweek(time_t, time_zone) Returns the current day of the week as a number (Sunday=1)
time_t_dayofyear(time_t, time_zone) Returns the number of days since the beginning of the year, including today
timezone() Returns an integer which is the number of hours behind or ahead of GMT (not accounting for Daylight Time)
mktime_t(year, month, dayofmonth,
    hours, minutes, seconds, time_zone)
Returns the time_t value for the time specified

 

Index

Time Variables:

Note: time_t (i.e. time stamp) numbers is defined in Miva Merchant as the number of seconds since Jan 1, 1970 Greenwich Mean Time (GMT). All time variables are generated based in Time Variables.
Dynamic Static Return Value
dyn_time_t time_t Number of seconds since 1 Jan. 1970 (numeric)
dyn_tm_hour tm_hour Hour in current day (numeric)
dyn_tm_isdst tm_isdst Has the value true (1) if daylight time is in effect in this time zone (boolean)
dyn_tm_mday tm_mday Day of the month (numeric)
dyn_tm_min tm_min Minutes in current hour (numeric)
dyn_stm_mon stm_mon Month of the year (string)
dyn_tm_mon tm_mon Month of the year (numeric)
dyn_tm_sec tm_sec Seconds in current minute (numeric)
dyn_tm_usec tm_usec The current microsecond, relative to dyn_tm_sec or tm_sec. (On Windows, this value is updated only in 50-millisecond increments).
dyn_stm_wday stm_wday Day of the week (string)
dyn_tm_wday tm_wday Day of the week (numeric)
dyn_tm_yday tm_yday Day in year (numeric)
dyn_tm_year tm_year Year (numeric)
dyn_stm_zone stm_zone The time zone (string)
  globaltimeout Maximum total number of seconds that this script can execute.
dyn_time_remaining   Number of seconds before the current script will time out.

 

Index

Inspection Validation:

These functions all start with "is" and return a 1 (true) or 0 (false) value depending on the composition of the string. When any of these functions are applied to a string like isdigit(string), they return true if all characters in the string pass the test.

Inspection: Returns Boolean String Values. Red indicates a Toolbelt function.
function(parameters) Description
isalnum(string) Returns true (1) if all characters in string are either alphabetic or digits, and false (0) otherwise.
isAlphaNumPlus(string, characters) Returns true (1) if all characters in string are either alphabetic, digits, or one of the extra characters. This is useful if you must validate a string
that may also contain specific characters e.g. spaces, periods, commas or other punctuation.
isalpha(string) Returns true (1) if all characters in string are alphabetic and false (0) otherwise.
isascii(string) Returns true (1) if all characters in string are ASCII characters (those with decimal value between 0 and 127), and false (0) otherwise.
iscntrl(string) Returns true (1) if all characters in string are control characters (those with decimal value between 0 and 31, or 127), and false (0) otherwise.
isdigit(string) Returns true (1) if all characters in string are digits in the range 0-9, and false (0) otherwise.
isEmail(string) Returns true (1) if all characters in string are formatted as a valid email address and false (0) otherwise.
isURL(string) Returns true (1) if all characters in string are formatted as a valid web address and false (0) otherwise.
isgraph(string) Returns true (1) if all characters in string are graphic characters (those with decimal value between 33 and 127), and false (0) otherwise.
islower(string) Returns true (1) if all characters in string are lowercase letters, and false (0) otherwise.
isprint(string) Returns true (1) if all characters in string are printable characters (same as graphic characters, with the addition of the space character), and false (0) otherwise.
ispunct(string) Returns true (1) if all characters in string are punctuation characters (non-alphanumeric graphics characters), and false (0) otherwise.
isspace(string) Returns true (1) if all characters in string are whitespace (space, tab, vertical tab, newline, form feed) characters, and false (0) otherwise.
isupper(string) Returns true (1) if all characters in string are uppercase letters, and false (0) otherwise.
isxdigit(string) Returns true (1) if all characters in string are hexadecimal digits (a-f, A-F, 0-9), and false (0) otherwise.

 

Index

Encryption:

These functions are poorly documented. The Miva forum may be your best resource for information.

function(parameters) Description
rsa_generate_keypair(pubkey_file, privkey_file, bits, e, passphrase) Generates an RSA keypair, saving the public key in "pubkey_file", the private key in "privkey_file", and encrypting the private key with "passphrase". Returns 1 on success, 0 on error.
rsa_load_publickey(pubkey_file, rsa var) Load an RSA public key from a PKCS#1 file specified by "pubkey_file". Returns 1 on success, 0 on error.
rsa_load_privatekey(privkey_file, rsa var, passphrase) Load an encrypted RSA private key from a PKCS#8 file specified by "privkey_file", and decrypt it using "passphrase". Returns 1 on success, 0 on error.
rsa_public_encrypt(rsa, plaintext, encrypted var) Encrypt the data in "plaintext", storing the result in "encrypted", using the public key portion of the RSA structure specified by "rsa". Returns 1 on success, 0 on error.
rsa_public_decrypt(rsa, encrypted, plaintext var) Decrypt the data in "encrypted", storing the result in "plaintext", using the public key portion of the RSA structure specified by "rsa". Returns 1 on success, 0 on error.
rsa_private_encrypt(rsa, plaintext, encrypted var) Encrypts the data in "plaintext", storing the result in "encrypted", using the private key portion of the RSA structure specified by "rsa". Returns 1 on success, 0 on error.
rsa_private_decrypt(rsa, encrypted, plaintext var) Decrypts the data in "encrypted", storing the result in "plaintext", using the private key portion of the RSA structure specified by "rsa". Returns 1 on success, 0 on error.
rsa_free(rsa var) Frees the RSA indicated by "rsa". Returns 1 on success, 0 on error.
crypto_rand_bytes(n) Generates "n" random bytes, and returns them.
crypto_base64_encode(data) Base-64 encodes "data", returning the encoded result.
crypto_base64_decode(data) Base-64 decodes "data", returning the decoded result.
crypto_md5(data) Calculates the MD5 hash of "data", returning the result.
bf_encrypt(key, plaintext, encrypted var) Blowfish encrypts "plaintext" using the key "key" in ECB mode, storing the result in "encrypted". Returns 1 on success, 0 on error.
bf_decrypt(key, encrypted, plaintext var) Blowfish decrypts "encrypted" using the key "key" in ECB mode, storing the result in "plaintext". Returns 1 on success, 0 on error.

 

Index

More Page Templates

Included in the download file ry_toolbelt.zip are several page template files for use in your store. While these are useful functional features, they also point the way to using Store Morph to develop your own applications and serve as working script examples.

Index

Contact Us:

Contact us page template: CONTACT.mvt

The Contact Us form collects form data from the customer and sends you or your support staff their email message. By providing customers a form instead of an email address you protect yourself from spam and keep your customers on your site while they are contacting you. Using this template and the Tell a Friend templates as examples, you can create an unlimited number of data collection forms and retain full control over how they are processed and delivered.

Index

Featured Products:

Featured Products page template FEATURED.mvt

This page template displays selected products on the Storefront page or any other page you desire in a three column format. It does this by using a special category called Featured Products. Using a category makes managing the display user friendly, simply add or remove products from the category.

Index

Mini Basket:

Mimi basket template: MINI.mvt

Use the Screen item to embed this template in your global header or on certain pages.

Index

Random Products:

Random Product template: RAND__v.mvt

This template displays randomly selected products vertically. Products can be selected from all products or from certain categories.

Index

Tell a Friend:

Tell a Friend consists of two page templates; TELL.mvt and TELLSEND.mvt

The page template (TELL.mvt) collects form data from the customer for up to three recipients and sends them an email link to a particular product or page. The second template TELLSEND.mvt validates and processes the form data then sends the email. By studying how the program processes the TELL form in TELLSEND, you can create your own scripts for an unlimited number of data collection forms and retain full control over how the forms are processed and delivered.

Index

MivaScript

MivaScript TM is the web language that Miva Merchant TM is written in. MivaScript programs are HTML documents that also contain tags (commands) from the MivaScript programming language. It is a powerful server-side scripting language that is implemented by the Miva Merchant Virtual Machine Empressa TM, rather than by the browser.

More information can be found here:

Index

Writing Modules:

The point of Toolbelt is that you don't need a module for everything, especially if you just want to manipulate the data or screens, after all it's your store. Examine the included Tell A Friend template closely and you will see what I mean.

If you really want to write a module start with these:

Index

Writing Functions:

Writing MivaScript functions is far simpler than writing modules. You can write an external function, compile and upload it, then use the Do item in Toolbelt to call the function from your page template. Obviously, a single file can contain many functions so you can build your own library. That is exactly how Toolbelt started.

Here is the piece of code from Toolbelt that implements the Compress() function.

<MvFUNCTION NAME="Compress" PARAMETERS="string" STANDARDOUTPUTLEVEL="">
<MvCOMMENT> Removes all whitespace from string </MvCOMMENT>
<  MvASSIGN NAME="l.newval" VALUE="{ l.string $ asciichar(10) $ '<eof>' }">
<  MvASSIGN NAME="l.retval" VALUE="">
<  MvASSIGN NAME="l.linenum" VALUE="{ l.linenum + 1 }">
<  MvASSIGN NAME="l.line" VALUE="{ gettoken(l.newval,asciichar(10),l.linenum) }">

<MvWHILE EXPR="{ l.line NE '<eof>' }">
<MvASSIGN NAME="l.line" VALUE="{
      glosub(glosub(l.line,asciichar(9),' '),asciichar(13),'') }">
<MvASSIGN NAME="l.line" VALUE="{ trim(l.line) }">
<MvIF EXPR="{ l.line }">
<MvASSIGN NAME="l.retval" VALUE="{ l.retval $ l.line $ asciichar(10) }">
</MvIF>
<MvASSIGN NAME="l.linenum" VALUE="{ l.linenum + 1 }">
<MvASSIGN NAME="l.line" VALUE="{ gettoken(l.newval,asciichar(10),l.linenum) }">
</MvWHILE>
<MvASSIGN NAME="l.newval" VALUE="">

<MvFUNCRETURN VALUE="{ l.retval }">
</MvFUNCTION>

Once compiled and can it could be called like this from your page template.

<mvt:item name="ry_toolbelt" param="do
|'/mm5/compress.mvc'|g.result|Compress(g.textstring)" />

The easiest way to learn, is to view scripts written by other people. Start by searching Google for MivaScript Tags.

Index

Credits and Copyrights

Parts of this document are excerpts from the Miva Merchant 5 Documentation and MivaScript Guide 4.0x. They and reproduced here with the permission of Miva Merchant.

PCI Net is a trade mark of Andreas Toman.

Miva Merchant, Store Morph, MivaScript, MivaScript compiler are trademarks of Miva Merchant.

PCI Net Toolbelt is a Trademark of Ray Yates.
The PCI Net Toolbelt module and documentation is copy written 2008 through 2010 by Ray Yates.

I want to personally thank Andreas Toman for getting me back into Miva and being a friend and Daren Ehlers for getting me hooked on scripting in Merchant 4 to begin with.
--- Ray Yates

Index

Toolbelt Items

Add these items as needed to your page templates to add new functionality. If you have created new pages since you installed Toolbelt, remember that you will have to assign the module to the page. The ry_toolbelt code must be checked on the Items tab before it can be used. 

Index

Assign

Read Me First

Assigns expression results to the variable; where varname could be any array, global, or local variable name and expression contains any valid MivaScript expression and/or functions. Most MivaScript functions are included in the Script Builder below, but this does not represent all possible combinations.

Variable names start with g. for global variables and l.all_settings for local variables. Variable name can contain letters, numbers, the characters period and underscore.

Expressions can consist of numbers ( 3.1416 ), string literals enclosed in single quotes ( 'Music' ), operators (e.g. /, *, +, -, $, IN, CIN, EIN, ECIN, AND, OR, NOT, EQ, NE, GE, LE, LT, GT, ROUND, CRYPT, MOD, SUBSTR, POW), as well as nested MivaScript . Most expressions that can be compiled by the MivaScript compiler can be evaluated here.

Arrays can be assigned using a variable as the index For example assign|l.all_settings:products[g.ndx]:shortname|substring(l.all_settings:products[g.ndx]:name,1,10)

Variables by Reference using { }: Given a string that contains a variable name, You can assign a value to the variable contained in the string. This allows you to create variable names dynamically.

Special Characters: Several characters can not be evaluated or directly embedded within string expressions due to limitation of the page template
compiler. These include:
Double Quotes: " = asciichar(34)
Single Quotes: " = asciichar(39)
Ampersand: &amp; = asciichar(38)
Pipe: | = asciichar(124)

<mvt:item name="ry_toolbelt" param="assign|g.varname|expression" />;
Examples 1, Simple Expressions:
<mvt:item name="ry_toolbelt" param="assign|g.markup|g.price + 20.99"" />;

Example 2, Nested MivaScript functions:
<mvt:item name="ry_toolbelt" param="assign|g.cat|tolower(glosub(l.all_settings:product:code,'-',''))" />;
<mvt:item name="ry_toolbelt" param="assign|g.imagefile|'/mm5/images/' $ g.cat $ '.jpg'" />;
<mvt:item name="ry_toolbelt" param="assign|g.found|sexist(g.imagefile)" />;

Example 3, Array assignment:
Array indexes can be numbers [1] or variables like [g.counter] or [l.all_settings:counter]
<mvt:item name="ry_toolbelt" param="assign|l.all_settings:MyArray[1]:code|'123456'" />

<mvt:item name="ry_toolbelt" param="assign|g.ndx|g.ndx + 1" />
<mvt:item name="ry_toolbelt" param="assign|l.all_settings:MyArray[g.ndx]:code|'abc123'" />

output: #&mvt:global:ndx; = &mvt:MyArray[1]:code; displays #1 = abc123

Example 4, Advanced, Build your own variable names, structures and arrays:
Notice the {   } characters.
<mvt:item name="ry_toolbelt" param="assign|g.name|'fieldname'" />;
<mvt:item name="ry_toolbelt" param="assign|g.varname|'l.all_settings:mydata:' $ g.name" />;
<mvt:item name="ry_toolbelt" param="assign|{ g.varname }|'PCInet' $ '.com'" />;

output: &mvt:mydata:fieldname; displays PCInet.com
Index

Array_Elements

This item returns a number of elements in an array.

<mvt:item name="ry_toolbelt" param="Array_Elements|g.length|array" />

Example:
<mvt:item name="ry_toolbelt" param="Array_Elements|g.length|l.all_settings:products" />
<mvt:if expr="g.length">
  (&mvt:global:length;) Products found
</mvt:if>
Index

Availgroup

Description and Examples

These fourteen functions provide you with all the tools you need to manage customers, categories, and products in availability groups. 

<mvt:item name="ry_toolbelt" param="availgroup|Load_All|g.count" />

<mvt:item name="ry_toolbelt" param="availgroup|Load_Name|g.pg_found|prgp_name_or_csv_list" />

<mvt:item name="ry_toolbelt" param="availgroup|Customer_Groups|g.count" />

<mvt:item name="ry_toolbelt" param="availgroup|Customer_Find|g.found|avgp_name_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Customer_Insert|g.result|avgp_name_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Customer_Delete|g.result|avgp_name_exprsn" />


<mvt:item name="ry_toolbelt" param="availgroup|Product_Groups|g.count|product_code_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Product_Find|g.found|avgp_name_exprsn|product_code_exprsn" />

<mvt:item name="ry_toolbelt" param="availgroup|Product_Insert|g.result|avgp_name_exprsn|product_code_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Product_Delete|g.result|g.product_code_exprsn" />


<mvt:item name="ry_toolbelt" param="availgroup|Category_Groups|g.count|category_code_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Category_Find|g.found|avgp_name_exprsn|category_code_exprsn" />
<mvt:item name="ry_toolbelt" param="availgroup|Category_Insert|g.result|avgp_name_exprsn|category_code_exprsn" />

<mvt:item name="ry_toolbelt" param="availgroup|Category_Delete|g.result|g.category_code_exprsn" />
Index

Basket

Returns basket totals assigned to a user selected variable name.

<mvt:item name="ry_toolbelt" param="basket|variablename" />

Example:
<mvt:item name="ry_toolbelt" param="basket|g.cart" />

&mvt:global:cart:length;<br>
&mvt:global:cart:weight;<br>

&mvt:global:cart:subtotal;<br>
&mvt:global:cart:subtotalF;<br>
&mvt:global:cart:charges;<br>
&mvt:global:cart:chargesF;<br>
&mvt:global:cart:total;<br>
&mvt:global:cart:totalF;<br>

<mvt:if expr="g.cart:length GT 0">
    Items in Basket: &mvt:global:cart:length;<br>
    Subtotal: &mvt:global:cart:subtotalF;
<mvt:else>
    Basket Empty
</mvt:if>
Index

BasketButtons

This set of functions add buttons to your basket screen to Empty the Basket, Checkout, and Continue Shopping. They take the form of action, button prompt, CSS class, and outputs a form and button to perform the action.

Note: Do not place these buttons inside another form.

There are six actions, empty (empty the basket), checkout (start the checkout process), continue_lastprod, (Return to the last product in the basket), continue_lastcat, (Return to the first assigned category of the last product in the basket), and finally continue and link. (Return to the previous page before the basket.) The setup for the last actions are more complex as explained below.

<mvt:item name="ry_toolbelt" param="basketbuttons|action|prompt|class" />

Examples:
<mvt:item name="ry_toolbelt" param="basketbuttons|empty|Empty Basket|submit120" />
<mvt:item name="ry_toolbelt" param="basketbuttons|checkout|Checkout Now|submit120" />

<mvt:item name="ry_toolbelt" param="basketbuttons|continue_lastcat|Continue Shopping|submit120" />
<mvt:item name="ry_toolbelt" param="basketbuttons|continue_lastprod|Continue Shopping|submit120" />

The Continue command button, when clicked, returns the user to the originating page. However, it requires additional setup steps.

  • 1. The basket link in the navigation bar or global header must be replaced using the link command.
  • 2. The continue command is to be added to the BASK page.
  • 3. The Remove and Update buttons on the BASK page, Basket Contents template must both updated with the update_remove command.
    They should be added just before the </form> tags for both buttons.
<mvt:item name="ry_toolbelt" param="basketbuttons|continue|Continue Shopping|submit120" />

Example:
<mvt:item name="ry_toolbelt" param="basketbuttons|link|Basket|" />

This example is for the Remove button. Do the same for the Update button.
<mvt:item name="buttons" param="Remove" />
<mvt:item name="ry_toolbelt" param="basketbuttons|continue|update_remove" />

</form>
Index

BasketCombined

When placed at the top of the basket or invoice page, this function makes 12 additional basket entities available.

Combine Price and Attribute prices. These entities allow you to display the combined price and remove the individual attribute prices from the basket display.

Basket Thumbnail and Image: Display the product thumbnail or image in the basket

Attribute Prompts and Images: Display the attribute/option prompts. Merchant normally displays attribute and option codes before the data. The function makes the attribute or option prompts available, as configured on your product attributes screen. Using the prompt can clarify the basket display if your attributed codes, are cryptic. (e.g. where code = XL, use the prompt instead = Extra Large). if the attribute or option also has an image, it also makes it available.

Use: Add the function to the top of any page that displays a basket or the top of the invoice page. There are no additional parameters. Edit the Basket Contents and Order Contents as needed.

Usage: <mvt:item name="ry_toolbelt" param="basketcombined" /> Place at the top of the basket or invoice page.

Basket Contents: (Note: the capital F at the end means currency formatted)
&mvt:item:Combined_PriceF; Product price + the sum of option prices.
Use it in place of &mvt:item:formatted_price;

&mvt:item:Combined_SubtotalF; Combined_price * quantity.
Use it in place of &mvt:item:formatted_subtotal;

&mvt:item:Options_PriceF; Sum of the option prices.
Allows you to display the combined options price.

&mvt:item:Options_SubtotalF; Options_price * quantity.
Allows you to display the extended combined options price.

&mvt:item:Combined_Price; These are non currency formatted versions of the above.
&mvt:item:Combined_Subtotal;
&mvt:item:Options_Price;
&mvt:item:Options_Subtotal;

Prompts:
Replace &mvt:option:attr_code; with &mvt:option:prompt;

Images:
<img src="&mvt:item:thumbnail;" border="0">

<mvt:if expr="l.settings:option:image">
    <img src="&mvt:option:image;" border="0" align="left">
</mvt:if>
Index

Benchmark

These four functions allow you to easily determine page template processing time for a page or sections of a page, like foreach loops, screen, or call functions.

The name parameter is a unique name or number given to each benchmark allowing you to have multiple benchmarks on the same page template.

There are four command keywords.

   START stores the starting time in g.benchmark:name:start.
   END stores the ending time in g.benchmark:name:end AND calculates the elapsed time stored in g.benchmark:name:elapsed.
   SHOW outputs the result string e.g. "Benchmark name: Elapsed Time = 1.56425"
   HIDE is the same as show encapsulated in HTML remarks to hide the results in the page. e.g. <!--  -->

<mvt:item name="ry_datafeed" param="benchmark|unique_name_literal|command_literal" />

Example: Time the Search_Products item.
<;mvt:item name="ry_toolbelt" param="benchmark|search|START" />
  <mvt:item name="ry_toolbelt" param="Product_Search|g.itemsreturned|g.Maxitems|g.Sortby" />
<mvt:item name="ry_toolbelt" param="benchmark|search|END" />

<b>Found: </b>&mvt:prod_page:records; products.
<span style="font-size: 11px">
  (<mvt:item name="ry_toolbelt" param="eval|NumberFormat(g.benchmark:search:elapsed, 2)" /> sec.)
</span>

<mvt:item name="ry_toolbelt" param="benchmark|search|SHOW" />
<mvt:item name="ry_toolbelt" param="benchmark|search|HIDE" />
Index

BreadCrumbs

When assigned to category or product pages, BreadCrumbs displays a history trail back to home. Domain SEO Settings are used to determine the format for the category links, so that changing the settings automatically changes the links.
A separator string is required including spaces (e.g. ' '). NOTE: Storemorph chokes on the ampersand (&) inside string expressions. Notice the work-a-round using asciichar(38)
Fields Returned: id, code, href, name.

Copy and past the code below into the page template. It is common for designers to past the code into the page header.

<mvt:item name="ry_toolbelt" param="breadcrumbs|expression, literal, or RAW" /> &raquo; &mvt:category:name;

Example 1, Category Page:
<mvt:item name="ry_toolbelt" param="assign|g.sep|' ' $ asciichar(38) $ 'raquo; '" />
<mvt:item name="ry_toolbelt" param="breadcrumbs|g.sep" /> &raquo &mvt:category:name;

Example 2, Product Page:
<mvt:item name="ry_toolbelt" param="assign|g.sep|' ' $ asciichar(38) $ 'raquo; '" />
<mvt:item name="ry_toolbelt" param="breadcrumbs|g.sep" /> &raquo &mvt:product:name;

When used with the optional keyword RAW only the data is returned allowing you to format the output as desired.

<mvt:item name="ry_toolbelt" param="breadcrumbs|RAW" />

<a href="http://&mvt:global:domain:name;/">Home</a>
<mvt:foreach iterator="crumb" array="breadcrumbs">
  > <a href="&mvt:crumb:href;" title="&mvt:crumb:name;">
    &mvt:crumb:name;</a>
</mvt:foreach>
> &mvt:category:name; OR &mvt:product:name;

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'breadcrumbs', l.all_settings)" />
Index

Call

This function comes in two types.

call_get

Given a URL expression, returns the contents of any web page at any location inside another page.

<mvt:item name="ry_toolbelt" param="call_get|g.webpage|url_exprsn" />

Example:
<mvt:item name="ry_toolbelt" param="call_get|g.webpage|'http://www.google.com'" />
&mvt:global:webpage;

call_post

Given a URL expression and a fieldlist, posts the data and returns the contents of any web page at any location inside another page.

<mvt:item name="ry_toolbelt" param="call_post|g.webpage|url_exprsn|fieldlist" />

Example:
<mvt:item name="ry_toolbelt" param="call_post|g.webpage|g.sessionurl|screen,store_code,category_code" />
&mvt:global:webpage;
Index

Category_Children

Category_Children loads all categories below (i.e. are assigned) to category_code into the array l.all_settings:category_children.

Additional Fields Returned: href, image_title, image_tree.

Parameters: Category_Code: Required expression. Contains the code for the category you wish to locate.

<mvt:item name="ry_toolbelt" param="category_children|g.Category_Code" />
<mvt:item name="ry_toolbelt" param="category_children|l.all_settings:category:code" />

Example: Display subcategory images with links
<mvt:if expr="l.settings:category_children">
  <mvt:foreach iterator="subcat" array="category_children">
    <div>
      <a href="&mvt:subcat:href">
        <img src="&mvt:subcat:image_tree;" border="0"><br>&mvte:subcat:name;
      </a>
    </div>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'category_children', l.all_settings)" />
Index

Category_Images

This item loads the Category Title and Category Tree images into a user selected variable name.

<mvt:item name="ry_toolbelt" param="category_images|g.imgsrc|g.category_code" />
<mvt:item name="ry_toolbelt" param="category_images|g.imgsrc|l.all_settings:subcat:code" />
 
Example 1: Category Title image
<mvt:if expr="NOT ISNULL g.imgsrc:title">
  <img src="&mvt:global:imgsrc:title;">
</mvt:if>
 
Example 2: Category Tree image
<mvt:if expr="NOT ISNULL g.imgsrc:tree">
  <img src="&mvt:global:imgsrc:tree;">
</mvt:if>
Index

Category_Load

Category_Load returns the specified category in the array l.all_settings:category letting you put any category information on any page.

Additional Fields Returned: href, image_title, image_tree.

Parameters:
found
: Required variable. Contains 1 if the category was found.
Category_Code: Required expression. Contains the code for the category you wish to load.

<mvt:item name="ry_toolbelt" param="Category_Load|g.found|g.Category_Code" />

<mvt:if expr="g.found">
  <a href="&mvt:category:href;" title="&mvte:category:name;">
    <img src="&mvte:category:image_title;" alt="&mvte:category:name;">
  </a>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'category', l.all_settings)" />
Index

Category_Meta

This item loads the Category Meta Tag Settings; Keywords and Description into a user selected variable name.

<mvt:item name="ry_toolbelt" param="category_meta|g.meta|g.category_code" />
<mvt:item name="ry_toolbelt" param="category_meta|g.meta|l.all_settings:category:code" /> 
 
Example 1: Category Meta keywords
<mvt:if expr="g.meta:keywords">
  <meta name="keywords" content="&mvt:meta:keywords" />
</mvt:if>
 
Example 2: Category Meta description
<mvt:if expr="g.meta:description">
  <meta name="description" content="&mvt:meta:description" />
</mvt:if>
Index

Category_Paging

When placed on a regular Merchant category page, displays paging links as shown below:

NOTE: the Category_Products item has it's own built in paging method. The two are not compatible.

Products found in this category: 102   Pages: 1 [2] 3 4 5   Page: 2 of 5

The variables shown are required; pagelength is a numeric value or variable containing the number of items on the page.

This function also has an optional parameter raw that returns the raw data stored in variables instead.

<mvt:item name="ry_toolbelt" param="category_paging|l.all_settings:category:id|g.offset|pagelength" />
<mvt:item name="ry_toolbelt" param="category_paging|l.all_settings:category:id|g.offset|pagelength|raw" />

Example:
<mvt:item name="ry_toolbelt" param="category_paging|l.all_settings:category:id|g.offset|'25'" />

Formatting is via CSS styles. This style sheet can be used as a starting point.

<style type="text/css">
#category_paging { text-align: right; }
#category_paging #cp_count { float: left; padding-right: 16px;}
#category_paging #cp_pages { float: left }
#category_paging #cp_page{ }
</style>

The raw form returns these variables.

g.cp:records or &mvt:global:cp:records;
g.cp:links or &mvt:global:cp:links;
g.cp:page or &mvt:global:cp:page;
Example:
<div id="category_paging">
<div id="cp_count">Products in this category: &mvt:global:cp:records;</div>

<div id="cp_pages">Pages: &mvt:global:cp:links;</div>
<div id="cp_page"> Page: &mvt:global:cp:page;</div>
</div>
Index

Category_Parents

Category_Parents loads the top level categories into the array l.all_settings:category_parents. This could be used to display all the top level category images on the storefront or as an alternative to the expanding category tree.

Additional Fields Returned: href, image_title, image_tree.

<mvt:item name="ry_toolbelt" param="category_parents" /> 
 
Example: display parent / top level categories
 
<mvt:if expr="l.all_settings:category_parents">
<div id="cat_wrapper">
  <mvt:foreach iterator="cat" array="category_parents">
  <mvt:comment> Lookup the images </mvt:comment>
  <mvt:item name="toolkit" param="cattreeimage|tree_image|l.all_settings:cat:code" />
 
  <mvt:comment> format the short href link </mvt:comment>
  <mvt:item name="ry_toolbelt" param="seolink|category|l.all_settings:cat:code" />
 
  <div class="imgwraper">
    <a href="&mvt:href:category;">
    <mvt:if expr="g.tree_image">
      <img src="&mvte:global:tree_image;" style="width: 100px">
    <mvt:else>
      <img src="graphics/00000001/tree_placeholder.gif" style="width: 100px">
    </mvt:if>
    </a>
    <h1><a href="&mvt:href:category;">&mvte:cat:name;</a></h1>
  </div>
  </mvt:foreach>
</div>
</mvt:if>
Index

Category_Products

Product Items: Integration Guide

Category_Products provides paging links (e.g. Page: [1] 2 3 4 ), user selectable sorting, and user selectable number of items to display per page. It returns all products assigned to the category, plus additional fields described below, allowing you to do more with less work. It can be used on the CTGY page template in conjunction with the Category Product List Layout or can be used as a replacement. It can also be used to create new alternate category page layouts as in the integration guide.

This item returns the products assigned to the category in the either the array l.all_settings:products for (MMUI stores) or l.all_settings:category_listing:products for (CSSUI stores).

 Pagination and sorting settings are returned in l.all_settings:prod_page.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:
length: Required variable. Contains the number of items returned.
Category_Code: Required expression. Contains the code for the category you wish to locate.
Maxitems: Required expression. This number sets the items displayed per page. Default value is 12. Assign  Maxitems = 'ALL' to display all records. You can set Maxitems as a fixed value or use the radio controls provided to make it user selectable.
SortBy: Contains one of the following keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used (i.e. disp_order-asc).
id-desc = Newest Items
price-asc = Price LOW to high
price-desc = Price HIGH to low
name-asc = Name a-z
name-desc = Name z-a
code-asc = Code a-z
code-desc = Code a-z
default-asc = Default display order

Global Variables Used:
g.PageNum:
Is used in the pagination and sorting features.
g.SortBy:
Optional expression. A default sorting value can be set before calling the item as show below.
g.Sortby_Options: Optional expression. Lets you set a string before calling the item, to change the sort option values to use in the dropdown box.
This is a colon plus comma separated list formatted as keyword:prompt,keyword:prompt etc.
The default options are shown in the integration guide below. Edit as desired.

Integration:  Step 1. Paste this section directly above the closing tag  of the head section. </head>.

<!-- Style the pagination section. -->
<style type="text/css">
.paging { text-align: right; }
.paging .count { float: left; margin: 4px 24px 0 0; }
.paging .max { float:left; }
.paging .sort{ }
.paging .page{ float: left; margin-right: 48px;}
.paging .pages { float: left; }
.paging a.current { font-weight: bold; font-size; 13px; }
</style>

<!-- Optional: Set the maximum items to display -->
<mvt:if expr="ISNULL g.Maxitems">
<mvt:item name="ry_toolbelt" param="assign|g.Maxitems|8" />
</mvt:if>

<!-- Optional: Set the Maximum items radio button options -->
<mvt:item name="ry_toolbelt" param="assign|g.maxradio:min|8" />
<mvt:item name="ry_toolbelt" param="assign|g.maxradio:max|24" />

<!-- Optional: Set a default sort value -->
<mvt:if expr="ISNULL g.SortBy">
<mvt:item name="ry_toolbelt" param="assign|g.SortBy|'price-desc'" />
</mvt:if>

<!-- Optional: Set the options displayed in the sort list. Edit as desired. -->
<mvt:item name="ry_toolbelt" param="assign|g.Sortby_Options|
'id-desc:Newest Items,price-asc:Price LOW to high,price-desc:Price HIGH to low,' $
'name-asc:Name a-z,name-desc:Name z-a,code-asc:Code a-z,code-desc:Code a-z,'" />

<mvt:item name="ry_toolbelt" param="Category_Products|g.length|g.Category_Code|g.Maxitems|g.Sortby" />

Integration:  Step 2.  In the template search for the closing </h1> tag. Paste this section directly after the tag and any closing </mvt:if> that may be found with it.

<mvt:if expr="l.settings:prod_page:records GT 0">
    <div class="paging">
        <div class="count">PRODUCTS: <b>&mvt:prod_page:records;</b></div>
        <mvt:if expr="l.settings:prod_page:records GT 1">
            <div class="max">Show: &mvt:prod_page:maxradio;</div>
        </mvt:if>
        <mvt:if expr="l.settings:prod_page:records GT 1">
            <div class="sort">Sort By: &mvt:prod_page:sortselect; </div>
        </mvt:if>
        <mvt:if expr="l.settings:prod_page:count GT 1">
            <div class="page">Page: <b>&mvt:prod_page:current;</b> of &mvt:prod_page:count;</div>
            <div class="pages">Pages: &mvt:prod_page:links;</div>
        </mvt:if>
        <br style="clear: left">
    </div>
</mvt:if>

Integration:  Step 3. Click the Category Product List Layout tab. You will have to update the product links on this template to &mvte:product:href; Example: <a href="&mvte:product:href;"> Also find the part of the script that displays the Previous and Next buttons. Delete it and paste this in its place.

<mvt:if expr="l.settings:prod_page:records GT 0">
    <div class="paging">
        <mvt:if expr="l.settings:prod_page:count GT 1">
            <div class="page">Page: <b>&mvt:prod_page:current;</b> of &mvt:prod_page:count;</div>
            <div class="pages">Pages: &mvt:prod_page:links;</div>
        </mvt:if>
        <br style="clear: left">
    </div>
</mvt:if>

View Returned Values: To temporarily view the pages data paste this directly above the closing </body> tag.

<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products', l.all_settings)" />
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'prod_page', l.all_settings)" />
Index

Category_Siblings

Category_Siblings loads all categories that are on the same level as category_code into the array l.all_settings:category_siblings.

Additional Fields Returned: href, image_title, image_tree.

Parameter: Category_Code: Required expression. Contains the code for the category you wish to locate.

<mvt:item name="ry_toolbelt" param="category_siblings|g.category_code" />
<mvt:item name="ry_toolbelt" param="category_siblings|l.all_settings:category:code" />

Example: Display subcategory images with links
<mvt:if expr="l.settings:category_children">
  <mvt:foreach iterator="cat" array="category_siblings">
    <div>
      <a href="&mvt:cat:href">
        <img src="&mvt:cat:image_tree;" border="0"><br>&mvte:cat:name;
      </a>
    </div>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'category_siblings', l.all_settings)" />
Index

CatTree_Expanded

Cattree_Expanded outputs the entire category tree structure at once as a multi level unordered list, e.i. <ul><li> tags. Using CSS, JavaScript or JQuery makes it possible to create horizontal dropdown or vertical fly out menus. (aka suckerfish style menus) This item is extremely fast, displaying hundreds of categories nested to any depth in milliseconds on most servers. Optional parameters are provided to control its operation. Domain SEO Settings are used to determine the format for the category links, so that changing the settings automatically changes the links.

Parameters: Each of these can be variables or expressions. See example 2 below.
ul_id: Optional expression. This is the id attribute of the first ul tag. e.g. (where g.ul_id = 'cssmenu1', outputs <ul id="cssmenu1">.
href_format: Optional expression. This is an href template string that you can provide as the basis for the link. Use @C@ as a token for the category code.
topcat_limit: Optional expression. Limits the number of top level categories to the first n items. For example, you have 12 top level categories buy only want to display the first 9 in a horizontal menu.
topcat_shortnames: Optional expression. Contains a comma separated list of alternate top level category names. For example the top level category names in your horizontal menu are to long, so you provide a list of shorter names.

Return Value: The array g.topcat[ ] is populated with the top level category information. One use would be to display the top level category images on the SFNT page. See example 3 below.

<mvt:item name="ry_toolbelt" param="cattree_expanded" />
<mvt:item name="ry_toolbelt" param="cattree_expanded|ul_id|href_format|topcat_limit|topcat_shortnames" />

Example 1: Horizontal Category menu.

<div class="horizontalcssmenu">
    <mvt:item name="ry_toolbelt" param="cattree_Expanded|'cssmenu1'" />
    <a class="staticlink" href="http://forum.mywebsite.com/" target="_blank">Forum</a>
</div>

Example 2: With Parameters:
<mvt:item name="ry_toolbelt" param="assign|g.ul_id|'nav'" />
<mvt:item name="ry_toolbelt" param="assign|g.href_format|'http://' $ g.domain:name $ '/clothing/@C@.html'" />
<mvt:item name="ry_toolbelt" param="assign|g.topcat_limit|6" />
<mvt:item name="ry_toolbelt" param="assign|g.topcat_shortnames|'Jackets,Shirts,Pants,Shorts,Footwear,Accessories'" />
<div class="nav_wrapper">
    <mvt:item name="ry_toolbelt" param="Cattree_Expanded|g.ul_id|g.href_format|g.topcat_limit|g.topcat_shortnames" />
</div>

Example 3: Using g.topcat[ ] to display Storefront images:
<div id="cat_wrapper">
    <mvt:comment> Convert the global to a local array</mvt:comment>
    <mvt:item name="ry_toolbelt" param="reference|l.all_settings:topcats|g.topcats" />

    <mvt:foreach iterator="cat" array="topcats">
    <mvt:comment> Lookup the images </mvt:comment>
    <mvt:item name="toolkit" param="cattreeimage|tree_image|l.all_settings:cat:code" />

    <mvt:comment> format the href link </mvt:comment>
    <mvt:item name="ry_toolbelt" param="seolink|category|l.all_settings:cat:code" />

    <div class="imgwraper">
        <a href="&mvt:href:category;">
        <mvt:if expr="g.tree_image">
            <img src="&mvte:global:tree_image;" style="width: 100px">
        <mvt:else>
            <img src="graphics/00000001/tree_placeholder.gif" style="width: 100px">
        </mvt:if>
        </a>
        <h1><a href="&mvt:href:category;">&mvte:cat:name;</a></h1>
    </div>
    </mvt:foreach>
</div>
Index

Compress

Returns a copy of string after removing tabs, leading and trailing spaces, and blank lines. See the compress() function.

<mvt:item name="ry_toolbelt" param="compress|g.varname" />
Index

Counter

Sets increments or decrements a counter; used in a for each loop to count iterations, where valid operators are are ( = + - ). Item is any variable name you choose, and n is any whole number.

<mvt:item name="ry_toolbelt" param="counter|item=n" />
<mvt:item name="ry_toolbelt" param="counter|item+n" />
<mvt:item name="ry_toolbelt" param="counter|item-n" />


&mvt:global:counter:item;
<mvt:if expr="g.counter:item EQ 3">
<hr>
</mvt:if>
Index

Cookie

Cookie loads, saves, or clears cookies at the users browser. You now have a way to easily create persistent global variables without having to pass the information from screen to screen using forms or embedding variables and values within links.

Usage:
They can only be used in the <head> </head> section of your page template.
The cookies name is the same as the global variable name that holds the value.
Load: This command loads a previously saved cookie into the global variable you specify. If none is found the variable is null.
Save: This command saves a cookie with the same name as global variable you specify. If the variable is null, the cookie is cleared.
Expiration: When saving a cookie the duration of the cookie is set in days or portion of a day. (e.g. for 1 year, use 365, for 1 hour use 1/24)
Hint: multiple values separated by a space can be stored in a single cookie.

<mvt:item name="ry_toolbelt" param="cookie|load|g.variablename" />
<mvt:item name="ry_toolbelt" param="cookie|save|g.variablename|numeric_expression_days" />

Example 1: Persistent Global Variable:

<mvt:item name="ry_toolbelt" param="cookie|load|g.user_preference" />
<mvt:if expr="g.user_preference">
  <mvt:comment> Re-save the cookie to refresh the vale for another day. </mvt:comment>
  <mvt:item name="ry_toolbelt" param="cookie|save|g.user_preference|1" />
<mvt:else">
  <mvt:comment> Add you code here that transmits the user value in a form. </mvt:comment>
  Enter your color: <input type="text" Name="user_preference" value="" /><br>
</mvt:if>

Example 2, Persistent Session after login:
A sample page template is included with the module called Sessions.txt
Index

CurrencyFormat

Returns a monetary number formatted in the currently configured currency.

<mvt:item name="ry_toolbelt" param="currencyformat|g.varname|expression" />


Example:
<mvt:item name="ry_toolbelt" param="currencyformat|g.newprice|g.cost * 1.5" />
Price: &mvt:global:newprice;<br><br>
Index

Custom_Category

Custom Category loads custom category fields into a global variable of your choice

Category_Code: Required expression. Contains the code for the category you wish to locate.

<mvt:item name="ry_toolbelt" param="custom_category|g.extcat|variable_name" />

<mvt:item name="ry_toolbelt" param="custom_category|g.extcat|g.Category_code" />

Example:
<mvt:if expr="g.extcat:value:fieldcode">
  &mvt:global:extcat:name:fieldcode;: &mvt:global:extcat:value:fieldcode;<br>
</mvt:if>
Index

Custom_Customer

This item comes in two types; read and write. A typical application would be to add tax id field to the add and edit customer pages. On the edit screen you can read the database, populate an input text box (e.g. name="TaxId" ) and allow the customer to edit it. On the next screen, usually the storefront, you test for the variable g.TaxId and the read the database, change the field using the assign token the write then record back out.

custom_customer_read

Given g.basket:cust_id, reads the custom customer fields into a global variable of your choice.

<mvt:item name="ry_toolbelt" param="custom_customer_read|g.varname|g.basket:cust_id" />

Example:
<mvt:item name="ry_toolbelt" param="custom_customer_read|g.extcust|g.basket:cust_id" />
<mvt:if expr="g.extcust:value:taxid">
    &mvt:global:extcust:name:taxid;: &mvt:global:extcust:value:taxid;
</mvt:if>

&mvt:global:extcust:name:taxid;: &mvt:global:extcust:value:taxid;

custom_customer_write

Given a g.basket:cust_id, writes the values to the custom customer fields. You must first read the custom customer fields, field values can be modified using the assign item, the writen back to the database.

<mvt:item name="ry_toolbelt" param="custom_customer_write|g.varname|g.basket:cust_id" />

Example:
<mvt:if expr="NOT ISNULL g.taxid">
  <mvt:item name="ry_toolbelt" param="custom_customer_read|g.extcust|g.basket:cust_id" />
  <mvt:item name="ry_toolbelt" param="assign|g.extcust:value:tax_id|encodeentities(trim(g.taxid))" />
  <mvt:item name="ry_toolbelt" param="custom_customer_write|g.extcust|g.basket:cust_id" />
</mvt:if>
Index

Custom_Products

Given a variable containing product id or product code, loads the custom product fields into a global variable of your choice. In order to determine if the id or code is entered, the following naming convention must be observed. A product id variable name must end with :id, _id or .id as shown below. a category code must end with :code, _code or .code.

<mvt:item name="ry_toolbelt" param="custom_products|g.extprod|variable_name" />

<mvt:item name="ry_toolbelt" param="custom_products|g.extprod|l.all_settings:product:id" />
<mvt:item name="ry_toolbelt" param="custom_products|g.extprod|g.prod_code"

Example:

<mvt:if expr="g.extprod:value:fieldcode">
&mvt:global:extprod:name:fieldcode;: &mvt:global:extprod:value:fieldcode;<br>
</mvt:if>
Index

Datetime_Format

This function converts time_t (i.e. time stamp) values to formatted date time strings. It provides an extensive set of formatting options. Note: time_t is defined in Miva Merchant as the number of seconds since Jan 1, 1970 Greenwich Mean Time (GMT).

The function takes a numeric date as a time_t value, (e.g. s.dyn_time_t) or the keyword NOW, and a date/time format string describing the return value. The format value can contain a keyword show below or a string expression containing the following:

(yy or yyyy), (m, or mm), (mmm, or mmmm), (d, or dd), (ddd, or dddd), (h or hh), (m or mm), (s or ss), /, -, :, ampm, zone, GMT.

In the format string; ampm refers to the 12 hour clock and display a.m. or p.m. and zone will display the time zone code (e.g. EST, PST, etc.).

GMT is a special keyword that forces the time conversion from time zone 0.

Keywords Results
SHORTDATE 11/23/2008
MEDIUMDATE Nov 23, 2008
LONGDATE November 23, 2008
FULL Thursday, November 23, 2008 CE 0:05:11 p.m. EST
SHORTTIME 12:05
MEDIUMTIME 12:05:11
LONGTIME 00:05:11 p.m.
* GMTSTRING Thu, 04-Dec-2009 16:30:03 GMT
Format string examples Results
yy, yyyy 08, 2008
m, mm, mmm, mmmm 1, 01, Jan, January
d, dd, ddd, dddd 4, 04, Thu, Thursday
h, hh, m, mm, s, ss 6, 06, 3. 03, 9, 09
hh:mm:sec zone 17:30:15 EST
mm/dd/yyyy 12/04/2008
ddd, mmm. d, yyyy Thu, Dec. 4, 2008
dddd, mmmm d, yyyy h:mm ampm zone Thursday, December 4, 2008 7:30 p.m. EST

* All time conversions are based on the time zone set at the server UNLESS the characters 'GMT' are included in the format string or the keyword GMTSTRING is used. GMTSTRING outputs the date and time in the format required for client side cookies.

<mvt:item name="ry_toolbelt" param="datetime_format|g.return|datevalue_exprsn|date_format_string_exprsn" />

Example 1. current complete time:

<mvt:item name="ry_toolbelt" param="datetime_format|g.return|NOW|FULL" />
Returns: Thursday, December 4, 2008 CE 1:32:53 a.m. EDT

Example 2. cookie date + 60 days:
<mvt:item name="ry_toolbelt" param="datetime_format|g.return|s.dyn_time_t + (86400 * 60)|GMTSTRING" />

Returns: Thu, Dec 5, 2009 CE 6:32:53 a.m. GMT

Index

Datetime_Value

This function converts formatted date / time string, returning time_t values (i.e. time stamp). Note: time_t is defined in Miva Merchant as the number of seconds since Jan 1, 1970 Greenwich Mean Time (GMT).

The function expects the date and time values, formatted as shown below, and a numeric time zone value. When a date and time are specified together, they must be separated by a space.

Dates value must contain a '/'or '-'.
m-d-yy, m/d/yy
mm-dd-yy, mm/dd/yy
mm-dd-yyyy, mm/dd/yyyy

Time value must contain a ':'. The am/pm strings are optional.
hh:mm [am, a.m., pm, p.m.]
hh:mm:ss [am, a.m., pm, p.m.]

The keyword NOW can be used instead of a date to return the current time_t value on the server.

The time zone value can be specified using the built in timezone() function as shown in the examples below.

<mvt:item name="ry_toolbelt" param="datetime_value|g.return|date_string|timezone()" />

Example 1. <mvt:item name="ry_toolbelt" param="datetime_value|g.timestamp|'12/04/2008'|timezone()" />

&mvt:global:timestamp;
displays: 1228366800

Example 2. <mvt:item name="ry_toolbelt" param="datetime_value|g.timestamp|'12/04/2008 18:05:11'|timezone()" />
<mvt:item name="ry_toolbelt" param="assign|g.fmt_string|'dddd, d-mmm-yyyy hh:mm ampm zone'" />

<mvt:item name="ry_toolbelt" param="datetime_format|g.reformated_date|g.timestamp|g.fmt_string" />
&mvt:global:reformated_date;
displays: Thursday, 4-Dec-2008 06:05 p.m. EDT
Index

Do

The short name of the Do item hides the fact that this is the most powerful command in Toolbelt. Use Do to call external compiled functions within any MivaScript file. Like MivaScripts MvDO tag, you can directly access your own compiled external functions or tap directly into Miva Merchants API. This command often makes it possible to avoid much of the work and overhead of writing complete modules.

Parameters:   
file_path:
Required expression. Contains the path from the root to the compiled .mvc file.
Function_Name: Required. This is the name of the function in the file

Function Parameters: These must be numbers, strings, global variables or local variable with the l.all_settings prefix. Parameters can not contain expressions or nested functions.

<mvt:item name="ry_toolbelt" param="do|g.file_path|g.result|Function_Name( parameter1, parameter2)" />

Examples:
<mvt:item name="ry_toolbelt" param="do|g.Module_Library_DB|g.btotal|Basket_SubTotal(g.Basket:BASKET_ID)" />

<mvt:item name="ry_toolbelt" param="do|g.Module_Library_DB|g.found|
      Runtime_Category_Load_Code(g.Category_Code, l.all_settings:category)" />
Index

Eval

Outputs the expression result; where expression is most valid MivaScript expressions.

<mvt:item name="ry_toolbelt" param="eval|expression" />
Index

Event_Timer

This function triggers events on your website at any timed interval; monthly, weekly, daily, hourly etc. Use it to pack the store, create batches, post form data, send emails or automate any other task you can think of.

Events are triggered when a user loads a web page containing an event_timer. Since it relies on page hits to trigger the event, the timing is of course not precise, so a duration is specified to provide a time window. The first page hit during the time window triggers the event and sets a flag preventing it from triggering again. The first page hit after the time windows, clears the flag.

When triggered, the function calls any webpage you specify, where the task has been scripted. Normally the call uses the GET method but if the optional field list is provided, the POST method is used. Using the Tell-A-Friend template included with the module as an example, you can script a new page template to send data via email at regular intervals.

Parameters:
name: This is a unique name or number given to each event timer.
g.return: This is the variable where the page results are returned.
time_exprsn: can contain the following:

  •    'now' Use the current time then repeat in time_window seconds
  •    'monthly dd hh:mm:ss' where dd is the day of the month
  •    'weekly monday hh:mm:ss' where monday is the day name or day number of the week (sunday = 1, monday = 2 etc)
  •    'daily hh:mm:ss' where hh is 0 to 24 hours, mm is 0 to 59 minutes and ss is 0 to 59 seconds
  •    'time_t value' when a time_t value is specified, the trigger will activate only once when the time is reached

duration: This is the number of seconds the timer will remain active. (e.g. 'daily 06:00:00'| 3600) means the first page hit between 6  and 7 a.m. will trigger the event.
url: This is the URL string of the page to be called when the event_timer is triggered. Note the use of the tilde character instead of & in the examples.
fieldlist: This is optional and used when the POST method is desired.

<mvt:item name="ry_toolbelt" param="event_timer|name|g.return|time_exprsn|duration|url|fieldlist" />

NOTE: in each of these examples &mvt:global:return; would be deleted after testing is complete.
Example #1: Pack the database every 12 hours
<mvt:item name="ry_toolbelt" param="assign|g.user|'joe'" />

<mvt:item name="ry_toolbelt" param="assign|g.password|'br549'" />
<mvt:item name="ry_toolbelt" param="assign|g.url|
'http://www.websitecom/mm5/admin.mvc?username='$g.user$'~password='$g.password$'~Screen=BLNK~Action=PACK'" />
<mvt:item name="ry_toolbelt" param="assign|g.url|glosub(g.url,'~',asciichar(38))" />

<mvt:item name="ry_toolbelt" param="event_timer|packdata|g.return|'now'|3600 * 12|g.url|" />
<mvt:item name="ry_toolbelt" param="assign|g.u|''" />
<mvt:item name="ry_toolbelt" param="assign|g.p|''" />

&mvt:global:return;
<mvt:item name="ry_toolbelt" param="assign|g.return|''" />

Example #2: Daily post data to a webpage every evening.
<mvt:item name="ry_toolbelt" param="assign|g.search|'test'" />

<mvt:item name="ry_toolbelt" param="assign|g.screen|'SRCH'" />
<mvt:item name="ry_toolbelt" param="event_timer|eveningpost|g.return|
'daily 22:00:00'|3600 * 2|'http://www.websitecom/mm5/merchant.mvc?'|g.search,g.screen" />
&mvt:global:return;

Index

For

Allows you to take control of the foreach tokens to create your own loop structure. Example: for|x=1 to 10 step 2
Expressions can be numbers, numeric variables, or numeric expressions but can not contain spaces. The step incriment_exprsn is optional and defaults to 1.
Parameters:
counter: Required simple variable name.
start_exprsn: Required numeric expression: The number to start from
end_exprsn: Required numeric expression: The number to end at.
step: Optional keyword. Indicates and increment number follows
incriment_exprsn: Optional expression. The value to increment by; may be positive or negative.

Note #1: Expression values can be zero or negative to execute a reverse loop (e.g for|j=20 to -20 step -1) however, nonsensical combinations (i.e. step 0) will return an error message.
Note #2: Due to limitations of the template compiler, there is no way to break out of a loop. You can place conditionals around your code to skip further processing while the loop finishes.

<mvt:item name="ry_toolbelt" param="for|counter=start_exprsn to end_exprsn step incriment_exprsn" />

Example: 1
<mvt:item name="ry_toolbelt" param="assign|g.max|32" />
<mvt:item name="ry_toolbelt" param="assign|g.bytwo|2" />
<mvt:item name="ry_toolbelt" param="for|j=0 to g.max step g.bytwo" />
<mvt:foreach iterator="j" array="for_j">
  &mvt:j; = <mvt:item name="ry_toolbelt" param="eval|l.all_settings:j" /><br>
</mvt:foreach>

Example: 2. Use a comma separated list to create a select box.
<mvt:item name="ry_toolbelt" param="assign|g.opts|
'January,February,March,April,May,June,July,August,September,October,November,December'" />
<select id="custom_field" name="custom_field">
  <option value="">Select a Month</option>
  <mvt:item name="ry_toolbelt" param="for|j=1 to GettokenCount(g.opts,',')" />
  <mvt:foreach iterator="j" array="for_j">
    <mvt:item name="ry_toolbelt" param="assign|g.opt|gettoken(g.opts,',',l.all_settings:j)" />
    <mvt:if expr="g.custom_field EQ g.opt">
      <option value="&mvt:global:opt;" selected>
    <mvt:else>
      <option value="&mvt:global:opt;">
    </mvt:if>
    &mvt:global:opt;</option>
  </mvt:foreach>
</select>
Index

HasAttributes

This item returns a number of attributes a product has. On a category page this can be used to change the Add to Basket button into a More Information link, for any product that has attributes.

<mvt:item name="ry_toolbelt" param="hasAttributes|g.attr_count|l.all_settings:product:code" />

Example:
<mvt:if expr="g.attr_count">
  <a href="&mvt:href:product">More Information...</a>
<mvt:else>
  <mvt:item name="buttons" param="Add1ToBasket" />
</mvt:if>
Index

Lookup|Header Footer

Save ANY category header or footer or ANY product header or footer to a variable by providing the category or product code. The final parameter is optional. If omitted, the current g.Category_Code or g.Product_code is used. This function can be used on any screen, and is not restricted to category or product pages.

This functions comes in four varieties.

<mvt:item name="ry_toolbelt" param="lookup|ctgy_header|g.cathead|g.catcode_exprsn" />

<mvt:item name="ry_toolbelt" param="lookup|ctgy_footer|g.catfoot|g.catcode_exprsn" />

<mvt:item name="ry_toolbelt" param="lookup|prod_header|g.prodhead|g.prodcode_exprsn" />

<mvt:item name="ry_toolbelt" param="lookup|prod_footer|g.prodfoot|g.prodcode_exprsn" />

Example 1: Used on a product page where g.Category_Code is known...
<mvt:item name="ry_toolbelt" param="lookup|ctgy_footer|g.catfoot|"

Example 2: <mvt:item name="ry_toolbelt" param="lookup|prod_header|g.prodhead|'tr500'"
&mvt:global:prodhead;
Index

Lookup|Login

This item outputs a form that allows customers to enter their email address and receive their account login name by email.

Integrate this item on the customer Login page (LOGN) and Order Login Page (ORDL) as show in example 1 below.
Optionally you can use the file LOOKUP_LOGIN.txt included in the modules zip file to fully control the formatting or place the lookup in a popup window.

Three methods for integrating the item are show below.

Keywords: Three options are provide to determine the "from" email address used in the form.
ORDER_CONFIRMATION_EMAIL: This is the email address configured in Email Merchant Notification (default if left blank.)
STORE_OWNER_EMAIL: This is the email address configured in the store Registration.
NOREPLY: This will output noreply@yourdomain.com

<mvt:item name="ry_toolbelt" param="lookup|login|FROM_KEYWORD" />

Example 1: Integrate the item directly onto the pages LOGN and ORDL.
Locate the Login <form> it will contain <input type="hidden" name="Action" value="LOGN" />
After the closing tag >/form> insert the item and use CSS to style the form elements

</form>
<mvt:item name="ry_toolbelt" param="lookup|login|NOREPLY" />

Example 2: Create a new page template call with the code lookuplogin.
Copy and paste the supplied file called LOOKUP_LOGIN.txt. Edit the template as desired.
Locate the login forms closing tag </form> on LOGN and ORDL.
Use the screen command to insert the form.

</form>
<mvt:item name="ry_toolbelt" param="screen|lookuplogin" />

Example 3: Create a template as show in Example 2.
Use JavaScript to open the page in a new window by clicking a link or button.

<mvt:item name="ry_toolbelt" param="assign|g.url|g.sessionurl $ 'screen=lookuplogin'" />
<b>Forgot your login?</b><br />
<a onclick="window.open ('&mvt:global:url;', 'Email my login','menubar=0,resizable=1,
width=300,height=150,left=400,top=300''); return false;"
href="#" title="Get my login id">Email my login</a>
Index

Lookup|SQL depreciated

See Query. lookup|SQL allows you to execute your own SQL Select * query on ANY Merchant database table within your store.

Knowledge of MySQL and the database tables is required. You can access a single record or return an array of records where table_name is a string expression that results in a table name in the database. Likewise, the query_exprsn will consists of a string variable or literal representing the records you wish to return.

Important: Table names are case sensitive and for security, are limited to the store tables. In the examples below, notice the single quote surrounding the entire expression and right quotes 'code=`shirt_50214`' that surround the product code shirt_50214. Right quotes are required to represent the inner string within the string expression. On my keyboard the right quote (`) is found with the tilde (~) character.

This function also returns several other variables useful for debugging. g.SQL contains the resulting query string, g.SQL_length contains the number of records returned, and l.settings:structure contains the structure of the table returned. See the sample code below and the Toolbelt Structure function.

<mvt:item name="ry_toolbelt" param="lookup|SQL|g.table_name|g.query_exprsn|returnarray" />

Examples:
1. Load specific product:
<mvt:item name="ry_toolbelt" param="assign|g.where|'WHERE code=`shirt_50214`'" />
<mvt:item name="ry_toolbelt" param="lookup|SQL|'Products'|g.where|SQLresults" />
&mvt:SQLresults[1]:code; = 'code=`shirt_50214`'

2. All products sorted by display order:
<mvt:item name="ry_toolbelt" param="assign|g.where|'WHERE 1 ORDER BY disp_prder ASC'" />
<mvt:item name="ry_toolbelt" param="lookup|SQL|'Products'|g.where|SQLresults" />

3. Products by descending price:
<mvt:item name="ry_toolbelt" param="assign|g.where|'WHERE price<`25.00` ORDER BY price DESC'" />
<mvt:item name="ry_toolbelt" param="lookup|SQL|'Products'|g.where|SQLresults" />

Display the Results:
<mvt:if expr="g.SQL_length">
<mvt:foreach iterator="item" array="SQLresults">

    <mvt:item name="ry_toolbelt" param="assign|g.count|g.count + 1" />
    &mvt:global:count;. Code: &mvt:item:code; : Name: &mvt:item:name; $ &mvt:item:price;<br>
</mvt:foreach>
</mvt:if>


Debugging Tools:
Query String = &mvt:global:SQL;<br>
SQL_length = &mvt:global:SQL_length;<br>
<mvt:foreach iterator="db" array="structure">
name: &mvt:db:field_name;, type: &mvt:db:field_type;,

length: &mvt:db:field_len;, decimals: &mvt:db:field_dec; <br>
</mvt:foreach>
Index

NumberFormat

This item and the NumberFormat() function returns a number formally formatted. For example 1214365.346 formats as 1,214,365.35

<mvt:item name="ry_toolbelt" param="NumberFormat|g.result|Numeric_expression|decimal_places" />
 
Example 1:
<mvt:item name="ry_toolbelt" param="asign|g.population|307006550" />
<mvt:item name="ry_toolbelt" param="NumberFormat|g.populationF|g.population|0" />
US Population: &mvt:global:populationF;<br>
 
US Population: 307,006,550
 
Example 2:
<mvt:item name="ry_toolbelt" param="eval|NumberFormat( g.StickerPrice, 2 )" />
Index

OrderSubtotal

Used only on the Invoice page, OrderSubtotal returns order subtotal, weight and number of items. It assigns values to a user selected variable name. This is very handy when you need to transmit these values to a third party like Google for ROE tracking.

Usage: Add the item as the first line of the INVC page template.

<mvt:item name="ry_toolbelt" param="ordersubtotal|variablename" />

Example:
<mvt:item name="ry_toolbelt" param="ordersubtotal|g.order_items" />

&mvt:global:order_items:length;<br>
&mvt:global:order_items:weight;<br>
&mvt:global:order_items:subtotal;<br>
&mvt:global:order_items:subtotalF;<br>

<mvt:if expr="g.order_items:length GT 0">
  Items in Order: &mvt:global:order_items:length;<br>
  Order Subtotal: &mvt:global:order_items:subtotalF;
</mvt:if>
Index

PercentFormat

This item and the PercentFormat() function returns a number formatted as a percentage. For example 0.15 would display as 15%

<mvt:item name="ry_toolbelt" param="PercentFormat|g.result|Numeric_expression|decimal_places" />
 
Example 1:
<mvt:item name="ry_toolbelt" param="asign|g.price|100.00" />
<mvt:item name="ry_toolbelt" param="asign|g.SalePrice|85.00" />
<mvt:item name="ry_toolbelt" param="PercentFormat|g.discount|(g.Price - g.SalePrice) / g.Price|2" />
You Saved: &mvt:global:discount;<br>
 
You Saved: 15.00%
 
Example 2:
<mvt:item name="ry_toolbelt" param="asign|g.markup|(g.price / g.cost) - 1" />
<mvt:item name="ry_toolbelt" param="eval|PercentFormat( g.markup, 2 )" />  
Index

Product_BestSellers

Product_BestSellers returns the stores best selling products in the array l.all_settings:bestsellers. It also provides sorting options.

Additional Fields Returned: formatted_price, formatted_cost, href, ordercount, price_original, and quantity (in basket).

Parameters:
length: Required variable. Contains the number of items returned.
Category_Code: Optional expression. If omitted it returns best selling products from all active products.
Maxitems:
Optional expression. Limits the number of items returned.
SortBy: Optional expression. Contains keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used. (i.e. disp_order-asc)
See: Category_Products for the sort keywords.

<mvt:item name="ry_toolbelt" param="Product_BestSellers|g.length|g.Category_Code|g.Maxitems|g.Sortby" />

<mvt:if expr="g.length">
  <mvt:foreach iterator="item" array="bestsellers">
    <a href="&mvt:item:href;" title="&mvte:item:name;">
      <img src="&mvt:item:thumbnail;" alt="&mvte:item:name;" border="0"><br>
      Price: &mvt:item:formatted_price;<br>
      <b>&mvte:item:name;</b><br>
    </a>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'bestsellers', l.all_settings)" />
Index

Product_Categories

Product_Categories returns each category record a product is assigned to into the array l.all_settings:product_categories.

Additional Fields Returned: href, image_title, image_tree.

Parameters:
length
: Required variable. Contains the number of items returned.
Product_Code: Required expression.

<mvt:item name="ry_toolbelt" param="Product_Categories|g.length|g.Product_Code" />

Example:
<mvt:if expr="g.length">
  <mvt:foreach iterator="cat" array="product_categories">
    Categories : &mvt:cat:code; &mvt:cat:name; <br>
  </mvt:foreach>
</mvt:if>

First Category: &mvt:product_categories[1].code; &mvt:product_categories[1].name;<br>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'product_categories', l.all_settings)" />
Index

Product_List

Product Items: Integration Guide

Product_List provides paging links (e.g. Page: [1] 2 3 4 ), user selectable sorting, and user selectable number of items to display per page. It returns products plus the additional fields described below, allowing you to do more with less work. Use it on the PLST page template.

This item returns the products assigned to the category in the either the array l.all_settings:products for (MMUI stores) or l.all_settings:all_products:products for (CSSUI stores).

 Pagination and sorting settings are returned in l.all_settings:prod_page.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost andquantity (in basket)

Integration and Optional Settings: are identical to the Category_Products item, only Category_Code is not needed. Go there for details.

Index

Product_Load

Product_Load returns a product record, in the array l.all_settings:product letting you put any product information on any page.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:
found
: Required variable. if found returns 1.
Product_Code: Required expression.

<mvt:item name="ry_toolbelt" param="Product_Load|g.found|g.Product_Code" />

Example:
<mvt:if expr="g.found">
  <a href="&mvt:product:href;" title="&mvte:product:name;">
    <img src="&mvte:product:thumbnail;" alt="&mvte:product:name;">
  </a>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'product', l.all_settings)" />
Index

Products_New

Products_New returns the newest products added to the store in the array l.all-settings:products_new.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:
length
: Required variable. Contains the number of items returned.
Maxitems: Required expression. Limits the number of items returned (Default = 10)
Category_Code: Optional expression. Limit the results to new items in this category. If omitted it will select from all products.
SortBy: Optional expression. Contains keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used. (i.e. disp_order-asc)
See: Category_Products for the sort keywords.

mvt:item name="ry_toolbelt" param="Products_New|g.length|g.Category_Code|g.MaxItems|g.SortBy" />

Example All new products: <mvt:item name="ry_toolbelt" param="products_new|g.length||10|'price-desc'" />

<mvt:if expr="g.length">
  <mvt:foreach iterator="item" array="products_new;">
    <a href="&mvt:item:href;" title="&mvte:item:name;">
      <img src="&mvt:item:thumbnail;" alt="&mvte:item:name;" border="0"><br>
      Price: &mvt:item:formatted_price;<br>
      &mvte:item:name;
    </a>
</mvt:if>
</mvt:foreach>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products_new', l.all_settings)" />
Index

Product_NextPrev

Product_NextPrev is used on a product page to create buttons links or image links for Previous and Next products in the category. It returns the arrays l.all_settings:next and l.all_settings:prev.

Fields returned: code, href, image, thumbnail.

Parameters:
Product_Code: Required expression. Contains the code for the product.
Category_Code: Required expression. Contains the code for the category.

Add just above the closing </head> tag.
<mvt:item name="ry_toolbelt" param="Product_NextPrev|g.Product_Code|g.Category_Code" />

Example:
<mvt:if expr="l.settings:next:code">
  <button class="button" style="float: right" onclick="document.location.href='&mvte:Next:href;';" title="&mvte:next:code;">
    Next Product
  </button>
</mvt:if>

<mvt:if expr="l.settings:prev:code">
  <button class="button" style="float: left" onclick="document.location.href='&mvte:prev:href;';" title="&mvte:prev:code;">
    Previous Product
  </button>
</mvt:if>
<br style="clear:both">

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'prev', l.all_settings)" />
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'next', l.all_settings)" />
Index

Products_Random

Products_Random returns randomly selected products from a category or from all products into the array l.all_settings:randprod.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:   
Category_Code:
Optional expression. Contains the code for the category you wish to locate. If omitted products are selected from all products. 
Maxitems: Required expression. Limits the number of items returned (Default = 10)

<mvt:item name="ry_toolbelt" param="Products_Random|g.category_code|g.maxitems" />

Examples:
<mvt:item name="ry_toolbelt" param="products_random|g.Category_Code|4" />

<mvt:if expr="l.settings:randprod">
  <b>Featured Products</b><br>
  <mvt:foreach iterator="prod" array="randprod">
    <a href="&mvt:prod:href;" title="&mvte:prod:name;">
      <img src="&mvte:prod:thumbnail;" alt="&mvte:prod:name;" border="0"><br>
      &mvte:prod:name;
    </a><br>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'randprod', l.all_settings)" />
Index

Products_Related

Products_Related returns all products related to product_code into the array l.all_settings:related, letting you put any related product information on any page. You could use it on the basket page to display products related to the last item in the basket.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:
length
: Required variable. Contains the number of items returned.
Product_code: Required expression. Contains the code for the product you wish to locate.
Maxitems: Optional expression. Limits the number of items returned. If zero or omitted, all related products are returned.
SortBy: Optional expression. Contains keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used. (i.e. disp_order-asc)
See: Category_Products for the sort keywords.

<mvt:item name="ry_toolbelt" param="Products_Related|g.length|g.Product_Code|g.Maxitems|g.SortBy" />

<mvt:if expr="g.length">
  <mvt:foreach iterator="item" array="related">
    <a href="&mvt:item:href;" title="&mvte:item:name;">
      <img src="&mvt:item:thumbnail;" alt="&mvte:item:name;" border="0"><br>
    </a><br>
    Price: &mvt:item:formatted_price;<br>
    &mvte:item:name;<br>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'related', l.all_settings)" />
Index

Products_Purchased

Products_Purchased returns the stores most recently sold products in the array l.all_settings:products_purchased. Sorting options provided.

Additional Fields Returned: formatted_price, formatted_cost, href, ordercount, price_original, and quantity (in basket)

Parameters:
length: Required variable. Contains the number of items returned.
Category_Code: Optional expression. If omitted it returns best selling products from all active products.
Maxitems:
Optional expression. Limits the number of items returned (Default = 10)
SortBy: Optional expression. Contains keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used. (i.e. disp_order-asc)
See: Category_Products for the sort keywords.

<mvt:item name="ry_toolbelt" param="Products_Purchased|g.length|g.Category_Code|g.MaxItems|g.SortBy" />

<mvt:if expr="g.length">
  <mvt:foreach iterator="item" array="products_purchased">
    <a href="&mvt:item:href;" title="&mvte:item:name;">
      <img src="&mvt:item:thumbnail;" alt="&mvte:item:name;" border="0"><br>
      Price: &mvt:item:formatted_price;<br>
      &mvte:item:name;<br>
    </a>
  </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products_purchased', l.all_settings)" />
Index

Products_Viewed

Products_Viewed outputs a drop down select box of previously view products. It can be placed on any page but only tracks product page views. When a product is selected from the list, the browser returns to that product page. It returns the array l.all-settings:products_viewed

Fields Returned: catcode, href, prodcode, and prodname,  When the keyword RAW  is used nothing is output and images are also returned; image and thumbnail;

Parameters:
Maxitems: Optional expression. Limits the number of items returned. (Default = 10)
Maxage: Optional expression. Determine how many minutes to keep track. Default = 740 (12 hrs), Max value = 1440 (24 hrs)
RAW: Optional keyword. Suppresses drop down output and just returns the data and also returns image and thumbnail fields.

<mvt:item name="ry_toolbelt" param="Products_Viewed|g.maxitems|g.maxage|RAW" />

Example 1: Output the select box
<mvt:item name="ry_toolbelt" param="Products_Viewed|8|120|" />
Displays a select box of the last 8 items viewed in the last 2 hours.

Example 2: Manually output the select box using default values.
<mvt:item name="ry_toolbelt" param="Products_Viewed|||RAW" />
<mvt:if expr="l.settings:products_viewed">
  <select id="prod_viewed" name="prod_viewed" size="1"
      onchange="document.location.href=this.options[this.selectedIndex].value">
    <option selected="selected">-- Previously Viewed --</option>
    <mvt:foreach iterator="view" array="Products_Viewed">
      <option value="&mvt:view:href;">&mvte:view:prodname;</option>
    </mvt:foreach>
  </select>
</mvt:if>

Example 3: Display 3 thumbnail images of products viewed in the last 6 hours.
<mvt:item name="ry_toolbelt" param="Products_Viewed|3|360|RAW" />
<mvt:if expr="l.settings:products_viewed">
  <b>Previously Viewed</b><br>
    <mvt:foreach iterator="view" array="Products_Viewed">
        <a href="&mvt:view:href;" title="&mvte:view:prodname;">
            <img src="&mvte:view:thumbnail;" alt="&mvte:view:prodname;"><br>
            &mvte:view:prodname;
        </a><br>
    </mvt:foreach>
</mvt:if>

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products_viewed', l.all_settings)" />
Index

Pricegroup

Description and Examples

These ten functions provide you with all the tools you need to manage customer and products in pricegroups. 
<mvt:item name="ry_toolbelt" param="pricegroup|Load_All|g.count" />

<mvt:item name="ry_toolbelt" param="pricegroup|Load_Name|g.pg_found|prgp_name_or_csv_list" />

<mvt:item name="ry_toolbelt" param="pricegroup|Customer_Groups|g.count" />

<mvt:item name="ry_toolbelt" param="pricegroup|Customer_Find|g.found|prgp_name_exprsn" />
<mvt:item name="ry_toolbelt" param="pricegroup|Customer_Insert|g.result|prgp_name_exprsn" />
<mvt:item name="ry_toolbelt" param="pricegroup|Customer_Delete|g.result|prgp_name_exprsn" />


<mvt:item name="ry_toolbelt" param="pricegroup|Product_Groups|g.count|product_code_exprsn" />
<mvt:item name="ry_toolbelt" param="pricegroup|Product_Find|g.found|prgp_name_exprsn|product_code_exprsn" />

<mvt:item name="ry_toolbelt" param="pricegroup|Product_Insert|g.result|prgp_name_exprsn|product_code_exprsn" />
<mvt:item name="ry_toolbelt" param="pricegroup|Product_Delete|g.result|g.product_code_exprsn" />
Index

PreAction PostAction

Description and Examples

PreAction & PostAction are not commands in the traditional sense. They are intercepts that allow you to insert script directly before or after any Miva Merchant action and affect the processing of the form data using regular Storemorph page templates as a subroutine. You can also construct your own custom action command scripts.

Examine any Merchant page template that contains a form and you will find an action command. When the form is submitted the action instructs Merchant what to do with the data. For example the ICST action tells Merchant to insert a new customer record.  Merchant will validate the data before saving the record but if an error occurs, the user is returned to the page to correct the error. If you add additional fields to the form, Merchant will simply ignore them. By inserting one or both of these new actions you can provide your own validation or processing scripts for the extra data.

<input type="hidden" name="keyword" value="keyword_pagecode">

Example:
<input type="hidden" name="PreAction" value="PREACTION_ACAD">
<input type="hidden" name="Action" value="ICST">
<input type="hidden" name="PostAction" value="POSTACTION_ACAD">

In the example above, the PREACTION_ and POSTACTION_ prefixes are required.
PREACTION_ACAD is the page code of the script that will process the form data, before Merchant processes it.
POSTACTION_ACAD is the page code of the script that will process the form data, after Merchant processes it.
For security, Toolbelt will not allow Merchant to display an page with those prefixes.

Possible Uses:

1. You want to collect additional required information from your customer during checkout then email that information to someone. Add the new form fields and the PreAction hidden field. In your PREACTION_CODE page template validate the new fields. When you find Invalid data, you want to send the customer back to the same page with warnings. Otherwise, use the SendEmail item to transmit the information by email.

2. You collect perform a survey and want to save the form data to a text log file. Using PostAction you format the data into a tab delimited string in your POSTACTION_CODE page template, then use these functions to create or append the data to file on the secure side of your site.

fexists(path)
file_create(path, location, data)
file_append(path, location, data)

Index

Query

This powerful item allows you to execute ANY well formed MySQL query on any Merchant table within your domain or store. IMPORTANT: Knowledge of MySQL and database tables is essential. It is possible to execute queries that can permanently alter or delete the data and tables within your store. Use with extreme caution and always back up your data before testing any query that modifies tables or data.

In the examples below, query_string_expression must be contain a valid MySQL query. Records will be returned in a structured array of records in the form l.all_settings:array_name[n]:field_name. This allows you to use the foreach command to loop through the results.

Important: Table names are case sensitive. text strings like g.customer_lname must be embedded in single quotes however due to a limitation in page templates, you have to use the left quote as shown below. Toolbelt will change these to single quotes for you.

<mvt:item name="ry_toolbelt" param="query|query_string|array_name" />

Example:
<mvt:item name="ry_toolbelt" param="assign|g.sql|'
SELECT * FROM s01_Orders WHERE (ship_lname = `' $ g.customer_lname $ '`) ORDER BY id ASC'" />
<mvt:item name="ry_toolbelt" param="query|g.sql|MyOrders" />

View Returned Values: 
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'MyOrders', l.all_settings)" />
Index

Random_Numbers

Generates a non repeating sequence of "size" randomly generated numbers between 1 and limit.

<mvt:item name="ry_toolbelt" param="random_numbers|return_array|size_exprsn|limit_exprsn" />

Example: <mvt:item name="ry_toolbelt" param="random_numbers|shuffle_cards|52|52" />

Index

Reference

The item creates a reference from one variable to another, such that changes to one will be made to the other. One use would be to reference a data structures in l.all_settings:products so that it can be passed in a global variable or a form. It is much more efficient to make a reference to a structure than making a copy with the assign item. For example;  the l.all_settings data is not normally available to a page template called using the Screen item. The reference item elegantly gets around that limitation.

<mvt:item name="ry_toolbelt" param="reference|new_variable_name|old_variable_name" />

Example:
Create a reference to the products data structure then call a page template called CUSTOM
<mvt:item name="ry_toolbelt" param="reference|g.clone_products|l.all_settings:products" />
<mvt:item name="ry_toolbelt" param="screen|CUSTOM" />

Then in the screen CUSTOM, reverse the reference to restore the data.
<mvt:item name="ry_toolbelt" param="reference|l.all_settings:products|g.clone_products" />
Index

RememberMe

These two functions work together to allow customers to stay logged into your web site even after browsing to another site, or closing the browser. When they return to your site, they will be automatically logged in. If they logout, the settings are cleared.

  1. Add the save function and prompt to the four page templates shown below. Insert the function inside the form tags directly below the [Submit] button;
    • LOGN Customer Login
    • ORDL Order Customer Login
    • ACAD Customer Create
    • ACED Customer Edit
  2. Add the load function to the bottom of the HEAD Tag Content.
  3. The login cookie expires after 1 year of inactivity.
  4. These functions won't work if the customer has cookies disabled.
<mvt:item name="ry_toolbelt" param="rememberme|load" />
<mvt:item name="ry_toolbelt" param="rememberme|save" /> Remember me on this computer?
Index

Screen

Given a Screen code, displays the contents of any page template at any location inside another page. This allows you to create sub-screens that can be inserted (i.e. mini basket, featured products) inside another page. Optionally a variable name can be added and the screen returned in a global variable.

Note: Make sure any needed global variables are set prior to calling (e.g. g.product_code, g.category_code, etc.)

<mvt:item name="ry_toolbelt" param="screen|screen_code" />
<mvt:item name="ry_toolbelt" param="screen|screen_code_exprsn|g.variable" />

Example:
<mvt:item name="ry_toolbelt" param="screen|'MINI'" />
<mvt:item name="ry_toolbelt" param="screen|'INFO' $ g.pagenumber|g.results" />
Index

Search_Products

Product Items: Integration Guide.

Search_Products provides advanced product search options, paging links (e.g. Page: [1] 2 3 4 ), user selectable sorting and user selectable number of items to display per page. You can specify fields to search including custom fields and search specific categories. It returns the products found plus additional fields described below, allowing you to do more with less work. Use it on the Search Page template in conjunction with the Search Results Layout, or used to create alternate search page layouts as described in the integration guide.

This item returns the products found in the either the array l.all_settings:products for (MMUI stores) or l.all_settings:search_results:products for (CSSUI stores).

 Pagination and sorting settings are returned in l.all_settings:prod_page.

Additional Fields Returned: href, price_original, formatted_price, formatted_cost and quantity (in basket)

Parameters:
length: Required variable. Contains the number of items returned.
Maxitems: Required expression. This number sets the items displayed per page. Default value is 12. Assign  Maxitems = 'ALL' to display all records. You can set Maxitems as a fixed value or use the radio controls provided to make it user selectable.
SortBy: Contains one of the following keywords in the form of sortfield-direction. If omitted, the order set in Merchant is used.
id-desc = Newest Items
price-asc = Price LOW to high
price-desc = Price HIGH to low
name-asc = Name a-z
name-desc = Name z-a
code-asc = Code a-z
code-desc = Code a-z
default-asc = Default display order

Global Variables Used:
Product_Search:
Required expression. Contains each search term separated by a space.
Search Category:
Optional expression. Allows you to limit the search to certain categories. Contains the code for the category products you wish to search. HINT: You could create a drop down load of categories to make it user selectable, create alternate search pages for certain categories, or integrate the search feature directly into a category page template.
g.PageNum: Is used in the pagination and sorting features.
g.SortBy:
Optional expression. A default sorting value can be set before calling the item as show below.
g.Sortby_Options: Optional expression. Lets you set a string before calling the item, to change the sort option values to use in the dropdown box.
This is a colon plus comma separated list formatted as keyword:prompt,keyword:prompt etc.
The default options are shown in the integration guide below. Edit as desired.

Integration:  Step 1. Paste this section directly above the closing tag  of the head section</head>

<!-- Style the pagination section. -->
<style type="text/css">
.paging { text-align: right; }
.paging .count { float: left; margin: 4px 24px 0 0; }
.paging .max { float:left; }
.paging .sort{ }
.paging .page{ float: left; margin-right: 48px;}
.paging .pages { float: left; }
.paging a.current { font-weight: bold; font-size; 13px; }
</style>

<!-- Optional: Limit the search to a specific category. -->
<mvt:if expr="ISNULL g.Search_Category">
  <mvt:item name="ry_toolbelt" param="assign|g.Search_Category|'enter a category code to search'" />
</mvt:if>

<!-- Optional: Set the maximum items to display -->
<mvt:if expr="ISNULL g.Maxitems">
  <mvt:item name="ry_toolbelt" param="assign|g.Maxitems|8" />
</mvt:if>

<!-- Optional: Set the Maximum items radio button options -->
<mvt:item name="ry_toolbelt" param="assign|g.maxradio:min|8" />
<mvt:item name="ry_toolbelt" param="assign|g.maxradio:max|24" />

<!-- Optional: Set a default sort value -->
<mvt:if expr="ISNULL g.SortBy">
  <mvt:item name="ry_toolbelt" param="assign|g.SortBy|'price-desc'" />
</mvt:if>

<!-- Optional: Set the options displayed in the sort list. Delete or Edit as desired. -->
<mvt:item name="ry_toolbelt" param="assign|g.Sortby_Options|
'id-desc:Newest Items,price-asc:Price LOW to high,price-desc:Price HIGH to low,' $
'name-asc:Name a-z,name-desc:Name z-a,code-asc:Code a-z,code-desc:Code a-z,'" />

<mvt:item name="ry_toolbelt" param="Search_Products|g.length|g.Maxitems|g.Sortby" />

Integration:  Step 2. Locate the search <form> and find the "search" text field. <input type="text" name="Search"... /> change name="Search" to name="Product_Search".
If you have other search forms on your screen (e.g the global header or category tree), change them as well.

Integration:  Step 3.  In the template search for the closing </h1> tag. Paste this section directly after the tag and any closing </mvt:if> that may be found with it.

<mvt:if expr="l.settings:prod_page:records GT 0">
    <div class="paging">
        <div class="count">PRODUCTS: <b>&mvt:prod_page:records;</b></div>
        <mvt:if expr="l.settings:prod_page:records GT 1">
            <div class="max">Show: &mvt:prod_page:maxradio;</div>
        </mvt:if>
        <mvt:if expr="l.settings:prod_page:records GT 1">
            <div class="sort">Sort By: &mvt:prod_page:sortselect; </div>
        </mvt:if>
        <mvt:if expr="l.settings:prod_page:count GT 1">
            <div class="page">Page: <b>&mvt:prod_page:current;</b> of &mvt:prod_page:count;</div>
            <div class="pages">Pages: &mvt:prod_page:links;</div>
        </mvt:if>
        <br style="clear: left">
    </div>
</mvt:if>

Integration:  Step 4. Click the Search Results Layout tab. You will have to update the product links on this template to &mvte:product:href; Example: <a href="&mvte:product:href;"> Also find the part of the script that displays the Previous and Next buttons. Delete it and paste this in its place.

<mvt:if expr="l.settings:prod_page:records GT 0">
    <div class="paging">
        <mvt:if expr="l.settings:prod_page:count GT 1">
            <div class="page">Page: <b>&mvt:prod_page:current;</b> of &mvt:prod_page:count;</div>
            <div class="pages">Pages: &mvt:prod_page:links;</div>
        </mvt:if>
        <br style="clear: left">
    </div>
</mvt:if>

View Returned Values: To temporarily view the pages data paste this directly above the closing </body> tag.

<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products', l.all_settings)" />
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'prod_page', l.all_settings)" />
Index

SearchArray

Binary search a simple sorted array; returns the index if found or 0. Results are so fast that timing is meaningless.

<mvt:item name="ry_toolbelt" param="searcharray|g.found_index|array_variable|search_exprsn" />
Index

SearchText

When given a delimited text file data, this item searches for a string and returns the text record (the entire line of text) containing the search string.

Parameters:
return_record: Required variable. The line of text returned if a match is found. If not found return_record is null.
filedata: Required search data: This is the delimited text data that will be searched.
search: Required search text: this is what we will be searching for.
fieldnumber: Required. The field number that will be searched where field is defined as each column of text. If fieldnumber is 0, all fields are searched.
sepchar: Required. The character that separates each record. Common values could be a line feed, pipe, comma or tab
( e.g. asciichar(10), asciichar(124), ',' or asciichar(9) ) but can be any character.

Note: Leading and trailing spaces in the search string and the searched field are ignored.

Usage:
<mvt:item name="ry_toolbelt" param="searchtext|return_record|filedata|search|fieldnumber|sepchar/" />

Example: Load a tab separated text file, and search field 1, to get shipping rates.
<mvt:item name="ry_toolbelt" param="assign|g.size|file_read('/mm5/ShippingRates.txt', 'script', g.filedata)" />
<mvt:if expr="g.size">
  <mvt:item name="ry_toolbelt" param="searchtext|g.return|g.filedata|'FL'|1|asciichar(10)" />
  <mvt:if expr="g.return">
    <mvt:item name="ry_toolbelt" param="assign|g.USPS:standard|trim(gettoken(g.return,asciichar(9),2))" />
    <mvt:item name="ry_toolbelt" param="assign|g.USPS:firstclass|trim(gettoken(g.return,asciichar(9),3))" />
    <mvt:item name="ry_toolbelt" param="assign|g.USPS:priority|trim(gettoken(g.return,asciichar(9),4))" />
  </mvt:if>
</mvt:if>
Index

SendEmail

Sends a text or html email; where g.mail can be any variable name with values assigned as shown below and html or text designates the type of email to send.

<mvt:item name="ry_toolbelt" param="sendemail|g.mail|html" />
 
<mvt:item name="ry_toolbelt" param="sendemail|g.mail|text" />
 
Example:
<mvt:item name="ry_toolbelt" param="assign|g.mail:to|'to_address@domain.com'" />
 
<mvt:item name="ry_toolbelt" param="assign|g.mail:from|'from_address@domain.com'" />
<mvt:item name="ry_toolbelt" param="assign|g.mail:cc|'cc_address@domain.com'" />
<mvt:item name="ry_toolbelt" param="assign|g.mail:subject|'This is an email test'" />
 
<mvt:item name="ry_toolbelt" param="assign|g.mail:message|'This is the message'" />
<mvt:item name="ry_toolbelt" param="sendemail|g.mail|text" />
<mvt:item name="ry_toolbelt" param="assign|g.mail:message|'This is the <b>HTML</b> message'" />
 
<mvt:item name="ry_toolbelt" param="sendemail|g.mail|html" />
Index

SeoLinks

These two items, SeoLinks & SeoLink, provide the simplest way possible to convert your site to short SEO links configured under Domain | SEO Settings. A page template SEOLINKS_Demo.txt is provided in the zip file to fully illustrate this item in action. A major benefit is that if you change your SEO settings later or even change your domain name, all your links are instantly updated and you won't have to revise your site.

SeoLinks: Use this item anywhere in the HEAD Tag Content/CSS section to globally load all of the store links into the data structure call l.all_settings:href.

Parameters:   
Category_code:
Required expression. Contains the code for the category.
Product_code: Required expression. Contains the code for the product.

Usage: Add to the head tag.
<mvt:item name="ry_toolbelt" param="seolinks" />

Example 1: Store links
<a href="&mvt:href:storefront; ">Storefront</a> |
<a href="&mvt:href:product_list; ">Product list</a> |
<a href="&mvt:href:search; ">Search</a> |
<a href="&mvt:href:sitemap; ">Sitemap</a> <br>

<a href="&mvt:href:customer_login; ">Customer login</a> |
<a href="&mvt:href:customer_account; ">Customer account</a> |
<a href="&mvt:href:order_history_login; ">Order History Login</a> |
<a href="&mvt:href:affiliate_account; ">Affiliate account</a> |
<a href="&mvt:href:affiliate_login; ">Affiliate login</a> <br>
<br>
<a href="&mvt:href:basket; ">Basket</a> |
<a href="&mvt:href:checkout; ">Checkout</a> |
<a href="&mvt:href:checkout_noaccount; ">Checkout without an Account</a><br>

Example 2: Canonical links can be added to the head tag so duplicate content is be ignored by Google.
<mvt:if expr="g.screen EQ 'PROD'">
  <mvt:if expr="g.Category_Code">
    <link rel="canonical" href="&mvt:href:category_product;" />
  <mvt:else>
    <link rel="canonical" href="&mvt:href:product;" />
    </mvt:if>
</mvt:if>

<mvt:elseif expr="g.screen EQ 'CTGY'">
    <link rel="canonical" href="&mvt:href:category;" />
</mvt:if>

Add to the SFNT template <head> section
<link rel="canonical" href="&mvt:href:storefront;" />
Index

SeoLink

 Use the Seolink item for category and product links everywhere in your store. It comes in three formats. Each item is optimized for placement inside the foreach loops. Internally each item stores a formatted template for the link the first time its called. On subsequent links it simply replaces part of the template with the correct code. The templates can be displayed using &mvt:href::template_cat; , &mvt:href::template_prod; , and &mvt:href::template_catprod;

Usage:
<mvt:item name="ry_toolbelt" param="seolink|category|g.Category_code" />
<mvt:item name="ry_toolbelt" param="seolink|product|g.Product_Code" />
<mvt:item name="ry_toolbelt" param="seolink|category_product|g.Category_code|g.Product_Code" />

Example 3: Category Tree
<mvt:foreach iterator="cattree_category" array="categories">
    <mvt:item name="ry_toolbelt" param="seolink|category|l.all_settings:cattree_category:code" />
    Locate every <a> tag in the foreach loop and replace it with this.
    <a href="&mvt:href:category;">

Example 4: Category Product List Layout.
<mvt:foreach iterator="product" array="products">
    <mvt:item name="ry_toolbelt" param="seolink|category_product|g.category_code|l.all_settings:product:code" />
    Locate every <a> tag in the foreach loop and replace it with this.
    <a href="&mvt:href:category_product;">

Example 5: Product List Layout
<mvt:foreach iterator="product" array="products">
    <mvt:item name="ry_toolbelt" param="seolink|product|l.all_settings:product:code" />
    Locate every <a> tag in the foreach loop and replace it with this.
    <a href="&mvt:href:product;">

Example 6: Basket Contents
<mvt:foreach iterator="item" array="basket:items">
    <mvt:item name="ry_toolbelt" param="seolink|product|l.all_settings:item:code" />
    Locate every <a> tag in the foreach loop and replace it with this.
    <a href="&mvt:href:product;">

View Returned Values:
<mvt:item name="ry_toolbelt" param="eval|varlist('l', 'href', l.all_settings)" />
Index

SortArray

Sorts an single dimension array blazingly fast.

<mvt:item name="ry_toolbelt" param="sortarray|array_variable" />
Index

SortCSV

Given a list of comma separated values, returns a sorted copy.

<mvt:item name="ry_toolbelt" param="sortcsv|g.sorted_variable|g.unsorted_variable" />

Example:

<mvt:item name="ry_toolbelt" param="assign|g.top5|'Rihanna,Perry,Beyonce,Spears,Rudolf'" /> <br>
<mvt:item name="ry_toolbelt" param="sortcsv|g.sorted|g.top5" />

<br>&mvt:global:sorted;<br>
Index

StripHTML

Returns a copy of a string with all html stripped out. See the function striphtml()

<mvt:item name="ry_toolbelt" param="striphtml|g.stripped|g.string_exprsn" />

Example:
<mvt:item name="ry_toolbelt" param="striphtml|g.text_only|l.all_settings:product:descrip" />
Index

Structure

Structure reveals the internal structure of any SQL database table for inspection. Table names are case sensitive and for security, are limited to the store tables.

<mvt:item name="ry_datafeed" param="structure|g.table_exprsn|returnarray" />

Example: <mvt:item name="ry_toolbelt" param="structure|'Products'|ProdStruct" />


<b>Products Table Structure</b>
<table border="0">
<tr><th>Name</th><th>Type</th><th>Decimals</th><th>Length</th></tr>

<mvt:foreach iterator="struct" array="ProdStruct">
<tr>
<td>&mvt:struct:field_name; </td>
<td>&mvt:struct:field_type; </td>
<td>&mvt:struct:field_dec; </td>

<td>&mvt:struct:field_len; </td>
</tr>
</mvt:foreach>
</table>
Index

Trace

The Trace debugging item outputs red text directly into you web page so you can visually see which toolbelt commands are being executed. Add trace to the top of your page template.

Two keywords control the output:
TOOL: Shows when an item is called. e.g. tool: assign.
PARAM: Shows the entire toolbelt command e.g. params: assign|g.sep|' ' $ asciichar(38) $ 'raquo; '.

If you want to trace a small section of code, you can turn trace off by omitting a keyword.

Usage: Add anywhere within a page to start Trace.
<mvt:item name="ry_toolbelt" param="Trace|TOOL" />
<mvt:item name="ry_toolbelt" param="Trace|PARAM" />

Stop Trace:
<mvt:item name="ry_toolbelt" param="Trace|" />
Index

Varlist

Like a popular free helper module, this item returns a sorted list of global, system or local variable names, entity expressions, and values.
Two version are provided, the Varlist() function and the depreciated Varlist item.

HINT #1: Comment out the item without removing it. Change eval to #eval.
HINT #2: Use your IP address so that only you see the output. Your IP address is 98.231.106.220
HINT #3: Add a filter to the function so you can limit it's output.

Parameters:   
variable_type:
Required string literal. Indicates what type of variables to return. Use 'g' for global, 'l' for l.all_settings, 's' for system
filter: Optional string literal. Contains name of the array or structure you wish to view. e.g. 'products_viewed'.
l.all_settings: Required constant. l.all_settings must be passed to the function.

<mvt:item name="ry_toolbelt" param="#eval|varlist(variable_type, filter, l.all_settings)" />

Example 1: Only allow you to see ALL variables
<mvt:if expr="s.Remote_Addr EQ '98.231.106.220'">
    <mvt:item name="ry_toolbelt" param="eval|varlist('l', 'products', l.all_settings)" />
    <mvt:item name="ry_toolbelt" param="eval|varlist('g', '', l.all_settings)" />
    <mvt:item name="ry_toolbelt" param="eval|varlist('s', '', l.all_settings)" />
</mvt:if>

Example 2: Capture the state of a variable or array and display it later.
<mvt:item name="ry_toolbelt" param="assign|g.storelist|varlist('l', 'store', l.all_settings)" />

&mvt:global:storelist;

Example 3: Depreciated Varlist item.
<mvt:item name="ry_toolbelt" param="varlist|local" />
<mvt:item name="ry_toolbelt" param="varlist|global" />
<mvt:item name="ry_toolbelt" param="varlist|system" />