Project

General

Profile

Plugin system » History » Version 9

Oscar van Eijk, 02/07/2011 02:36 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 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*:
55 9 Oscar van Eijk
<pre><code class="php">
56 7 Oscar van Eijk
class plgVmPayment<myPlugin> extends vmPaymentPlugin {
57
	function plgVmPayment<myPlugin>(&$subject, $config) {
58
		$this->_pelement = basename(__FILE__, '.php');	// Required!
59
		$this->_createTable();				// Required, see below
60
		parent::__construct($subject, $config);
61
	}
62
}
63 9 Oscar van Eijk
</code></pre>
64 7 Oscar van Eijk
65
Below is the list with events and a description on what moment they are fired.
66 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.
67 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.
68
+Return:+
69
It must return the HTML code for displaying the form (radio button and optional extra selections).
70
+Parameters:+
71
# (VirtueMartCart object) The cart object 
72
# (integer, default 0) ID of an already selected payment method ID, if any
73
74 6 Oscar van Eijk
* *plgVmOnPaymentSelectCheck()* - This event is fired after the payment method has been selected. It can be used to store
75 5 Oscar van Eijk
additional payment info in the cart.
76
+Return:+
77
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
78
+Parameters:+
79
# (VirtueMartCart object) The cart object 
80
81 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.
82 5 Oscar van Eijk
+Return:+
83
Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
84
+Parameters:+
85
None
86
87 6 Oscar van Eijk
* *plgVmOnConfirmedOrderStorePaymentData()* - This event is fired after the payment has been processed; it stores the payment method-specific data.
88 5 Oscar van Eijk
All plugins _must_ reimplement this method.
89
+Return:+
90
If the plugin is NOT actually executed (not the selected payment method), this method must return NULL
91
If this plugin IS executed, it MUST return the order status code that the order should get. This triggers the stock updates if required
92
+Parameters:+
93
# (integer) The ordernumber being processed
94
# (object) Data from the cart
95
# (array) Price information for this order
96
	
97 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.
98 5 Oscar van Eijk
All plugins _must_ reimplement this method.
99
+Return:+
100
Null when for payment methods that were not selected, text (HTML) otherwise
101
+Parameters:+
102
# (integer) The order ID
103
# (integer) Payment method used for this order
104
105 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.
106 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
107 9 Oscar van Eijk
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
108 5 Oscar van Eijk
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
109
	return;
110 9 Oscar van Eijk
}</code></pre>
111 5 Oscar van Eijk
+Parameters:+
112
 (integer The order ID
113
 (char) Previous order status
114
 (char) New order status
115
116 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
117 5 Oscar van Eijk
When reimplementing this methis, the body _must_ start with this code:
118 9 Oscar van Eijk
<pre><code class="php">$_paymethodID = $this->getPaymentMethodForOrder($_orderID);
119 5 Oscar van Eijk
if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
120
	return;
121 9 Oscar van Eijk
}</code></pre>
122 5 Oscar van Eijk
+Return:+
123
True on success, False on failure, Null if this plugin was not activated
124
+Parameters:+
125 1 Oscar van Eijk
# (integer) Order ID
126 7 Oscar van Eijk
127
Other helper functions inherited from the base class:
128
129 9 Oscar van Eijk
* *_ createTable()* - This method is used to create and maintain the plugin specific database table(s).
130 7 Oscar van Eijk
It _must_ be reimplemented by all plugins.
131 1 Oscar van Eijk
+Example:+
132 8 Oscar van Eijk
<pre><code class="php">
133 7 Oscar van Eijk
$_scheme = DbScheme::get_instance();
134
$_scheme->create_scheme('#__vm_order_payment_'.$this->_pelement);
135
$_schemeCols = array(
136
	 'id' => array (
137
			 'type' => 'int'
138
			,'length' => 11
139
			,'auto_inc' => true
140
			,'null' => false
141
	)
142
	,'order_id' => array (
143
			 'type' => 'int'
144
			,'length' => 11
145
			,'null' => false
146
	)
147
	,'payment_method_id' => array (
148
			 'type' => 'text'
149
			,'null' => false
150
	)
151
);
152
$_schemeIdx = array(
153
	 'idx_order_payment' => array(
154
			 'columns' => array ('order_id')
155
			,'primary' => false
156
			,'unique' => false
157
			,'type' => null
158
	)
159
);
160
$_scheme->define_scheme($_schemeCols);
161
$_scheme->define_index($_schemeIdx);
162
if (!$_scheme->scheme()) {
163
	JError::raiseWarning(500, $_scheme->get_db_error());
164
}
165
$_scheme->reset();
166 8 Oscar van Eijk
</code></pre>
167 7 Oscar van Eijk
168 8 Oscar van Eijk
* *getPaymentMethodForOrder()* - Get the order payment ID for a given order number
169 7 Oscar van Eijk
+Return:+
170
The payment method ID, or -1 when not found 
171
+Parameters:+
172
# (integer) The order ID
173
174 8 Oscar van Eijk
* *getThisMethodName()* - Get the name of the payment method.
175 7 Oscar van Eijk
This method can _not_ be reimplemented
176
+Return:+
177
Paymenent method name
178
+Parameters:+
179
# (integer) The payment method ID
180
181 8 Oscar van Eijk
* *selectedThisMethod()* - This method checks if the selected payment method matches the current plugin
182 7 Oscar van Eijk
+Return:+
183
True if the calling plugin has the given payment ID, False otherwise.
184
+Parameters:+
185
# (string) Element name, taken from the plugin filename
186
# (integer) The payment method ID
187
188 8 Oscar van Eijk
* *writePaymentData()* - This method writes all payment plugin specific data to the plugin's table
189 7 Oscar van Eijk
+Return:+
190
True if the calling plugin has the given payment ID, False otherwise.
191
+Parameters:+
192
# (array) Indexed array in the format 'column_name' => 'value'
193
# (string) Table name