Before we start, please make sure that you know the basics of building Joomla! plugins:
https://docs.joomla.org/J3.x:Creating_a_Plugin_for_Joomla
What we should know in the first place is that our plugin should belong to a group named "djcatalog2payment". For example, if the plugin is named "my_plugin" then plugin's directory and its files should be stored in:
JROOT/plugins/djcatalog2payment/my_plugin
The plugin directory should contain one PHP (plugin's class) and one XML (manifest file) files named after the name of the plugin:
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin.php
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin.xml
It is also recommended to place language files inside the "language" directory. In this case, the path and names would be:
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin/language/en-GB/en-GB.plg_djcatalog2payment_my_plugin.ini
JROOT/plugins/djcatalog2payment/my_plugin/my_plugin/language/en-GB/en-GB.plg_djcatalog2payment_my_plugin.sys.ini
Finally, and this will be covered later in this article, you can create another XML file in the following location:
JROOT/plugins/djcatalog2payment/my_plugin/config/configuration.xml
We strongly suggest you have a look at existing plugins that are the part of DJ-Catalog2 package by default such as "Standard" and "PayPal" payment plugins.
The manifest file of the payment plugin is not different than a regular manifest file. It's important to remember that the "group" attribute should. Here's an example of the manifest file used in "Standard" payment plugin:
- <?xml version="1.0" encoding="utf-8"?>
- <extension
- type="plugin"
- version="3.0"
- client="site"
- method="upgrade"
- group="djcatalog2payment">
- <name>plg_djcatalog2payment_standard</name>
- <creationDate>March 2015</creationDate>
- <author>DJ-Extensions.com</author>
- <copyright>Copyright (C) 2010-2012 DJ-Extensions.com, All rights reserved.</copyright>
- <license> http://www.gnu.org/licenses GNU/GPL</license>
- <version>1.1</version>
- <description>PLG_DJCATALOG2PAYMENT_STANDARD_DESCRIPTION</description>
- <files>
- <filename plugin="standard">standard.php</filename>
- <filename>index.html</filename>
- <folder>language</folder>
- <folder>config</folder>
- </files>
- <config>
- </config>
- </extension>
- defined('_JEXEC') or die('Restricted access'); class plgDjcatalog2paymentStandard extends JPlugin { protected $autoloadLanguage = true; protected function isAllowed($plgInfo, $type = 'djcatalog2payment') { // .... } public function onContentPrepareForm($form, $data) { // .... } public function onDJC2BeforeSaveOrder($context, $table, $isNew, $plgInfo) { // .... } public function onDJC2AfterSaveOrder($context, $table, $isNew, $plgInfo) { // .... } public function onDJC2CheckoutDetailsDisplay($context, $plgInfo) { // .... } public function onDJC2OrderDetailsDisplay($context, $order, $plgInfo) { // .... } public function onEmailAfterPaymentDisplay($context, $data, $plgInfo) { // .... } public function onDJC2PaymentProcess($context, $order, $plgInfo) { // .... } public function onDJC2EmailAfterPaymentDisplay($context, $order, $plgInfo) { // .... } }
This method allows you to determine whether your specific plugin should be allowed to be triggered in a specific context. For example, if a customer chooses a different payment method that is not controlled by your plugin then isAllowed method should return false. Usually, the following code should be sufficient in most cases:
- protected function isAllowed($plgInfo, $type = 'djcatalog2payment'){ return (bool)($plgInfo->plugin == $this->_name && $this->_type == $type); }
- `name` varchar(255) NOT NULL, `description` text, `published` tinyint(4) NOT NULL, `plugin` varchar(255) NOT NULL, `price` decimal(14,4) DEFAULT NULL, `tax_rule_id` int(11) NOT NULL, `free_amount` decimal(14,4) DEFAULT NULL, `ordering` int(11) NOT NULL DEFAULT '0', `params` text, `access` int(11) NOT NULL DEFAULT '0', `countries` mediumtext, `postcodes` text, `recurring` tinyint(4) NOT NULL DEFAULT '0',
This event is triggered in the back-end area when administrator is editing a Payment Method. It allows to provide an XML file containing set of additional fields (usually settings) that will later be renderd in payment method "settings" tab:
Below you fill find a sample code
- public function onContentPrepareForm($form, $data){ if ($form->getName() != 'com_djcatalog2.payment') { return; } $plugin = ''; if (!empty($data) && !empty($data->plugin)) { $plugin = $data->plugin; } else { $jform = JFactory::getApplication()->input->get('jform', array(), 'array'); if (!empty($jform) && isset($jform['plugin'])) { $plugin = $jform['plugin']; } } if ($plugin != $this->_name) { return true; } return $form->loadFile(dirname(__FILE__) . '/config/configuration.xml', false); }
This event is triggered right before the order is stored in the database.
This event is triggered right after the order is stored in the database.
This method should return a string, usually HTML formatted that displays the information about the payment. The information will appear during checkout when a customer selects payment method, e.g.:
This event is triggered when a customer opens the Order Details page which is displayed after a customer confirms the order (finishes checkout). In most cases, this method should render either a link such as the "Pay Now" button. The link should contain a very specific URL that begins the payment processing. The URL should be constructed as follows:
JRoute::_('index.php?option=com_djcatalog2&task=paymentProcess&oid='.$order->id.'&plg='.$plgInfo->plugin.'&plgid='.$plgInfo->id);
When a customer hits that link, the component will keep the record of the fact that the customer initiated the payment and after that, another plugin event (onDJC2PaymentProcess) will be triggered.
It is probably the most important of all the events which are triggered by DJ-Catalog2 after the checkout. The method, depending on the nature of the payment gateway you are integrating with, is used to either redirect the customer from your site to payment gateway or otherwise process payment request. At this point, you will usually need to return a string containing hidden HTML form which will automatically be posted to the payment processor.
This method is executed before onDJC2PaymentResponse() and it concerns a situation when Payment Gateway sends a notification about the status of customer's payment. This method is supposed to analyze the request from the gateway and return the ID (integer) of the order in which payment status is to be updated.
This method is actually a webhook. It is executed behind the scenes when the payment processor sends to your website a notification about the status of the payment. Here you should receive the data from the gateway, validate it, and update the status of the order using $model->changeStatus() method. The method accepts the following arguments:
changeStatus($order, $value, $notifyUser, $notifyAdmin, $statusComment = '')
where