24/7 Support: 800.608.6482


Developer Videos

Videos | Miva Merchant Module API – Working With Features

ver. 9.0 and later

Video Transcript

Let's jump right in and talk about the Miva Merchant Module API. Module API is what allows you to build custom modules or apps for Miva Merchant. Now, what is the module API? A module itself is really just a compiled MivaScript file. However, in order for it to be used within Miva Merchant, it needs to contain certain functions that Miva's looking for. These functions are grouped into what Miva calls Features. So a Miva Merchant Module is simply a compiled MivaScript file that implements one or more different features. Now these features will depend on what you're trying to do. If you want to execute your own code when an order is placed, you can implement the order fulfillment feature. Now there are hundreds of different features that you can implement with Miva Merchant. A module can implement one feature or it can implement many features. Each feature consist of a series of functions that must be present in your module in order for it to work in Miva Merchant. Now these functions will vary depending on what you implement. Some features may only have two or three other functions. Other features may have six or more functions that must be implemented. 

Say for example, you implement a feature and you don't have all the functions. When you try to install the module in Miva Merchant, you will get an install error. When you try to use the module in Miva Merchant, you will get a runtime error. Miva Merchant is very event based or action based. When an action occurs, Miva calls into your Module to execute specific functions it is looking for. This is how your module is able to tie into Miva Merchants existing functionality and add new functionality or overwrite existing functionality. It's all based off this concept of features. Let's take a look at Miva's online documentation to see what features are available and what functions are required for each feature. 

Here I am on the Miva.com web site. You can get to the online documentation by going here. Now I'm going to click on the Module tab and I'm going to scroll down a little bit and you'll see this "Module API." This Module API will give you a list of all the features that are part of Miva Merchant. You'll see there's quite a few of them and we'll keep adding more and more all the time. These features are essentially hooks that are tied into Miva and allow you to execute your own functions based off Miva Merchant events. Let's drill in to one. 

We talked earlier about the Order Fulfillment Feature. This feature can be found here, Feature Fulfilled. If I click on this, it will drill down to this feature and it will show me all the functions that are required in my module in order for this feature to work. Now, this features actually simple. It only has a simple function. Functions called FulfillmentModule_ProcessOrder. It takes in two parameters. Say for example I wanted to build a module that when an order is placed, it makes a call to a third party system and passes order data, customer data, some data about the transaction to some third party service. This is the feature you need to implement. It's a single function and when an order is placed, it will call in all the modules to implement this feature and it will look for this FulfillmentModule_ProcessOrder and it will execute that code within that function. Let me go back and let's look at another example. 

Here is Feature component. This is another popular feature within Miva Merchant. Now you notice, this feature has quite a few functions that need to be implemented in order for this feature to work correctly. Now the component feature is one of the core features in Miva Merchant. Miva Merchant's Template Language is paged based. It's a series of pages that make up the core templates of Miva Merchant. Now the functionality of each page is dependent on items that are assigned to a page. So the functionality of the storefront page will be vastly different than that of the product page because the items that are assigned to the page are different. Now, there's a bunch of built in items that are all part of Miva Merchant itself. However, as a module developer you have the ability to implement the component feature, which allows you to create your own items that get executed when a page initializes or runs. That's why you see here you have componentmodule_initialized, your own items that get executed when a page initializes or runs. That's why you see here you have componentmodule_assigned. So these are functions that Miva will call when these actions occur. When the item gets assigned to the page or unassigned, or when the page render starts or ends. 

I want to show you one other resource that you should be using to help you as a reference guide when figuring out what features are available and the functions that must be implemented as part of those features. That's the Miva Merchant Module API Reference Guide. So here, if I jump down to chapter 3, the Module API, it talks about this Module Description Function. Now this Module Description Function is a function that must be included in every single module. This is actually a good way to find what features your module implements. If I scroll down here this is what it looks like. So the function is always called Module_Description and you define a module code and name, provider version, the API version, and this last one here is features. This features is a comma separated list of all the features this module implements. So this module implements the batchreport feature. Miva will look for this function for every single module and it will look for the feature your module implements and then go look for the functions that need to be within your module for that feature to work correctly. You can also use the search up here to look for certain features and what functions need to be included. So if I look for fulfill, it actually takes me to a description of what this feature does and then what functions are contained within that feature. I scroll down a little bit more and it gives me some more details about the functions themselves. So the function fulfillment module which will process an order, when Miva Merchant calls this function, the syntax, the parameters that are passed into it and its returned value. 1 on success, 0 on error. So this is a great resource to use when determining what functions need to be included to implement which features and also details about the functions themselves. The last thing I would say is leverage the LSK, the Limited Source Kit, as much as possible. There's a bunch of great resources and example modules contained within the LSK that already implement features. You can use that source code, strip out what you don't need, and use that as a starting point for your module. 

Let's take a look at the LSK. Here I downloaded the LSK and I'm going to go into modules and then you'll see this list of folders match the feature names that are part of Miva Merchant. So if I want to go to System, which is a System Extension Module, you'll see there's a file here that's an example system extension module. So once I have the file open, let's take a look at some of these functions. Like I said earlier, this module description function is required for every single module. So here we determine the code, then the code, provider version, API version, and then features. So this module implements two features, "system, vis_system." That "vis" stands for "visible" system extension, which means that it actually provides an interface that the customers see in the admin. When they click on System Extension Settings. Implementing vis_system allows this module to have a tab that's available in the Admin that the customer can see. 

Now you can see the different functions that are required in order to implement these two features. So here's all the features for the system extension feature as well as for the vis_system. So leveraging LSK is a great way to get sample code that will give you a great starting point for your modules. 

Now I want to show you one last thing. So here I am back in the Miva Merchant Admin. On the left hand menu I'm going to go to Modules. Now this will show you a list of all the modules that are currently installed within Miva Merchant. Now, Miva Merchant comes with a lot of build in modules that are just part of the core software. There's also third party modules. Now you can tell which ones are built in and which ones are third party by adding the provider to this list. So you see, these are all Miva Merchant build in modules. You can also quickly see at a glance what features each module implements. So most of these modules implement more than one feature. However, this is a great way to see what each module does and what features it implements. Using the tools in this video, you should be able to determine what features your module needs based on the functionality you're trying to accomplish. Then find what modules are required and implement those features. The Miva Merchant Module API is extremely powerful and gives you the Developer almost unlimited control and flexibility to create any features and functionality you need. 

Looking for Developer Docs?

We have a whole section for that, including: Developer Training Series, Template Language docs, Module Development tutorials and much, much more.

Head to the Developer Section

This website uses cookies to identify visitors, track visitors to our website, store login session information and to remember your user preferences. By continuing to use this site you agree to our use of cookies. Learn More.

This website uses cookies. By continuing to use this site you agree to our use of cookies. Learn More.


Copyright © 1997 – 2024 Miva®, Miva Merchant®, MivaPay®, MivaCon®, Camp Miva®, Miva Connect®, Miva, Inc. All Rights Reserved.