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

What MIVA Says

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

Required function: TaxModule_Order_Hide_Fields [back]

Parameters:

  • module var

Return Type:bool

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

What MIVA Says

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

Required function: TaxModule_Order_Fields [back]

Parameters:

  • module var

Return Type:cslist

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

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="TaxModule_Order_Fields" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
   <MvFUNCTIONRETURN VALUE="test1,test2">
</MvFUNCTION>

Required function: TaxModule_Order_Prompt [back]

Parameters:

  • module var
  • field_id

Return Type:string

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

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="TaxModule_Order_Prompt" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
   <MvIF EXPR="{ l.field eq 'test1'}">
      <MvFUNCTIONRETURN VALUE = "First Test Field:">
   <MvELSEIF EXPR="{ l.field eq 'test2'}">
      <MvFUNCTIONRETURN VALUE = "Second Test Field:">
   </MvIF>
</MvFUNCTION>

Required function: TaxModule_Order_Required [back]

Parameters:

  • module var
  • field_id

Return Type:

<MvFUNCTION NAME="TaxModule_Order_Required" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
</MvFUNCTION>

What MIVA Says

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

Required function: TaxModule_Order_Invalid [back]

Parameters:

  • module var
  • field_id

Return Type:boolinv

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

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="TaxModule_Order_Invalid" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
   <MvIF EXPR="{ miva_variable_value( 'g.apitest_taxfield_' $ l.field $ '_invalid' ) }">
      <MvFUNCTIONRETURN VALUE="1">
   </MvIF>
   <MvFUNCTIONRETURN VALUE="">
</MvFUNCTION>

Required function: TaxModule_Order_Field [back]

Parameters:

  • module var
  • field_id

Return Type:

<MvFUNCTION NAME="TaxModule_Order_Field" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
</MvFUNCTION>

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="TaxModule_Order_Field" PARAMETERS="module var,field_id" STANDARDOUTPUTLEVEL="">
   <MvIF EXPR="{ l.field eq 'test1'}">
      <MvEVAL EXPR = "{ '<input type="text" name="apitest_taxfield_test1" value="'$ encodeattribute(g.apitest_taxfield_test1) $'" size="25">
' }">
   <MvELSEIF EXPR="{ l.field eq 'test2'}">
      <MvEVAL EXPR = "{ '<input type="text" name="apitest_taxfield_test2" value="'$ encodeattribute(g.apitest_taxfield_test2) $'" size="25">
' }">
   </MvIF>
</MvFUNCTION>

Required function: TaxModule_Order_Validate [back]

Parameters:

  • module var

Return Type:bool

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

What MIVA Says

MIVA Merchant calls Action_Save_OrderInformation in response to form submission containing Action=ORDR, 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

Example 1:

<MvFUNCTION NAME="TaxModule_Order_Validate" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
   <MvIF EXPR="{ NOT g.apitest_taxfield_test1 }">
      <MvASSIGN NAME="g.apitest_taxfield_test1_invalid" VALUE="1">
      <MvASSIGN NAME="l.invalid" VALUE="1">
   </MvIF>
   <MvIF EXPR="{ NOT g.apitest_taxfield_test2 }">
      <MvASSIGN NAME="g.apitest_taxfield_test2_invalid" VALUE="1">
      <MvASSIGN NAME="l.invalid" VALUE="1">
   </MvIF>
   <MvIF EXPR="{ l.invalid }">
      <MvFUNCTIONRETURN VALUE = "0">
   </MvIF>
   <MvFUNCTIONRETURN VALUE="1">
</MvFUNCTION>

Required function: TaxModule_Calculate_Basket [back]

Parameters:

  • module var

Return Type:bool

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

What MIVA Says

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

Example 1:

<MvFUNCTION NAME="TaxModule_Calculate_Basket" PARAMETERS="module var" STANDARDOUTPUTLEVEL="">
   <MvASSIGN NAME = "l.basket_charge:basket_id" VALUE = "{ g.Basket:basket_id }">
   <MvASSIGN NAME = "l.basket_charge:module_id" VALUE = 0>
   <MvASSIGN NAME = "l.basket_charge:type" VALUE = "TAX">
   <MvASSIGN NAME = "l.basket_charge:descrip" VALUE = "Forced Test Tax">
   <MvASSIGN NAME = "l.basket_charge:amount" VALUE = "1.23">
   <MvASSIGN NAME = "l.basket_charge:disp_amt" VALUE = "1.23">
   <MvASSIGN NAME = "l.basket_charge:tax_exempt" VALUE = 0>
   <MvFUNCTIONRETURN VALUE = "{ [ g.Module_Library_DB ].BasketCharge_Insert( l.basket_charge ) }">
</MvFUNCTION>

Required function: TaxModule_ProcessOrder [back]

Parameters:

  • module var

Return Type:bool

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

What MIVA Says

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

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.