VirtueMart 1.0 Developer's Guide
VirtueMart Developer Manual
Soeren Eberhardt(www.virtuemart.net [http://www.virtuemart.net])
Copyright © 2005 Soeren Eberhardt
This document is published under the Open Content License available from
http://www.opencontent.org/opl.shtml [http://www.opencontent.org/opl.shtml]
Revision History
Revision 1.1 November 21, 2005 soeren_nb
Update for VirtueMart
Revision 1.0 June 29, 2005 soeren_nb
Initial Release (mambo-phpShop v1.2 stable-pl3)
Table of Contents
1.Preambel..............................................................................................................................1
2.Introduction..........................................................................................................................1
3.Basics..................................................................................................................................3
4.ModifyingtheLayout ............................................................................................................. 12
5.CreatingormodifyingExtensions ............................................................................................. 13
6.AbouttheProject ................................................................................................................... 18
1. Preambel
The content of this document is related to VirtueMart.
VirtueMart is free Software, licensed under GNU/GPL; VirtueMart [ http://www.virtuemart.net ]
Conversion to Joomla and much more: © 2005 Sören Eberhardt
The Software 'VirtueMart' is intended for use in Joomla and Mambo (version 4.5.1 and 4.5.2.x). Joomla or
Mambo are required for running VirtueMart.
(Joomla / Mambo is free Software, licensed under GNU/GPL)
The abbrevation VM, which stands for VirtueMart is used in this document.
2. Introduction
2.1. History
VM has its roots in a Shop Script called phpShop. This script was developed by Edikon Corp. and the phpShop
community (see www.phpshop.org [http://www.phpshop.org]).
VM was forked from phpShop version 0.8.0 at the end of the year 2003. It was maintainend and developed under the name Joomla-phpShop until September 2005. In October 2005it was renamed to VirtueMart.
1
VirtueMart Developer Manual
2.2. Differences to phpShop
VM still contains some code parts from phpShop, but experiences phpShop coders will see similarities.
So when you have experience with phpShop or you are to integrate an existing Add-On for phpShop into VM,
you will have to know what is the difference between both scripts.
1. Parameter Renames/Changes
VM has introduced several new parameters and parameter name changes.
page Syntax Change Most important is the change of the page parameter syntax from a pattern
like "shop/index" to "shop.index" just to provide support for Search Engine Friendly
(SEF) links in your Joomla site. All references to the paramter page that contain a slash
instead of a dot will not be recognized and VM will print out "module not found" error.
offset Outdated/removed The offset parameter was completely replaced by the parameter "limit-
start", which is Joomla standard for page navigation. Although there's a global
workaround to fill $offset with the value of $limitstart it's not recommended to work with
offset.
limitstart The limitstart parameter is the replacement for offset and can be used just like this.
Itemid This parameter is new and not VM-specific. It's a mandatory parameter that tells Joomla,
which Menu Item is selected and active, so the pathway can be written correctly (Home -
> Online-Shop) and modules which shall only be shown on specific pages are hidden/
shown.
2. Database Interface
phpShop has its own database class: ps_DB, in a file called db_mysql.inc. This database class has been
completely modified to be a wrapper class for the Joomla Standard Database Class 'database'. The new filename is ps_database.php. The class name is still ps_DB, but its a Child Class of the Joomla database
class (class ps_DB extends database) and inherits all methods and properties. This has a lot of advantages:
the class is safe against Joomla database class changes and it provides backward compatibility for the
masses of database calls and queries in the scripts (which don't use the Joomla functions, but the phpShop
functions!). VM doesn't connect to the database, but it uses the connection Joomla has built up. This is for
optimal performance since VM doesn't connect to the database each time a query is to be run.
3. Database Structure
Table names have changed and got a prefix!! Use #__{vm}_tablename instead of tablename. The #__
stands for the dynamic Joomla table name prefix. The {vm} stands for the dynamic table name prefix of
VM which allows to have more than one shop in one database.
The database structure of phpShop had to be changed, because Joomla provides an excellent framework
with session handling and user management. The following tables have been removed:
• auth_user_md5 (jos_users stores passwords)
• intershipper
• language
• sessions
There have been added several tables: jos_pshop_affiliate, jos_vm_affiliate_sale, jos_vm_creditcard,
jos_vm_manufacturer, jos_vm_manufacturer_category, jos_vm_product_download,
jos_vm_product_mf_xref, jos_vm_product_reviews, jos_vm_product_votes, jos_vm_shipping_carrier,
jos_vm_shipping_rate, jos_vm_visit, jos_vm_waiting_list, jos_vm_zone_shipping.
4. Session handling
2
VirtueMart Developer Manual
Joomla provides a framework with session handling - no need to have an own session class! No hidden_session() calls are needed anymore. The existing session class has become the global link formatter!
The functions url and purl are needed to format links SEF or append the Itemid parameter.
5. Separation into component and modules
A Joomla site consists of various elements like components, modules, templates and Mambots - most likely
you will know components, modules and templates. A Component is the Main Part of the Page in the
"Main Body". Can be installed/uninstalled trough the Component Manager and have their own configuration/interface. Modules are sideblocks surrounding the Main body. They can be installed/uninstalled and
configured using the Module Manager. The Main application "VirtueMart" is run in the component part.
The Component contains all core files. The module "mod_virtuemart" was written to provide all important
links so the component can be controlled: Category links, Mini-Cart, Product Search Form, Account Maintenance, Admin.
2.3. Joomla Integration
The Joomla Integration of VM is very special, because of its origin. It doesn't completely comply to Joomla's
Component Coding Standards. VM uses some own functions for database access, page navigation, search and
listings. By using old code from phpShop, this little bit of compatiblity can be maintained (so one can integrate
extensions written for phpShop).
3. Basics
3.1. Directory and File Structure
VM holds most of its files in the /administrator part of Joomla. The only files stored in the /
components part of a Joomla site are those, which must be accessible from the Frontend of a Joomla site,
even when the Administrator part is secured by htaccess files.
/administrator/components/com_virtuemart/
Contains file for the administration interface of VM. Because the administrative interface is also accessible from the frontend, those files are not
restricted to the Joomla Coding Standards. Important files:
• header.php (Code for the Drop-Down Menu of the administration)
• virtuemart.cfg.php (central Configuration File)
• toolbar.phpshop.html.php (controls the administrative Toolbar)
/administrator/components/com_virtuemart/classes/
Holds all the core classes which are used by VM Important:
• ps_database.php (wrapper for Joomla's database object
$database)
• ps_cart.php (controls the cart contents)
• ps_main.php (not a class, contains central functions, e.g. for image
upload)
• ps_session.php (basic session management, URL formatting)
/administrator/components/com_virtuemart/classes/Log/Contains a slightly modified version of PEAR's Log class
3
VirtueMart Developer Manual
/administrator/components/com_virtuemart/classes/shipping/
Contains Shipping Modules & their informational Files
/administrator/components/com_virtuemart/classes/payment/
Contains Payment Modules & their informational Files
/administrator/components/com_virtuemart/classes/pdf/
Contains the classes of the HTML2FPDF Package (see source-
forge.net/projects/html2fpdf [http://sourceforge.net/projects/html2fpdf])
/administrator/components/com_virtuemart/classes/phpInputFilter/contains the phpinputfilter class for VirtueMart
/administrator/components/com_virtuemart/classes/phpmailer/
Contains the classes of the phpMailer Package (also used by Joomla and
Mambo) - see phpmailer.sourceforge.net/
[http://phpmailer.sourceforge.net/].
/administrator/components/com_virtuemart/html/
Holds files which are used for presentation of HTML Code.
They are ordered by shop core module name (e.g. checkout.*.php for the
core module checkout)
Important files:
• basket.php (controls the Cart)
• ro_basket.php (controls the Cart on the last step of checkout, ro
= read only)
/administrator/components/com_virtuemart/html/templates/
Contains Templates for some pages
../basket Templates for Cart Display.
../browse Templates for Product Listing Pages (can be
../order_emails Templates for the Order Confirmation Email
../product_details Templates for the Product Details Pages.
/administrator/components/com_virtuemart/languages/
Contains the Language Files which are included from virtuemart_parser.php.
/administrator/components/com_virtuemart/sql/
Holds SQL Dump Files for building up the structure for the tables used
by VirtueMart.
assigned in the Category Form)
/components/com_virtuemart/
Holds the files wich are used to control the call of the Shop from the
Frontend.
Important files:
• virtuemart.php (the file included by Joomla on a call to in-
dex.php?option=com_virtuemart&....)
4
• virtuemart_parser.php (the central file for VM, prepares
• show_image_in_imgtag.php (used to display dynamically re-
/components/com_virtuemart/css/
Contains the shop's css file (shop.css) and css styles needed for the
frontend administratin (admin.css)
/components/com_virtuemart/js/
Contains Javascripts (WebFX – Tabs, JSCookTree and the IEPNG-Transpareny Fix)
/components/com_virtuemart/shop_image/
/availability Contains images for displaying the availability of a
Tip
VirtueMart Developer Manual
the session, authentication, cart & runs functions)
sized images - using the class.img2thumb.php)
product.
All images in this folder are automatically parsed and displayed in the product form for selection as the
availability image for a product - so just copy them here.
/category Contains images for categories
/product Contains Product Images + resized product images
/ps_image Images for the administrative interface
/vendor Vendor Logos
3.2. Main Flow Chart
3.2.1. Joomla Part
Joomla uses the variable option to load a specific component. This variable must have the value
"com_virtuemart" to load VM. Called on the Frontend, Joomla searches the directory /components for a directory called com_virtuemart and a file called virtuemart.php in it.
When called in the backend, Joomla searches the directory /administrator/components for a directory
called com_virtuemart and a file called admin.phpshop.php in it.
If found, the file is included.
3.2.2. Shop Part
When the Shop is loaded, one of the first things is to load the file virtuemart_parser.php using the require_once command. It makes core interactions like the Joomla.php file /mainframe class and after that looks
for a variable called page (can be passed by GET or POST).
The page variable consists of the pagename and the core module name:
shop.browse => shop is the name of the shop core module and browse is the name of the page.
Tip
5
VirtueMart Developer Manual
Core modules are listed in the table mos_vm_modules.
Calling index.php?com_virtuemart&page=shop.browse in your Joomla site would let VM include
the file
/administrator/components/com_virtuemart/html/shop.browse.php.
3.3. Core Modules & their Functions, Environment Variables
3.3.1. Core Modules
In order to ease with which new features can be added to mp, the concept of using modules has been introduced.
A module defines a feature set of VM by providing class files and html layouts related to that particular module.
It is very important to understand how modules work since everything, including the shop, is a module.
Each module is defined and set in the VM module register. The module definition form allows the site administrator to define the information for each module, e.g. the module name, the perms of this module and its description.
You can reach the module list in the administrative interface using "Admin" => "List Modules".
Example: The core module "product" is one entry in the table mos_vm_module. Its pages must be called using
"..&page=product. ....". If the user has appropriate permissions, the page is loaded - if not, an error message is
generated.
3.3.2. func
Each core module has a list of functions that can be executed. For example, to add a product into the system, a
function called productAdd exists in the table mos_vm_function.
When you add a product, you pass the hidden variable func with a value of productAdd to the system (besides
all the other form fields).
If the current user has the permissions to execute the function (permissions can be set for each function separately), the file virtuemart_parser.php looks for the class file name and the function name mapped in
the table mos_vm_function for that specific function name (productAdd). In this case we get ps_product
as the class name and add as the function name.
After having fetched this information, we can start to execute the real function, which is done in this part of
virtuemart_parser.php:
// Load class definition file
require_once( CLASSPATH.$db->f("function_class").".php" );
// create an object
$string = "\$" . $func_class . " = new " . $func_class . ";";
eval( $string );
// RUN THE FUNCTION
$cmd = "\$ok = \$" . $func_class . "->" . $func_method . "(\$vars);";
eval( $cmd );
First, the file ps_product.php is loaded, then an object of the class ps_product is created and the function add is called on that object. The function returns true on success and false on failure. The variable $ok
stores the function result. All this code is exectuted using the PHP eval command for creating and executing
PHP code on-the-fly.
6
Loading...