Project

General

Profile

Shipper Plugins » History » Version 2

Max Milbers, 07/07/2011 02:14 PM

1 1 Max Milbers
h1. Shipper Plugins
2
3
4
Shipper plugins are used both in the front-end and the backend. They must be created as classes deriving from the base class *vmShipperPlugin*:
5
<pre><code class="php">
6
class plgVmShipper<myPlugin> extends vmShipperPlugin {
7
	function plgVmPayment<myPlugin>(&$subject, $config) {
8
		$this->_pelement = basename(__FILE__, '.php');	// Required!
9
		$this->_createTable();				// Required, see below
10
		parent::__construct($subject, $config);
11
	}
12
}
13
</code></pre>
14
15
Here's a short overview of the events:
16
* When a shopper selects a shipper, *plgOnSelectShipper()* is fired. It displays the shipper and can be used for collecting extra - shipper specific - info.
17
* 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.
18
* *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)
19
20
When a stored order is displayed in the backend, the following events are used:
21
* *plgVmOnShowOrderShipperBE()* displays specific data about (a) shipment(s) (NOTE: this plugin is _OUTSIDE_ any form!)
22
* *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.
23
* *plgVmOnEditOrderLineShipperBE() can be used add a package code for an order line when more packages are shipped.
24
* *plgVmOnUpdateOrderShipperBE()* is fired inside a form. It can be used to add shipper data, like package code.
25
* *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.
26
* *plgVmOnUpdateOrderLine()* is fired from the backend after an order line has been saved. This method must be reimplemented if plgVmOnEditOrderLineShipperBE() is used.
27
* *plgVmOnShipperSelectedCalculatePrice()* is fired before the order is saved, and used to calculate the cart prices. 
28
* *plgVmOnConfirmedOrderStoreShipperData()* This event is fired after the order has been stored; it gets the shipping method specific data.
29
30
The frontend 1 show method:
31
* plgVmOnShowOrderShipperFE() collects and displays specific data about (a) shipment(s)
32
33
Below is the list with events and a description on what moment they are fired.
34
35
* *plgVmOnSelectShipper()* - This event is fired during the checkout process. It allows the shopper to select one of the available shippers.
36
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)
37
+Return:+
38
HTML code to display the form
39
+Parameters:+
40
# (VirtueMartCart object)  Cart object
41
# (integer, default 0) ID of the currently shipper selected
42
43
* *plgVmOnShipperSelected()* - This event is fired after the shipping method has been selected. It can be used to store additional shipper info in the cart.
44
+Return:+
45
True on succes, false on failures, null when this plugin was not selected.
46
On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
47
+Parameters:+
48
# (VirtueMartCart object)  Cart object
49
# (integer, default 0) ID of the shipper selected
50
51
* *plgVmOnShipperSelectedCalculatePrice()* - This event is fired before the order is saved, and used to calculate the cart prices.  
52
+Return:+
53
True on success, false on failures, null when this plugin was not selected.
54
On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
55
+Parameters:+
56
# (VirtueMartCart object)  Cart object
57
# (array )  Shipping array containing: shipping_name, shipping_value, shipping_rate_vat_id 
58
59
60
61
* *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).
62
Reimplementation is not required, but when done, the following check MUST be made:
63
<pre><code class="php">
64
if (!$this->selectedThisShipper($this->_selement, $_cart->shipper_id)) {
65
	return null;
66
}</code></pre>
67
+Return:+
68
The shipping rate ID
69
Do _not_ return parent::plgVmOnConfirmShipper($_cart); it is valid but will produce extra overhead!
70
+Parameters:+
71
# (VirtueMartCart object) Cart object
72
73
74
* *plgVmOnConfirmedOrderStoreShipperData()* This event is fired after the order has been stored; it gets the shipping method specific data.
75
+Return:+mixed Null when this method was not selected, otherwise true
76
#(integer) The order_id being processed
77
#(object) the cart
78
#array Price information for this order
79
80
81
82
* *plgVmOnShowOrderShipperBE()* - This method is fired when showing the order details in the backend. It displays the shipper-specific data.
83
NOTE, this plugin should NOT be used to display form fields, since it's called outside a form! Use *plgVmOnUpdateOrderBE()( instead!
84
+Return:+
85
Null for shippers that aren't active, text (HTML) otherwise
86
+Parameters:+
87
# (integer) The order ID
88
# (integer) Vendor ID
89
# (object) Object with 2 properties 'carrier' and 'name' 
90
91
* *plgVmOnEditOrderLineShipperBE()* - This method is fired when editing the order line details in the backend. It can be used to add line specific package codes
92
+Return:+
93
Null for shippers that aren't active, text (HTML) otherwise
94
+Parameters:+
95
# (integer) The order ID
96
# (integer) The order Line ID
97
98
* *plgVmOnUpdateOrderShipper()* - Save updated order data to the shipper specific table
99
+Return:+
100
True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
101
+Parameters:+
102
# (array) Form data
103
104
* *plgVmOnUpdateOrderLineShipper()* - Save updated orderline data to the shipper specific table
105
+Return:+
106
True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
107
+Parameters:+
108
# (array) Form data
109
110
* *plgVmOnShowOrderShipperFE()* - This method is fired when showing the order details in the frontend.  It displays the shipper-specific data.
111
+Return:+
112
Null for shippers that aren't active, text (HTML) otherwise
113
+Parameters:+
114
# (integer) The order ID
115
116
* *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
117
+Return:+
118
Null for shippers that aren't active, text (HTML) otherwise
119
+Parameters:+
120
# (integer) The order ID
121
# (integer) The order LineID
122
123
Other helper functions inherited from the base class:
124
125
* *_ createTable()* - This method is used to create and maintain the plugin specific database table(s).
126
It _must_ be reimplemented by all plugins.
127
+Example:+
128
<pre><code class="php">$_scheme = DbScheme::get_instance();
129
$_scheme->create_scheme('#__vm_order_shipper_'.$this->_selement);
130
$_schemeCols = array(
131
	 'id' => array (
132
			 'type' => 'int'
133
			,'length' => 11
134
			,'auto_inc' => true
135
			,'null' => false
136
	)
137
	,'order_id' => array (
138
			 'type' => 'int'
139
			,'length' => 11
140
			,'null' => false
141
	)
142
	,'shipper_id' => array (
143
			 'type' => 'text'
144
			,'null' => false
145
	)
146
);
147
$_schemeIdx = array(
148
	 'idx_order_payment' => array(
149
			 'columns' => array ('order_id')
150
			,'primary' => false
151
			,'unique' => false
152
			,'type' => null
153
	)
154
);
155
$_scheme->define_scheme($_schemeCols);
156
$_scheme->define_index($_schemeIdx);
157
if (!$_scheme->scheme()) {
158
	JError::raiseWarning(500, $_scheme->get_db_error());
159
}
160
$_scheme->reset();
161
</code></pre>
162
163
* *getThisShipperName()* -  Get the name of the shipper
164
+Return:+
165
Shipper name
166
+Parameters:+
167
# (integer) The Shipper ID
168
	final protected function ($_sid)
169
170
* *writeShipperData()* - This method writes all shipper plugin specific data to the plugin's table
171
+Parameters:+
172
# (array) Indexed array in the format 'column_name' => 'value'
173
# (string) Table name
174
175
* *getShippingRateIDForOrder()* - Get the shipping rate ID for a given order number
176
+Return:+
177
The shipping rate ID, or -1 when not found 
178
+Parameters:+
179
# (integer) The order ID
180
181
* *getShippingRate()* -  Get the total price for a shipping rate
182
+Return:+
183
Price in display format
184
+Parameters:+
185
# (integer) Shipping rate ID
186
	
187
* *getShipperIDForOrder()* - Get the shipper ID for a given order number
188
+Return:+
189
The shipper ID, or -1 when not found 
190
+Parameters:+
191
# (integer) The order ID
192
193
* *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.
194
+Return:+
195
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.
196
+Parameters:+
197
# (VirtueMartCart object) Cart object
198
# (integer, default 0) Shipper ID, by default taken from the cart
199
200
* *selectedThisShipper()* - This method checks if the selected shipper matches the current plugin
201
+Return:+
202
True if the calling plugin has the given payment ID
203
+Parameters:+
204
# (string) Element name, taken from the plugin filename
205
# (integer) The shipper ID
206
207
* *getOrderWeight()* - Get the total weight for the order, based on which the proper shipping rate can be selected.
208
+Return:+
209
Total weight for the order
210
+Parameters:+
211
# (VirtueMartCart object) Cart object
212
213
* *getShippers()* - Fill an array with all shippers found with this plugin for the current vendor
214
+Return:+
215
True when shipper(s) was (were) found for this vendor, false otherwise
216
+Parameters:+
217
# (integer) The vendor ID taken from the cart.
218
219
* *validateVendor()* - Check if this shipper has carriers for the current vendor.
220
+Return:+
221
True when a shipper_id was found for this vendor, false otherwise
222
+Parameters:+
223
# (integer) The vendor ID taken from the cart.
224
225
* *getShippingHtml* - returns the HTML code to display the form, based on the $shipper_name, $shipper_id, $selectedShipper, $shipper_logo, $shipping_value, $tax_id, $currency_id. To be used by the function plgVmOnSelectShipper().
226
+Return:+
227
returns HTML code to display the form
228
+Parameters:+
229
# (string)  shipper_name
230
# (integer) shipper_id
231
# (integer) selectedShipper id
232
# (string)  shipper_logo to be displayed
233
# (integer) shipping_value to use to calculate the SalesPriceShipping
234
# (integer) tax_id to use to calculate the SalesPriceShipping
235
236
237
* *calculateSalesPriceShipping()* - Returns the 'salesPriceShipping' for a given shipping value, tax id, and currency id.
238
+Return:+
239
returns salesPriceShipping
240
+Parameters:+
241
# (integer) shipping_value 
242
# (integer) tax_id
243
# (integer) currency_id
244
245
* *getShipperLogo()* - Returns the shipper logo image html.
246
+Return:+
247
returns the html code to display the image
248
+Parameters:+
249
# (string) logo image name
250
# (string) alt text to the image
251 2 Max Milbers
252
Back to [[Plugin system]]