Project

General

Profile

Plugin system » History » Version 24

Valérie Isaksen, 06/13/2011 06:45 PM

1 10 Oscar van Eijk
{{>toc}}
2
3 1 Oscar van Eijk
h1. Plugin system
4
5 5 Oscar van Eijk
Since VirtueMart v2, the Joomla! plugin system is used form payment and shipper plugins.
6 1 Oscar van Eijk
7
h2. Installing plugins
8
9
During development the the VM2 branch, the plugins are not available as Joomla install packages, so for test environments, they must be installed manually.
10
11
h3. Payment plugins
12
13
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!!
14
15
Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):
16
17 12 Christopher Roussel
J1.5:
18 1 Oscar van Eijk
<pre>
19 4 Devendra Kumar Shukla
INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
20 1 Oscar van Eijk
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
21
VALUES
22
 (NULL, 'VMPayment - Authorize', 'authorize', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
23 12 Christopher Roussel
,(NULL, 'VMPayment - Cash on delivery', 'cashondel', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00','');
24 1 Oscar van Eijk
</pre>
25 12 Christopher Roussel
J1.6:
26
<pre>
27
INSERT INTO `jos_extensions` (`extension_id`,  `type`, `name`, `element`, `folder`, `access`, `ordering`
28
  , `enabled`, `protected`, `client_id`, `checked_out`, `checked_out_time`, `params`)
29
VALUES
30
 (NULL, 'plugin', 'plg_vmpayment_authorize', 'authorize', 'vmpayment', 1, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
31
,(NULL, 'plugin', 'plg_vmpayment_cashondel', 'cashondel', 'vmpayment', 1, 0, 1, 0, 0, 0, '0000-00-00 00:00:00','');
32
</pre>
33 1 Oscar van Eijk
34 13 Max Milbers
Next, when you did not use the svn checkout, copy the plugin files (authorize.php, authorize.xml, cashondel.php and cashondel.xml), located in the folder /plugins/vmpayment, to the Joomla plugin directory. If that doesn't exist, it must be created first.
35 1 Oscar van Eijk
36 19 Valérie Isaksen
Now, in the store maintenance, you can add payment methods based on one of these plugins, then click Apply button to display the appropriate parameters in the configuration tab. Note at this moment it is required to select a vendor!
37 1 Oscar van Eijk
38
h3. Shipper plugins
39 3 Oscar van Eijk
40 1 Oscar van Eijk
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.
41
*Note:* Installing the sample data does _NOT_ provide shipping rates anymore!
42
43
Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):
44
45 12 Christopher Roussel
J1.5:
46 1 Oscar van Eijk
<pre>
47
INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
48
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
49
VALUES
50 17 Valérie Isaksen
 (NULL, 'By weight, ZIP and countries', 'weight_countries', 'vmshipper', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
51 24 Valérie Isaksen
,(NULL, 'By products and countries', 'nbproducts_countries', 'vmshipper', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
52
,(NULL, 'By order amount and countries', 'orderamount_countries', 'vmshipper', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
53 14 Valérie Isaksen
;
54 1 Oscar van Eijk
</pre>
55
56 12 Christopher Roussel
J1.6: 
57
<pre>
58
INSERT INTO `jos_extensions` (`extension_id`, `type`, `name`, `element`, `folder`, `access`, `ordering`
59 1 Oscar van Eijk
  , `enabled`, `protected`, `client_id`, `checked_out`, `checked_out_time`, `params`)
60
VALUES
61 16 Valérie Isaksen
 (NULL, 'plugin', 'plg_vmshipper_weight_countries', 'weight_countries', 'vmshipper', 1, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
62 1 Oscar van Eijk
,(NULL, 'plugin', 'plg_vmshipper_products_countries', 'products_countries', 'vmshipper', 1, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
63 24 Valérie Isaksen
,(NULL, 'plugin', 'plg_vmshipper_orderamount_countries', 'orderamount_countries', 'vmshipper', 1, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
64 14 Valérie Isaksen
;
65 12 Christopher Roussel
</pre>
66 19 Valérie Isaksen
Next, when you did not use the svn checkout, copy the plugin files (weight_countries.php, weight_countries.xml, products_countries.php and products_countries.XML), located in the folder /plugins/vmshipper, to the Joomla plugin directory. If that doesn't exist, it must be created first.
67 1 Oscar van Eijk
68 19 Valérie Isaksen
Now use the 'Shipping methods' menu item in the backend to add 1 or more shipping methods. Give a shipping method name, select the shipping method,and click Apply button to display the appropriate parameters in the configuration tab. 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).
69
Make sure a there's always a valid shipping rate: the plugin must be able to find a matching rate based on the shipto address!
70 1 Oscar van Eijk
71 5 Oscar van Eijk
h2. Plugin Development
72 1 Oscar van Eijk
73 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.
74
75
h3. Payment Plugins
76
77 7 Oscar van Eijk
Payment plugins are used both in the front-end and the backend. They must be created as classes deriving from the base class *vmPaymentPlugin*:
78 9 Oscar van Eijk
<pre><code class="php">
79 7 Oscar van Eijk
class plgVmPayment<myPlugin> extends vmPaymentPlugin {
80
	function plgVmPayment<myPlugin>(&$subject, $config) {
81
		$this->_pelement = basename(__FILE__, '.php');	// Required!
82
		$this->_createTable();				// Required, see below
83
		parent::__construct($subject, $config);
84
	}
85
}
86 9 Oscar van Eijk
</code></pre>
87 7 Oscar van Eijk
88
Below is the list with events and a description on what moment they are fired.
89 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.
90 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.
91
+Return:+
92
It must return the HTML code for displaying the form (radio button and optional extra selections).
93
+Parameters:+
94
# (VirtueMartCart object) The cart object 
95
# (integer, default 0) ID of an already selected payment method ID, if any
96
97 6 Oscar van Eijk
* *plgVmOnPaymentSelectCheck()* - This event is fired after the payment method has been selected. It can be used to store
98 5 Oscar van Eijk
additional payment info in the cart.
99
+Return:+
100
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
101
+Parameters:+
102
# (VirtueMartCart object) The cart object 
103
104 10 Oscar van Eijk
105
106 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.
107 5 Oscar van Eijk
+Return:+
108
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
109
+Parameters:+
110
None
111
112 6 Oscar van Eijk
* *plgVmOnConfirmedOrderStorePaymentData()* - This event is fired after the payment has been processed; it stores the payment method-specific data.
113 5 Oscar van Eijk
All plugins _must_ reimplement this method.
114
+Return:+
115
If the plugin is NOT actually executed (not the selected payment method), this method must return NULL
116
If this plugin IS executed, it MUST return the order status code that the order should get. This triggers the stock updates if required
117
+Parameters:+
118
# (integer) The ordernumber being processed
119
# (object) Data from the cart
120
# (array) Price information for this order
121
	
122 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.
123 5 Oscar van Eijk
All plugins _must_ reimplement this method.
124
+Return:+
125
Null when for payment methods that were not selected, text (HTML) otherwise
126
+Parameters:+
127
# (integer) The order ID
128
# (integer) Payment method used for this order
129
130 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.
131 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
132 9 Oscar van Eijk
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
133 5 Oscar van Eijk
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
134
	return;
135 9 Oscar van Eijk
}</code></pre>
136 5 Oscar van Eijk
+Parameters:+
137
 (integer The order ID
138
 (char) Previous order status
139
 (char) New order status
140
141 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
142 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
143 9 Oscar van Eijk
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
144 5 Oscar van Eijk
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
145
	return;
146 9 Oscar van Eijk
}</code></pre>
147 5 Oscar van Eijk
+Return:+
148
True on success, False on failure, Null if this plugin was not activated
149
+Parameters:+
150 1 Oscar van Eijk
# (integer) Order ID
151 7 Oscar van Eijk
152
Other helper functions inherited from the base class:
153
154 9 Oscar van Eijk
* *_ createTable()* - This method is used to create and maintain the plugin specific database table(s).
155 7 Oscar van Eijk
It _must_ be reimplemented by all plugins.
156 1 Oscar van Eijk
+Example:+
157 8 Oscar van Eijk
<pre><code class="php">
158 7 Oscar van Eijk
$_scheme = DbScheme::get_instance();
159
$_scheme->create_scheme('#__vm_order_payment_'.$this->_pelement);
160
$_schemeCols = array(
161
	 'id' => array (
162
			 'type' => 'int'
163
			,'length' => 11
164
			,'auto_inc' => true
165
			,'null' => false
166
	)
167
	,'order_id' => array (
168
			 'type' => 'int'
169
			,'length' => 11
170
			,'null' => false
171
	)
172
	,'payment_method_id' => array (
173
			 'type' => 'text'
174
			,'null' => false
175
	)
176
);
177
$_schemeIdx = array(
178
	 'idx_order_payment' => array(
179
			 'columns' => array ('order_id')
180
			,'primary' => false
181
			,'unique' => false
182
			,'type' => null
183
	)
184
);
185
$_scheme->define_scheme($_schemeCols);
186
$_scheme->define_index($_schemeIdx);
187
if (!$_scheme->scheme()) {
188
	JError::raiseWarning(500, $_scheme->get_db_error());
189
}
190
$_scheme->reset();
191 8 Oscar van Eijk
</code></pre>
192 7 Oscar van Eijk
193 8 Oscar van Eijk
* *getPaymentMethodForOrder()* - Get the order payment ID for a given order number
194 7 Oscar van Eijk
+Return:+
195
The payment method ID, or -1 when not found 
196
+Parameters:+
197
# (integer) The order ID
198
199 8 Oscar van Eijk
* *getThisMethodName()* - Get the name of the payment method.
200 7 Oscar van Eijk
This method can _not_ be reimplemented
201
+Return:+
202
Paymenent method name
203
+Parameters:+
204
# (integer) The payment method ID
205
206 8 Oscar van Eijk
* *selectedThisMethod()* - This method checks if the selected payment method matches the current plugin
207 7 Oscar van Eijk
+Return:+
208
True if the calling plugin has the given payment ID, False otherwise.
209
+Parameters:+
210
# (string) Element name, taken from the plugin filename
211
# (integer) The payment method ID
212
213 8 Oscar van Eijk
* *writePaymentData()* - This method writes all payment plugin specific data to the plugin's table
214 7 Oscar van Eijk
+Return:+
215
True if the calling plugin has the given payment ID, False otherwise.
216
+Parameters:+
217
# (array) Indexed array in the format 'column_name' => 'value'
218
# (string) Table name
219 10 Oscar van Eijk
220
h3. Shipper Plugins
221
222
Shipper plugins are used both in the front-end and the backend. They must be created as classes deriving from the base class *vmShipperPlugin*:
223
<pre><code class="php">
224
class plgVmShipper<myPlugin> extends vmShipperPlugin {
225
	function plgVmPayment<myPlugin>(&$subject, $config) {
226
		$this->_pelement = basename(__FILE__, '.php');	// Required!
227
		$this->_createTable();				// Required, see below
228
		parent::__construct($subject, $config);
229
	}
230
}
231
</code></pre>
232
233
Here's a short overview of the events:
234
* When a shopper selects a shipper, *plgOnSelectShipper()* is fired. It displays the shipper and can be used for collecting extra - shipper specific - info.
235
* After selecting, *plgVmShipperSelected()* can be used to store extra shipper info in the cart. The selected shipper ID will be stored in the cart by the checkout process before this method is fired.
236
* *plgOnConfirmShipper()* is fired when the order is confirmed and stored to the database. It is called before the rest of the order or stored, when reimplemented, it _must_ include a call to parent::plgOnConfirmShipper() (or execute the same steps to put all data in the cart)
237
238
When a stored order is displayed in the backend, the following events are used:
239
* *plgVmOnShowOrderShipperBE()* displays specific data about (a) shipment(s) (NOTE: this plugin is _OUTSIDE_ any form!)
240
* *plgVmOnShowOrderLineShipperBE()*) can be used to show information about a single orderline, e.g. display a package code at line level when more packages are shipped.
241
* *plgVmOnEditOrderLineShipperBE() can be used add a package code for an order line when more packages are shipped.
242
* *plgVmOnUpdateOrderShipperBE()* is fired inside a form. It can be used to add shipper data, like package code.
243
* *plgVmOnSaveOrderShipperBE()* is fired from the backend after the order has been saved. If one of the show methods above have to option to add or edit info, this method must be used to save the data.
244
* *plgVmOnUpdateOrderLine()* is fired from the backend after an order line has been saved. This method must be reimplemented if plgVmOnEditOrderLineShipperBE() is used.
245 22 Valérie Isaksen
* *plgVmOnShipperSelectedCalculatePrice()* is fired before the order is saved, and used to calculate the cart prices. 
246
* *plgVmOnConfirmedOrderStoreShipperData()* This event is fired after the order has been stored; it gets the shipping method specific data.
247 10 Oscar van Eijk
248
The frontend 1 show method:
249
* plgVmOnShowOrderShipperFE() collects and displays specific data about (a) shipment(s)
250
251
Below is the list with events and a description on what moment they are fired.
252
253
* *plgVmOnSelectShipper()* - This event is fired during the checkout process. It allows the shopper to select one of the available shippers.
254
It should display a radio button (name: shipper_id) to select the shipper. In the description, the shipping cost can also be displayed, based on the total order weight and the shipto country (this wil be calculated again during order confirmation)
255
+Return:+
256
HTML code to display the form
257
+Parameters:+
258
# (VirtueMartCart object)  Cart object
259
# (integer, default 0) ID of the currently shipper selected
260
261
* *plgVmOnShipperSelected()* - This event is fired after the shipping method has been selected. It can be used to store additional shipper info in the cart.
262
+Return:+
263
True on succes, false on failures, null when this plugin was not selected.
264 1 Oscar van Eijk
On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
265
+Parameters:+
266
# (VirtueMartCart object)  Cart object
267
# (integer, default 0) ID of the shipper selected
268 16 Valérie Isaksen
269 21 Valérie Isaksen
* *plgVmOnShipperSelectedCalculatePrice()* - This event is fired before the order is saved, and used to calculate the cart prices.  
270 16 Valérie Isaksen
+Return:+
271
True on succes, false on failures, null when this plugin was not selected.
272
On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
273
+Parameters:+
274
# (VirtueMartCart object)  Cart object
275
# (integer, default 0) ID of the shipper selected
276
# (array, default 0)  Shipping array containing: shipping_name, shipping_value, shipping_rate_vat_id, shipping_currency_id
277
278
279 10 Oscar van Eijk
280 20 Valérie Isaksen
* *plgVmOnConfirmShipper()* - This event is fired after the payment has been processed; it selects the actual shipping rate  and/or order weight, and optionally writes extra info to the database (in which case this method must be reimplemented).
281 10 Oscar van Eijk
Reimplementation is not required, but when done, the following check MUST be made:
282
<pre><code class="php">
283
if (!$this->selectedThisShipper($this->_selement, $_cart->shipper_id)) {
284
	return null;
285
}</code></pre>
286
+Return:+
287
The shipping rate ID
288
Do _not_ return parent::plgVmOnConfirmShipper($_cart); it is valid but will produce extra overhead!
289
+Parameters:+
290 1 Oscar van Eijk
# (VirtueMartCart object) Cart object
291 21 Valérie Isaksen
292 20 Valérie Isaksen
293
* *plgVmOnConfirmedOrderStoreShipperData()* This event is fired after the order has been stored; it gets the shipping method specific data.
294
+Return:+mixed Null when this method was not selected, otherwise true
295
#(integer) The order_id being processed
296
#(object) the cart
297
#array Price information for this order
298
299
300 10 Oscar van Eijk
301
* *plgVmOnShowOrderShipperBE()* - This method is fired when showing the order details in the backend. It displays the shipper-specific data.
302
NOTE, this plugin should NOT be used to display form fields, since it's called outside a form! Use *plgVmOnUpdateOrderBE()( instead!
303
+Return:+
304
Null for shippers that aren't active, text (HTML) otherwise
305
+Parameters:+
306
# (integer) The order ID
307
# (integer) Vendor ID
308
# (object) Object with 2 properties 'carrier' and 'name' 
309
310
* *plgVmOnEditOrderLineShipperBE()* - This method is fired when editing the order line details in the backend. It can be used to add line specific package codes
311
+Return:+
312
Null for shippers that aren't active, text (HTML) otherwise
313
+Parameters:+
314
# (integer) The order ID
315
# (integer) The order Line ID
316
317
* *plgVmOnUpdateOrderShipper()* - Save updated order data to the shipper specific table
318
+Return:+
319
True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
320
+Parameters:+
321
# (array) Form data
322
323
* *plgVmOnUpdateOrderLineShipper()* - Save updated orderline data to the shipper specific table
324
+Return:+
325
True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
326
+Parameters:+
327
# (array) Form data
328
329
* *plgVmOnShowOrderShipperFE()* - This method is fired when showing the order details in the frontend.  It displays the shipper-specific data.
330
+Return:+
331
Null for shippers that aren't active, text (HTML) otherwise
332
+Parameters:+
333
# (integer) The order ID
334
335
* *plgVmOnShowOrderLineShipperFE()* - This method is fired when showing the order details in the frontend, for every orderline. It can be used to display line specific package codes, e.g. with a link to external tracking and tracing systems
336
+Return:+
337
Null for shippers that aren't active, text (HTML) otherwise
338
+Parameters:+
339
# (integer) The order ID
340
# (integer) The order LineID
341
342
Other helper functions inherited from the base class:
343
344
* *_ createTable()* - This method is used to create and maintain the plugin specific database table(s).
345
It _must_ be reimplemented by all plugins.
346
+Example:+
347
<pre><code class="php">$_scheme = DbScheme::get_instance();
348
$_scheme->create_scheme('#__vm_order_shipper_'.$this->_selement);
349
$_schemeCols = array(
350
	 'id' => array (
351
			 'type' => 'int'
352
			,'length' => 11
353
			,'auto_inc' => true
354
			,'null' => false
355
	)
356
	,'order_id' => array (
357
			 'type' => 'int'
358
			,'length' => 11
359
			,'null' => false
360
	)
361
	,'shipper_id' => array (
362
			 'type' => 'text'
363
			,'null' => false
364
	)
365
);
366
$_schemeIdx = array(
367
	 'idx_order_payment' => array(
368
			 'columns' => array ('order_id')
369
			,'primary' => false
370
			,'unique' => false
371
			,'type' => null
372
	)
373
);
374
$_scheme->define_scheme($_schemeCols);
375
$_scheme->define_index($_schemeIdx);
376
if (!$_scheme->scheme()) {
377
	JError::raiseWarning(500, $_scheme->get_db_error());
378
}
379
$_scheme->reset();
380
</code></pre>
381
382
* *getThisShipperName()* -  Get the name of the shipper
383
+Return:+
384
Shipper name
385
+Parameters:+
386
# (integer) The Shipper ID
387
	final protected function ($_sid)
388
389
* *writeShipperData()* - This method writes all shipper plugin specific data to the plugin's table
390
+Parameters:+
391
# (array) Indexed array in the format 'column_name' => 'value'
392
# (string) Table name
393
394
* *getShippingRateIDForOrder()* - Get the shipping rate ID for a given order number
395
+Return:+
396
The shipping rate ID, or -1 when not found 
397
+Parameters:+
398
# (integer) The order ID
399
400
* *getShippingRate()* -  Get the total price for a shipping rate
401
+Return:+
402
Price in display format
403
+Parameters:+
404
# (integer) Shipping rate ID
405
	
406
* *getShipperIDForOrder()* - Get the shipper ID for a given order number
407
+Return:+
408
The shipper ID, or -1 when not found 
409
+Parameters:+
410
# (integer) The order ID
411
412
* *selectShippingRate()* - Select the shipping rate ID, based on the selected shipper in combination with the shipto address (country and zipcode) and the total order weight.
413
+Return:+
414
Shipping rate ID, -1 when no match is found. Only 1 selected ID will be returned; if more ID's match, the cheapest will be selected.
415
+Parameters:+
416
# (VirtueMartCart object) Cart object
417
# (integer, default 0) Shipper ID, by default taken from the cart
418
419
* *selectedThisShipper()* - This method checks if the selected shipper matches the current plugin
420
+Return:+
421
True if the calling plugin has the given payment ID
422
+Parameters:+
423
# (string) Element name, taken from the plugin filename
424
# (integer) The shipper ID
425
426
* *getOrderWeight()* - Get the total weight for the order, based on which the proper shipping rate can be selected.
427
+Return:+
428
Total weight for the order
429
+Parameters:+
430
# (VirtueMartCart object) Cart object
431
432 18 Valérie Isaksen
* *getShippers()* - Fill an array with all shippers found with this plugin for the current vendor
433 10 Oscar van Eijk
+Return:+
434 23 Valérie Isaksen
True when shipper(s) was (were) found for this vendor, false otherwise
435 10 Oscar van Eijk
+Parameters:+
436
# (integer) The vendor ID taken from the cart.
437
438
* *validateVendor()* - Check if this shipper has carriers for the current vendor.
439
+Return:+
440
True when a shipper_id was found for this vendor, false otherwise
441
+Parameters:+
442
# (integer) The vendor ID taken from the cart.