MIVA Merchant 5 Module Functions Reference Manual

Reformatted by Ray Yates


MIVA Small Business A division of MIVA, Inc. 5060 Santa Fe Street San Diego, CA 92109

Telephone: 858-490-2570 Fax: 858-731-4200

http://smallbusiness.miva.com info@miva.com

This document and the software described by this document are copyright © 2005 by MIVA Small Business, a division of MIVA, Inc.. All rights reserved. Use of the software described herein may only be done in accordance with the License Agreement provided with the software. This document may not be reproduced in full or partial form except for the purpose of using the software described herein in accordance with the License Agreement provided with the software. Information in this document is subject to change without notice. Companies, names and data used in the examples herein are fictitious unless otherwise noted.

MIVA is a registered trademark of MIVA, INC. MIVA Order, MIVA Merchant, MIVA Mia, MIVA Empresa, the MIVA “Infinite Growth” logo, and the MIVA Engine are trademarks of MIVA, Inc. QuickBooks Pro and Premier are trademarks of Intuit, Inc. Windows is the registered trademark of Microsoft Corporation. All other trademarks are the property of their respective owners. This document was developed and produced in San Diego, CA, USA.

MIVA, INC. WILL NOT BE LIABLE FOR (A) ANY BUG, ERROR, OMISSION, DEFECT, DEFICIENCY, OR NONCONFORMITY IN SOFTWARE OR THIS DOCUMENTATION; (B) IMPLIED MERCHANTIBILITY OF FITNESS FOR A PARTICULAR PURPOSE; (C) IMPLIED WARRANTY RELATING TO COURSE OF DEALING, OR USAGE OF TRADE OR ANY OTHER IMPLIED WARRANTY WHATSOEVER; (D) CLAIM OF INFRINGEMENT; (E) CLAIM IN TORT, WHETHER OR NOT ARISING IN WHOLE OR PART FROM MIVA INC.'S FAULT, NEGLIGENCE, STRICT LIABILITY, OR PRODUCT LIABILITY, OR (F) CLAIM FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR LOSS OF DATA, REVENUE, LICENSEE’S GOODWILL, OR USE. IN NO CASE SHALL MIVA INC.'S LIABILITY EXCEED THE PRICE THAT LICENSEE PAID FOR SOFTWARE.


Introduction

This document describes each of the module functions in use with the MIVA Merchant 5 application.

Feature

We group the functions by feature type. Each module declares, in the Module_Description function, the features it makes use of. The MIVA Merchant application will expect to find in each module, only those functions belonging to a declared feature.

Primary Feature

Some modules make use of multiple features. Such modules appear in multiple points in the admin, say in both the system and the fulfillment configuration screens. MIVA Merchant will recognize a primary feature type. An administrator can assign the module to the store only via the configuration screen for the primary feature. One configures components using the Edit Page configuration screen for a page using an item based on the component.

Terms Used in this Document

MIVA Merchant: The storefront application, including the file merchant.mvc and the files it uses, such as those governing the UI and various features.

Admin: The administration interface, admin.mvc, and the files it makes use of.

The UI: That portion of the application concerned with displaying the screens that the shopper actually sees and interacts with.

Module Functions

All Modules

Module_Description(module var)

MIVA Merchant, Admin and the UI all call this function at several different points.

It provides information that identifies the module, such as the module code and the module name and describes some of its major characteristics, such as the list of features it makes use of. One uses this function to load all this information into a structure with the name “module”.

As is frequently the case, one makes use of the “var” option on the parameter in order to pass variable values to the calling program by reference. The actual value returned by MvFuncReturn does not contain the main information.

Default Return: NULL

Example:

<MvFUNCTION NAME"Module_Description" PARAMETERS"module var" STANDARDOUTPUTLEVEL"">
	<MvASSIGN NAME"l.module:code" VALUE"your_mod_code">
	<MvASSIGN NAME"l.module:name" VALUE"Your Mod Name">
	<MvASSIGN NAME"l.module:provider" VALUE"Your Company Name">
	<MvASSIGN NAME"l.module:version" VALUE"1.0">
	<MvASSIGN NAME"l.module:api_ver" VALUE"5.0">
	<MvASSIGN NAME"l.module:features" VALUE"component">
</MvFUNCTION>

batchreport

MIVA Merchant allows the online business to create batches of orders. This can be daily, weekly, or whenever the store manager chooses. The batch reporting module creates summary report for a specified batch order. The module has total control over what information is used and how it is displayed.

BatchReportModule_Report(module var, batch_id)

Admin calls this function if one selects this module from the Report dropdown menu on Run Report screen.

It instructs Admin what to display as a report for the order batch identified by l.batch_id.

Default Return: 1

component

Component modules underlie the items used in Store Morph Technology, providing information to the UI on how to display data and/or instructing MIVA Merchant how to alter the data before displaying it. One assigns a component to its corresponding item.

One installs a component to a store by assigning it to an item within the store. This one accomplishes on the Edit Item configuration page. Alternatively, one may assign a component to the store by assigning it as an extension of a component already installed to the store. This one accomplishes via the Items tab on the Edit Page configuration screen.

ComponentModule_Tabs(module var, item, settings var)

MIVA Merchant calls this function when Admin displays an Edit Page configuration screen for a page using an item based on the component.

Recommended return (if one desires to have a tab show): {toupper(l.module:code) $ ‘:’ $ l.module:name }

Default Return: NULL

ComponentModule_Validate(module var, item, field_prefix, fields var)

MIVA Merchant calls this function when one hits Update on the Edit Page configuration screen for a page using an item based on the component

Default Return: 1

ComponentModule_Update(module var, item, field_prefix, fields var, settings var)

MIVA Merchant calls this function when one hits Update on configuration screen for a page using an item based on the component

Default Return: 1

ComponentModule_Content(module var, item, tab, load_fields, field_prefix, fields var, settings var)

Runs when Admin displays the Edit Page configuration screen for a page using an item based on the component. Contains instructions on what Admin should display on Edit Page screen when user selects the tab belonging to this module.

Default Return: NULL

ComponentModule_Defaults(module var, settings var)

Admin calls this function when one assigns corresponding item to page.

Default Return: NULL

ComponentModule_Page_Assign(module var, page var, item, settings var)

Admin calls this function when one assigns corresponding item to page.

Default Return: 1

ComponentModule_Page_Unassign(module var, page var, item, settings var)

Admin calls this function when one assigns corresponding item to page.

Default Return: 1

ComponentModule_Initialize(module var, item, all_settings var, settings var)

MIVA Merchant calls this function when displaying a page using an item based on the component.

One uses this function to add, delete, or edit values in the settings and all_settings structure which contain the data for display on the page (e.g. product name, list of shipping methods).

MIVA Merchant will also sequently call this function from any component extending the first component, allowing them to, say, add to the product name, or alter the order of the shipping methods in the list.

Default Return: 1

ComponentModule_Render_Start(module var, item, all_settings var, settings var, param)

Called when template manager encounters item tag start (<mvt:item>) in template. The function provides MIVA Merchant instructions on what html source to place at that point in the page.

Default Return: NULL

ComponentModule_Render_End(module var, item, all_settings var, settings var, param)

Called when template manager encounters item tag end (<mvt:item />) in template. The function provides MIVA Merchant instructions on what html source to place at that point in the page.Default Return: NULL

component_prov

Note: modules must include the provision_store feature in order to make use of the component_prov feature.

ComponentModule_Provision(module var, provide_xml var, settings var)

Like the Provision_Store function, this function receives the data from the provide_xml that exists twixt the <module code[code for this module] featurecomponent> tags. In addition, it receives the item settings.

The function can contain instructions on, for instance, where to place the data.

Default Return: NULL

currency

Each function belonging to this feature adds formatting to a decimal number that is passed to it. It provides a place to specify, among other things, the currency symbol and number of decimal places for use in displaying a price value.

In addition to simple formatting, a currency module could convert values of various currencies. It could display US currency, Eurodollars, or Canadian currency using the daily rate of exchange data to give updated values from day to day.

The currency module could go one step further and do a lookup every hour to update the currency values.

CurrencyModule_AddFormatting(module var, value)

MIVA Merchant calls this function wherever it displays a price on one of the store pages. MIVA Merchant will call this function only from the currency module selected by the store administrator using the Edit Store configuration screen.

Default Return: NULL

CurrencyModule_AddFormatPlainText(module var, value)

This function exists to provide alternate (presumably simpler) formatting to the CurrencyModule_AddFormatting. Email modules make use of it.

Default Return: {CurrencyModule_AddFormatting(l.module,l.value)}

CurrencyModule_AddFormatPlainTextShort(module var, value)

This function exists to provide alternate (presumably simpler) formatting to CurrencyModule_AddFormatting. Email modules make use of it.

Default Return: {CurrencyModule_AddFormatting(l.module,l.value)}

custrt

MIVA Merchant calls these functions when a shopper creates or edits his or her customer account.

Module_Customer_Runtime_Insert(module var)

Default Return: 1

Module_Customer_Runtime_Update(module var, customer)

Default Return: 1

Module_Customer_Runtime_Validate(module var, customer)

Default Return: 1

data_domain

Module_Install(module var, version)

Admin runs this function when the administrator adds the module to the domain.

One employs this function only when the module performs some functionality or provides data that is shared between all of the stores in a domain. It is the job of this function to create any databases and directories that may be required.

Default Return: 1

Module_Upgrade(module var)

Admin runs this function when one hits Update on the Edit Module configuration screen.

It provides a place to define what action Admin must take to upgrade from one version of the module to another. If the module has more than two versions that could be actively used, the action for each upgrade should be given. If there are four version in use (v1.0, v1.1, v2.0 and v3.0), the code should be written transparently.

Therefore, if a person is upgrading from v1.0 to v3.0 the code should first upgrade to v1.1 then to v2.0 and finally to v3.0.

A simple example would be if the fields used in the module have changed somehow with each new version. There may be fields in a the new version that are were not in an older version. If this is the case, the databases would have to be each upgraded and the data written into the new database from the old. If a person were upgrading from v1.1 to v3.0 this process would have to be done twice.

Default Return: 1

Module_Uninstall(module var)

Admin runs this function when one removes the module from the domain.

It should contain the code necessary to reverse what was done during Module_Install. Any action that is taken in Module_Install should be reversed in this function. It could be deleting a database or directory or deleting a user from the licensed-user database.

Default Return: 1

data_store

Module_Install_Store(module var)

Admin runs this function when the store administrator assigns the module to the store.

The function provides a place to create any databases and directories that may be required by the module for each store location.

Default Return: 1

Module_Upgrade_Store(module var, version)

Admin calls this function when a store administrator clicks Update on the Edit Module configuration page.

This function provides a place for code altering, during a module upgrade, the databases and directories that apply to a specific store.

Default Return: 1

Module_Uninstall_Store(module var)

Admin calls this function when the store administrator removes a module from the store.

It should perform the opposite of the Module_Install_Store function. Every action that takes place in the install function should be reversed in this module. All databases and directories that have been established should be deleted. The store should be taken out of the "installed stores" database. Any other functions that were required to establish the store must be reversed and cleaned up.

Default Return: 1

export

Functions belonging to this feature allow an opportunity to move data from a MIVA Merchant database file to another file location.

ExportModule_Validate(module var)

Admin calls this function when one submits information from the Export UI screen in the administration tool.

This function provides a place for code to validate any input data that is required to run the module. For example, if the module requires a database name and the fields to be exported, this function must validate that the names of the database and fields exist and can be read.

Default Return: 1

ExportModule_Screen(module var)

Admin calls this function when one selects the Export UI screen (by clicking the module’s link under Utilities>Export Data in Admin’s left menu).

It’s purpose is to provide Admin with instruction on how to build a UI screen for the module.

Default Return: 1

ExportModule_Export(module var)

Admin calls this function when one submits information from the Export UI screen in the administration tool.

It provides Admin with instructions about exporting data in a MIVA Merchant database or file to a database or file outside of the MIVA Merchant environment. For example, this type of module could read the customer database and write it to a file on another computer. Any data that is available to MIVA Merchant can be exported.

Default Return: 1

externalreq

The purpose of this feature is to provide an opportunity to make sure that the running environment for the store meets special requirements of the module, such as ssl being available.

Module_External_Requirements_Met(module var)

Admin calls this function when displaying one of the feature configuration screens, such as:

System Extension Configuration Shipping Config Payment Config Order Fulfil Config Logging Config System Extension Config Utilities Config

The function must return true or else Admin will not include module in list of those assignable to store. One could code the module to test for the state of some arbitrary requirement, e.g. that the server runs ssl, and return false if the server fails the test. This would prevent store administrators from installing the module to the store until and unless the ssl requirement is met.

Default Return: 1

fields_cust

Analogous to the fields_prod feature. This feature allows an administrator to set up additional db fields for each customer record. One activates the feature (along with custom product fields) under Utilities.

Module_Customer_Fields(module var, fields var)

Admin calls this function when displaying the Customer configuration screen.

The Customer Export module also consults this function.

Its purpose is to load the l.fields structure with the name and code for each custom field the module supplies. It must return the number of elements added to l.fields.

l.fields[x]:id the internal customer id

l.fields[x]:name the field name visible in the admin tool (as on point and click administration of template)

l.fields[x]:code the code MIVA Merchant uses to identify the field

Default Return: l.field_count

Module_Customer_Field_Name(module var, code)

This function returns a string for display as a field name for the field corresponding to l.code.

Default Return: NULL

Module_Customer_Field_Value(module var, cust_id, code)

Admin calls this function if required to fill in the value of a custom field on the Customer configuration screen.

The purpose of the function is to return the value stored for the field identified by l.code for the customer identified by l.cust_id.

Default Return: NULL

Module_Customer_Set_Field(module var, cust_id, code, value)

Admin relies on this function to instruct it how to update the value, known from the value parameter, of a custom customer field, identified by the code parameter, for a given customer, identified by the cust_id parameter. The value comes from manual input from an administrator, an import etc.

Default Return: 1

fields_prod

Module_Product_Fields(module var, fields var)

Admin calls this function when displaying the Product configuration screen.

Admin calls this function when displaying the Edit Page: Product Display configuration screen.

Product import and export modules also consult this function.

When one views the point and click administration of the Product Display Layout, the field(s) created by the module will be available to select for display.

Its purpose is to load the l.fields structure with the name and code for each custom field the module supplies. It must return the number of elements added to l.fields.

l.fields[x]:id the internal product id

l.fields[x]:name the field name visible in the admin tool (as on point and click administration of template)

l.fields[x]:code the code MIVA Merchant uses to identify the field

Default Return: l.field_count

Module_Product_Field_Name(module var, code)

The UI calls this function when displaying a custom product field on the product screen (PROD) or product list screen (PLIST).

It returns a string for display as a field name for the field corresponding to l.code.

Default Return: NULL

Module_Product_Field_Value(module var, prod_id, code)

Admin may call this function if required to display the value of a custom field on the Product configuration screen.

The UI calls this function when displaying a custom product field on the product page.

It returns a string for display as a field value for the field corresponding to l.code.

Default Return: NULL

Module_Product_Set_Field(module var, prod_id, code, value)

Admin relies on this function to instruct it how to update the value, known from the value parameter, of a custom product field, identified by the code parameter, for a given product, identified by the prod_id parameter. The value comes from manual input from an administrator, an import etc.

Default Return: 1

fulfill

Functions in this feature type provide an opportunity to execute all of the tasks that are needed to acknowledge an order.

FulfillmentModule_ProcessOrder(module var, order var)

MIVA Merchant calls this function after a successful run of PaymentModule_Authorize.

The instructions a module author includes here can be as simple as sending an Email to the customer acknowledging the order. One could also use the function to acknowledge the order by sending an invoice to the customer and sending a packing list to the shipping department.

Alternatively, the fulfillment process can be as extensive as sending a parts list that defines the components of a customer built computer to the manufacturing floor.

Default Return: 1

import

Functions within this feature type obtain data from outside the MIVA Merchant environment and write it to files within the environment.

ImportModule_Validate(module var)

Admin calls this function when one submits information from the Import UI screen in the administration tool.

This function provides a place for code to validate any input data that is required to run the module. For example, if the module requires a database name and the fields to be exported, this function must validate that the names of the database and fields exist and can be written to.

Default Return: 1

ImportModule_Screen(module var)

Admin calls this function when one selects the Export UI screen (by clicking the module’s link under Utilities>Import Data in Admin’s left menu).

It’s purpose is to provide Admin with instruction on how to build a UI screen for the module.

Default Return: 1

ImportModule_Import(module var)

Admin calls this function when one submits information from the Importing UI screen in the administration tool.

It provides Admin with instructions about importing the data to a MIVA Merchant database from a database or file outside of the MIVA Merchant environment. For example, this type of module could read a product database outside of MIVA Merchant and write it to the MIVA Merchant products database. Any data in the MIVA Merchant database can be imported.

Default Return: 1

log

Logging functions provide a place to insert supplementary instructions for MIVA Merchant at various points during the shoppers session, such as after the display of each screen, after processing each form submission and after processing a UIException. The Logging functions are counterparts of the System functions which MIVA Merchant calls before rather than after each activity.

Modules may use this feature to gather information from store shoppers and write it to a log file. The log information can then be used for statistical analysis of the store. This could be traffic volume and patterns, purchase volume and patterns, etc.

LogModule_Action(module var, action)

MIVA Merchant calls this function after responding to a shopper submitting a form with an Action variable, such as when the shopper clicks Add to Basket.

Default Return: 1

LogModule_Screen(module var, screen)

MIVA Merchant calls this function after displaying a screen to the shopper.

Default Return: 1

LogModule_UIException(module var, code)

MIVA Merchant calls this function after processing a UIException, i.e. an error with the input received from the shopper.

Default Return: 1

not_fields

a.k.a Notify Standard Fields

These functions exist to allow a module to make changes to templates when an administrator modifies the displays settings for the customer fields that show up on OINF etc.

Module_Notify_StandardFields(module var, standardfields var)

Admin calls the function when one makes changes to the Customer Fields settings and hits Update on the Customer Fields configuration screen ([Store Name]::Customer Fields).

Default Return: 1

payment

Modules including this feature provide methods for MIVA Merchant stores to receive payment for the products offered. The methods could be from among the following:

* Check payment mailed before shipment * COD * Credit card processing manually * Credit card processing in real time * Electronic Funds Transfer (ETF) for total of purchase

PaymentModule_LeftNavigation(module var, indent)

Admin calls this function when it expands the store’s Order Processing link in Admin’s left navigation menu.

It allows one to enter a link into the admin tool’s left navigation menu, if desired.

Default Return: NULL

PaymentModule_Payment_Methods(module var, methods var)

The UI calls this function when displaying a list of payment methods available for use in checkout.

It loads the l.methods structure with information about available shipping methods offered via this module, such as name and code.

It must return the number of methods added.

Default Return: NULL

PaymentModule_Payment_URL(module var)

MIVA Merchant calls this function before displaying the OPAY screen.

If the function returns a value, MIVA Merchant knows it needs to deal with a CGI gateway for payment authorization and it forms the OPAY page appropriately, i.e. it sets the action of the main form to the payment url.

The module should return NULL for non CGI gateways.

PaymentModule_Payment_Description(module var, data)

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a textual description of the module, for display as a heading above the payment information input fields on the OPAY screen.

Default Return: NULL

PaymentModule_Payment_Message(module var, data)

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a textual description of the module, for display above the payment information input fields and below the heading from PaymentModule_Payment_Descrioption.

Default Return: NULL

PaymentModule_Payment_Hide_Additional_Fields(module var, data)

MIVA Merchant calls this function when displaying the OPAY screen.

It allows a module to insert hidden input fields on the OPAY form, such as might be required to pass state information to the CGI gateway processor.

Default Return: 1

PaymentModule_Payment_Fields(module var, data)

MIVA Merchant calls this function before displaying the OPAY screen.

It returns comma separated list of field identifiers, of the form id[,id,id,id-]. MIVA Merchant will display the fields during the checkout process (usually on OPAY screen).

Default Return: NULL (i.e. no fields to diplay)

PaymentModule_Payment_Prompt(module var, data, field_id)

MIVA Merchant calls this function before displaying the OPAY screen.

It returns a prompt (i.e. text) for the field named in the field_id parameter originally named in PaymentModule_Payment_Fields.

Default Return: NULL

PaymentModule_Payment_Invalid(module var, data, field_id)

The UI calls this function when displaying the OPAY screen.

It is a boolean flag to indicate whether or not the customer entered invalid data for the field specified by field_id.

The UI uses this flag so as to know whether to turn prompt red on screen (i.e. visually signal to the user that the valued entered in the field is invalid). The function may check flags set in PaymentModule_Payment_Field (e.g. g.Check_Number_Invalid) in order to determine whether the field is invalid or not.

Default Return: NULL

PaymentModule_Payment_Field(module var, data, field_id)

MIVA Merchant calls this function when displaying the payment information input fields on the OPAY screen. It receives the "data" element of the selected payment method from PaymentModule_Payment_Methods and the "field_id" identifier from the list returned by PaymentModule_Payment_Fields(). It outputs the HTML code required to display the field specified by field_id, for the method specified in data.

Default Return: 1

PaymentModule_Payment_Validate(module var, pay_data)

MIVA Merchant uses this function to determine whether to proceed with PaymentModule_Authorize.

One can insert here logic to determine whether or not to continue or to ask the shopper to re-enter data, for instance if the shopper failed to input a credit card expiration date.

Default Return: 1 (i.e. payment data is valid)

PaymentModule_Report_Description(module var, data)

It returns a textual description of the payment processing method, for use by MIVA Merchant during display during order processing and by batchreport modules.

Default Return: NULL

PaymentModule_Report_Fields(module var, data, secure_data)

This function is an analog of PaymentModule_Payment_Fields, but for batchreport display.

It returns a comma-separated list of field identifiers

Default Return: NULL

PaymentModule_Report_Label(module var, field_id)

This function is an analog of PaymentModule_Payment_Prompt.

It returns text for display beside the field identified by field_id (generated by PaymentModule_Report_Fields).

Default Return: NULL.

PaymentModule_Report_Value(module var, field_id, data, secure_data)

This function returns the value corresponding to the field identified in field_id, e.g. the check number for field check.

Default Return: NULL

PaymentModule_Manipulate_Shipping(module var, data)

MIVA Merchant runs this function upon receiving the form submission from the OSEL screen.

The function provide an opportunity for a payment module to introduce extra charges for shipping, as may be the case with COD for example.

Default Return: 1

PaymentModule_Authorize(module var, module_data, total, data var, secure_data var)

This function provides a place for the code for determining whether to authorize a charge of l.total given the information in l.data. This is typically where the call to the payment processor resides, for use during order placement.

It The module should return 1 if successful, 0 on failure.

Default Return: 1

PaymentModule_Process(module var, data var, secure_data var, order var)

Admin calls this function during order processing in admin when one clicks Process Order.

This function exists for processing the payment data, typically for a post authorization.

It should It The module should return 1 on success, 0 on failure.

Default Return: 1

PaymentModule_Order_Validate(module var)

Admin calls this function to validate fields when one clicks Update on the Edit Order configuration screen.

It returns 1 if all fields are valid, 0 on failure.

Default Return: 1

PaymentModule_Order_Update(module var, data var, secure_data var)

Admin calls this function to validate fields when one clicks Update on the Edit Order configuration screen. One typically uses it to update any module-specific records for the order.

It The module should return 1 on success, 0 on error.

Default Return: 1

PaymentModule_Order_Delete(module var, data, secure_data)

Admin calls this function when one clicks Delete on the Edit Order screen. One typically uses it to clean up any module specific records for the order.

It The module should return 1 on success, 0 on error.

Default Return: 1

PaymentModule_Order_Tabs(module var)

Admin calls this function when displaying the Edit Order configuration screen.

It returns a tab list for the Edit Order configuration screen.

Default Return: {toupper(l.module:code) $ ‘:’ $ l.module:name}

PaymentModule_Order_Content(module var, tab, load_fields, data, secure_data)

Admin calls this function to know what to display on the Edit Order configuration screen. This is similar to the other vis content functions.

Default Return: 1

provision_store

Provisioning allows one to add automatic instructions for the manipulation of data in the store. The upgrade system makes use of the provisioning system to transfer data from one store to another.

Module_Provision_Store(module var, provide_xml var)

Admin calls this function whet processes the provide.xml file if it encounters a tag identifying this module: <Module code[code of module]>. Admin will then pass the information contained by the tag to the function. The function can then act accordingly, for example, writing data to the appropriate database table.

Default Return: NULL

shipping

Functions in this feature type provide an opportunity for MIVA Merchant stores to offer shipping methods by which the storeowner can ship products to their customers. These methods might be from among the following:

- Mail - Global delivery services (USPS, FedEx, etc.) - Local Delivery service (for grocery deliver sites, etc.) - Truck shipment

ShippingModule_Description(module var, data)

Admin calls this function when displaying the standard batch report.

It returns a textual description of the module.

Default Return: NULL

ShippingModule_Report_Fields(module var)

Admin calls this function when displaying a standard batch report.

It returns a comma separated list of field identifiers for fields displayed in the batch report.

Default Return: NULL (i.e. no fields)

ShippingModule_Report_Label(module var, field_id)

Admin calls this function when displaying a standard batch report.

It returns a string for use as visible text for display beside field identified by field_id

Default Return: NULL

ShippingModule_Report_Value(module var, field_id, data)

Admin calls this function when displaying a standard batch report.

It returns the value to display in field identified by field_id for method identified in data.

Default Return: NULL

ShippingModule_Shipping_Methods(module var, methods var)

The UI calls this function when displaying the OSEL screen, where shipping selection exists.

The purpose of the function is to loads the method structure with information about available shipping methods offered via this module. It must return the number of methods added.

Default Return: NULL

ShippingModule_Calculate_Basket(module var, data)

MIVA Merchant calls this function when processing a form submission with Action SHIP.

Its purpose is to insert a SHIPPING basket charge for the shipping method chosen by the shopper, as identified in l.data.

It returns 1 if successful, 0 on error.

Default Return: 1

ShippingModule_Order_Validate(module var)

Admin calls this function to validate fields when a user clicks Update on the Edit Order configuration screens.

It returns 1 if all fields are valid, 0 if any field is invalid.

Default Return: 1

ShippingModule_Order_Update(module var)

Admin calls this function when one clicks Update on the Edit Order configuration screen.

It The module should return 1 on success, 0 on failure.

Default Return: 1

ShippingModule_Order_Delete(module var)

Admin calls this function when one clicks Delete on the Edit Order configuration screen.

One typically uses it to clean up any module-specific records for the order.

It returns a 1 on success, 0 on failure.

Default Return: 1

ShippingModule_Order_Tabs(module var)

Admin calls this function when displaying the Edit Order configuration screen.

It returns a tab list using the following format:

code:text[,code:text,code:text]

Codes must be unique across modules, so it is recommended that the codes somehow include the module code.

Default Return: {toupper(l.module:code) $ ‘:’ $ l.module:name}

ShippingModule_Order_Content(module var, tab, load_fields)

Admin uses this function to determine what to display on the Edit Order configuration screen when the user clicks on the tab identified by l.tab.

Default Return: 1

storeselui

This feature provides an opportunity for modules to affect the display and operation of the UI a shopper encounters when a domain has more than one store.

UIModule_StoreSelection_Validate()

Admin calls this function from the selected storeselui module when an administrator clicks Update on the Domain Settings screen.

It The module should return 1 on success, 0 on error.

Default Return: 1

UIModule_StoreSelection_Tabs()

Admin calls this function from the selected storeselui module when it (Admin) displays the Domain Settings screen.

It returns a comma delimited list of colon delimited tab-code and tab-name pairs. Admin uses this information to create tabs on the Domain Settings screen.

Default Return: NULL

UIModule_StoreSelection_Content(tab, load_fields)

Admin calls this function from the selected storeselui module when it (Admin) displays the Domain Settings screen.

Default Return: 1

UIModule_StoreSelection_Update()

Admin calls this function from the selected storeselui module when an administrator clicks Update on the Domain Settings screen.

It The module should return 1 on success, 0 on failure.

Default Return: 1

UIModule_StoreSelection_Thumbnail()

Admin calls this function when the store administrator selects Store Selection Layout tab on the Domain Settings configuration screen.

Default Return: NULL

UIModule_StoreSelection_Render()

MIVA Merchant runs this function in response to request for domain. (MIVA Merchant bypasses it in the common situation where there exists only one store in the mall.)

Default Return: NULL

storewizard

Modules using the wizard feature provide the user with a simple step-by-step method to accomplish a common task in the administrative interface at the store level.

StoreWizardModule_Action(module var)

Admin calls this function after the user completes all steps and after a successful return from StoreWizardModule_Privileges and StoreWizardModule_Validate.

Here one can place instructions about what to do with or in reaction to the input submitted by the user.

Default Return: 1

StoreWizardModule_Content(module var, step, load_fields)

Admin calls this function each time it displays a new screen.

It provides the instructions for the main portion of the wizard screen.

Default Return: 1

StoreWizardModule_Icon(module var) One uses this function to defines the path and name of the icon graphic that is displayed on the admin.mv front page, under the store section.

Default Return: NULL

StoreWizardModule_Logo(module var)

Admin calls this function each time it displays a new screen.

One uses this function to define the path and name of the icon graphic that is displayed in the upper left corner of the wizard.

Default Return: NULL

StoreWizardModule_Privileges(module var)

Admin calls this function when it expands the store portion of its left menu. The module should return 1 if current user has privileges to run wizard. The module should return 0 if current user does not.

Default Return: 1

StoreWizardModule_Title(module var, step)

Admin calls this function each time it displays a new screen.

Default Return: NULL

StoreWizardModule_Validate(module var)

Admin calls this function after the user completes all steps

One should include instructions in the function to determine that any information the administrator submits is acceptable in format.

The function should return a 1 on success, 0 on failure.

Default Return: 1

StoreWizardModule_Validate_Step(module var, step)

Admin calls this function each time it receives input from the submission of a wizard screen (one screen per step).

One should include instructions in the function to determine that any information the administrator submits is acceptable in format.

The function should return a 1 on success, 0 on failure. In the case of failure, Admin will not allow the wizard to move onto the next screen.

One can also set invalidity flags for use by the UI in a fashion similar to that of PaymentModule_Payment_Invalid.

Default Return: 1

system

System functions provide a place to insert supplementary instructions for MIVA Merchant at various points during the shoppers session, such as before the display of each screen, before processing each form submission and before processing a UIException. The System functions are counterparts of the Logging functions which MIVA Merchant calls after rather than before each activity.

SystemModule_Action(module var, screen)

MIVA Merchant calls this function in response to a shopper clicking a form submission button on the site.

Default Return: 1

SystemModule_Screen(module var, screen)

MIVA Merchant calls this function at the beginning of displaying a screen.

Default Return: 1

SystemModule_UIException(module var, exception)

MIVA Merchant calls this function at the beginning of processing a UI Exception.

Default Return: 1

tax

Modules including this feature provide MIVA Merchant the ability to collect the appropriate information and charge the appropriate sales taxes.

TaxModule_Order_Hide_Fields(module var)

The UI calls this function when displaying the OSEL screen.

The purpose of this function is to insert hidden fields on checkout screens, so as to carry data through, as form variables, from earlier screens, e.g. OINF, through later ones, e.g. OSEL, until the shopper is able to submit a form with Action CTAX.

Default Return: 1

TaxModule_Order_Fields(module var)

The UI calls this function at each checkout screen to determine what, if any tax fields to display.

The function should return a comma-separated list of field ids of the form id[,id,id,id-].

Default Return: NULL

TaxModule_Order_Prompt(module var, field_id)

This function returns a text string for display beside the tax field identified by the field_id parameter (set in TaxModule_Order_Fields).

Default Return: NULL

TaxModule_Order_Required(module var, field_id)

The UI consults this function to know whether or not a field needs validation, such as would be necessary to make sure the shopper made a selection on a field.

The function should return 1 to indicate that yes, the field does need validation. Otherwise, the function returns a zero (i.e. not a required field).

Default Return: NULL

TaxModule_Order_Invalid(module var, field_id)

The UI consults this function to determine whether to highlight a given field so as to indicate that the last information the shopper entered in that field was invalid. The function itself may make that determination based on an invalidity flag set in TaxModule_Order_Validate. The strategy is the same as used for PaymentModule_Payment_Invalid and PaymentModule_Payment_Validate.

The function should return a 1 to indicate that the field submission is invalid. If there is no problem with the field submission, then the function should return 0.

Default Return: NULL

TaxModule_Order_Field(module var, field_id)

This function creates the HTML code needed to display the tax field identified by the field_id parameter (set in TaxModule_Order_Fields).

Default Return: NULL

TaxModule_Order_Validate(module var)

MIVA Merchant calls Action_Save_OrderInformation in response to form submission containing ActionORDR, as is the case with the form shoppers submit from the OINF page. The function provides an opportunity to check if the tax information is acceptable.

One use is to set invalidity flags for consultation by TaxModule_Order_Invalid. TaxModule_Order_Invalid can check the status of a given flag, perhaps an id number, and decide whether to declare the submission invalid on that basis. (For another implementation of the same strategy, see PaymentModule_Payment_Validate and PaymentModule_Payment_Invalid.

If the function returns 0, i.e. failure, the UI will return to the previous page. The UI will know, from the invalidity flags, that the previous submissions were invalid and will highlight the relevant input fields appropriately.

The function should return 1 to indicate success or 0 to indicate failure.

Default Return: 1

TaxModule_Calculate_Basket(module var)

MIVA Merchant calls this function when responding to a form submission from the shopper containing Action CTAX.

This function should contain the instructions necessary to insert a ‘TAX’ basket charge in the basket.

Return 1 on success, 0 on failure.

Default Return: 1

TaxModule_ProcessOrder(module var)

MIVA Merchant calls this function after creating an order, but before calling FulfillmentModule_Process_Order.

The function provides an opportunity to perform operations at the time the shopper places the order, such as calculating taxes real time.

Default Return: 1

upload

Module_ProcessFileUpload(module var, tempfile, filename_nopath)

The MIVA virtual machine calls this function when handling the upload of a file.

Default Return: 1

util

A module author employs this feature to enhance the functionality of MIVA Merchant. It provides a means of defining a custom configuration screen, ScreenSUTL and a means of placing a link to the screen in Admin’s left navigation menu. Operations that do not fit into other feature types can be included here.

StoreUtilityModule_Action(module var)

Admin calls this fuction if StoreUtilityModule_Validate returns a success.

Default Return: 1

StoreUtilityModule_LeftNavigation(module var, indent)

Admin calls this function to determine what to place in its left menu. The indent parameter tells Admin at what depth of indentation to display the link. For example an indent value of "2" would represent the second indent level.

One can place the variable ScreenSUTL in the link, which will cause Admin to call StoreUtilityModule_Screen.

Default Return: NULL

StoreUtilityModule_Screen(module var)

This function instructs Admin what to display as main content when rendering the SUTL screen.

Default Return: 1

StoreUtilityModule_Validate(module var)

Admin calls this function when processing a form submission that includes ActionSUTL

It should return a 1 to indicate the success, a 0 on failure.

Default Return: 1

wizard

Modules using the wizard feature provide the user with a simple step-by-step method to accomplish a common task in the administrative interface at the domain level.

WizardModule_Action(module var)

Admin calls this function after the user completes all steps and after a successful return from WizardModule_Privileges and WizardModule_Validate.

Here one can place instructions about what to do with or in reaction to the input submitted by the user.

Default Return: 1

WizardModule_Content(module var, step, load_fields)

Admin calls this function each time it displays a new screen.

It provides the instructions for the main portion of the wizard screen.

Default Return: 1

WizardModule_Icon(module var) - One uses this function to defines the path and name of the icon graphic that is displayed on the admin.mv front page, under the domain section. Default Return: NULL

WizardModule_Logo(module var)

Admin calls this function each time it displays a new screen.

One uses this function to define the path and name of the icon graphic that is displayed in the upper left corner of the wizard.

Default Return: NULL

WizardModule_Privileges(module var)

Admin calls this function when it builds its left menu. The module should return 1 if current user has privileges to run wizard. The module should return 0 if current user does not.

Default Return: 1

WizardModule_Title(module var, step)

Admin calls this function each time it displays a new screen.

Default Return: NULL

WizardModule_Validate(module var)

Admin calls this function after the user completes all steps

One should include instructions in the function to determine that any information the administrator submits is acceptable in format.

The function should return a 1 on success, 0 on failure.

Default Return: 1

WizardModule_Validate_Step(module var, step)

Admin calls this function each time it receives input from the submission of a wizard screen (one screen per step).

One should include instructions in the function to determine that any information the administrator submits is acceptable in format.

The function should return a 1 on success, 0 on failure. In the case of failure, Admin will not allow the wizard to move onto the next screen.

One can also set invalidity flags for use by the UI in a fashion similar to that of PaymentModule_Payment_Invalid.

Default Return: 1

Vis Functions

Vis functions are those called by Admin. They provide the administrator with a means of configuring the modules.

_Content

Admin calls these functions when displaying a configuration page. The _Content function tells Admin what to display in the main portion of the configuration screen. They usually return 1 to indicate that they have completed their task successfully.

Default Return: 1

_Tabs

Admin calls these functions to determine if it should add any extra tabs to the configuration screen in question, and to determine what those tabs should contain.

Each tab needs a unique code, so it is best practice to include the module code in the tab.

If the function supports the licensing feature, it needs to include the unlicensed prefix on the tab:

{toupper(l.module:code) $ ‘:’ $ g.buildTabHeader $ l.module:name }

Default Return: {toupper(l.module:code) $ ‘:’ $ l.module:name }

_Validate

Admin calls these functions in response to an administrator’s clicking Add or Update on a configuration screen.

Admin uses these functions to determine that any information the administrator submits is acceptable in format, e.g. they have entered something into a required field, they have entered the correct number of digits for a zip code.

The module should return 1 if everything is valid, 0 if any part of the mission is invalid.

Default Return: 1

_Insert

Admin calls these functions in response to an administrator’s clicking Add on a configuration screen, such as when adding a product or customer.

Default Return: 1

_Update

Admin calls these functions in response to an administrator’s clicking Update on a configuration screen, usually because she or he wants to alter the configuration somehow.

Default Return: 1

_Delete

Admin calls these functions in response to an administrator’s clicking Delete on a configuration screen, such as when removing a product or customer.

Default Return: 1

_BatchEdit_

Admin calls these function when an store administrator adds, removes or updates an item “inline” from a configuration screen showing a list of such items, e.g. customers, categories or affiliates. The configuration screen showing the list of items includes an “Add” button in addition to a “Remove” check box and an “Edit Here” button on each line item.

vis_affil

Module_Affiliate_Content(module var, tab, load_fields, affiliate var)

Module_Affiliate_Delete(module var, affiliate var)

Module_Affiliate_Tabs(module var, affiliate var)

Module_Affiliate_Insert(module var, affiliate var)

Module_Affiliate_Update(module var, affiliate var)

Module_Affiliate_Validate(module var)

vis_affilbe

Module_Affiliate_BatchEdit_Update(module var, id)

Module_Affiliate_BatchEdit_Delete(module var, id)

Module_Affiliate_BatchEdit_Validate(module var)

vis_category

Module_Category_Content(module var, tab, load_fields, category var)

Module_Category_Delete(module var, category var)

Module_Category_Tabs(module var, category var)

Module_Category_Insert(module var, category var)

Module_Category_Update(module var, category var)

Module_Category_Validate(module var)

vis_categorybe

Module_Category_BatchEdit_Update(module var, id)

Module_Category_BatchEdit_Delete(module var)

Module_Category_BatchEdit_Validate(module var)

vis_cust

These functions apply when one edits products in Admin>>Store>>Customers and clicks Update.

Module_Customer_Tabs(module var, customer var)

Module_Customer_Content(module var, tab, load_fields, customer var)

Module_Customer_Insert(module var, customer var)

Module_Customer_Delete(module var, customer var)

Module_Customer_Validate(module var)

Module_Customer_Update(module var, customer var)

vis_custbe

Module_Customer_BatchEdit_Update(module var, customer var)

Module_Customer_BatchEdit_Delete(module var, customer var)

Module_Customer_BatchEdit_Validate(module var)

vis_domain

Module_Domain_Validate(module var)

Module_Domain_Update(module var)

Module_Domain_Tabs(module var)

Module_Domain_Content(module var, tab, load_fields)

vis_fulfill

Module_Fulfillment_Validate(module var)

Module_Fulfillment_Update(module var)

Module_Fulfillment_Tabs(module var)

Module_Fulfillment_Content(module var, tab, load_fields)

vis_log

Module_Logging_Validate(module var)

Module_Logging_Update(module var)

Module_Logging_Tabs(module var)

Module_Logging_Content(module var, tab, load_fields)

vis_order

Module_Order_Validate(module var)

Module_Order_Update(module var)

Module_Order_Tabs(module var)

Module_Order_Content(module var, tab, load_fields)

vis_payment

Module_Payment_Validate(module var)

Module_Payment_Update(module var)

Module_Payment_Tabs(module var)

Module_Payment_Content(module var, tab, load_fields)

vis_product

Module_Product_Tabs(module var, product var)

Module_Product_Content(module var, tab, load_fields, product var)

Module_Product_Insert(module var, product var)

Module_Product_Delete(module var, product var)

Module_Product_Validate(module var)

Module_Product_Update(module var, product var)

vis_productbe

These functions apply when one edits products in Admin>>Store>>Products (screen PBED) and clicks Update.

Module_Product_BatchEdit_Validate(module var)

Module_Product_BatchEdit_Update(module var, product var)

Module_Product_BatchEdit_Delete(module var, product var)

vis_shipping

Module_Shipping_Validate(module var)

Module_Shipping_Update(module var)

Module_Shipping_Tabs(module var)

Module_Shipping_Content(module var, tab, load_fields)

Called when administrator hits update on Shipping Config screen. Admin calls this function when it needs to display Shipping Config screen.

vis_store

Module_Store_Validate(module var)

Module_Store_Update(module var)

Module_Store_Tabs(module var)

Module_Store_Content(module var, tab, load_fields)

vis_system

Module_System_Validate(module var)

Module_System_Update(module var)

Module_System_Tabs(module var)

Module_System_Content(module var, tab, load_fields)

vis_util

Module_Utility_Content(module var, tab, load_fields)

Module_Utility_Tabs(module var)

Module_Utility_Update(module var)

Module_Utility_Validate(module var)

vis_wizard

The vis_wizard functions relate to the wizard and store wizard interfaces in the same way that the standard vis functions relate to the administration interface. They provide Admin with configuration instructions specific to the module to which they belong.

Module_Is_Wizardable(module var)

The module should return 1 to indicate that the wizard ought to take notice of this module and ask it for further instructions about configuration. The module should return 0 to indicate that the wizard ought to ignore it.

Default Return: NULL

Module_Wizard_Validate_Step(module var, step)

Default Return: 1

Module_Wizard_Validate(module var)

Default Return: 1

Module_Wizard_Action(module var)

Default Return: 1

Module_Wizard_Content(module var, step, load_fields)

Default Return: 1

Module_Wizard_Summary_Fields(module var)

Wizard modules call this function.

This function should return a comma-separated list of field identifiers of the form id[,id,id,id-]. Wizard modules make use of this function along with Module_Wizard_Summary_Prompt and Module_Wizard_Summary_Field to create a table displaying the inputs provided by the administrator over the course of using the wizard.

Default Return: NULL

Module_Wizard_Summary_Prompt(module var, field_id)

Wizard modules call this function.

This function should return a text string for use as a field label or table heading. The value of the prompt is dependent upon the field_id parameter, received from the list set in Module_Wizard_Summary_Fields.

Default Return: NULL

Module_Wizard_Summary_Field(module var, field_id)

Wizard modules call this function.

This function should render the value of the field identified by the field_id parameter received from the list set in Module_Wizard_Summary_Fields. One would use it, for example, to fill in a table listing each of tax rates entered by the administrator during use of the wizard.

Default Return: NULL