Intercooler Requests & Responses

Intercooler makes AJAX requests to various paths when certain events occur (e.g. A button with a ic-post-to attribute is clicked, or a polling interval occurs.) and expects a response of a certain format (typically an HTML fragment). Below we describe both the request and response formats.

Intercooler Requests

Intercooler requests can come take four different forms:

  • GET - Typically created due to a refresh of an ic-src attribute.
  • POST - Created by an element with a ic-post-to attribute.
  • PUT - Created by an element with a ic-put-to attribute.
  • DELETE - Created by an element with a ic-delete-from attribute.

Because not all browsers support PUT and DELETE requests in AJAX, Intercooler uses the Rails convention and adds a _method parameter to the request.

Standard Parameters

Intercooler requests include a few standard parameters:

  • ic-request - This will always be true for Intercooler-based requests.
  • ic-last-refresh - This is a timestamp of the last time the target element was refreshed. This can be used to calculate time-sensitive UI updates (e.g. appending to a list of messages.)
  • ic-fingerprint - The SHA256 fingerprint of the current content. This can be used to avoid sending down unnecessary updates, caching, etc.

Request Headers

Intercooler requests include a few request headers:

Header Description
X-IC-Request Set to true
X-HTTP-Method-Override Set to the HTTP Method type (e.g. DELETE) for the request, to communicate the actual request type to the server if it cannot be directly supported by the client.

Additional Parameters

Also included in the request is the form value of the element that is initiating the request. So, if the element is an input, it will include its name/value in the request. If it is a form, it will include the names/values of all inputs within the form.

You can also include other parameters using the ic-include attribute.

Intercooler Responses

Intercooler responses are typically HTML fragments. In the typical case, a fragment of HTML will be returned. Here is a simple example of a response body:

  <div>Here Is Some Content!<div>

This would be swapped in as the body of the element that initiated the request.

The returned content can contain Intercooler attributes itself, which will be all wired up.

You can control the exact style of the swap using the ic-transition attribute, and you can control the element that will be swapped out via the request by using the ic-target attribute.

Empty Bodies

Intercooler interprets an empty body in a request as a No-Op, and will do nothing in response.

Intercooler HTTP Response Headers

Sadly, not all UI patterns can be elegantly captured via straight element swapping. Occasionally you need to invoke a bit more client side javascript, let other elements know to refresh themselves, redirect the user entirely, etc.

To handle these situations, Intercooler responses have at their disposal some custom HTTP headers. These headers can be used to instruct intercooler to perform additional work :

The following Intercooler response headers are available:

Header Description
X-IC-Trigger Allows you to trigger a JQuery event handler on the client side
X-IC-Trigger-Data Allows you to pass JSON data to the event triggered by the X-IC-Trigger header. Note that extraParameters passed to the event are treated as an argument list if the data is a JSON array. See the JQuery trigger() documentation for more information.
X-IC-Refresh A comma separated list of dependency paths to refresh.
X-IC-Redirect Causes a client-side redirect to the given URL.
X-IC-Script Allows you to evaluate arbitrary javascript.
X-IC-CancelPolling Cancels any polling associated with the target element.
X-IC-Open Opens a new window at the given location.
X-IC-SetLocation (Experimental) Pushes a new location (still in development)
X-IC-Transition Overrides the elements normal transition.
X-IC-Remove Removes the target element.