How to: Working with AJAX

This article explains how to:

• request the server to perform an action without reloading the page
• wait for a confirmation message from the server
• start some changes to the page

Sending an AJAX request to the server

To send an AJAX request you should execute the following JavaScript code on your page:

core.post(

  URLHandler.buildURL({target: 'example', action: 'save'}),

  function(XMLHttpRequest, textStatus, data, valid) {
  },

  {
    x: 1,
    y: 2
  }

);

The code will trigger "save" action in "example" controller. Depending on the current area (the storefront or the backend) it will run either \XLite\Controller\Customer\Example::doActionSave() or \XLite\Controller\Admin\Example::doActionSave() method.

The specified variables ("x" and "y") will be submitted to the server via a POST reqest, so you can retrieve them in your doActionSave() method.

core.post() has three parameters:

1. The URL where to send the request
2. The JavaScript callback function to handle the server response (optional)
3. Data to be submitted to the server (optional)

Since the two last parameters are optional, it is possible to call the function as follows:

core.post(URLHandler.buildURL({target: 'example', action: 'save'}));

Processing the AJAX reqest

Notyfing of a success or a failure

The action method confirms whether the requested actions has been performed successfully by setting the "valid" variable to true.

protected function doActionSave()
{
    // Do something and set $success to TRUE if all is OK
    // (and FALSE if something goes wrong)
    // ...

    // Pass the status back to JavaScript
    $this->valid = $success;
}

The variable will be passed to the JavaScript callback function as the 4th parameter. So, on the client side we can handle this as follows:

core.post(

  URLHandler.buildURL({target: 'example', action: 'save'}),

  function(XMLHttpRequest, textStatus, data, valid) {
    if (valid) {
      ..."success" scenario...
    } else {
      ..."fail" scenario...
    }
  }

);

Redirecting the user after processing the request

After processing the request you can redirect the user to other page as follows:

protected function doActionSave()
{
  // Process the request
  // ...

  // Redirect the user
  $this->setReturnURL([your-url]);
  $this->setHardRedirect(true);
}

Reloading the page after processing the request

After processing the request you can reload the page as follows:

protected function doActionSave()
{
  // Process the request
  // ...

  // Reload the page
  $this->setHardRedirect(true);
}

Triggering and processing JavaScript events

From your action method you can trigger one or more events to be processed on the client side:

protected function doActionSave()
{
    // ...

    // Trigger two events: "MyEvent" and "AnotherEvent".
    \XLite\Core\Event::MyEvent('param-1', 'param-2', ...);
    \XLite\Core\Event::AnotherEvent('param-1');

    // ...
}

To handle the events on the client side you are to bind JavaScript functions to these events as follows:

core.bind(
  '[event-name]',
  function (event, arg1, arg2, ...) {
    ...
  }
);

You can bind more than one JavaScript function to an event.