Today we’re going to talk about how to use the built-in Miva Empressa Functions that are a part of every Miva Merchant store. This graphic is from one of the earlier videos when we talked about the architect of Miva Merchant. If you remember, one of the core components of Miva Merchant is the engine, called Empressa, that’s installed on the web server. Empressa is what allows Miva Merchant to run. It is also what parses the Template Language and compiles it into the underlying Miva Merchant Script Language.
Miva Merchant itself is written in a scripting language called, “Miva Script.” This is then run through the compiler and outputted in an executable format that the engine can then run. While you can’t execute raw Miva Script tags within the Miva Merchant template language, you have access to all the built-in functions of Empressa.
There’s a great web site at www.mivascript.com which documents the entire Miva Script programming language as well as all the built-in functions of the engine. Let’s take a look.
So Miva Script is a language you would use if you wanted to write a module or a plugin for Miva Merchant. There’s an entire video series dedicated to learning how to do that if you’re interested. However, for now we want to take a look at the built-in functions that are a part of Miva Merchant Empressa that you can access within the Miva Merchant Template Language. Here, if I click on Function Index, it will give me a list of over 100 functions that are all native to the engine. One of the powerful parts about the Miva Merchant Template Language is that we have access to every single one of these functions and can execute them within the Miva Merchant Templates. These functions include a lot of core programming functionality that you’d expect from a programming language. Such things like file_read_write, time, working with arrays, length, substring, it’s really a great toolset available at your fingertips.
Let’s take a look at a few of the common ones that you may use on a day to day basis. The first one I want to look at is called “gettoken.” So gettoken has three parameters; it takes in a string, it has characters, and the third parameter is a position_num we want to return. So what this function does is it takes a common delimited list, you tell it what the delimiter is, and you tell it what position or substring you want to return based on delimiters. Let’s take a look at a real example:
So here I’m using mvt:assign to create a variable called g.list. That variable is a string and it contains four values: apples, oranges, bananas and grapes and it’s a comma separated list. So using gettoken, I can split this list up into different tokens which is basically the substring that each delimiter separates.
So here, I have g.first, and to use a built-in engine function - there’s nothing special that you have to do. You just call the function within the value. Because the value of the mvt:assign or mvt:eval is always being evaluated, it just works and there’s nothing special you need to do. So “gettoken” and my delimited list is g.list, which is the value or variable I created up here, and here, my delimiter is a comma. So I put the comma in single quotes, so it’s not confused with the actual parameters we’re passing in. Then the third parameter is a position or substring that I want to return. So, #1 refers to apples, #2 would refer to oranges, #3 bananas and $4 would be grapes. So if I upload this to the page we should expect g.first to contain apples. Let’s run it and see what happens.
So here I’m back in the Miva Merchant Admin and I’m going to go to the SFNT page and to the Content section. So here I’m just going to paste in the same code we’ve been working with and hit “Save.” Now we’ll go back to the Storefront and hit “Refresh.” You’ll now see that it outputs “apples,” exactly what we’d expect. So now to test the other values, if I change this 1 to 2 and hit “Update,” it should go back to the next value “oranges.” So this is a great way to be able to target a specific index within a delimited list.
The next function I’m going to look at is called “glosub” or “global substitution.” Glosub is a find and replace function and it’s very powerful. So looking at the docs on Miva.com, the function takes in a string as the first parameter, the second parameter is what you want to find, and the third is what you want to replace and these are all strings. You can also pass in variables for for each parameter vs. hard coding each string. Let’s take a look at an example. So here I have a string called g.string and the value is Miva Merchant vs. 9 is the current version of Miva Merchant. I’m now creating a new variable g.new_string and here I’m using glosub, so global substitution. I’m passing in g.string I want to find and replace against and I’m finding the word Miva Merchant and replacing it with the word, just Miva and then I’m outputting the string to the page. So let’s execute this and then hit refresh on the storefront, and you’ll see here Miva Merchant 9 is now just Miva Version 9 is the current version of Miva. So it went through and found every instance of Miva Merchant and replaced it with the word “Miva.” Also, this is case sensitive. So if Miva Merchant wasn’t capitalized it wouldn’t have picked that up, so just something to be aware of.
The next built-in function I want to take a look at is substring. Substring is similar to every other substring you’ve ever worked with. You take a string, which i have here, the same string we were working with previously and you give it a position or a starting point, and then the length, which is the number of characters until it ends. So here, this is going to be the string value. We’re going to pass in our string from above called g.string and then for position, position is the starting point. Strings in Miva always have a starting index of 1. So one stands for the very first character of the string. So here, let’s stee if we can strip out Miva Merchant from the beginning of this string. So there’s 14 characters here, including both the spaces. So we want the starting position to be 14, and this should start us right here at Version 9. For the length we could count the number of characters in the string, but that’s not an ideal way to do it. Instead we want to use another built-in function called “length” to calculate the entire length of the string. So the way we do that is len which is the length function, and then pass it in g.string and so this will return the total number of characters in that string. So here we have the substring of the string starting at character 14 through the length of the string. So let’s run this and see what happens. Once I refresh here I have Version 9 is the current version of Miva Merchant. That’s exactly what we expected. So it cut out that first Miva Merchant in our string. So I just showed you four common functions built-into the Miva Merchant Empressa engine, there are actually over 100 that you can use and play around with. There’s great documentation on Mivascript.com. I would definitely recommend doing some experimenting to see what each one does and how to use it within the Miva Merchant Template Language.