Miva Merchant API Functions and How To Use Them

Miva Merchant is an eCMS - an eCommerce Content Management System. 

It's more than just a way to put a store on your site, it's a powerful site manager all on it's own, and one of the things that makes it so powerful is how much programming and scripting you can do right in the store pages combing Store Morph scripting, Miva Template Language, and Miva Script.

However, there are some common areas of confusion that can be frustrating (I know from experience!) so hopefully I can clear that up for you here with two examples.

Just a note: I'm going to explain things in depth, so experienced uses may find some of the information redundant.

Documentation and Reference Material

Available API functions for Miva Merchant store pages (and module development)

Miva Template Language reference with examples

Database Reference: let's you know what information you have available to you

Miva Script reference docs by Ray Yates (very nice- I use this all the time.)

Example 1: Getting information for any product

Let's say you have a sidebar or footer that you want to display a featured product on that you change on a regular basis. You don't want to enter a bunch of new information each time you do this, so instead make it so all you have to do is change the product code.

The function to load product info from it's code is product_load_code(code, product var)

product_load_code = name of function

code = the product code

product var = the variable the product info will go into

Point of confusion: product var is a reference variable. The var part let's us know that the product data is passed by reference (the function does not return the product data) which means it is assigned it to the var variable. When you call the function, you do not include the var part:

product_load_code(l.product_code, l.product)

In the line above, l.product_code would be some product code and l.product would be assigned the product data.

If you want to access this data using page entities such as &mvte:product:name; you must load the data into the settings structure. So instead of l.product you load it into l.settings:product.

Load product information for a product with the code prod123 in a store page like this:

<mvt:do file="g.Module_Library_DB" name="l.success" value="Product_Load_Code('prod123', l.settings:product)" />

The function returns l.success which will be 1 if the product information was loaded successfully.

l.settings:product will contain the product information which can be accessed using Store Morph page entities:

Product Name: &mvte:product:name;


Product Code: &mvte:product:code;


Formatted price: &mvte:product:formatted_price;

For things like names, codes, and descriptions we use &mvte instead of &mvt because it's safer, as in, javascript and other possibly dangerous code will be displayed without any damaging effects. 

The same information can also be accessed and displayed using built in template language functions:

 Product Name: <mvt:eval expr="encodeentities(l.settings:product:name)" />
Product Code: <mvt:eval expr="encodeentities(l.settings:product:code)" />
Formatted price: <mvt:eval expr="encodeentities(l.settings:formatted_price)" />

Examine your store pages and use the database reference link above to see what other information is available when you load a product. In this example, I would be pouring over the PROD page template because certain bits of data are not part of the "basic" product data, such as l.settings:formatted_price - you will only learn about this and certain other data fields by examining the relevant store pages.

Displaying product info for prod123 is as easy as:

<mvt:do file="g.Module_Library_DB" name="l.success" value="Product_Load_Code('prod123', l.settings:product)" />
<p>
    Product Name: &mvte:product:name;
</p>
<p>
    Product Code: &mvte:product:code;
</p>
<p>
    Formatted price: &mvte:product:formatted_price;
</p>

If I want to change the product, all I have to do is change the product code in the function call.

Example 2: Loading an array of all categories

An array is a group of things that share the same properties. In a nutshell, it's like a group of people. Everyone in the group is a person, but each person probably has a different birthday. 

In this case we're going to load all the categories in the store into an array and then display them in a list. All the categories share the same properties, it's just the details that are different.

The function to load the categories into an array is CategoryList_Load_All(categories var)

Just like the product var in the product_load_code(..) function, categories var let's you know this is a reference variable. In this case, all the categories will be loaded into it as an array.

CategoryList_Load_All(l.settings:categories)

You must load the categories into the l.settings structure if you want to roll through it using the store template language. If you don't, you can't easily access the array on the store page.

<mvt:do file="g.Module_Library_DB" name="l.success" value="CategoryList_Load_All(l.settings:categories)" />

Once you have your categories in an array, you can use the mvt:foreach template language function to roll through them:

<mvt:do file="g.Module_Library_DB" name="l.success" value="CategoryList_Load_All(l.settings:categories)" />
<ul>
<mvt:foreach iterator="category" array="categories">
    <li>
        Category: &mvte:category:name; (&mvte:category:code;)
    </li>
</mvt:foreach>
</ul>

In the mvt:foreach function the iterator is basically the variable that you use to access the information for the category currently in the "loop". In this case I named it category because it makes sense; each item in the array is a category. The array is the list of categories that you loaded in the CategoryList_Load_All function.

Like the product information, you could also display the category information using template functions:

<mvt:do file="g.Module_Library_DB" name="l.success" value="CategoryList_Load_All(l.settings:categories)" />
<ul>
<mvt:foreach iterator="category" array="categories">
    <li>
        Category: <mvt:eval expr="'Category: ' $ l.settings:category:name $ ' (' $ l.settings:category:code $ ')'" />
    </li>
</mvt:foreach>
</ul>

Explanation of displaying more complex strings:

In the example above I've joined several strings, text and variables, together using the $ symbol.

In the template language you can create and display complex strings this way. The one important bit to remember is:

All constants - words and characters - must have single quotes around them. This includes spaces.

Let's say you want to display the current time like this:

[Current time: 13:30]

Your variables for the time are s.dyn_tm_hour and s.dyn_tm_min and your constants are Current time and a space, brackets, and a : symbol between the hour and minute. Variables starting with s are system variables. You can see a full list of system variables in the Miva Script reference docs that Ray Yates put together.

The way to put this together for display is:

'[Current time: ' $ s.dyn_tm_hour $ ':' $ s.dyn_tm_min $ ']'

Evaluate it like this:

<mvt:eval expr="'[Current time: ' $ s.dyn_tm_hour $ ':' $ s.dyn_tm_min $ ']'" />

What about if the minute is less than 10 and you want to put a zero in front of it? We can use a built in Miva Script function to do that:

padl( string, length, character )

What this function does is add a characters to the left side of a string to make the string a certain length. In this case, we just want to add a 0 in case the minutes are less than ten, so we tell it to make it length 2 and use the 0 character to do that:

<mvt:eval expr="'[Current time: ' $ s.dyn_tm_hour $ ':' $ padl(s.dyn_tm_min,2,'0') $ ']'" />

Notice how the '0' has single quotes around it? This is how Miva Script deals with displaying constants, same as the template language. Now if the minutes were 5, instead of displaying 12:5 it will display 12:05.

Summary:

• Load variables and arrays into l.settings:some_variable_name so you can access them using page entities like &mvte:some_variable_name;  as well as making it so mvt:foreach loops can access array (list) data.
• Examine the reference documents linked at the top of this page to figure out what functions you can use, how to manipulate the data, and what data will be available.
• Examine relevant pages in your store for more information on "extra" data that is loaded behind the scenes by modules and helper functions that are sometimes difficult to track down otherwise. Also examine pages to see how data is displayed to learn more.

Related Articles

These articles might be interesting for you as well: