MIVA Merchant 5 Module API Feature shipping
MIVA Merchant 5 Module API Overview MIVA Merchant 5 Module API Table of Contents MIVA Merchant 5 Module API Tid Bits

What MIVA Says

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

Required function: ShippingModule_Description [back]

Parameters:

  • module var
  • data

Return Type:string

<MvFUNCTION NAME="ShippingModule_Description" PARAMETERS="module var,data" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

What MIVA Says

Admin calls this function when displaying the standard batch report.

It returns a textual description of the module.

Default Return: NULL

Required function: ShippingModule_Report_Fields [back]

Parameters:

  • module var

Return Type:cslist

<MvFUNCTION NAME="ShippingModule_Report_Fields" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

What MIVA Says

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)

Required function: ShippingModule_Report_Label [back]

Parameters:

  • module var
  • field_id

Return Type:string

<MvFUNCTION NAME="ShippingModule_Report_Label" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Report_Value [back]

Parameters:

  • module var
  • field_id
  • data

Return Type:string

<MvFUNCTION NAME="ShippingModule_Report_Value" PARAMETERS="module var,field_id,data" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Shipping_Methods [back]

Parameters:

  • module var
  • methods var

Return Type:acount

The method parameter is expected to be populated with an array of methods. The structure of the array is three fields, code, name, and price. With code being the unique to the module method code that allows it to tell one method from another, and the name being the visible text that appears in the drop down list or wherever the UI renders it, and the price being the price of that method

<MvFUNCTION NAME="ShippingModule_Shipping_Methods" PARAMETERS="module var,methods var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="0">
</MvFUNCTION>

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="ShippingModule_Shipping_Methods" PARAMETERS="module var,methods var" STANDARDOUTPUTLEVEL="">
   <MvASSIGN NAME="l.methods[1]:code" VALUE="meth1">
   <MvASSIGN NAME="l.methods[1]:name" VALUE="Method 1">
   <MvASSIGN NAME="l.methods[1]:price" VALUE="1.23">
   <MvASSIGN NAME="l.methods[2]:code" VALUE="meth2">
   <MvASSIGN NAME="l.methods[2]:name" VALUE="Method 2">
   <MvASSIGN NAME="l.methods[2]:price" VALUE="4.56">
   <MvFUNCTIONRETURN VALUE="2">
</MvFUNCTION>

Required function: ShippingModule_Calculate_Basket [back]

Parameters:

  • module var
  • data

Return Type:bool

<MvFUNCTION NAME="ShippingModule_Calculate_Basket" PARAMETERS="module var,data" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Order_Validate [back]

Parameters:

  • module var

Return Type:bool

<MvFUNCTION NAME="ShippingModule_Order_Validate" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Order_Update [back]

Parameters:

  • module var

Return Type:bool

<MvFUNCTION NAME="ShippingModule_Order_Update" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Order_Delete [back]

Parameters:

  • module var

Return Type:bool

<MvFUNCTION NAME="ShippingModule_Order_Delete" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

What MIVA Says

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

Required function: ShippingModule_Order_Tabs [back]

Parameters:

  • module var

Return Type:cclist

<MvFUNCTION NAME="ShippingModule_Order_Tabs" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

What MIVA Says

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}

Required function: ShippingModule_Order_Content [back]

Parameters:

  • module var
  • tab
  • load_fields

Return Type:bool

<MvFUNCTION NAME="ShippingModule_Order_Content" PARAMETERS="module var,tab,load_fields" STANDARDOUTPUTLEVEL="">
    <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

What MIVA Says

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

Return Types [back]

Return Types are expressed in the document by the following codes:

  • string: A string return type is any string you wish though normally it is a string that has a specific intent such as the formatted version of a decimal number as you might use in a currency module.
  • cslist: This is a comma separated list values. Most commonly used to return a list of codes for fields.
  • cclist: This is a comma separated list of colon separated values. Most commonly used as a return from tab functions so that you might have a value like "NVALS:Normal Values,SPECVALS:Special Values,OVALS:Other Values" and the system would be treating each comma separated pair as a tab and using the value on the right of the colon as the label for the tab and the value on the left of the colon as the code for the tab.
  • bool: A boolean "true/false" return value, normally a "1" represents a true value and a "0" represents false. Because of the way the MIVA script language treats strings and numbers any string other than a space, and any number other than a 0 will be treated as a true return value whereas a false value can be expressed by a null value like "" or an expression that evaluates to null or zero like "{ 1 - 1 }" or the absence of the "VALUE" attribute entirely.
  • boolinv: An inverted boolean "true/false" return value. This is when the value returned is a boolean value just like the type "bool" but that the normal default return is a false rather than a true value and that you only return true if some special case is true. In the MIVA Merchant API Most functions that are boolean expect a return of true unless something has gone wrong or some special condition occurs, but in this case it is "normal" to return a false value and you only return a true value if something unusual happens. A specific example would be the TaxModule_Order_Invalid function which only returns a true value if one of the fields is invalid.
  • tristate: Acts like a boolean except that a negative value, usually -1 by convention, indicates an unusual but non error state. In most cases this will be used to cause the normal operations to not be completed without causing an error to be output in order to interrupt something that the system was about to do. This is used for example in system extension interrupts to stop a normal action like adding a product to the basket from taking place so the module can take on the role of adding the item to the basket itself, or preventing it from happening without causing the system to throw the normal errors.
  • acount: This is a numeric value that represents a count of the size of an array passed back by reference. A null or 0 return value acts the same as for a bool return type, meaning nothing happens, but a value of 1 indicates only one array index point exists whereas a return of 3 indicates 3 array index points returned. This is used for example in the shipping and payment method functions that have a method parameter passed in by reference and the return indicates the size of the method array being set in the l.method variable.

For information and function requirements for the various MIVA Merchant 5 Module API Feature Codes see the following:
batchreport, component, component_prov, currency, custrt, data_domain, data_store, export, externalreq, fields_cust, fields_prod, fulfill, import, log, not_fields, payment, provision_store, shipping, storeselui, storewizard, system, tax, upload, util, wizard, vis_affil, vis_affilbe, vis_category, vis_categorybe, vis_cust, vis_custbe, vis_domain, vis_fulfill, vis_log, vis_order, vis_payment, vis_product, vis_productbe, vis_shipping, vis_store, vis_system, vis_util, vis_wizard

This document is copyright 2005-2006 4TheBest eCommerce Solutions and was last generated using Serade on 01/13/2006 23:04:54. It is permissible to place a copy of this document in it's current or altered form on your website as long as you leave the copyright notice along with the links to the websites referenced intact.