Table of contents

Using jQuery and Ajax

About jQuery

jQuery is a solid JavaScript framework. Among its many advantages:

...

You can learn more about jQuery on the official website: http://jquery.com/

jQuery's $

jQuery has the $() function, and the $ namespace, which contains all the other functions.

...

You can learn more about jQuery() and $() on the official website: http://api.jquery.com/jQuery/

Functions in jQuery

jQuery's $ namespace contains all the functions that are not attached to a specific node.

...

• http://api.jquery.com/category/ajax/ (for instance, http://api.jquery.com/jQuery.post/)
• http://api.jquery.com/category/utilities/

Selectors

jQuery offers two ways to selection elements:

...

You can learn more about jQuery's selectors on the official website: http://api.jquery.com/category/selectors/

Methods and callbacks

A whole set of methods are available in the standard API: DOM manipulation, CSS manipulation, event management, visual effects, etc.

...

$(".emptyContent").append("This is a test")
  .css("border", "1px solid red")
  .addClass("fullContent")
  .removeClass("emptyContent");

A couple other functions

jQuery's API is incredibly complete, and you will spend hours finding new possibilities.

...

if($.browser.msie) {
  if($.browser.version == 6) {
    // Your IE6 specific code.
  } else {
    // Code for any other IE browser.
  }
}

Making Ajax calls with jQuery

About Ajax

The term "Ajax" is really an acronym for Asynchronous JavaScript and XML. It describes the use of JavaScript to load new content into the current page without having to reload the whole page. The process is called asynchronous because once the Ajax request has been sent to the web server, the browser does not have to wait for the answer in order to perform other tasks. The transferred does not have to be formatted in XML: it can use JSON, HTML or plain text.

In effect, using Ajax makes it possible to build very dynamic websites

You can learn about the Ajax technique on the following sites:

• Wikipedia: http://en.wikipedia.org/wiki/Ajax_%28programming%29
• Mozilla Developer Network: https://developer.mozilla.org/en/docs/AJAX

How to use Ajax in PrestaShop

By default, PrestaShop's controllers use the standard full-page-reload process.

Once PrestaShop detects the "ajax" parameter in a GET or POST query, the controller's ajax property is switched to true: $this->ajax = true;.

For instance, if your code triggers a URL like such: http://...&ajax&action=updatelist
...the controller will then execute the displayAjaxUpdateList() method if it exists. If it doesn't exist, it will execute the displayAjax() method (by default).

You therefore have to include the code that will take the Ajax call into account. Here is how you would write a simple Ajax query using jQuery:

var query = $.ajax({
  type: 'POST',
  url: baseDir + 'modules/mymodule/ajax.php',
  data: 'method=myMethod&id_data=' + $('#id_data').val(),
  dataType: 'json',
  success: function(json) {
    // ....
  }
});

And here is how the ajax.php script would work:

// Located in /modules/mymodule/ajax.php
require_once(dirname(__FILE__).'../../../config/config.inc.php');
require_once(dirname(__FILE__).'../../../init.php');
switch (Tools::getValue('method')) {
  case 'myMethod' :
    die( Tools::jsonEncode( array('result'=>'my_value'));
    break;
  default:
    exit;
}
exit;

As you can see in the code sample above, PrestaShop's Tools object contains jsonEncode(), a method that makes it easy to turn a PHP array into a JSON object:

public function displayAjax() {
  $return = array(
    'hasError' => true,
    'errors' => 'Ceci est le message'
  );
  die(Tools::jsonEncode($return));
}

jQuery's Ajax methods

jQuery.ajax(url [, settings ] )

Parameters:

• url: the URL to which the query should be sent
• settings: options and functions

Some options:

• async (boolean): default is true
• type: default is 'GET'
• cache (boolean): default is true
• data: GET array sent to the server
• dataType: either xml, json, script or html

Some functions:

• beforeSend: triggered before the Ajax call
• error: in case of error
• success: in case of success
• timeout: in case of timeout
• complete: triggered after the call's success or error, whatever the result

You can learn more about ajax() here: http://api.jquery.com/jQuery.ajax/

Alternative: jQuery.load(url [, data ] [, complete(responseText, textStatus, XMLHttpRequest) ] )

This method is used to directly load the HTML result to an Ajax call, right within an element on the current page.

For instance:

$('#result').load('ajax/test.html', function() {
  alert('Load was performed.');
});

Alternative: jQuery.get( url [, data ] [, success(data, textStatus, jqXHR) ] [, dataType ] )

This method enables you to call an Ajax script with an HTTP GET query. It is equivalent to the following Ajax call:

$.ajax({
  url: url,
  data: data,
  success: success,
  dataType: dataType
});

Return value on a jQuery Ajax call

All these jQuery methods return a jqHXR object, which is an extension of the XMLHTTPRequest object. That object makes it possible to trigger various functions depending on the result of the call:

• Success: jqXHR.done(function(data, textStatus, jqXHR) {});

• Error: jqXHR.fail(function(jqXHR, textStatus, errorThrown) {});

• Success or Error: jqXHR.always(function(data|jqXHR, textStatus, jqXHR|errorThrown){ });

• Success AND Error: jqXHR.then(function(data, textStatus, jqXHR) {}, function(jqXHR, textStatus, errorThrown) {});

Here is an example with functions calls depending on the query's result:

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.get("example.php", function() {
  alert("success");
})
.done(function() { alert("second success"); })
.fail(function() { alert("error"); })
.always(function() { alert("finished"); });

// perform other work here ...
// Set another completion function for the request above
jqxhr.always(function(){ alert("second finished"); });