About Components

MIVA Merchant Component Modules are the main means by which developers can influence the user interface of a MIVA Merchant store. Components that ship with MIVA Merchant 5 include the fonts, headers and footers, colors, product lists, search results, and pretty much everything else. At the core of things a MIVA Merchant 5 store user interface is made up of pages each of which is a template that is plain html code and tokens that represent output by components. That's basically it, so understanding how components work is essential.

Using Components

MIVA Merchant Component Modules are used in templates in basically two ways, either by calling the component using the MIVA Merchant template language ""mvt:item" tag, or by using a MIVA Template language item entity referencing a setting the component has set.

The tag to call an item looks like this: <mvt:item name="itemname" param="parameter"> and at the point where that tag is found in the template the ComponentModule_Render_Start function will be called in the component, and where the closing tag is displayed, which looks like this </mvt:item>, the ComponentModule_Render_End function is called. Note also that the _End function will be called right after the _Start function if you do this <mvt:item name="itemname" param="parameter" /> which is programmatically the same as doing this <mvt:item name="itemname" param="parameter"></mvt:item>.

An item entity reference looks like &mvt:itemname:settingname;. The settings would be set by adding them to the l.settings structure when MIVA Merchant makes the call to ComponentModule_Initialize which happens before any portion of the page is displayed. In fact you can have a component that does nothing but load a bunch of values into it's l.settings and it coudl be very useful to a template depending on the values it was making available. A good example of that can be found by looking at the breadcrumbs example module.

Note: the name of an item is not the same as the code of the component module. The MIVA Merchant administrator editing the templates can add new items to a page and when they do so they choose what name the item is given and what MIVA Merchant module will be called when that item name is used. In fact the same MIVA Merchant module could be assigned to three different item names and both could be referenced on the same page. When this happens the ComponentModule_Initialize function will be called twice. If you need or want to know what item name your module is being called as you can reference the l.item variable which is available in the appropriate functions. Note also that when your module is added as an item to a page the

Example modules using the feature component

• 4TheBest Loop Counters
  This module is a component that can be used in templates to create and increment counters. A common use would be inside a foreach loop to do something like break after every third item.
• 4TheBest Save data using settings API example
  This module shows how to use the MIVA Merchant 5 API l.settings structure to store data for your module without you needing to create a data table.
• 4TheBest Load Child Cats To Array
  This module demonstrates the loading of an array into settings so that you can use the array in a template using a foreach loop.
• 4TheBest Category Bread Crumbs
  This module demonstrates the use of ComponentModule_Initialize by pre-populating a bread crumb trail for the current category which can be accessed by using &mvt:itemcode:breadcrumbs; in a template.
• 4TheBest Product Bread Crumbs
  This module displays a category/product bread crumb trail for the current category/product which can be accessed by using <mvt:item name="itemcode" /> in a template, and demonstrates existing store table access using the g.Store_Table_Prefix variable, use of l.settings, and l.all_settings.
• 4TheBest View Variable Value
  This module is a simple component that lets you output the value of a variable named in the parameter passed to the componenet. If the variable named is an array/structure it serializes the data and adds break tags after each index/member.
• 4TheBest Product Image Detect
  This module loads an array of products with flags saying whether or not a thumbnail or fullsize image that was specified is missing.

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.