VirtueMart Developer Manual Soeren Eberhardt-Biermann
VirtueMart Developer Manual Soeren Eberhardt-Biermann Copyright © 2005-2007 Soeren Eberhardt-Biermann This document is published under the Open Content License available from www.opencontent.org/opl.shtml] http://www.opencontent.org/opl.
Table of Contents Preamble .................................................................................................................... ix 1. Introduction .............................................................................................................. 1 1.1. History ........................................................................................................... 1 1.2. Differences to phpShop .....................................................................................
vi
List of Figures 4.1. Payment Method Form, Tab 1 ................................................................................. 20 4.2. Payment Method Form, Tab 2 .................................................................................
viii
Preamble 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-2007 Sören Eberhardt-Biermann The Software 'VirtueMart' is intended for use in Joomla! and Mambo (versions 4.5.1 - 4.6.2). 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.
x
Chapter 1. Introduction 1.1. History VM has its roots in an Open Source Shopping Cart 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 mambo-phpShop until September 2005. In October 2005 it was renamed to VirtueMart. 1.2.
Joomla! Integration 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.
Chapter 2. Basics 2.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.
Directory and File Structure 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 loading VirtueMart pages. They are ordered by the core module name (e.g. checkout.*.php for the core module checkout) Important files: • basket.php (controls the Cart) • ro_basket.
Main Flow Chart for selection as the availability image for a product - so just copy them here. /components/com_virtuemart/ themes Directory/File /category Contains images for categories /product Contains Product Images + resized product images /ps_image Images for the administrative interface /vendor Vendor Logos Contains the themes for VirtueMart. Each theme has the following structure: Function /admin.css the stylesheet for the frontend administration /theme.config.
Shop Part 2.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.
Other important Environment variables // Load class definition file require_once( CLASSPATH."$class.php" ); $classname = str_replace( '.class', '', $funcParams["class"]); if( !class_exists(strtolower($classname))) { $classname = 'vm'.$classname; } if( class_exists( $classname )) { // create an object $$classname = new $classname(); // RUN THE FUNCTION // $ok = $class->function( $vars ); $ok = $$classname->$funcParams["method"]($vars); } First, the file ps_product.
Logging events with the vmLogger object These are the example settings for an unregistered, not-logged-in user. ps_session $sess Mainly used to format and print URLs for the Shop. 2.3.4. Logging events with the vmLogger object VirtueMart allows logging events that occur during the execution of the script. The global variable $vmLogger, which is used for logging purposes is an object of the class Log_display. This class is a child class of the Log class, which is a PEAR extension.
Database Structure • $vmLogger->warning( 'My warning message to the user' ); // Mainly used to t • $vmLogger->notice( 'My Notice to the user' ); • $vmLogger->info( 'My informational message to the user' ); // Used to give • $vmLogger->debug( 'My debug message to the user' ); // Only displayed when • $vmLogger->tip( 'My advice to the user' ); // Used to display Advice messag 2.4. Database Structure As said before, all Tables used for VM begin with the prefix _vm_.
User Integration 2.6. User Integration VM uses Joomla's user table jos_users for the User Management. Users which are no customers, have just empty values in their additional customer fields in that table. There can be users who are no customers, but there can't be customers who are no registered users on the Joomla Site. The Shop has an own registration procedure which adds all entries for the additional user fields durch (assigning the customer to a shopper group, to a vendor...
Chapter 3. Modifying the Layout The most important part of the Layout of your Shop is the Joomla template (Joomlahut.com [http:// mambohut.com/] is a good start)! 3.1. Themes and Templates Starting with version 1.1, VirtueMart offers to style the shop using themes and templates. 3.1.1. Themes 3.1.1.1. Introduction A theme is what defines certain parts of the look and feel of your shop. All installations of VirtueMart should start out with the default theme.
Templates A template is a file holding HTML and PHP code for displaying a page or a part of it. Example: the file /templates/product_details/flypage.tpl.php. It is used to display details of a product. 3.1.2.2. Placeholders or Variables? You might want to know which placeholders or variables are available to style and display certain details...well that differs from template to template. The reason for this is that all variables must be imported into the template before you can use them.
Templates product_url The Product URL product_in_stock The Number of Products currently in Stock product_available_date The UNIX Timestamp for the Product Availability Date product_availability The Product Availability String product_special Y or N, is the product on special? product_discount_id The Product's Discount ID cdate The Product's Creation Date (UNIX Timestamp) mdate The Product's last Modification Date (UNIX Timestamp) product_sales The Number of Sales of this Product product_u
Templates edit_link The link to the product form of this product (admin only) ask_seller The link to the "Ask a question about this product" page related_products The list of related products navigation_childlist The child categories for the current category (this product is located in) images The object list of all additional images this product has files The object list of all additional files this product has Predefined Variables for the Browse Page / Product Listing Templates 14 product_n
Templates files The object list of all addtional files this product has buttons_header The PDF, Email and Print buttons browsepage_header The heading, the category description parameter_form The Parameter search form orderby_form The sort-by, order-by form PLUS top page navigation navigation_pathway The pathway to the product (Power Tools # Outdoor Tools # Chain Saw) navigation_childlist The child categories for the current category (this product is located in) browsepage_footer The footer w
Finding the right File 3.2. Finding the right File When you want to modify a part of your Shop (that can't be changed in its layout using the Joomla template's CSS), you must of course know, which file you have to modify, to create the layout you want. To quickly find the file, which produces the HTML output you're seeing, you can enable the DEBUG mode ("Admin" # "Configuration" # "Path & URL" # check "DEBUG?" and save.
Basket Templates 3.3.4. Basket Templates Basket templates control the layout of the basket. The templates can be found in the directory /themes/VM_THEME/templates/basket/. The special about the basket is that there are four different templates: Two for displaying the Cart content including Tax (basket_b2c.html.php and ro_basket_b2c.html.php) and two for displaying the Cart content without tax (adding it afterwards) - basket_b2b.html.php and ro_basket_b2b.html.php.
18
Chapter 4. Creating or modifying Extensions Besides core modules, you can also add shipping and payment modules into VM. The concept of both - shipping and payment modules is to provide an API with a defined specification (similar to an interface), where the modules can plug themselves in. The modules implement the required functions and thus can communicate with the Shop and give their services. 4.1. Payment Modules VirtueMart has a lot of predefined payment methods.
Quick-Create a new payment method Figure 4.1. Payment Method Form, Tab 1 Note Be sure that you have NOT selected "credit cart payment" or "automatic processor". On the second tab you must fill your form code (you can use HTML and PHP!) into the text area called "Payment Extra Info": Figure 4.2.
Implementation Details Caution The code inside this form MUST BE VALID! If you use PHP code, check if you have written correct code that can be parsed! 4.1.3. Implementation Details Important The information in this section only applies to situations when you want to implement a new payment method of the type “Payment Processor” or “HTML-form-based” (simliar to PayPal).
Installing a Payment Module returns true if the configuration file for that payment module is readable, false if not void write_configuration( Array ) Stores all configuration values for this payment module in the configuration file. boolean process_payment(String $order_number, Float $order_total, Array &$d) This is the main function for all payment modules that use direct connections to a payment gateway (like authorize.net or eWay XML).
The Shipping API specification • myShipping.cfg.php (containing all necessary configuration constant definitions) When activated in the Shop configuration, this payment module will be loaded on the shipping method selection screen, beside all other activated shipping modules. The shipping rate, a user has selected during checkout is passed from step to step by the parameter shipping_rate_id.
Installing a Shipping Module returns true if the configuration file for that module is writeable, false if not Note Please always change configuration variables in both functions: show_configuration and write_configuration! 4.2.3. Installing a Shipping Module Shipping modules also can't be automatically installed, but you must copy the three files mentioned above into the directory /administrator/components/com_virtuemart/classes/shipping/.
Chapter 5. Developer Guidelines 5.1. General 5.1.1. Using and updating the Changelog The file CHANGELOG.txt contains the Changelog for the recent Major version of VirtueMart. For every change you make to the source code you must make an entry to that Changelog. Please use the date, your dev.virtuemart.
Accessibility All SQL queries must be compatible with at least MySQL version 4.0. 5.1.2.3. Mambo version compatibility Future versions of VirtueMart will support Mambo versions from 4.5.1a until 4.5.3. It's allowed to copy functionality from a later Mambo version into VirtueMart's ps_main file to maintain compatibility. Compatibility to Mambo 4.5. 1.0.x is not supported. On the other hand, it is necessary to stay up-to-date with Joomla!. Mambo and Joomla will be developed in two different directions.
Order and Spacing Order and Spacing To ease long term readability of source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard. SVN ident strings Include SVN $Header$ strings in your code. This makes it easier for people to know which version of a file they have and where it came from, so that they can usefully refer to the file’s SVN history to find out about bugs and fixes, etc.
Required Tags That Have Variable Content * @copyright 2004-2007 VirtueMart Developer Team * @license http://www.gnu.org/copyleft/gpl.
SVN Access Feel free to apply whatever copyrights you desire. When formatting this tag, the year should be in four digit format and if a span of years is involved, use a hyphen between the earliest and latest year. The copyright holder can be you, a list of people, a company, the PHP Group, etc. Examples: * @copyright 2003 John Doe and Jennifer Buck * @copyright 2001-2004 John Doe * @copyright 2005 XYZ Corporation 5.3. SVN Access 5.3.1. How to obtain the latest VirtueMart source code from SVN 5.3.1.1.
Documentation Sources Important Before you run the scripts make sure that 7Zip is installed on your computer. 1. Configure the scripts! First you must open the files and change the paths inside to match your configuration. 2. Build your own packages by running the script: • Build_Component.bat - (Win) build just the component archive • Build_VirtueMart_complete.bat - (Win) build the whole “Complete Package” including modules and mambots • build_component.
Code 5.4.1.3. Using tags If in doubt, lay down a tag. Tags are useful for pinning down a particular version of the code, e.g. one that is being run in service, or just before a big change or import. They are also used to identify branches. Tag names should be short and meaningful, like variable names. For example, virtuemart-20051222, pre-new-virtuemart, fanf-patches, corresponding to the uses mentioned above. Tags should be commented in the modules file. 5.4.2.
Database 5.4.3.1. "Whoops! I checked in the wrong thing!" Once a change has been committed you cannot un-commit it. You have to reverse the change and check in a new revision with the old code. Sometimes you might have a number of changes in your working copy which should be committed separately but accidentally get committed all at once with a commit message that's only appropriate to one of the changes.
Chapter 6. About the Project 6.1. The Project VirtueMart is an Open Source E-Commerce solution for Joomla! and Mambo. VirtueMart is released under the GNU Public License. It is free to download and use. There's a small group of developers who help in making this Shopping Cart Script more professional and easily usable. The author of this documentation is the Lead Developer...and having not much time besides Wife, Work & Studies. History: VirtueMart is the successor of mambo-phpShop.
34
