Vince's aide memoire to making gateway mini-components for Jomres
This is a series of notes to indicate what each of the files in the gateway plugins do.
For a long time Jomres was stuck with having a small handful of gateways. Partly because due to time I was unable to create more and partly because each new gateway would require a fresh version of Jomres to release it. V2 has changed that because of it's mini-component handling functionality. Gateways are now handled like mini-components in that they are freely installable (although Jomres has the basic "form" and "paypal" options installed by default).
The components of a payment module in Jomres:
Obviously _GATEWAYNAME_ is substituted with the name of the gateway in question. Gateways are only triggered at the Confirm Booking stage when the user doing the booking is not an authorised manager.
Brief explanation of each file and what it does
Called by: j00501gateways.class.php
Purpose: To acknowledge existence of the module to the configuration panel "gateways".
Notes: When the gateways config panel is generated this file is called. It generates the link seen in the config panel that is clicked to enable the gateway module configuration popup.
Called by: Independently triggered by clicking on link generated by j00509_GATEWAYNAME_.class.php above
Purpose: Compiles configuration options that the user can edit.
Called by: j00509_GATEWAYNAME_.class.php,j00510_GATEWAYNAME_.class.php, j03108_GATEWAYNAME_.class.php (indirectly)
Purpose: The gateway image
Called by: j00510_GATEWAYNAME_.class.php
Purpose: patTemplate file used when generating module configuration popup
Called by: jomres.php
Purpose: 00600 module interrupt.
Notes: function showBookingConfirmation in jomres_bookingroom_functions.php lists active gateway modules. When a gateway is chosen and the customer clicks submit to proceed to payment the module designer is able to program an 'interrupt' that will be triggered before the customer is sent off-site to perform payment. This enables data collection that the system has not collected elsewhere that the module specifically requires. This file is optional, if it doesn't exist then Jomres will skip it and go straight to 00605 eventTrigger.
Called by: j00600_GATEWAYNAME_.class.php
Purpose: patTemplate file for generating input/output for j00600 class file.
Called by: jomres.php
Purpose: Sends any required postage data to payment gateway, eg paypal. and redirects the user to the payment gateway's interface.
Notes: Is triggered after 00605, or if 00605 doesn't exist then is called straight away.
Called by: jomres.php
Purpose: Is called by payment gateways confirming receipt of payment, and when customers are redirected back to the jomres site after payment.
Notes: It is worth noting that the payment data is still only stored in the temporary session data at this point. It is only when the insertInternetBooking function is specifically called, normally by this file but there are other places it can be called, that the booking is transferred from the temporary data to the contracts table. If the process is not completed then the booking is technically lost. Available but liable to be overwritten if the guest should return to the booking form). Also note that in some cases this file may be optional, eg. the cheque (or offline payment) module doesn't use it, the insertInternetBooking function is called by 00605cheque.class.php as there's no extra processing required.
Because the temporary data is stored in session variables it's not unheard of for Paypal's IPN to take so long returning it's information that the session has expired and the data lost, therefore it's advised that you up the Joomla session timeout from the pretty short timescale configured by the CMS's to something a little more reasonable. I can't suggest what's reasonable because that's down to you to decide what's best, but I wouldn't be surprised if many people set their timeouts to an hour or more.
Called by: function showBookingConfirmation in jomres_bookingroom_functions.php
Purpose: Reports file path to the calling function.
Notes: Provides the calling function with the path to the gateway gif.
before you do the insert otherwise Jomres will mark the deposit as unpaid.
Finally, don't attempt to clean up any data stored in $tmpBookingHandler unless you specifically put it there yourself (you probably won't need to), I had another gateway developer do the same and it caused Jomres to behave in some very weird and wonderful ways until I took it out. Jomres will clean up that variable itself in the "insertInternetBooking" function.
This document is copyright Vince Wooll/Woollyinwales IT, 2011. All rights reserved.