Building a Module#

Modules in Miva Merchant consist of Miva Script files, templates, and configuration that extend the platform’s functionality. Under the hood, Miva Script tags resemble HTML tags and can be mixed freely with HTML or embedded JavaScript. Attributes specify values or expressions, and Miva Script provides built-in functions and commands for string manipulation, math, file system operations, array handling, encryption, graphics, and more.

Miva Script File Types#

File Type	Extension	Description
Miva Script Source File	`.mv`	A Miva Script program source code file.
Compiled Miva Script Program	`.mvc`	Executable program file for web or local hosting; also used for compiled templates.
Page Template Source File	`.mvt`	Page template source file compiled by `miva_template_compile()`.
xBase3 Database Files	`.dbf` / `.dbt`	Database tables (`.dbf`) with optional memo file (`.dbt`).
xBase3 Index Files	`.mvx`	Indexes used to create ordered views of `.dbf` files.
Delimited Data Files	`.dat` / `.txt` / `.csv` / `.tsv`	Text files with one record per line, fields separated by ASCII delimiters.

Database Backend Options#

Miva Merchant supports several database backends besides MIA (MivaScript Database), including MySQL, PostgreSQL, and Microsoft SQL Server. While MIA is file-based and bundled with the Local Server Kit, most production deployments use a relational database:

MySQL: the most common choice with extensive tooling.
PostgreSQL: supported alternative for advanced features.
MIA (MivaScript Database): default, file-based, no separate server.

Choose and configure your database during installation by specifying connection parameters. For local development, MySQL is recommended for its tooling and parity with production, while MIA can be a lightweight option without installing a DB server.

Module Development Requirements#

Before you begin development, ensure you have:

Miva Merchant ≥ v5.00 PR5 installed with a MySQL, PostgreSQL, or MivaSQL backend.
The Miva Merchant Empresa (or Mia on Windows) engine to interpret compiled scripts.
The Miva Script Compiler (mvc) available in your PATH.

All of these requirements are available when using a Docker image found here: hub.docker.com/r/mivainc/agency-partners

Modules must implement the Module_Description function to define it’s purpose and have access to certian features within Miva:

<MvFUNCTION NAME="Module_Description" PARAMETERS="l.module">
  <MvASSIGN NAME="l.module:code"    VALUE="my_module">
  <MvASSIGN NAME="l.module:name"    VALUE="My Module">
  <MvASSIGN NAME="l.module:provider"VALUE="Your Company">
  <MvASSIGN NAME="l.module:version" VALUE="1.0">
  <MvASSIGN NAME="l.module:api_ver" VALUE="5.00">
  <MvASSIGN NAME="l.module:features"VALUE="feature1, feature2">
</MvFUNCTION>

Field	Description
`l.module`	Declares the structure to populate.
`l.module:code`	Unique alphanumeric identifier (no spaces).
`l.module:name`	Display name shown in Admin.
`l.module:provider`	Vendor or organization name.
`l.module:version`	Module version for upgrades.
`l.module:api_ver`	Minimum required API version.
`l.module:features`	Comma‑separated list of implemented features.

With Module_Description defined, Miva Merchant knows what your module is and what capabilities it provides.

Module Features#

Modules will include features which are predefined capability sets defined by the Miva Merchant Module API. Each feature corresponds to a group of related functions (hooks) that your module can implement. Common feature names include:

currency: Formatting and conversion functions.
util: General utilities (string manipulation, math, etc.).
vis_util: Visual utilities for templates.
item: Item module functions for product/item integrations.
basket: Basket and checkout hooks.
order: Order processing and status hooks.

Note

Refer to the API References for a list of available features and their required function signatures.

For every feature you declare, you must define all of its required functions in your .mv source. The naming convention is:

Module_<Feature>_<FunctionName>

where <Feature> is the feature name (pascal‑cased) and <FunctionName> is the specific hook. For example, if you include basket in your features, you must implement:

<MvFUNCTION NAME="Module_Basket_Build" PARAMETERS="l.module">
  <!-- code to modify basket display -->
</MvFUNCTION>

<MvFUNCTION NAME="Module_Basket_CalculateShipping" PARAMETERS="l.module">
  <!-- code to calculate shipping -->
</MvFUNCTION>

Note

Missing functions will cause install or runtime errors.

Lifecycle & Utility Functions#

Define additional functions such as:

<MvFUNCTION NAME="Module_Install_Store" PARAMETERS="l.module">
  <!-- code -->
</MvFUNCTION>

Use <MvDO>, <MvASSIGN>, and include lib/config.mv if needed.

Compilation & Deployment#

Compile: mvc my_module.mv
Upload my_module.mvc via Admin Settings > Domain Settings > Modules then Add Modules.
The module will be placed under /modules/<feature>/my_module.mvc and activated.

Setting Up Docker Environment#

The steps below walk through setting up your Miva Merchant Docker environment and adding a compiled Miva Script program to the store.

1. Download the Miva Docker Image#

Using Docker Desktop (Recommended):

Open Docker Desktop
Go to the search bar and search for mivainc/agency-partners:
https://hub.docker.com/r/mivainc/agency-partners
Find the image with your desired tag (e.g., 10.04.00-RC1)
Click Pull to download

2. Run the Container#

Using Docker Desktop:

Go to the Images tab
Locate your agency-partners image
Click the Run/Play button
In the “New Container” dialog, expand Optional Settings and click + until all ports are visible
Configure ports:
- HTTP Port: 8080
- HTTPS Port: 8443 (optional)
- MySQL Port: 3306 (if direct DB access needed)
Add a volume:
- Host path: your local scripts folder (e.g., C:\miva-scripts or ~/miva-scripts)
- Container path: /scripts
Click Run

3. Configure Miva Merchant#

In your browser, go to: http://localhost:8080/configure
Enter:
- License Number: your Miva Merchant Developer Store license
  
  (Reach out to developer_support@miva.com for a developer store license.)
- Email Address: your email
- HTTP Port: 8080
- HTTPS Port: 8443 (if used)
- Click Configure
- You’ll be redirected to the Admin login page

Default Credentials:

Username: Administrator
Password: P@ssw0rd

4. Create Your Scripts Directory#

# Windows
mkdir C:\miva-scripts && cd C:\miva-scripts

# Mac/Linux
mkdir ~/miva-scripts && cd ~/miva-scripts

5. Create Example Module#

Create discount.mv in your local scripts folder:

<MvFUNCTION NAME="Module_Description" PARAMETERS="l.module">
  <MvASSIGN NAME="l.module:code"    VALUE="discount_display">
  <MvASSIGN NAME="l.module:name"    VALUE="Discount Example Module">
  <MvASSIGN NAME="l.module:provider"VALUE="MivaLearn Example Module">
  <MvASSIGN NAME="l.module:version" VALUE="1.0">
  <MvASSIGN NAME="l.module:api_ver" VALUE="5.00">
  <MvASSIGN NAME="l.module:features"VALUE="discount">
</MvFUNCTION>

<MvASSIGN NAME="g.price" VALUE="100.00">
<MvASSIGN NAME="g.discount" VALUE="0.20">
<p>
  <b>Discount Price: </b> $<MvEVAL EXPR="{ (g.price - (g.price * g.discount)) ROUND 2 }">
</p>

6. Make Script Executable#

Via Docker Desktop Terminal:

In Containers, select your miva-dev container
Open Terminal
Run:
```
cd /scripts
mvc discount.mv
```

7. Test Your Script#

Visit: http://localhost:8080/scripts/discount.mvc

You should see: “Discount Price: $80.00”

8. Access MySQL Database (Optional)#

Via Docker Desktop Terminal:

mysql merchant

No root password needed.

9. Enable diagtool (Optional)#

The diagtool is already setup and can be accessed by visiting: http://localhost:8080/scripts/diagtool.mvc

Key Concepts#

Tags & Nesting:

All Miva Script tags use <MvTAG> syntax. Closed tags (e.g., <MvIF>…</MvIF>) must nest correctly; empty tags (e.g., <MvEVAL>) do not require closing tags.

Attributes & Expressions:

Attributes are quoted (NAME="g.age") and may be literal values or expressions within {}. String literals use single quotes inside expressions.

Embedding HTML & JS:

You can generate HTML attributes or JavaScript dynamically with Miva Script, but Miva Script runs server-side before the browser processes JavaScript.