JAM Plugin Tutorial

JAM Plugin Tutorial - Overview

The Joomla! Admin Mobile application communicates with a Joomla! site through the JAM component. The application and component use the XML-RPC protocol to transmit data.

Initial Call - onGetAvailablePlugins

In the case of the JAM plugins, the application first calls the getAvailablePlugins method on the component to find out which plugins are installed and enabled on a Joomla! site. You can test this using curl:

curl -A "XML-RPC for PHP 2.2.1" -H "Content-Type: text/xml" -d "<methodCall><methodName>joomlaadminmobile.getAvailablePlugins</methodName><params><param><value><string>xmlrpcuser</string></value></param><param><value><string>pass</string></value></param></params></methodCall>" "http://jam.covertapps.com/index.php?option=com_joomlaadminmobile&format=xmlrpc"

The response is returned with the following format:

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><array>
<data>
...
<value><struct>
<member><name>display_name</name>
<value><string>Banners</string></value>
</member>
<member><name>description</name>
<value><string>Displays information about the Joomla! banners component.</string></value>
</member>
<member><name>class_name</name>
<value><string>plgJoomlaAdminMobileBanners</string></value>
</member>
<member><name>method_name</name>
<value><string>getBanners</string></value>
</member>
<member><name>data_type</name>
<value><string>html</string></value>
</member>
</struct></value>
...
</data>
</array></value>
</param>
</params>

This response is an array of structures. Each structure is a response from a single plugin and contains the following information:

display_name: Banners
description: Displays information about the Joomla! banners component.
class_name: plgJoomlaAdminMobileBanners
method_name: getBanners
data_type: html

This information is returned to the component from each plugin from the onGetAvailablePlugin method:

class  plgJoomlaAdminMobileBanners extends JPlugin
{
        ...
        function onGetAvailablePlugins()
        {
                return array(
                        "display_name" => "Banners",
                        "description" => "Displays information about the Joomla! banners component.",
                        "class_name" => get_class(),
                        "method_name" => "getBanners",
                        "data_type" => "html",
                );
        }

The display_name and description values are shown to the user on the plugins table screen in the JAM application. The class_name and method_name values are used to call the PHP plugin class method that will be called when the user clicks the plugin in the plugins table screen. The data_type is the type of data the app can expect the component/plugin to return (currently only html is supported).

Primary Method Call - User Defined Plugin Class Method

To test calling this method to see the response the user will see when clicking the plugin row in the plugins table screen, you can once again use curl to see the XML-RPC request and the XML-RPC response:

curl -A "XML-RPC for PHP 2.2.1" -H "Content-Type: text/xml" -d "<methodCall><methodName>joomlaadminmobile.callPluginMethod</methodName><params><param><value><string>xmlrpcuser</string></value></param><param><value><string>pass</string></value></param><param><value><string>plgJoomlaAdminMobileBanners</string></value></param><param><value><string>getBanners</string></value></param><param><value><array><data></data></array></value></param></params></methodCall>" "http://jam.covertapps.com/index.php?option=com_joomlaadminmobile&format=xmlrpc"

The response will come back in the following format:

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><struct>
<member><name>data</name>
<value><string>
...
</string></value>
</member>
</struct></value>
</param>
</params>
</methodResponse>

The data value will be HTML that is returned from the method called on the plugin. In the case of the Banners plugin, it returns something like this:

<script language="javascript">
var jamCallPluginMethodParamValues = new Array();
function jamCallPluginMethod(className, methodName, displayName, dataType, paramValues) {
	command = 'jam://' + className + '/' + methodName + '/' + displayName + '/' + dataType;
	var i = 0;
	for(key in paramValues) {
		jamCallPluginMethodParamValues[i] = paramValues[key].toString();
		command += '/jamCallPluginMethodParamValues[' + i + ']';
		i++;
	}
	window.location = command;
}
</script>

<b>Total Banners:</b> 8<br />
<table border="1">
<tr><th>Name</th><th>Impressions</th><th>Clicks</th></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 1', 'html', [ 1 ]); return false;">1</a>
</td><td>OSM 1</td><td>43</td><td>0</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 2', 'html', [ 2 ]); return false;">2</a>
</td><td>OSM 2</td><td>49</td><td>0</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 3', 'html', [ 3 ]); return false;">3</a>
</td><td>Joomla!</td><td>4506</td><td>151</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 4', 'html', [ 4 ]); return false;">4</a>
</td><td>JoomlaCode</td><td>4506</td><td>169</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 5', 'html', [ 5 ]); return false;">5</a>
</td><td>Joomla! Extensions</td><td>4501</td><td>172</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 6', 'html', [ 6 ]); return false;">6</a>
</td><td>Joomla! Shop</td><td>4501</td><td>155</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 7', 'html', [ 7 ]); return false;">7</a>
</td><td>Joomla! Promo Shop</td><td>9410</td><td>239</td></tr>
<tr><td>
<a href="#" onclick="javascript:jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 8', 'html', [ 8 ]); return false;">8</a>
</td><td>Joomla! Promo Books</td><td>9470</td><td>251</td></tr>
</table>
<br>

Subsequent Calls - More User Defined Plugin Class Methods

In the above HTML, you will see multiple calls like this one to the jamCallPluginMethod javascript method:

jamCallPluginMethod('plgJoomlaAdminMobileBanners', 'getBanner', 'Banner 1', 'html', [ 1 ]);

The jamCallPluginMethod is defined in the component and included in the plugin response with the following line of code:

$data = JoomlaAdminMobileHelper::getJamJavascriptInclude();

The jamCallPluginMethod method signature looks like this:

function jamCallPluginMethod(className, methodName, displayName, dataType, paramValues) {

Using the jamCallPluginMethod, the plugin can tell the app to make calls back to the component. The component will then call the requested method on the requested class passing the param values. The results will be displayed on a new HTML screen with the provided display name.

This functionality allows the developer to define and call their own interface rather than being constrained to a specific format. While this makes initially understanding how the JAM plugins work a little more difficult, it will allow the developer more flexibility and allow for endless plugin functionality.

The easiest way to see how the JAM plugins work is to read over the examples, download the example code, install them, and modify the code to change the way the function.