Project

General

Profile

Plugin system » History » Version 6

Oscar van Eijk, 02/07/2011 02:09 PM

1 1 Oscar van Eijk
h1. Plugin system
2
3 5 Oscar van Eijk
Since VirtueMart v2, the Joomla! plugin system is used form payment and shipper plugins.
4 1 Oscar van Eijk
5
h2. Installing plugins
6
7
During development the the VM2 branch, the plugins are not available as Joomla install packages, so for test environments, they must be installed manually.
8
9
h3. Payment plugins
10
11
At the time of writing, only 2 of the former payment plugins have been converted to the new plugin system. Others should follow soon, all help is appreciated!!
12
13
Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):
14
15
<pre>
16 4 Devendra Kumar Shukla
INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
17 1 Oscar van Eijk
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
18
VALUES
19
 (NULL, 'VMPayment - Authorize', 'authorize', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
20
,(NULL, 'VMPayment - Cash on delivery', 'cashondel', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00','')
21
;
22
</pre>
23
24 2 Oscar van Eijk
Next, copy the plugin files (authorize.php, authorize.xml, cashondel.php and cashondel.xml), located in the folder /plugins/vmpayment in the SVN checkout, to the Joomla plugin directory. If that doesn't exist, it must be created first: <pre>mkdir <document_root>/plugins/vmpayment</pre>
25 1 Oscar van Eijk
26
Now, in the store maintenance, you can add payment methods based on one of these plugins. Note at this moment it is required to select a vendor!
27
28
h3. Shipper plugins
29
30
This is very similar to the payment plugins. Only 1 plugin has been created (again: all help is appreciated!); 'standard', which provides a basic shipping option for postal services.
31 3 Oscar van Eijk
*Note:* Installing the sample data does _NOT_ provide shipping rates anymore!
32 1 Oscar van Eijk
33
Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):
34
35
<pre>
36 4 Devendra Kumar Shukla
INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
37 1 Oscar van Eijk
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
38
VALUES
39
 (NULL, 'VMShipper - Standard', 'standard', 'vmshipper', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
40
;
41
</pre>
42
43 2 Oscar van Eijk
Next, copy the plugin files (standard.php and standard.xml), located in the folder /plugins/vmshipper in the SVN checkout, to the Joomla plugin directory. If that doesn't exist, it must be created first: <pre>mkdir <document_root>/plugins/vmshipper</pre>
44 1 Oscar van Eijk
45
Now use the 'Shipping' menu item in the backend to add 1 or more carriers based on this plugin. All you need to do here is give the shipper a name and select a vendor (this is optional; when no vendor is selected, this carrier is valid for all vendors).
46
Finally you can add the shipping rates for the created vendor. Make sure a there's always a valid shipping rate: customers select the carrier only and the plugin must be able to find a mathcing rate based on the total order weight and the shipto address!
47
48 5 Oscar van Eijk
h2. Plugin Development
49 1 Oscar van Eijk
50 5 Oscar van Eijk
All plugins for VirtueMart should be developed confirming the Joomla! plugin development methods. Refer to http://docs.joomla.org/Tutorial:Plugins for developers documentation for Joomla! plugins.
51
52
h3. Payment Plugins
53
54
Payment plugins are used both in the front-end and the backend. Below is the list with events and a description on what moment they are fired.
55 6 Oscar van Eijk
* *plgVmOnSelectPayment()* - This event is fired during the checkout process. It allows the shopper to select one of the available payment methods.
56 5 Oscar van Eijk
It should display a radio button (name: paym_id) to select the payment method. Other information (like credit card info) might be selected as well, depending on the plugin.
57
+Return:+
58
It must return the HTML code for displaying the form (radio button and optional extra selections).
59
+Parameters:+
60
# (VirtueMartCart object) The cart object 
61
# (integer, default 0) ID of an already selected payment method ID, if any
62
63 6 Oscar van Eijk
* *plgVmOnPaymentSelectCheck()* - This event is fired after the payment method has been selected. It can be used to store
64 5 Oscar van Eijk
additional payment info in the cart.
65
+Return:+
66
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
67
+Parameters:+
68
# (VirtueMartCart object) The cart object 
69
70 6 Oscar van Eijk
* *plgVmOnCheckoutCheckPaymentData()* - This event is fired during the checkout process. It can be used to validate the payment data as entered by the user.
71 5 Oscar van Eijk
+Return:+
72
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
73
+Parameters:+
74
None
75
76 6 Oscar van Eijk
* *plgVmOnConfirmedOrderStorePaymentData()* - This event is fired after the payment has been processed; it stores the payment method-specific data.
77 5 Oscar van Eijk
All plugins _must_ reimplement this method.
78
+Return:+
79
If the plugin is NOT actually executed (not the selected payment method), this method must return NULL
80
If this plugin IS executed, it MUST return the order status code that the order should get. This triggers the stock updates if required
81
+Parameters:+
82
# (integer) The ordernumber being processed
83
# (object) Data from the cart
84
# (array) Price information for this order
85
	
86 6 Oscar van Eijk
* *plgVmOnShowOrderPaymentBE()* - This method is fired when showing the order details in the backend. It displays the the payment method-specific data.
87 5 Oscar van Eijk
All plugins _must_ reimplement this method.
88
+Return:+
89
Null when for payment methods that were not selected, text (HTML) otherwise
90
+Parameters:+
91
# (integer) The order ID
92
# (integer) Payment method used for this order
93
94 6 Oscar van Eijk
* *plgVmOnCancelPayment()* - This event is fired each time the status of an order is changed to Cancelled. It can be used to refund payments, void authorization etc.
95 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
96
<pre>$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
97
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
98
	return;
99
}</pre>
100
+Parameters:+
101
 (integer The order ID
102
 (char) Previous order status
103
 (char) New order status
104
105 6 Oscar van Eijk
* *plgVmOnShipOrderPayment()* - This event is fired when the status of an order is changed to Shipped. It can be used to confirm or capture payments
106 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
107
<pre>$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
108
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
109
	return;
110
}</pre>
111
+Return:+
112
True on success, False on failure, Null if this plugin was not activated
113
+Parameters:+
114
# (integer) Order ID