VirtueMart - 1.1 Developer's Guide
Contents
1. auth Array show prices 1 user_id 0 username demo perms first_nam guest last_name shopper_group_id 5 shopper_group_discount 0 00 show_price_including_tax 1 default shopper group Ji is registered customer 2 3 4 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 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 Note You must declare global vmLogger to be able to use this variable inside of a function Logging means to log a message to display them to the user While a function is executed because its execution was triggered by the variable func in the file virtuemart parser php the events are buffered When the function call has ended the contents of the log are flushed and all messages are displayed to the user in the order they were added to the log first in first out After that implicit flushing is enabled what means that you can log a message and it is printed into the HTML code where you call the log func2. themes following structure Directory File Function admin css the stylesheet for the frontend administration theme config php the configuration file for the theme theme css the main stylesheet for the theme theme js the main javascript controller for the theme theme php the controller for the theme used to declare functions and include stylesheets and more theme xml contains the theme configuration parameters and additional information images holds the theme images templates holds the template files that allow you to style and restructure the shop pages templates basket holds the basket templates templates browse holds the templates for the product listing page templates common holds some commonly used templates like the price display pathway and the product snapshot templates pages holds the templates for all other pages e g account order details tpl php templates order emails holds the order email templates as used when an order is placed templates product details holds the product detail templates 2 2 Main Flow Chart 2 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 component s for a directory called com virtuemart and a file called virtuemart php in it When called in the backend Joomla searches the direc
3. This parameter follows a strcit syntax and must be a string build like this ShippingClassNamelcarrier namelrate nameltotalshippingcostslrate id For our example the shipping rate id for one rate could be myShippinglMy CarrierlMy Rate Namel45 00 The last field rate id can be left empty The shipping rate id parameter is always passed as an urlencoded string The Shipping API specification The following is a list of all methods that must be implemented by a shipping module s class file string list rates Array d Lists all available shipping rates Tip The array d contains the values for the cart total weight Sd weight and the ID for the shipping address the user has selected d ship to info id The ship to info id refers to the field user info id in the tables mos users OR mos vm user info Check both for a matching entry float get rate Array d Returns the amount for the selected shipping rate by analyzing the parameter shipping rate id float get tax rate Array d Returns the tax rate for this shipping module e g 0 16 boolean validate Array d Validates the value for the parameter shipping rate id usually using isset SESSION shipping rate id Assumes you have set the value in the function list rates for each returned shipping rate void write configuration Array Stores all configuration values for this shipping module in the configuration file string show config
4. gt lt p gt Product Name lt php echo product name gt lt p gt Don t forget to close the PHP brackets and always use valid code If you don t it might break your site Predefined Global Variables VM LANG This is the global language object It displays strings which are defined in the language file for VirtueMart Usage lt php echo SVM LANG PHPSHOP FLYPAGI This would print Product Details E LBL sess Used to build SEF enabled URLs that can be used in links Usage ERV lt a href lt php echo sess gt url _S ER PHP SELF Predefined Variables for the Flypage Product Details Template product name The Product Name product sku The Product SKU product s desc The Product Short Description product description The Product Description product weight uom The Product Weight s unit of measure product length The Product Length product height The Product Height product width The Product Width product Iwh uom The Unit of Measure for the Product Length Width Height page shop product 12 Templates product url product in stock product available date product availability product special product discount id cdate mdate product sales product unit product packaging product price Ibl product price product packaging file list product availability addtocart product type product reviews product reviewform product image pro
5. and not foo name or foo name Use single quotes instead of double quotes as much as possible because it s faster to parse Line Spacing Indent using 4 spaces or a tab 26 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 If your repository is configured appropriately use the custom tag instead of Header Variable Settings e Always run Mambo Joomla and PHP will full Error Reporting Level E ALL You can change this level in the global configuration see Server Error Reporting Level and in your PHP ini Always initialize variables just a 0 is initialization Use isset var to check if a variable has been set Use empty var to check if Array indexes have been set or are empty Header Comment Blocks All source code files in the repository shall contain a page level docblock at the top of each file and a class level docblock immediately above each class Below are examples of such docblocks php Short description for file Long descript
6. Important files basket php controls the Cart ro basket php controls the Cart on the last step of checkout ro read only Contains the Language Files which are included from virtuemart_parser php Holds SQL Dump Files for building up the structure for the tables used by VirtueMart Holds the files wich are used to control the call of the Shop from the Frontend Important files e virtuemart php the file included by Joomla on a call to index php option com virtuemart amp e virtuemart parser php the central file for VM prepares the session authentication cart amp runs functions show image in imgtag php used to display dynamically resized images using the class img2thumb php Contains the shop s css file shop css and css styles needed for the frontend administration admin css Contains Javascripts Images for the Shop availability Contains images for displaying the availability of a product Tip All images in this folder are automatically parsed and displayed in the product form Main Flow Chart components com_virtuemart category product ps_image vendor for selection as the availability image for a product so just copy them here Contains images for categories Contains Product Images resized product images Images for the administrative interface Vendor Logos Contains the themes for VirtueMart Each theme has the
7. The variables which have been prefilled in html basket php and html ro basket php are just printed out in the templates 17 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 4 1 1 4 1 2 VirtueMart has a lot of predefined payment methods Some of these payment methods are controlled by payment modules Example Payment Method Credit Card Payment Module ps authorize Handles credit card authentication with the authrize net server Payment Method Cash on delivery Payment Module none ps payment is an empty payment module No business logic needed for this kind of payment Basics Virtuemart knows the following general payment method types Payment Processor Credit Card Bank Debit Address only Cash on delivery HTML form based Asks the Customer for Credit Card Details and processes the payment before the order is placed Automatic Credit Card Processors do a server to server communication before the order is placed e g authorize net AIM Just asks the customer for the credit card details The details are
8. this gt get cfg parameterName to get the value for this parameter Example from templates product details flypage tpl php Show the vendor link if Sthis gt get cfg showVendorLink 1 echo vendor link The second parameter let s you predefine a default value which is used when the configuration file for this theme doesn t have a value for this parameter 3 1 2 Templates 3 1 2 1 Introduction Important A template in VirtueMart has nothing in common with what is a template in Joomla 11 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 Most important there are no more placeholders like product name as used in VirtueMart 1 0 x AII details are avalaible in PHP variables So all you need to know is which variables can be used in what template and how can I use them Use PHP in the template If you want to output the value of a variable all you need to do is add PHP brackets and echo the variable inside lt Print out the value of a variable
9. 0 x sources 5 3 1 4 How to build an installable archive from the sources Before you can install VirtueMart you will have to build installable archives There are 2 types of build scripts available one version for Windows and one for Linux which can help you build the correct archives You should have got the build scripts by following the instructions from the first section on this page 29 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 sh Linux build the component archive build virtuemart complete sh Linux build the whole Complete Package including modules and mambots 5 3 2 Documentation Sources The VirtueMart Project manages the documentation in the DocBook http docbook org format You can checkout the sources in the DocBook format and transform the DocBook source using an XSL Transformer into PDF HTML CHM or whatever else All you have to do is checkout the directory trunk documentation from dev virtuemart net details see above The easiest and most professional software to
10. 75 Bug desription added feature from request Task 56 feature description Note Please keep your descriptions as readable as possible A lot of people are following the changes and are interested in understanding all changes and their consequences Important If you had to make a change to the database schema please indicate those changes with extra emphasis Because you re not the only one working on a development version please add all queries which are necessary to update a database to comply with your changes 44 Database structure changed ALTER TABLE jos vm order user info ADD extra field 1 varchar 255 defa Please read the section Database for all notes about the database and its scheme 5 1 2 Compatibility 5 1 2 1 PHP version compatibility All PHP code written must be compatible down to PHP version 4 3 0 5 1 2 2 MySQL version compatibility As there is no real database abstraction in Mambo we keep compatibility to MySQL 25 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 Mam
11. Developer Platform for VirtueMart and Open Source Projects related to VirtueMart can be found at https dev virtuemart net That s the place where VirtueMart can be downloaded And you can create your own Project there We offer free Project Hosting for your VirtueMart related Open Source Project 33 34
12. Product s Creation Date UNIX Timestamp The Product s last Modification Date UNIX Timestamp The completely formatted product price The Add To Cart Button Code The average Product Rating The string Details The relative filename of the product full image relative to components com virtuemart shop image products The relative filename of the product thumbnail image relative to components com virtuemart shop image products The object list of all additional images this product has 14 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 with page navigation and result counter 3 1 2 3 Using and Fetching Templates Create a template object First of all the template object must be created as an instance of the class vmTemplate Create an object of the class vmTemplate Stpl vmTemplate getInstance Import variables into the template If you want to use a certain variable in your template you must import it before Templates don t have the global scope So all
13. September 2005 In October 2005 it was renamed to VirtueMart 1 2 Differences to phpShop VM still contains some code parts from phpShop but experienced phpShop coders will find 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 Parameter Renames Changes VM has introduced several new parameters and parameter name changes page offset limitstart Itemid 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 Outdated removed The offset parameter was completely replaced by the parameter limitstart 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 The limitstart parameter is the replacement for offset and can be used just like this 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 gt Online Shop and modules which shall only be shown on specific pages
14. 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 Joomla Integration Table names have changed and got a prefix Use t 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 e auth user md5 jos users stores passwords intershipper language sessions There have been a
15. classname create an object S classname new classname RUN THE FUNCTION Sok class function vars Sok SSclassname gt SfuncParams method Svars T 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 If you wonder what the variable vars is it s just a working copy of the superglobal REQUEST Array and used as the array d inside of the functions 2 3 3 Other important Environment variables Array cart The current cart contents The array has the following structure cart Array idx 1 0 Array quantity Ji product id 10 description Size big Power 100W In this example the car contains one product with the quantity of 1 the product ID 10 and a description The index idx is an integer and contains the size of the cart number of different products in it regardless of their quantity This variable is always available in the global SESSION array SESSION cart Array auth All the user information in one Array always available in the global SESSION array
16. content in the file htm1 shop browse php Order Confirmation Email Templates Order Confirmaton Email Templates define the layout of the confirmation email that is sent out to a user after having placed an order These Email templates can be found in html themes VM THEME templates order emails They are loaded and filled with content in the file classes ps_checkout php function email receipt The concept is to define placeholders in the template and replaced them by the real contents on load This is done using the PHP function str replace 16 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 b2c Business to Customer prices include tax b2b Business to Business prices don t include tax The basket files are included in html shop cart php html basket php html ro_basket php and in the html checkout index php except that the ro_basket_ file is displayed on the last step of the checkout when the cart contents can t be modified any more ro_basket read only basket
17. images The link to the manufacturer info page The link to the vendor info page 13 Templates edit link ask seller related products navigation childlist images files The link to the product form of this product admin only The link to the Ask a question about this product page The list of related products The child categories for the current category this product is located in The object list of all additional images this product has The object list of all additional files this product has Predefined Variables for the Browse Page Product Listing Templates product name product sku product s desc product weight uom product length product height product width product Iwh uom product flypage product url product in stock product available date product availability cdate mdate product price form addtocart product rating product details product full image product thumb image images The Product Name The Product SKU The Product Short Description The Product Weight s unit of measure The Product Length The Product Height The Product Width The Unit of Measure for the Product Length Width Height The internal Product URL to the details page The external Product URL The Number of Products in Stock The UNIX Timestamp for the Product Availability Date The product availability information includes the number of products in stock and the average delivery time The
18. variables are not available in a template unless you import them This can be done using the set method from the controller file e g shop browse php Importing a variable into the template Syntax tpl gt set This is the variableName available in the template tpl gt set product name S product name The variable product name is just an example You must care to get the variables from the database The browse page offers an database object holding all important product information db browse So if you need to access the product weight or whatever value you need to call tpl set product_weight db browse f product weight in order to get the correct value Parse the template If you have finished importing all needed variables into the template object you can fetch it using this syntax Parse a template Scontents tpl gt fetch product details myFlypage tpl php Print out the contents echo Scontents Alternative Fetch a cached template caches if no cached copy available Scontents tpl gt fetch_cache product details myFlypage tpl php Print out those contents echo contents 15 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 fi
19. 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 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 component s 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 administrator components com virtuemart classes administrator components com virtuemart classes Log administrator components com virtuemart classes shipping administrator components com virtuemart classes payment administrator components com virtuemart classes pdf administrator components com virtuemart classes phpInputFilter administrator components com_virtuemart classes phpmailer 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 Configur
20. 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 shtml http Table of Contents Preamble EET ix 1 Introduction ii er NI rei Ie 1 E e ase O NO 1 1 2 Differences to phpShop cooccooccnnconoconncnnncnnnconoronornnrnnor non ron scan veen veen ro hee thee rene 1 1 3 Joomla Integration eee ee eh sr areas 2 25 Basics IEEE 3 2 1 Directory and File Structure 55 oir petet sn sn ge nen en shape riet 3 2 2 Main Flow Chart GET RES eiii 5 2 3 Core Modules amp their Functions Environment Variables nennen 6 24 Database Structure u 2er dette reete bs 9 2 5 Database Accessori e err pr dirias 9 2 6 User Integration ubere iia diia oo 10 3 Modifying the Layout eit tere een ER Es Ans 11 3 1 Themes and Templates errem tee EE Bestes Sana 11 3 2 Finding the right File i i erret etre rie ES alba 16 3 3 Modifying Templates e tt E M pam 16 4 Creating or modifying Extensions reereeereeeeeneeneeenee even enen neem veen ve eneen eenn 19 4 1 Payment Modules 2022er BR ereen dere 19 4 2 Shipping Modules ie ord een Re Re E ERI EP Re E m e 22 5 Developer Guidelines 5 5 25 eee Anis ns 25 a 25 5 2 C
21. ation File toolbar virtuemart html php Standard Toolbar Joomla style toolbar html php Toolbar for ExtJS in extended Layout Holds all the core classes which are used by VM Important ps database php object database wrapper for Joomla s database e ps cart php controls the cart contents ps main php nota class contains central functions e g for image upload ps session php basic session management URL formatting Contains a slightly modified version of PEAR s Log class Contains Shipping Modules amp their informational Files Contains Payment Modules amp their informational Files Contains the classes of the HTML2FPDF Package see sourceforge net projects html2fpdf http sourceforge net projects html2fpdf contains the phpinputfilter class for VirtueMart Directory and File Structure administrator components com virtuemart html administrator components com virtuemart languages administrator components com virtuemart sql components com virtuemart components com virtuemart css components com virtuemart js components com_virtuemart shop_image Contains the classes of the phpMailer Package also used by Joomla and Mambo see phpmailer sourceforge net http phpmailer sourceforge net 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
22. bo and Joomla will be developed in two different directions This process will someday lead to the effect that components written for Joomla won t work on a Mambo 4 5 3 or higher Note VirtueMart will keep track with the Joomla development 5 1 3 Accessibility 5 1 3 1 XHTML Compliance All HTML code used in files must be XHTML compliant This means syntax like lt br gt instead of lt br gt and using quotes for attribute values lt div id myid gt instead of div id myid gt and using lower case tag and attribute names lt div gt lt div gt instead of lt DIV gt lt DIV gt 5 1 3 2 Javascript Javascript can be used in the frontend is NO problem at all in the backend and for all administration pages But in the frontend all functionality that is used by a customer must also work with Javascript disabled This includes Javascript based category trees always also include a lt noscript gt Non JS code lt noscript gt section for people who have disabled Javascript 5 2 Coding Guidelines Register Globals is Off All code must work with PHP register globals Off PHP Code Tags Always use lt php gt to delimit PHP code not the gt shorthand This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups Single Quotes vs Double Quotes Use single quotes to refer to an index between brackets of an array ex foo name
23. 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 The safe thing to do is revert the inadvertent commits then re commit them with the right message editing the repository directly is possible but foolishly dangerous 5 4 3 2 Whoops cocked up a svn import Getting an import right is important because it affects the long term usefulness of the repository Check import commands particularly carefully before running them If you do make a mistake the solution depends on exactly what went wrong You might have run the command in the wrong working directory or you might have used the wrong repository path etc The important point is whether the imported files coincide with files in the repository or not 1 If none of the files in the erroneous import have the same name as an existing file in the repository e g they all ended up in a completely new directory then just removing the files from the repository can be done by using the appropriate xm command in the repository 2 If the import is OK apart from an incorrect tag the tag can probably be deleted and re applied correctly without too much pain This may not be true for a misspelled vendor branch tag 3 If there is a filename clash with an unrelated file then ther
24. dded 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 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 1 3 Joomla Integration The Joomla
25. de 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 Code Most of the guidelines in this section are common sense but it s worth while re iterating them in the context of SVN because it has implications that might not be immediately obvious 5 4 2 1 Never reformat code Never ever reformat code This is a really bad thing to do because it makes diffs hard to understand and apply Upstream authors won t accept patches against reformatted code Bugfixes and patches against the upstream code won t apply New versions of the upstream code can t be imported Real changes get hidden in the mass of reformatting No one s favourite coding style is significantly better or worse than anyone else s so reformatting code provides no advantage to oppose the disadvantages 5 4 2 2 Format code consistently Use the same coding style as the code you are editing This is a corollary to the previous subsection It is easier for people reading the code if it uses consistent layout rules throughout so when you are editing someone else s code the cod
26. duct full image product thumb image buttons header navigation pathway more images manufacturer link vendor link The Product URL The Number of Products currently in Stock The UNIX Timestamp for the Product Availability Date The Product Availability String Y or N is the product on special The Product s Discount ID The Product s Creation Date UNIX Timestamp The Product s last Modification Date UNIX Timestamp The Number of Sales of this Product The Product s Packaging Unit The Number of Products per Package The price label Price The completely formatted product price Product Packaging information The list of additional files for this product when the product has files assigned to it The product availability information includes the number of products in stock and the average delivery time The Add To Cart Button Code Product Parameter Values The List of Product Reviews The Form to post a new Product Review The small product image complete image tag wrapped into an URL when available The relative filename of the product full image relative to components com virtuemart shop image products The relative filename of the product thumbnail image relative to components com virtuemart shop image products The PDF Email and Print buttons The pathway to the product Power Tools Outdoor Tools Chain Saw The link to the Product Images page when the product has additional product
27. e default theme You can change the Theme in the Site section of the configuration form Usually there s only one theme available so you can t switch A good way to think of themes is as plugins which contain a collection of page templates images stylesheets javascript and other files While editing these files can be a bit technical the layout is separated from the content allowing you to make and distribute your own themes 3 1 1 2 Theme Configuration Themes can be configured for better usability Configuration parameters can be used to turn on and off certain parts in templates The configuration parameters are defined in the file component s com virtuemart themes THEMENAME theme xml and follow the common parameter syntax for components modules and mambots as used in Mambo 4 5 1 and Joomla Read more about the mosinstall parameter XML syntax When a user chooses to configure a theme Shop Configuration Tab Site Layout these parameters are parsed and displayed in a nice form Now the user can make changes to the configuration The current configuration values are stored in the file components com virtuemart themes THEMENAME theme config php This file is renewed with the new configuration values each time a user saves the theme configuration How to use configuration values in templates It s easy to get or set the value of a configuration parameter from inside a template You just need to call
28. e s a fairly serious problem Find a SVN guru and help him or her to fix the repository manually You won t be popular 5 5 Database 5 5 1 5 5 2 Changes to the main db schema require a that an upgrade patch is posted as well Your change will be backed out if you don t provide a patch as well Changelog First of all you need to make an entry in the Changelog including the SQL Queries to update a database scheme SQL Update File All changes to the database scheme are collected in an SQL file There s a file for each minor version jump e g UPDATE SCRIPT com virtuemart 1 0 x to 1 1 0 sql The file can be found in the subdirectory sql A user must see which version of VirtueMart this SQL patch file applies to and to which version it updates the db scheme In this case the SQL file would update a db scheme from version VirtueMart 1 0 x to 1 1 0 32 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 amp Studies History VirtueMart is the successor of mambo phpShop mambo phpShop was the first port of phpShop to Mambo phpShop was develop
29. e that can be parsed 4 1 3 Implementation Details 4 1 4 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 All other payment methods can be created by just adding a new payment method in the shop administration Then you don t need to create a new payment module A payment module implements a technique to either communicate with a remote server to authenticate the credit card of a user or create a HTML Form to send the user to the pages of the payment provider where he she can pay and return to your shop afterwards All payment modules are located in the directory administrator components com virtuemart classes payment and provide two files the class file and the configuration file Example Module mynewpayment You must have two files called ps mynewpayment php including the class ps mynewpayment ps mynewpayment cfg php containing all necessary configuration constant definitions If the user has chosen to pay using a payment method which has this class as its processor entry under Class Name the file ps mynewpayment php will be included on checkout and its functions will be used to process the payment details regardless of the implementation The API specification The following is a list of all methods that must be implemented in a payment module s class f
30. e you add should be in the same style 5 4 2 3 Tab settings Tabs are four characters wide This is also a corollary to the previous subsections Although indentation sizes vary greatly tabs are almost universally eight characters so using a different setting is liable to cause confusion or even reformatting A four character tab might suit your indentation style but the rest of the world will think your code is a mess 5 4 2 4 Comments Commit messages are not a substitute for comments or vice versa Comments should describe data structures and why the code does what it does commit messages should explain why code was changed 5 4 2 5 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 If your repository is configured appropriately use the custom tag instead of Header 5 4 3 Handling tricky situations Because of limitations in SVN certain tasks are inherently difficult particularly recovering from mistakes Although changing the repository directly is nearly always a Really Bad Idea sometimes it cannot be avoided These guidelines explain what to do in these situations 31 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
31. ed by Edikon Corp http www edikon com and the phpShop community http www phpshop org 6 2 Documentation This documentation was written using XMLMind XML Editor http www xmlmind com xmleditor using the DocBook http www docbook org XML Format DocBook defines a set of markup elements useful for marking up text so that the text can then be transformed into several different formats It s possible to create documents in different formats PDF HTML HTML Help chm Files for Windows Help XML RTF TeX WordML Word 2003 and others The author of this document uses eDE http docbook e novative de for generating the End User documents The idea is to write just once and reach the largest possible number of people with the information Digital information not stored properly tends to get lost Due to the fact that not containing uncommon characters such as binary formats it s possible to index and search directly on the documents written on SGML and consequently on DocBook The SGML systems use markups to make their description DocBook holds over 300 markup elements each one with several attributes which can assume several values these can be fixed or defined by the document style that the author has used 6 3 Homepage Forum Developer Resources The project homepage is http virtuemart net The Forum can be found at http forum virtuemart net You are invited to join Discussions at our Developer Board The Central
32. f 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 amp page product If the user has appropriate permissions the page is loaded if not an error message is generated 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 productA dd exists in the table jos 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 productA dd 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 Other important Environment variables Load class definition file require once CLASSPATH class php Sclassname str replace class funcParams class if class exists strtolower classname Sclassname vm classname if class exists
33. ht 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 General Information In order to download source code from the SVN repositories you ll need a SVN client software A recommended SVN client is SmartSVN http www syntevo com smartsvn or TortoiseSVN http tortoisesvn tigris org You can access the repository read only anonymously by using an empty password Please note that the SVN server is case sensitive Fill in the details into your SVN client just as they are provided here 5 3 1 2 Development Version You can checkout the development version of VirtueMart from https dev virtuemart net svn virtuemart trunk If the trunk is downloaded you will have 4 new directories build scripts batch shell scripts to build installable archives documentation the documentation sources languagemanager the language manager component to modify language files and add modify delete language tokens virtuemart the VirtueMart 1 1 x sources 5 3 1 3 Latest code from VirtueMart 1 0 x stable branch You can checkout the latest version from the stable branch of VirtueMart from https dev virtuemart net svn virtuemart branches virtuemart 1 0 0 If the branch virtuemart 1 0 0 is downloaded you will have 2 new directories build scripts batch shell scripts to build installable archives virtuemart the VirtueMart 1
34. ied by nameOfTheAttribute or when it s not available the value of Svars SnameOfTheAttribute Get the number of returned records method num rows void if db gt num_rows gt 0 we have a record set 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 e jos users contains BillTo Address Information jos vm user info contains ShipTo Address Information when the customer has added ShipTo Addresses jos vm order user info contains a copy of the BillTo amp ShipTo Address at the moment when an order is placed 10 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 th
35. ile string show configuration void Shows the configuration form for this payment module in the payment method form boolean has configuration void returns true if the payment module can be configured false if not boolean configfile writeable void returns true if the configuration file for that payment module is writeable false if not boolean configfile readable void 21 Installing a Payment Module 4 1 5 returns true if the configuration file for that payment module 1s 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 This is the main function for all payment modules that use Array amp d direct connections to a payment gateway like authorize net or eWay XML This is the place where the payment details are validated and captured on success Returns true on sucess false on failure float get payment rate Float subtotal This is the function to calculate the fee discount for this special payment module so you can calculate a fee depending on the order total amount Note IF you are about to change configuration variables do this in both functions show configuration and write configuration Installing a Payment Module Since there s no real installer for payment modules you must copy the two files ps mynewpaymen
36. ion for file if any Qpackage VirtueMart subpackage classes product author Original Author lt author example com gt author Another Author lt another example com gt copyright 2007 VirtueMart Developer Team Qlicense http www gnu org copyleft gpl html GNU GPL Qversion Id Developer Manual xml 1079 2007 12 07 18 34 232 soeren nb A bs Place includes constant defines and GLOBAL settings here Make sure they have appropriate docblocks to avoid phpDocumentor construing they are documented by the page level docblock Short description for class Long description for class if any Gauthor Original Author lt author example com gt Gauthor Another Author lt another example com gt A ok A F Ro X 27 Required Tags That Have Variable Content copyright 2004 2007 VirtueMart Developer Team Qlicense http www gnu org copyleft gpl html GNU GPL version Release xy class foo var database Internal database class pointer var db null Qvar object An object of configuration variables var config null Qvar object An object of path variables var path null var mosSession The current session var session null var string The current template var template null var array An array to hold global user state within a session This function does something special since VirtueMart 1 0 1 param s
37. modify DocBook sources is the XML Mind XML Editor http xmImind com xmleditor download shtml After you have downloaded and installed the software you can just open the main documentation file and start working on it trunk documentation User Manual User Manual xml the User Manual trunk documentation Developer Manual Developer Manual xml the Developer Manual 5 4 Using SVN 5 4 1 Basic points This section describes things that are generally applicable when using SVN guidelines that are more specific to particular tasks or uses are described in the other sections 5 4 1 1 When to check in Check in early check in often When you have made a change that works check it in Check in separate changes in separate commits as much as possible Don t be shy to check in work in progress so long as it is minimally functional or at least compilable without errors 5 4 1 2 Commit messages Use meaningful commit messages Explain what bug the commit fixes or what features it adds Don t be too concise fixed typo is too short fixed Task 2432 or fixed typo in function name is OK The aim is to make it easier to find the desired change easily from just the commit messages The converse of this is including too much information SVN automatically maintains information like the date and time of the commit who made the commit what code was changed etc You don t need to include it in the commit message yourself 30 Co
38. nd the file which produces the HTML output you re seeing you can enable the DEBUG mode Admin Configuration Path amp URL check DEBUG and save After having done that you will see blue info icons all over the Shop which show the file name of the included file on mouseover The most changed files are e html shop browse the product listing category overview e html shop product details php the product detail page view html shop index php the default Shop Homepage when the parameter page is omitted 3 3 Modifying Templates 3 3 1 3 3 2 3 3 3 Flypage Templates Flypage or product details templates can be found in themes VM THEME templates product details They are loaded and filled with content in the file htm1 shop product details php Browse Templates Browse templates define the display of a single product in the product listing So you can only modify the contents of the boxes which are filled with product information in the product listing of a category The number of those boxes which are displayed in a single row of the product listing can be changed in the Category Form of that category see Number of Products per row or globally in the Shop Configuration for the case that no category id is passed to the Shop Browse or product listing templates can be found in themes VM THEME templates browse They are loaded and filled with
39. oding Guidelines 88 seen Enke 26 5 3 SVN Access een e ren er ER RO ries 29 34 Using SVN 2 sin ED EIER 30 5 5 Database en tasten ie ke isis betas 32 6 About the Project oreet ere epe terere re ree PO en eei rib d sedato er se 33 6 1 The Project iino Prem RE ries 33 6 2 Documentation cross grep erede ae teet RD etai eer ern 33 6 3 Homepage Forum Developer Resources ann oannoen teen seen nene nene 33 vi List of Figures 4 1 Payment Method Form Tab 1 4 2 Payment Method Form Tab 2 vil 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 1X Chapter 1 1 1 History Introduction 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
40. securely stored in the database for capturing the payment manually afterwards Asks the customer for his her bank account details so you can get the money from the customer s bank account afterwards No payment processing by the module Transfers the customer to another server where he she can pay This is done after the order has been placed examples PayPal Worldpay 2Checkout Quick Create a new payment method If you have form code for a form based payment method most payment providers use this way you just need to select Store Add Payment Method from the VirtueMart admin drop down menu An empty payment method form opens Now fill in the details of your payment method like this 19 Quick Create a new payment method Payment Method Forn General Configuration Active Payment Method Name my New Payment Code np Payment class name e g ps_netbanx default ps_payment Leave blank if you re not sure what to fill in Payment method type C credit Card C use Payment Processor C Bank debit C Address only Cash on Delivery ee PayPal or related Shopper Group default Washupito s Tiendita Vendor ID 1 vf Discount fo 00 List Order zi 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 Paymen
41. t Extra Info Payment Method Form General Configuration Payment Extra Info O lt php your iTransact account details vendorID XXXXX global vendor name mername vendor name order details total db gt ordek_total first_name user gt first_name last_name user gt last_ user gt address_1 city user gt city state user gt state zip user gt zip country u user gt email phone user phone l home page mosConfig_live_site index php ret_a mosConfig live site index php cc payment image mosConfig live site components com virtuemart shop image ps image cc payment jpg form action https secure paymentclearing com cgi bin mas split cgi method POST gt input type hidden vendor id value lt php echo vendorID gt lt input type hidden name home page value lt php echo home page gt lt input type hidden name ret addr value lt php echo ret addr input type hidden name mername value php echo mername lt Enter text in the next value that should appear on the bottom of the o lt INPUT type hidden name mertext value lt I you are accepting checks enter the number 1 in the next value En Figure 4 2 Payment Method Form Tab 2 20 Implementation Details Caution The code inside this form MUST BE VALID If you use PHP code check if you have written correct cod
42. t php and ps mynewpayment cfg php into the directory administrator components com virtuemart classes payment first After you have done that you can add a new payment method Store Add Payment Method It s important to fill in the correct name for Payment Class Name in this case ps mynewpayment here s the reason why you must give the class file the same name as the class inside the file the Shop now tries to include a file called ps mynewpayment php on Saving the payment method When you now re open the newly created payment method you have access to the configuration form 4 2 Shipping Modules 4 2 1 The Basics Shipping modules are located in the directory administrator components com virtuemart classes shipping and have three files the class file the information file and the configuration file Example Module myShipping You must have three files called myShipping php including the class myShipping myShipping ini containing the Name of the Module amp the Author and the File Version 22 The Shipping API specification 4 2 2 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
43. tion Currently the Log display class used by VM offers 9 log levels System is unusable PEAR LOG EMERG Immediate action required PEAR LOG ALERT Critical conditions PEAR LOG CRIT formatted by CSS style log crit Error conditions PEAR LOG ERR formatted by CSS style log error Warning conditions PEAR LOG WARNING formatted by CSS style log warning Normal but significant PEAR LOG NOTICE Informational PEAR LOG INFO formatted by CSS style log info Debug level messages PEAR LOG DEBUG formatted by CSS style log debug Advice messages PEAR LOG TIP added for VM formatted by CSS style 1og tip Please note that Debug log entries are only shown to the user when DEBUG is enabled by configuration To log an event you can use a special function for each log level e SvmLogger gt emerg My emergency message to the user e vmLogger alert My alarm message to the user e vmLogger crit My critical message to the user e SvmLogger gt err My error message to the user Mainly used to log errors ir Database Structure vmLogger gt warning My warning message to the user Mainly used to t e vmLogger notice My Notice to the user vmLogger info My informational message to the user Used to give e vmLogger debug My debug message to the user Only displayed when e SvmLogger gt tip My advice to the user Used to displa
44. tory administrator components for a directory called com virtuemart and a file called admin virtuemart php in it If found the file is included 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 f shop is the name of the shop core module and browse is the name of the page Tip Core modules are listed in the table mos vm modules Calling index php com virtuemart amp page shop browse in your Joomla site would let VM include the file administrator components com virtuemart html shop browse php 2 3 Core Modules amp their Functions Environment Variables 2 3 1 2 3 2 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 o
45. tring The name of the product param int The ID of the product return string HTML Table with a snapshot of the product function myFunction Sargl amp Sarg2 Required Tags That Have Variable Content Short Descriptions Short descriptions must be provided for all docblocks They should be a quick sentence not the name of the item but the description of the what does this file class license VirtueMart is released under the GNU GPL license You should keep this license for best compatibility license http www gnu org copyleft gpl html GNU GPL author There s no hard rule to determine when a new code contributor should be added to the list of authors for a given source file In general their changes should fall into the substantial category meaning somewhere around 10 to 20 of code changes Exceptions could be made for rewriting functions or contributing new logic Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors Optional Tags copyright 28 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 copyrig
46. uration void Shows the configuration form for this shipping module in the shipping module form boolean configfile writeable void 23 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 After having done that you must go to the Shop Configuration where your new shipping module will be automatically recognized by reading its ini File and presented to you as an additional shipping method under the Tab Shipping You can now select it and save the Configuration 24 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 net username and the following characters to indicate a modification gt Bug Fix gt Addition gt Change gt Removed gt Note An example entry could like like this 06 09 2005 soeren changed this and that Task
47. y Advice messac 2 4 Database Structure As said before all Tables used for VM begin with the prefix vm VM doesn t use Joomla core tables for storing data 2 5 Database Access VM uses its own database access class for dealing with the database The database class file is administrator components com virtuemart classes ps database php This database class extends Joomla s database class class ps DB extends database and provides additional functions to be able to use older phpShop code So this class is just a wrapper class for Joomla s database object and doesn t open new connections to the database e Start a query call the method query string query Sdb gt query SELECT email FROM users e Get the resulting record set call method next record void db next record returns false when no result can be returned or the end of the record set has been reached e Fetch the value of an attribute of the record set method f string nameOfTheAttribute Sdb gt f email Alternative method sf string nameOfTheAttribute returns the value of the attribute specified by nameOfTheAttribute or when it s not available the value of Svars SnameOfTheAttribute Print echo the value of an attribute of the record set method p string SnameOfTheAttribute db p email Alternative method sp string SnameOfTheAttribute prints the value of the attribute specif
Download Pdf Manuals
Related Search