Ajax requests

There are two different use-cases for sending ajax requests aside from push-state: one is where you want to send arbitrary requests out of the blue based on some user interaction (standard requests), the other is where you want to submit data from a form (form requests).

Warning! Before beginning, be sure you’ve set up the OFW Javascript API properly. Ajax requests will not work without {{ofw.js}} in place.

Standard requests

Standard requests should be used when you just need to perform a regular ajax request.
ofw.ajax.get() – docs
ofw.ajax.post() – docs
ofw.ajax.submit() – docs
ofw.ajax.alert() – docs

These methods can be used to send and process and ajax request. See documentation for possible parameters. Like all OFW JS API requests, the URL is relative to the project base url. Here’s an example:

ofw.ajax.post('my/example/?postdata=can&go=here', function(result){
  // Add some processing code here.
});

The above example will call my.ctl.php / example function where you can return an ajax response:

function example(){
  $this->zajlib->ajax('Hello, this is my result');
}

Or perhaps a JSON response:

function example(){
  $this->zajlib->json(array('status'=>'ok'));
}

Form requests

Form requests are not any different from standard requests, but because they automatically populate data from a form element they are a bit easier to use for sending form data. The method parameters are the same for standard and form requests.

$(element).$ofw().get() – send the form data with an ajax GET
$(element).$ofw().post() – send the form data with an ajax POST
$(element).$ofw().submit() – send the form data with an ajax POST and block all further requests (see below)

You can create form manually:

<form id='example'><input type='text' name='title'></form>

Or with the {% input %} tags:

<form id='example'>{% input example.title %}</form>

We can now submit the form:

$('#example').$ofw().submit('my/example/', 'thank/you/page/');

The form data is sent via standard $_GET, $_POST, or $_REQUEST arrays. You can validate the data and perform any necessary actions in the controller method. Then you must return a success or error message depending on the result. We recommend you use the form validation framework for nice, popover errors. See below for a discussion on form responses.

Attention! Only input elements that are inside a form and have a name attribute will be sent!

Standard and form responses

As mentioned before, there is a simple way of responding to OFW form requests, by simply sending a string via ajax. If you send ok, the response is considered successful on the client side. If you send a message (anything other than ‘ok’), the response is considered an error. See examples above.

Another, more advanced way to provide form responses is to send json data.

Here is an example of a successful json request:

Here is an example of an unsuccessful json request:

Any form fields that are listed in the highlight array or the errors object receive the has-error class. If they are in a form-group div the form-group is also marked with the has-error class.

If you use the errors object, the messages will be displayed as Bootstrap Tooltips. You can use the data-parameters to modify their behavior, such as data-placement='left' to change its placement.

Processing responses

You can use a callback function process the response from an ajax request to provide custom functionality. Responses can regular text, html, or json data – depending on what you return in the controller method.

The callback function will receive two parameters:

• {string} responseTxt – the simple text or html response
• {mixed|null} responseJson – if your response included json data, this will be the json-decoded data. It will be null if the response is not valid json.

Here’s an example of returning and processing json data:

Blocking form requests

Blocking form requests are to be used if you want to avoid multiple submissions of data because users click the submit button several times (when they are impatient and/or double click).
$(element).$ofw().submit()

The submit method will always use POST and block any additional submit requests while it is still running. It is useful to avoid multiple submits of the same data from a form. Otherwise, it is the same as the above post() form request method.

Visual feedback for blocking requests

Blocking requests are especially useful when the submitting process takes more than just a few milliseconds. If this is the case, you probably also want some sort of visual feedback that the system is thinking, for example a nice little Facebook-style thinking gif:

This can be done easily with the data-submit-toggle-class attribute. Here’s how to add it:

<img src='{{baseurl}}system/img/assets/ajax-loader.gif' data-submit-toggle-class='hide' class='hide'>

This image will have the hide class by default. When a submit() is started, it will be removed. When a submit() completes, it will be added again.

Modal / popup request responses

In certain cases you just want to display the response in a modal popup. This would be the case when you want to display terms and conditions, cookie policies, etc.

Here’s a simple example implementation:

Updating certain parts of the page

You can use a combination of zaj.ajax.get and {% block %} to easily update only certain parts of the page. See the code example:

Events

If you use a standard ofw json response for your ajax requests, certain events will be triggered based on the result. You can use these events to subscribe to and extend the way your code reacts to the response.

The events are triggered on the $(form) element when $(form).$ofw().submit() or $(form).$ofw().post() is used.

ofw-ajax-response Triggered when any ajax request response is returned.
ofw-ajax-success Triggered if the ajax request returns status: ok or status: success.
ofw-ajax-error Triggered if the ajax request returns status: error.