Miva Merchant SMT / Storemorph Basics

When you want to add new code to your Miva Merchant page templates sometimes there's a learning curve, or more of a learning bump because when you get over it the rest is smooth sailing.

Resources:

1. Miva Merchant API Functions and How to Use Them

This post on Scot's Scripts explains in detail how to use Miva Merchant API Functions.

2. Miva Merchant Template API Functions

These are all functions you can use in your page templates (and your modules if you are developer.)

3. Official Miva documentation

Store Morph Template (SMT) coding reference. Reference this as go through this post.

mvt:assign 

This is used to assign a variable a value. Let's assign the value "Scot" to the variable l.settings:my_name using the code below.

<mvt:assign name="l.settings:my_name" value="'Scot'" />

l.settings: 

To use page items like &mvt:my_name; to display data you must assign the data to a variable name that starts with l.settings otherwise you will need to use  themvt:eval function (see below) to display the data.

Module Development Note: If you are writing a module and want to assign values to l.settings from the Component module API functions, you need to assign them to l.all_settings because l.all_settings gets copied to l.settings via internal Miva Merchant processes.

The example above is the most basic use of mvt:assign. What if we want to display the date where we are going to connect some internal system variable data with strings?

The system variable for the day of the week is s.stm_wday and for the month is s.stm_mon

Let's assign a variable called l.settings:hello_customer using mvt:assign and the date variables above.

<mvt:assign name="l.settings:hello_customer" value="'Hello Customer, today is ' $ s.stm_wday $ ', day ' $ s.tm_mday $ ' of ' $ s.stm_mon" />

Then we can display it anywhere below on the page like:

&mvt:hello_customer;

This would output something like: 

Hello Customer, today is Sun, day 13 of Oct

You probably noticed the $ symbols in the "value" section of the code above. In template coding and miva script coding we must distinguish between variables and strings. Strings are anything that is not a variable or a function, strings are words and symbols, such as "Hello Customer, today is" in the example above.

The basic rule is strings are surround by single quotes, and all variables and strings are separated by $ symbols.

mvt:eval 

This is used to evaluate, or output, data.

It's used in a very similar manner to mvt:assign , however instead of assigning data to a variable, you are displaying it directly on the page.

Using the variable in the example above, l.settings:hello_customer, we can display the contents of the variable like so:

<mvt:eval expr="l.settings:hello_customer" />

The output from this is identical to &mvt:hello_customer;.

We can also use mvt:eval for more complex output. Using the example above, we can mvt:eval the "hello customer" string instead of assigning it to a variable.

<mvt:eval expr="'Hello Customer, today is ' $ s.stm_wday $ ' day ' $ s.tm_mday $ ' of ' $ s.stm_mon" />

Evaluate Customer Name

If your customer is logged in and has their billing information set (for this example) you can say hello to them personally like this:

<mvt:eval expr="'Hello ' $ g.customer:bill_fname $ ' ' $ g.customer:bill_lname $ ', today is ' $ s.stm_wday $ ' day ' $ s.tm_mday $ ' of ' $ s.stm_mon" />

Remember: All literal strings, including spaces, must be enclosed with single quotes, and, we must use $ to connect (concatenate) them together.

Tip: You can also mvt:eval any of the mivascript functions. For example if you wanted to add zeros in front of a number so that there are always three digits in total (1 would turn into 001), you could use the padl(string, length, character) function like this:

<mvt:assign name="l.number" value="'1'" />
<mvt:eval expr="'This is your number: ' $ padl(l.number,3,'0')" />

This would output: 

This is your number: 001

mvt:do 

This is used to call functions that have been created in modules and mivascript files that run your store. The api function reference page lists all the functions available in stock Miva Merchant. This does not include functions in third party modules, although some third party modules might have their own api function reference (while others hide their functions.)

The mvt:do functions in the API function reference are ready to copy and paste into your templates, it's just the variable names that need changing to reflect the data you are using and loading. Here is one example to help understand how they are used. Let's look at the function that loads a product URI. The code below is copied straight from the function reference guide.

<mvt:do file="g.Module_Feature_URI_DB" name="l.success" value="URI_Load_Product_Canonical(product_id, canonical_uri var)" />

This function could be used to display a list of products manually with links. In this example, we will load product data from the product code, then load the URI into the product data.

Note: Notice the "var" after "canonical_uri" in the URI_Load_Product_Canonical function? This "var" denotes that it is a reference variable. This simply means that after the function is run, the canonical information will be stored in the reference variable rather than returned.

Some functions return their data into the "name" field (in this case the name field is "success" which will be a 1 or 0 based on if the canonical uri was found) and some load data into reference variables.

See the Miva Merchant API Functions and How to Use Them post for more details about reference variables.

Load Product Canonical URI Example

<mvt:assign name="l.product_code" value="'product_code_1'" />

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

<mvt:do file="g.Module_Feature_URI_DB" name="l.success" value="URI_Load_Product_Canonical(l.settings:product:id, l.settings:product:canonical_uri)" />

<mvt:if expr="l.success">
    The product URI is: <mvt:eval expr="l.settings:product:canonical_uri:uri" />
<mvt:else>
    Error: Problem loading URI for &mvt:product:name;.
</mvt:if>

In this example we arbitrarily set a product code, load the product data into l.settings:product, try to load the URI based on the product id, and if it loads we display it and if not we display an error message.

See below in the mvt:foreach section for an example of loading a list of products.

mvt:if 

This uses operators to test for conditions that we use to figure out what the next step is. Check the operators reference for a rundown of all available operators.

Operators: Operators make mvt:if work. Understanding how to use operators is required for miva scripting and template language and programming in general.

In this example we'll assign a variable an animal type and then check what kind of food it needs.

"IF" it's a cat, feed it cat food,

"ELSE" do not feed it cat food.

<mvt:assign name="l.animal_type" value="'cat'" />

<mvt:if expr="l.animal_type EQ 'cat'">
    Let's feed it cat food.
<mvt:else>
    Do not feed it cat food.
</mvt:if>

In this example we'll assign the variable again and use mvt:elseif to extend the condition tests.

"IF" it's a cat, feed it cat food,

"ELSE IF" it's a dog, feed it dog food,

"ELSE" do not feed it.

<mvt:assign name="l.animal_type" value="'cat'" />

<mvt:if expr="l.animal_type EQ 'cat'">
    Let's feed it cat food.
<mvt:elseif expr="l.animal_type EQ 'dog'">
    Let's feed it dog food.
<mvt:else>
    Do not feed it cat food or dog food.
</mvt:if>

These are basic examples, but conditionals are the life blood of coding in templates and anything else.

Did you see the EQ being used above? That's an operator. See the operator reference for a list of them all.

This is an example of using the AND operator with a more complex conditional situation where we use AND and NE

"IF" it's a calico cat feed it calico cat food,

"ELSE IF" it's a non-calico cat feed it non-calico cat food,

"ELSE IF" it's a dog, feed it dog food,

"ELSE" do not feed it.

<mvt:assign name="l.animal_type" value="'cat'" />

<mvt:assign name="l.cat_color" value="'calico'" />

<mvt:if expr="l.animal_type EQ 'cat' AND l.cat_color EQ 'calico'">
    Let's feed it cat food for calico cats.
<mvt:elseif expr="l.animal_type EQ 'cat' AND l.cat_color NE 'calico' ">
    Let's feed it cat food for not calico cats.
<mvt:elseif expr="l.animal_type EQ 'dog'">
    Let's feed it dog food.
<mvt:else>
    Do not feed it cat food or dog food.
</mvt:if>

mvt:foreach 

This is a way to process a list by looping through it. In coding a list is usually called an array. An array is nothing more than a bucket to hold a bunch of things that are the same, like products.

Let's use the mvt:do example from above where we loaded a canonical URI for a product based on the product code but do it for a list of product codes rather than just one.

In this case we'll assign a list of product codes to a variable, turn that into an array using miva_array_deserialize(...) and then loop through to show a product list with links.

<mvt:assign name="l.product_codes" value="'product_code_1,product_code_2,product_code_3,product_code_4'" />
<mvt:assign name="l.settings:_products" value="miva_array_deserialize(l.product_codes)" />

<mvt:foreach iterator="product" array="_products">
    <mvt:do file="g.Module_Library_DB" name="l.success" value="Product_Load_Code(l.product_code, l.settings:product)" />

    <mvt:do file="g.Module_Feature_URI_DB" name="l.success" value="URI_Load_Product_Canonical(l.settings:product:id, l.settings:product:canonical_uri)" />

    <mvt:if expr="l.success">
        <a href="&mvte:product:canonical_uri:uri;">&mvt:product:name;</a>
    <mvt:else>
        Error: Problem loading URI for &mvt:product:name;.
    </mvt:if>
</mvt:foreach>

miva_array_deserialize(...) : this is a built in mivascript function that turns a simple list of items that are separated by commas and into an array. Note that if there are commas in the item codes/names then you'd have to do it another way, probably one at a time with the function miva_array_insert(...)

Notice that instead of using mvt:eval for the product name and uri, we used page entities (&mvt:product:name;)

Conclusion

These are the most often used SMT tags in your Miva Merchant page templates and should help you get a grip on what's going on in that template code. Send us a message if you would like to see a tutorial on anything else.