Using com_ajax for Modules, Plugins and Templates
This section demonstrates how you can use Ajax within your modules, plugins and templates by making use of com_ajax. Because you can't send an HTTP request directly to your module/plugin/template you have to use com_ajax as a proxy, and it will pass control to your extension based on parameters within the Ajax HTTP request.
You can also use com_ajax in a manner not related to Ajax calls, to support defining a URL for ad hoc jobs.
Modules
To pass an Ajax call to a module you need to set within the URL of the Ajax HTTP request
- option - com_ajax
- module - the name of your module without the "mod_" prefix.
- method - when "Ajax" is added as a suffix, this is the name of the module's helper method to call
- format - the format of response expected - either "json" or "raw"
The method to call must a public instance function of your module's helper class,
and the helper class must be named <Modulename>Helper
, and be namespaced following the Joomla pattern for helper classes.
Your helper function just returns the required data; com_ajax will use JsonResponse to provide a JSON or raw format output,
depending on the format
parameter in the HTTP Request.
If you choose format=raw then whatever is returned from the helper method is echoed directly to the output.
Module Example
You can find an example in the Module Tutorial step 9 Ajax.
In this example:
- the module is called mod_hello
- the method within the helper file is countAjax()
- the format requested is json.
Hence the URL has to be of the form:
index.php?option=com_ajax&module=hello&method=count&format=json
Plugins
This works by com_ajax raising an Event called OnAjax<Methodname>
which your plugin must listen for.
To pass an Ajax call to a plugin you need to set within the URL of the Ajax HTTP request
- option - com_ajax
- plugin - when "OnAjax" is added as a prefix, this is the name of the event which is dispatched
- format - the format of response expected - either "json" or "raw"
Your plugin should be of the "ajax" plugin group, so in your plugin's manifest file:
<extension method="upgrade" type="plugin" group="ajax">
Your plugin should add the result to the event "result" argument and com_ajax will use JsonResponse to provide a JSON or raw format output,
depending on the format
parameter in the HTTP Request.
Your plugin can raise an Exception, and this will be captured by com_ajax and treated as a failure, with the Exception text being passed down in the Ajax response.
Plugin Example
As an example you can easily modify the com_ajaxdemo code of the Ajax documentation section.
Within media/js/divide.js just change the line:
let url = vars.root + 'index.php?option=com_ajaxdemo&format=json&task=ajax.divide';
to
let url = vars.root + 'index.php?option=com_ajax&plugin=divide&format=json',
This will route the Ajax HTTP request to com_ajax, which will import the "ajax" plugin group, and raise the "OnAjaxDivide" event.
You can download plg_ajaxdemo, and then install and enable this plugin. This plugin performs the a/b division in a similar way to the com_ajaxdemo component.
Templates
To pass an Ajax call to a template you need to set within the URL of the Ajax HTTP request
- option - com_ajax
- template - the name of the template (eg cassiopeia)
- method - when "Ajax" is added as a suffix, this is the name of the method within the template's helper method to call
- format - the format of response expected - either "json" or "raw"
The method to call must a public static function of your template's helper class,
and the helper class must be named Tpl<Templatename>Helper
, and be in helper.php within the template's directory.
Your helper function just returns the required data; com_ajax will use JsonResponse to provide a JSON or raw format output,
depending on the format
parameter in the HTTP Request.
If you choose format=raw then whatever is returned from the helper method is echoed directly to the output.
Template Example
As an example you can easily modify the com_ajaxdemo code of the Ajax documentation section.
Within media/js/divide.js just change the line:
let url = vars.root + 'index.php?option=com_ajaxdemo&format=json&task=ajax.divide';
to
let url = vars.root + 'index.php?option=com_ajax&template=cassiopeia&format=json',
Then store the following file:
<?php
defined('_JEXEC') or die;
use Joomla\CMS\Factory;
class TplCassiopeiaHelper
{
public static function divideAjax()
{
$app = Factory::getApplication();
$input = $app->input;
$a = $input->get("a", 0, "float");
$b = $input->get("b", 0, "float");
$result = self::_divide($a, $b);
return $result;
}
private static function _divide($a, $b)
{
if ($b == 0)
{
throw new \Exception('Division by zero!');
}
return $a/$b;
}
}
Of course, you should never write files in a folder belonging to Joomla's core files.
However, if you have developed your own template, or if you have created a child template of cassiopeia, then you can use that template, and store the helper.php file in that template's directory.