Extension module example

[Mark Hughes]

A key element of Store Morph Technology is the item. Items contain information drawn from the database and also embody the ability to display that information in a particular way. Item extensions modify the data before the primary item displays it.

Underlying every item for use in templates is a component module. These modules contain the MIVA Script instructions that extract information from the database and make it accessible through the l.settings array and entity tags in the template. Component modules also contain the MIVA Script instructions that direct the creation of the HTML code that Empresa inserts in place of the item start and end tags when processing the template.

The Basket Contents module (cmp-mmui-basket), via its initialization function, loads the Basket Contents item (code = ?basket?) with the information about the products currently contained in the customer?s basket, along with any information about the product attributes, sales tax, shipping charges, subtotal, total etc.. It also contains instructions, in the render functions, about how to display that information.

The purpose of some component modules is to provide item extensions; that is to alter the data provided by another component module. With item extension modules, it is possible to adjust the information that, for instance, the Basket Contents item displays (perhaps, say, appending a 5 star rating to the end of selected product names), without having entirely to replace cmp-mmui-basket.mvc and alter the templates to point at a replacement basket item. Additionally or alternatively, one might choose to add additional pieces of information to an item, say, a count of all the products in the basket. Templates could then access this information through the l.settings array or via entities.

Plug the following pieces of code into the build system <http://smallbusiness.miva.com/support/docs/api/> to obtain a module capable of extending the Basket Contents (code = ?basket?) item. The first adjustment incorporated in this module is to add a setting by the name of ?prodcount? to the basket item. This item represents the number of products currently in the basket. Once you have this module assigned as an extension to the basket item, you will be able to use code in the template such as this below:

<mvt:if expr="l.settings:basket:prodcount">
<p>Total # of items in basket: &mvt:basket:prodcount;<p>
</mvt:if>


Note: the module as written does not automatically assign/unassign itself as an extension.

Is there additional information about the basket you would like to have available in the template?


Inputs to the build system to produce example extension module:

cmp-mv-basket_ext.mv
<MvComment>

Basket Contents Extension Component Module

</MvComment>

<MvFUNCTION NAME = "SubComponentModule_Initialize" PARAMETERS = "module var, item, all_settings var, settings var" STANDARDOUTPUTLEVEL = "">
<MvIFDEF NAME="DEBUG_TRACE">
<MvEVAL EXPR="{ '<HR color="#ff0000"> <b>' $ l.module:code $ ' <i>stub</i></b> SubComponentModule_Initialize(module var, item, all_settings var, settings var)<br>' }">
</MvIFDEF>

<MvCOMMENT>Add a new member to the structure containing settings for the basket contents item.</MvCOMMENT>
<MvASSIGN NAME = "l.all_settings:basket" MEMBER = "prodcount" VALUE = "{miva_array_elements(l.all_settings:basket:items)}">


<MvFUNCRETURN VALUE = "{1}">
</MvFUNCTION>


Makefile


# Basket Extension Module
#
#

MODULE_SOURCE= cmp-mv-basket_ext.mv
MODULE_CODE= cmp-mv-basket_ext
MODULE_NAME= Basket Extension
MODULE_PROVIDER= MIVA Small Business
MODULE_VERSION= 5.0000
MODULE_APIVERSION= 5.00
MODULE_FEATURES= component

include ../Makerules

[Kent Multer]

Mark, thanks for getting back to us on this question. A couple of follow-ups:

1. Is there any documentation on these "SubComponent" functions? I don't think we've seen anything about them before now. Any examples of this in the LSK?

2. In the future, please don't base your examples on the assumption that developers are using the build system. Considering that it's still a Beta release, and it's only available for Unix, I think it's safe to say that many of us aren't using it. In this example, the code is simple enough that I think I can figure out how to use it in my own projects; but next time, that may not be the case.

Thanks --

[Mark Hughes]

Hi Kent,

The "Sub" prefix to function names is a characteristic of the build system and explained in the build system's documentation. Sub functions correspond to the parent function by the same name without the "Sub" prefix. The quick answer is that any code in a "Sub" function in a source file used with the build system belongs in the "non-Sub" function of the corresponding name in a source file not used with the build system. So SubComponentModule_Intialize, is plain old ComponentModule_Initialize if the build system is not in use.

I note your request about not basing examples on the build system and will take your input into account. I will nonetheless continue to take advantage of the build system as a way of speeding the process by which I can test and release a working example. The presentation and format of information is important. It greatly increases its use to the audience. That said, getting the information out at all, and sooner rather than later, is still a higher priority for me. I hope it helps folks out there.

Happy coding,

Mark

[Kent Multer]

Hi Mark --

Can you answer another question about extensions, please?

I'm working on a component module now, which creates an Item that most users will want to display on all their store pages, in some common location: say, just below the global header. With a "normal" component, the only way to do that is to manually insert the mvt:item tag on every page.

Suppose users assign my new component module as an extension to the header/footer item. In that case, could my module be written to always render its HTML after the header? In other words, can extensions render HTML, or can they only manipulate variables such as l.settings?

Thanks --

[Jung]

Hi Mark

The message (module extension) is very helpful.
I really need to make an module extension, same as in your message.
I'm using MIVA Script compiler on Windows XP. I also downloaded MM5 API Module Build System.
Are those enough for me to build a module, or at least: a module extension.
Can you show me the steps compiling your sample?

Thank you very much for your help.

[Mark Hughes]

In other words, can extensions render HTML, or can they only manipulate variables such as l.settings?




Hi Kent,

Sorry to give you a long wait for a short answer: extensions do not render HTML.

[Mark Hughes]

Hi Mark

The message (module extension) is very helpful.
I really need to make an module extension, same as in your message.
I'm using MIVA Script compiler on Windows XP. I also downloaded MM5 API Module Build System.
Are those enough for me to build a module, or at least: a module extension.
Can you show me the steps compiling your sample?

Thank you very much for your help.

Hi Jung,

I'm glad my post helps. And best of luck with your module. As you know, you will need the compiler to create .mvc files from the .mv ascii files that you author. The command line syntax is easy enough: mvc [filename.mv].
To run your .mvc files, you need either a server equipped with Empresa, such as a host can provide, or to install MIVA Mia (available through our website) on your PC.

The Build System is optional. Probably the most immediate benefit it provides is to ensure that your modules include all the required functions. The list of required functions varies depending on the type of module. To run the Build System on your PC, you will need to install Cygwin, a popular unix/linux emulator for Windows, available for download through the web. The Build System uses unix tools such as "make" and "sed".

Mark

[Jung]

Hi Jung,

I'm glad my post helps. And best of luck with your module. As you know, you will need the compiler to create .mvc files from the .mv ascii files that you author. The command line syntax is easy enough: mvc [filename.mv].
To run your .mvc files, you need either a server equipped with Empresa, such as a host can provide, or to install MIVA Mia (available through our website) on your PC.

The Build System is optional. Probably the most immediate benefit it provides is to ensure that your modules include all the required functions. The list of required functions varies depending on the type of module. To run the Build System on your PC, you will need to install Cygwin, a popular unix/linux emulator for Windows, available for download through the web. The Build System uses unix tools such as "make" and "sed".

Mark

Thanks Mark,
I'm trying to build a module and your post helps me so much.
Thank you very much.

Jung

[Jung]

Hi Mark,
I tried to build your module extension example today. It was built sucessfully but when I uploaded and added to MM5, I had not seen this module when editing page.
Then I tried to add your sample code:

<mvt:if expr="l.settings:basket:prodcount">
<p>Total # of items in basket: &mvt:basket:prodcount;<p>
</mvt:if>

It displayed nothing about the product count. How I can use this example? or did I miss something?

In Make_Vendor_Data file, I see MVCOOL_PARTNERID and SECRET_KEY variables. Are they importance to build module, and if so how can I get these values?

Thank you.

[Mark Hughes]

Hi Jung,

The do***entation on the build system briefly describes the MVCCOOL_PARTNERID and SECRET_KEY variables. The build system incorporates MVCCOOL_PARTNERID into the product code, if I remember correctly, to help make it easier to sell the modules through MIVA Central. The SECRET_KEY variable makes it harder for others to steal your code.

As for not seeing the module, did you assign it as an extension of the basket item?

You might also try building the module using the DEBUG flag, described in the readme file that comes with the build system. That will help you to determine when the module functions and when it does not.

HTH,

Mark

[Jung]

Hi Jung,

The do***entation on the build system briefly describes the MVCCOOL_PARTNERID and SECRET_KEY variables. The build system incorporates MVCCOOL_PARTNERID into the product code, if I remember correctly, to help make it easier to sell the modules through MIVA Central. The SECRET_KEY variable makes it harder for others to steal your code.

As for not seeing the module, did you assign it as an extension of the basket item?

You might also try building the module using the DEBUG flag, described in the readme file that comes with the build system. That will help you to determine when the module functions and when it does not.

HTH,

Mark
Hi Mark,
Thanks for your help.
As you mean in reply, if I build module only for my website, I don't need the MVCCOOL_PARTNERID variable, and I can assign it any value?
I did every step as shown in your Extension module example. How can I assign it to be an extension of basket item?

I think Miva Merchant is a simple and good solution to make an online store, and I planed to build up some more online stores using MM5. But now I am stuck in MM5 modules, and your post is my only hope to build my own modules.

At present, I need to arrange product attributes on product page with specific layout (extract seperated atribute and put it on page at specific position). Do you have advices for me?

Thanks for your help
Jung

[Mark Hughes]

Hi Jung,

Correct, you can use any alphanumeric string for MVCOOL_PARTNERID, say for instance "jung".

Manual procedure to assign an item as an extension to another item:

1) In the administration interface, navigate to the "Edit Item" screen for the item you want to extend:
a) Left menu: Click Stores>>[Your store name]>>Pages
b) Main frame: Click "Items" tab.

2) Click "Edit" for the item you are interested in--in this case "basket".

3) Click the "Extensions" tab.

4) Click the "Add Extension" button.

5) Select your component module from among the list that appear.

HTH,

Mark

[wcw]

Hi Jung,
Manual procedure to assign an item as an extension to another item:


Mark,

Since this thread is about a module to extend an item, it would be nice to know how to do it automatically instead of the manual instructions above. Could we have an example of the automatic way of doing it?

[sebenza]

Example:
<MvIF EXPR = "{ NOT [ g.Module_Feature_TUI_MGR ].TemplateManager_Create_ItemExtension( 'basket', l.module:code ) }">
<MvFUNCTIONRETURN VALUE = 0>
</MvIF>

[wcw]

Thanks. That did the trick.