Difference between revisions of "Using Joomla Ajax Interface"
From Joomla! Documentation
m (→Details: indent) |
(Marked this version for translation) |
||
(14 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | <noinclude>{{version | + | <noinclude><languages /></noinclude> |
− | ==What is The Joomla Ajax Interface (com_ajax)== | + | <noinclude>{{Joomla version|version=3.2|time=and after|comment=<translate><!--T:37--> |
− | 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. | + | 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> | ||
− | '''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><!--T:3--> |
+ | '''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> | ||
+ | <translate><!--T:4--> | ||
Examples of use cases include, but are not limited to: | Examples of use cases include, but are not limited to: | ||
*A module that retrieves data from an external API | *A module that retrieves data from an external API | ||
*A module that interacts with a component that you did not develop | *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 | + | *A plugin that implement API like functionality to allow consumption of data from your site</translate> |
− | ==Anatomy of an Ajax Request== | + | <translate>==Anatomy of an Ajax Request== <!--T:5--></translate> |
− | ===Required=== | + | <translate>===Required=== <!--T:6--></translate> |
*<code>option=com_ajax</code> | *<code>option=com_ajax</code> | ||
*<code>[module|plugin]=name</code> | *<code>[module|plugin]=name</code> | ||
+ | *<code>format=[json|debug|raw]</code> | ||
− | ===Optional=== | + | <translate>===Optional=== <!--T:7--></translate> |
− | + | *<code>method=[custom fragment]</code> <translate><!--T:8--> | |
− | *<code>method=[custom fragment]</code> defaults to <code>get</code> if omitted. | + | defaults to <code>get</code> if omitted.</translate> |
− | ===Overview=== | + | <translate>===Overview=== <!--T:9--></translate> |
+ | <translate><!--T:10--> | ||
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. | 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. | ||
− | Additional variables and values used by your extension may also be included in the URL. | + | <!--T:11--> |
+ | Additional variables and values used by your extension may also be included in the URL.</translate> | ||
− | For example, a request to <code>?option=com_ajax&module=session</code> would call <code>mod_session</code> with results returned in the default format. In contrast,<code>?option=com_ajax&plugin=session&format=json</code> would trigger the <code>onAjaxSession</code> plugin group with results returned in JSON. | + | <translate><!--T:12--> |
+ | For example, a request to <code>?option=com_ajax&module=session</code> would call <code>mod_session</code> with results returned in the default format. In contrast,<code>?option=com_ajax&plugin=session&format=json</code> would trigger the <code>onAjaxSession</code> plugin group with results returned in JSON.</translate> | ||
− | ==Module Support== | + | <translate>==Module Support== <!--T:13--></translate> |
− | ===Summary=== | + | <translate>===Summary=== <!--T:14--></translate> |
− | Module support is accomplished by calling a method in the module's <code>helper.php</code> file. | + | <translate><!--T:15--> |
+ | Module support is accomplished by calling a method in the module's <code>helper.php</code> file.</translate> | ||
− | ===Details=== | + | <translate>===Details=== <!--T:16--></translate> |
− | 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>). | + | <translate><!--T:17--> |
+ | 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>).</translate> | ||
+ | <translate><!--T:18--> | ||
This value is also used for: | This value is also used for: | ||
+ | <!--T:19--> | ||
*The name of the directory to check for the helper file, e.g. <code>/modules/mod_session/helper.php</code> | *The name of the directory to check for the helper file, e.g. <code>/modules/mod_session/helper.php</code> | ||
− | *The class name to call, e.g. <code>modSessionHelper</code> | + | <!--T:20--> |
+ | *The class name to call, e.g. <code>modSessionHelper</code></translate> | ||
− | Optionally, the <code>method</code> variable may be included to override the default method prefix of <code>get</code>. | + | <translate><!--T:21--> |
+ | Optionally, the <code>method</code> variable may be included to override the default method prefix of <code>get</code>.</translate> | ||
− | :'''NOTE''': All methods must end in <code>Ajax</code>. | + | :<translate><!--T:22--> |
− | : | + | '''NOTE''': All methods must end in <code>Ajax</code>. For example:</translate> |
+ | :<code>method=mySuperAwesomeMethodToTrigger</code> <translate><!--T:23--> | ||
+ | will call</translate> <code>mySuperAwesomeMethodToTriggerAjax</code> | ||
− | The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality. | + | <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> | ||
− | ==Plugin Response== | + | <translate>==Plugin Response== <!--T:25--></translate> |
− | ===Summary=== | + | <translate>===Summary=== <!--T:26--> |
− | Plugin support is accomplished by triggering the <code>onAjax[Name]</code> plugin event. | + | <!--T:27--> |
+ | Plugin support is accomplished by triggering the <code>onAjax[Name]</code> plugin event.</translate> | ||
− | ===Details=== | + | <translate>===Details=== <!--T:28--> |
− | 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>. | + | <!--T:29--> |
+ | 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>.</translate> | ||
+ | <translate><!--T:30--> | ||
This value is also used for: | This value is also used for: | ||
+ | <!--T:31--> | ||
*The plugin class name following the <code>plgAjax[Name]</code> convention. | *The plugin class name following the <code>plgAjax[Name]</code> convention. | ||
*The plugin function name following the <code>onAjax[Name]</code> convention. | *The plugin function name following the <code>onAjax[Name]</code> convention. | ||
+ | *The default plugin group is <code>ajax</code>. You can change it specifying the <code>group</code> request parameter. (From Joomla! 3.4) | ||
− | The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality. | + | <!--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> | ||
− | ==Response Format== | + | <translate>==Response Format== <!--T:33--></translate> |
+ | <translate><!--T:34--> | ||
<code>format=[json|debug]</code> is an optional argument for the results format: | <code>format=[json|debug]</code> is an optional argument for the results format: | ||
+ | <!--T:35--> | ||
*<code>json</code> for JSON format | *<code>json</code> for JSON format | ||
− | *<code>debug</code> for human-readable output of the results. | + | *<code>debug</code> for human-readable output of the results.</translate> |
+ | |||
+ | <translate><!--T:36--> | ||
+ | [[Category:AJAX]] | ||
+ | [[Category:JavaScript]] | ||
+ | [[Category:Development]]</translate> |
Revision as of 09:44, 26 May 2015
What is The Joomla Ajax Interface (com_ajax)[edit]
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[edit]
Required[edit]
option=com_ajax
[module|plugin]=name
format=[json|debug|raw]
Optional[edit]
method=[custom fragment]
defaults toget
if omitted.
Overview[edit]
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[edit]
Summary[edit]
Module support is accomplished by calling a method in the module's helper.php
file.
Details[edit]
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 callmySuperAwesomeMethodToTriggerAjax
The Ajax Session Module is an example module that demonstrates this functionality.
Plugin Response[edit]
Summary[edit]
Plugin support is accomplished by triggering the onAjax[Name]
plugin event.
Details[edit]
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 thegroup
request parameter. (From Joomla! 3.4)
The Ajax Latest Articles plugin is an example plugin that demonstrates this functionality.
Response Format[edit]
format=[json|debug]
is an optional argument for the results format:
json
for JSON formatdebug
for human-readable output of the results.