Project

General

Profile

Shipper Plugins » History » Version 2

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