Project

General

Profile

Shipper Plugins » History » Version 5

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