Using Joomla Ajax Interface: Difference between revisions

From Joomla! Documentation

← Older edit
No edit summary
Robbiej (talk | contribs)
671 edits
Added deprecation notice and link to Joomla Manual
 
(19 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<noinclude>{{version/tutor|3.2}}</noinclude>
{{Warning|This page has been superseded and is no longer maintained. Please go to [https://manual.joomla.org/docs/general-concepts/javascript/com-ajax/ Joomla Manual ] instead}}
<h1>What is The Joomla Ajax Interface (com_ajax)</h1>
<p>A slim, extensible component to act as an entry point for Ajax functionality in Joomla for stand alone modules and plugins. Examples of use cases include, but are not limited to:
<ul>
<li>A module that retrieves data from an external API</li>
<li>A module that interacts with a component that you did not develop</li>
<li>A plugin that implement API like functionality to allow consumption of data from your site</li>
</ul>
</p>
<p><strong>NOTE</strong>: If you are a component developer, you do not need to use com_ajax to implement Ajax functionality in it. You can do so directly in your component.</p>
<h1>Anatomy of an Ajax Request</h1>


<p><strong>Required</strong></p>
<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.2|time=and after|comment=<translate><!--T:37-->
series</translate>}}</noinclude>
{{-}}
<translate>==What is The Joomla Ajax Interface (''com_ajax'')== <!--T:1--></translate>
<translate><!--T:2-->
A slim, extensible component to act as an entry point for HTTP requests for stand alone modules and plugins, thus allowing for the potential of Ajax functionality in them. ''com_ajax ''is generally used when you are not the developer of the component that the module or plugin is interacting with.</translate>


<ul>
<translate><!--T:3-->
<li><code>option=com_ajax</code></li>
'''NOTE''' If you are a component developer, you do not need to use ''com_ajax'' to implement Ajax functionality in it. You can do so directly in your component.</translate>
<li><code>[module|plugin]=name</code></li>
</ul><p><strong>Optional</strong></p>


<ul>
<translate><!--T:4-->
<li>
Examples of use cases include, but are not limited to:
<code>format=[json|debug]</code> defaults to raw if omitted.</li>
*A module that retrieves data from an external API
<li>
*A module that interacts with a component that you did not develop
<code>method=[custom fragment]</code> defaults to <code>get</code> if omitted.</li>
*A plugin that implement API like functionality to allow consumption of data from your site</translate>
</ul><p><strong>Overview</strong></p>


<p>All requests begin with <code>?option=com_ajax</code>, which calls this extension, and must indicate the type of extension to call, and the data format to be returned.</p>
<translate>==Anatomy of an Ajax Request== <!--T:5--></translate>


<p>Additional variables and values used by your extension may also be included in the URL.</p>
<translate>===Required=== <!--T:6--></translate>


<p>For example, a request to <code>?option=com_ajax&amp;module=session</code> would call <code>mod_session</code> with results returned in the default format. In contrast,<code>?option=com_ajax&amp;plugin=session&amp;format=json</code> would trigger the <code>onAjaxSession</code> plugin group with results returned in JSON.</p>
*''option=com_ajax''
*''[module|plugin]=name''
*''format=[json|debug|raw]''


<h2>
<translate>===Optional=== <!--T:7--></translate>
Module Support</h2>
*''method=[custom fragment]'' <translate><!--T:8-->
defaults to ''get'' if omitted.</translate>


<p><strong>Summary</strong></p>
<translate>===Overview=== <!--T:9--></translate>
<translate><!--T:10-->
All requests begin with ''?option=com_ajax'', which calls this extension, and must indicate the type of extension to call, and the data format to be returned.


<p>Module support is accomplished by calling a method in the module's <code>helper.php</code> file.</p>
<!--T:11-->
Additional variables and values used by your extension may also be included in the URL.</translate>


<p><strong>Details</strong></p>
<translate><!--T:12-->
For example, a request to ''?option=com_ajax&amp;module=session'' would call ''mod_session'' with results returned in the default format. In contrast,''?option=com_ajax&amp;plugin=session&amp;format=json'' would trigger the ''onAjaxSession'' plugin group with results returned in JSON.</translate>


<p>Module requests must include the <code>module</code> variable in the URL, paired with the name of the module (i.e. <code>module=session</code> for <code>mod_session</code>).</p>
<translate>==Module Support== <!--T:13--></translate>


<p>This value is also used for:</p>
<translate>===Summary=== <!--T:14--></translate>


<ul>
<translate><!--T:15-->
<li>The name of the directory to check for the helper file, e.g. <code>/modules/mod_session/helper.php</code>
Module support is accomplished by calling a method in the module's ''helper.php'' file.</translate>
</li>
<li>The class name to call, e.g. <code>modSessionHelper</code>
</li>
</ul><p>Optionally, the <code>method</code> variable may be included to override the default method prefix of <code>get</code>. </p>


<p>NOTE: All methods must end in <code>Ajax</code>. For example, <code>method=mySuperAwesomeMethodToTrigger</code> will call <code>mySuperAwesomeMethodToTriggerAjax</code></p>
<translate>===Details=== <!--T:16--></translate>


<p>The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality.</p>
<translate><!--T:17-->
Module requests must include the ''module'' variable in the URL, paired with the name of the module (i.e. ''module=session'' for ''mod_session'').</translate>


<h2>
<translate><!--T:18-->
Plugin Response</h2>
This value is also used for:


<p><strong>Summary</strong></p>
<!--T:19-->
*The name of the directory to check for the helper file, e.g. ''/modules/mod_session/helper.php''


<p>Plugin support is accomplished by triggering the <code>onAjax[Name]</code> plugin event.</p>
<!--T:20-->
*The class name to call, e.g. ''modSessionHelper''</translate>


<p><strong>Details</strong></p>
<translate><!--T:21-->
Optionally, the ''method'' variable may be included to override the default method prefix of ''get''.</translate>


<p>Plugin requests must include the <code>plugin</code> variable in the URL, paired with the name of the plugin event, e.g. <code>plugin=session</code> for <code>onAjaxSession</code>.</p>
:<translate><!--T:22-->
'''NOTE''' All methods must end in ''Ajax''. For example:</translate>
:''method=mySuperAwesomeMethodToTrigger'' <translate><!--T:23-->
will call</translate> ''mySuperAwesomeMethodToTriggerAjax''


<p>This value is also used for:</p>
<translate><!--T:24-->
The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality.</translate>


<ul>
<translate>==Plugin Response== <!--T:25--></translate>
<li>The plugin class name following the <code>plgAjax[Name]</code> convention.</li>
<li>The plugin function name following the <code>onAjax[Name]</code> convention.</li>
</ul><p>The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality.</p>


<h2>
<translate>===Summary=== <!--T:26-->
Response Format</h2>


<p><code>format=[json|debug]</code> is an optional argument for the results format:</p>
<!--T:27-->
Plugin support is accomplished by triggering the ''onAjax[Name]'' plugin event.</translate>


<ul>
<translate>===Details=== <!--T:28-->
<li>
 
<code>json</code> for JSON format</li>
<!--T:29-->
<li>
Plugin requests must include the ''plugin'' variable in the URL, paired with the name of the plugin event, e.g. ''plugin=session'' for ''onAjaxSession''.</translate>
<code>debug</code> for human-readable output of the results.</li>
 
</ul>
<translate><!--T:30-->
This value is also used for:
 
<!--T:31-->
*The plugin class name following the ''plgAjax[Name]'' convention.
*The plugin function name following the ''onAjax[Name]'' convention.
*The default plugin group is ''ajax''. You can change it specifying the ''group'' request parameter. (From Joomla! 3.4)
 
<!--T:32-->
The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality.</translate>
 
<translate>==Response Format== <!--T:33--></translate>
 
<translate><!--T:34-->
''format=[json|debug]'' is an optional argument for the results format:
 
<!--T:35-->
*''json'' for JSON format
*''debug'' for human-readable output of the results.</translate>
 
<translate><!--T:36-->
[[Category:AJAX]]
[[Category:JavaScript]]
[[Category:Development]]</translate>

Latest revision as of 10:30, 27 November 2024

Warning!

This page has been superseded and is no longer maintained. Please go to Joomla Manual instead


Other languages:
Joomla! 
≥ 3.2
series

What is The Joomla Ajax Interface (com_ajax)

A slim, extensible component to act as an entry point for HTTP requests for stand alone modules and plugins, thus allowing for the potential of Ajax functionality in them. com_ajax is generally used when you are not the developer of the component that the module or plugin is interacting with.

NOTE If you are a component developer, you do not need to use com_ajax to implement Ajax functionality in it. You can do so directly in your component.

Examples of use cases include, but are not limited to:

  • A module that retrieves data from an external API
  • A module that interacts with a component that you did not develop
  • A plugin that implement API like functionality to allow consumption of data from your site

Anatomy of an Ajax Request

Required

  • option=com_ajax
  • [module|plugin]=name
  • format=[json|debug|raw]

Optional

  • method=[custom fragment] defaults to get if omitted.

Overview

All requests begin with ?option=com_ajax, which calls this extension, and must indicate the type of extension to call, and the data format to be returned.

Additional variables and values used by your extension may also be included in the URL.

For example, a request to ?option=com_ajax&module=session would call mod_session with results returned in the default format. In contrast,?option=com_ajax&plugin=session&format=json would trigger the onAjaxSession plugin group with results returned in JSON.

Module Support

Summary

Module support is accomplished by calling a method in the module's helper.php file.

Details

Module requests must include the module variable in the URL, paired with the name of the module (i.e. module=session for mod_session).

This value is also used for:

  • The name of the directory to check for the helper file, e.g. /modules/mod_session/helper.php
  • The class name to call, e.g. modSessionHelper

Optionally, the method variable may be included to override the default method prefix of get.

NOTE All methods must end in Ajax. For example:
method=mySuperAwesomeMethodToTrigger will call mySuperAwesomeMethodToTriggerAjax

The Ajax Session Module is an example module that demonstrates this functionality.

Plugin Response

Summary

Plugin support is accomplished by triggering the onAjax[Name] plugin event.

Details

Plugin requests must include the plugin variable in the URL, paired with the name of the plugin event, e.g. plugin=session for onAjaxSession.

This value is also used for:

  • The plugin class name following the plgAjax[Name] convention.
  • The plugin function name following the onAjax[Name] convention.
  • The default plugin group is ajax. You can change it specifying the group request parameter. (From Joomla! 3.4)

The Ajax Latest Articles plugin is an example plugin that demonstrates this functionality.

Response Format

format=[json|debug] is an optional argument for the results format:

  • json for JSON format
  • debug for human-readable output of the results.
Retrieved from "https://docs.sandbox.joomla.org/index.php?title=Using_Joomla_Ajax_Interface&oldid=1033483"