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