Built-In Ajax System

The Gantry framework comes with a built-in Ajax system which acts as a bridge between the client and the Gantry framework. Every Ajax call is directed to an "Ajax Model" that receives in the Ajax parameters and after its operations is able to return a response with what the original Ajax Call request is expecting. Below you can see a schematic sum of the process.

The real power of the Gantry framework built-in Ajax system are the models. Every developer can create its own custom Ajax Models and use the Ajax calls client-side to retrieve specific types of data.

There are 2 Ajax systems in the Gantry framework that actually work exactly the same with one exception: restrictions. In fact the first can be used for everything regarding the template while the second can only be used admin side. The restriction makes it so that even by error you cannot use the admin Ajax System on the frontend.

What differs about the two are the URI to call and a "template" parameter that needs to be passed in the admin Ajax System only.

The Models

As the 2 systems are kept on purpose separately, the core Ajax Models folders are separated as well. The template Ajax Models can be found in the folder YOUR_SITE/components/com_gantry/ajax-models/ while the admin Ajax Models can be found in the folder YOUR_SITE/components/com_gantry/admin/ajax-models/.

Due to the ability of the Gantry framework to override, you don't have (and we highly suggest to not to) to go touching the mentioned above folders. In fact you can just work at the template folder level, keeping the same structure.

So your custom template Ajax models should be stored in the folder YOUR_SITE/templates/YOUR_TEMPLATE/ajax-models/ while your custom admin Ajax models should be stored in the folder YOUR_SITE/templates/YOUR_TEMPLATE/admin/ajax-models/.

Below an example of model that will return all the query requests back to the Ajax:

<?php

    defined('JPATH_BASE') or die();
    global $gantry;

    print_r(JRequest::get());

?>

The Ajax Call Syntax

As mentioned earlier, the Ajax Call Syntax for the template and admin Models, is slightly different. Below is the schematic summarization of the two syntaxes:

new Ajax('http://URI/?tmpl=gantry-ajax', {
  onSuccess: function(response) {console.log(response);}
}).request({
     'model': 'example', // <- mandatory, the Ajax Model name
     'framework': 'Gantry', // <- from here it's all about your custom queries
     'page': 'documentation',
     'message': 'Hello World!'
});

new Request({
  url: 'http://URI/?tmpl=gantry-ajax',
  onSuccess: function(response) {console.log(response);}
}).post({
     'model': 'example', // <- mandatory, the Ajax Model name
     'framework': 'Gantry', // <- from here it's all about your custom queries
     'page': 'documentation',
     'message': 'Hello World!'
});

new Ajax('http://URI/administrator/index.php?option=com_admin&tmpl=gantry-ajax-admin', {
  onSuccess: function(response) {console.log(response);}
}).request({
     'model': 'example', // <- mandatory, the Ajax Model name
  'template': 'template_folder', // <- mandatory, the name of the gantry template folder (rt_gantry_j15)
     'framework': 'Gantry', // <-- from here it's all about your custom queries
     'page': 'documentation',
     'message': 'Hello World!'
});

new Request({
  url: 'http://URI/administrator/index.php?option=com_admin&tmpl=gantry-ajax-admin',
  onSuccess: function(response) {console.log(response);}
}).post({
     'model': 'example', // <- mandatory, the Ajax Model name
  'template': 'template_folder', // <- mandatory, the name of the gantry template folder (rt_gantry_j15)
     'framework': 'Gantry', // <- from here it's all about your custom queries
     'page': 'documentation',
     'message': 'Hello World!'
});

A Practical Example

Now that all the documentation regarding the Ajax System is covered, let's get into a real and very simple example.

We are going to create an interaction with the Logo of your site where, when clicked, an Ajax call to our new "which-version" ajax model will start and return which version of Gantry the system is using with a custom message.

This is a very basic example but it will gives the idea of how powerful is the Ajax System. Note that after the site has rendered, client side we have no way to know which Gantry version is being used, here is where it comes handy asking directly to the server.

Before starting, I'm going to assume our current template name is rockettheme_gantry, stored in the folder /templates/rockettheme_gantry/.

Step 1:

We need to create a new ajax model. We want the model to be a template model and we want to call it "which-version". So we are going to create a new file and store it into /templates/rockettheme_gantry/ajax-models/which-version.php whith the following content:

<?php
defined('JPATH_BASE') or die();
global $gantry;

$message = JRequest::getVar('message', '');
$version = (defined('GANTRY_VERSION')) ? GANTRY_VERSION : 'Unknown Version';

echo $message . " " . $version;

?>

Step 2:

Now the model is created, we need the JavaScript with the Ajax call to be put in place.

NOTE: For example purpose only, we are going to load the JavaScript from the index.php. However, the best way to create and load custom JavaScript files, is through the features, please refer to the Creating a New Feature documentation bit to know how to achieve it.

Let's edit the index.php, located in /templates/rockettheme_gantry/index.php and before the ending head section (</head>), we are going to add our inline JavaScript:

$gantry->addInlineScript("
  window.addEvent('domready', function() {
    var logo = $('rt-logo');
    logo.addEvent('click', function(e) {
      new Event(e).stop();
      
      new Ajax('".$gantry->baseUrl."?tmpl=gantry-ajax', {
        onSuccess: function(response) {alert(response);}
      }).request({
           'model': 'which-version',
           'message': 'The current version of Gantry you are currently using is'
      });
    });
  });
");

$gantry->addInlineScript("
  window.addEvent('domready', function() {
    var logo = $('rt-logo');
    logo.addEvent('click', function(e) {
      e.stop();
      
      new Request({
        url: '".$gantry->baseUrl."?tmpl=gantry-ajax',
        onSuccess: function(response) {alert(response);}
      }).post({
           'model': 'which-version',
           'message': 'The current version of Gantry you are currently using is'
      });
    });
  });
");

Step 3:

Everyhing is set and ready to be tested. Save your documents, reload your site and click on the logo. An alert should appear giving the informations we want based on the Ajax Call.