Intercooler Reference

HTML Attributes

Attribute

Description

ic-action

This attribute allows you to make client-side modifications (e.g. element removal) to the DOM without a server request.

ic-action-target

This attribute allows you to change the target of a ic-action attribute

ic-add-class

This attribute allows you to add one or many classes to an element after a specified time delay.

ic-append-from

When triggered this attribute will issue a GET and append all content returned to the children of the element it is on.

ic-attr-src

Like ic-style-src, this attribute allows you bind to a URL. However, this attribute binds an attribute value to a URL. The syntax is "attribute:url". For example, to bind the style of an element to "/style/random", you would say ic-attr-src="style:/style/random"

ic-confirm

This attribute can be used to confirm an action with a user before proceeding.

ic-delete-from

This attribute allows you to bind the "action" of an element to a given URL. Once it is bound, when an "action" occurs (e.g. clicking a button) Intercooler will issue a DELETE to the URL and replace the element with the new content. Intercooler will detect any other elements that the DELETE effects and automatically refresh them.

ic-deps

This attribute allows you to express additional path dependencies for a given element, beyond the implied ones.

ic-disable-when-doc-hidden

Disables requests when a document is hidden (e.g. for polling)

ic-disable-when-doc-inactive

Disables requests when a document is inactive, that is it does not have focus (e.g. for polling)

ic-fix-ids

This attribute tells Intercooler to replace the IDs of any added elements with globally unique IDs so that they don't conflict with any existing IDs on the page.

ic-get-from

This attribute allows you to bind the "action" of an element to a given URL. Once it is bound, when an "action" occurs (e.g. clicking a button) Intercooler will issue a GET to the URL and replace the element with the new content.

ic-global-include

This attribute can be used to add data to all requests made by Intercooler

ic-history-elt

This attribute attribute tells intercooler the element to take a snapshot of when storing history entries, as well as the element to restore history snapshots into.

ic-include

A selector attribute that can be used to include additional input with an action request (e.g. can be used to include a form with an unrelated button.)

ic-indicator

This attribute can be used to show a progress indicator while an Intercooler AJAX request is in flight.

ic-limit-children

Limits the number of children that an element is allowed to have after an ic-prepend-from or ic-append-from fires.

ic-local-vars

A comma separated list of variables from localStorage to include intercooler requests.

ic-on-beforeSend

This attribute allows a script to be evaluated during the beforeSend stage of AJAX requests made on behalf of Intercooler.

ic-on-beforeTrigger

This attribute allows a script to be evaluated before a trigger is processed.

ic-on-complete

This attribute allows a script to be evaluated after any AJAX requests made on behalf of Intercooler.

ic-on-error

This attribute allows a script to be evaluated after unsuccessful AJAX requests made on behalf of Intercooler.

ic-on-success

This attribute allows a script to be evaluated after successful AJAX requests made on behalf of Intercooler.

ic-patch-to

This attribute allows you to bind the "action" of an element to a given URL. Once it is bound, when an "action" occurs (e.g. clicking a button) Intercooler will issue a PATCH to the URL and replace the element with the new content. Intercooler will detect any other elements that the PATCH effects and automatically refresh them.

ic-pause-polling

If true then an ic-poll attribute will not start polling. This can be used to implement a Pause/Play UX.

ic-poll

This attribute tells Intercooler to poll the source URL for the element it is on in a given interval, expressed as milliseconds or seconds. (e.g. '500ms' or '2s')

ic-poll-repeats

This attribute limit the number of polling calls (e.g. '5')

ic-post-errors-to

Allows you to specify a URL to post javascript errors to that occur when intercooler is making requests and swapping content.

ic-post-to

This attribute allows you to bind the "action" of an element to a given URL. Once it is bound, when an "action" occurs (e.g. clicking a button) Intercooler will issue a POST to the URL and replace the element with the new content. Intercooler will detect any other elements that the POST effects and automatically refresh them.

ic-prepend-from

When triggered this attribute will issue a GET and prepend all content returned to the children of the element it is on.

ic-prompt

This attribute allows you to prompt the user before intercooler issues a request.

ic-push-url

This attribute tells Intercooler to update the current location with the target URL of the element after a successful AJAX request, with history support.

ic-put-to

This attribute allows you to bind the "action" of an element to a given URL. Once it is bound, when an "action" occurs (e.g. clicking a button) Intercooler will issue a PUT to the URL and replace the element with the new content. Intercooler will detect any other elements that the PUT effects and automatically refresh them.

ic-remove-after

This attribute tells Intercooler to remove the element it is on after the given amount of time has elapsed.

ic-remove-class

This attribute allows you to remove one or many classes to an element after a specified time delay.

ic-replace-target

If this attribute is set to "true", the target element of the intercooler request will be replaced entirely with the server response, rather than replacing the inner HTML of the element. This is useful in cases where you cannot wrap an element around a potential target easily, like table rows.

ic-scroll-offset

An offset in pixels to adjust the scroll position when using the ic-scroll-to-target attribute

ic-scroll-to-target

If this attribute is set to "true", the target element of the intercooler request will have its top scrolled into the viewport if it is not visible. The scroll destination can be adjusted using the ic-scroll-offset attribute.

ic-select-from-response

This attribute tells Intercooler to filter the servers response to content matching the given CSS selector. This can be useful for making a full HTML response act like a partial response.

ic-src

This attribute allows you to bind an element to a given URL. Once it is bound, when a change occurs that Intercooler recognizes as affecting the URL (or given an event such as a poll), Intercooler will issue a GET to the URL and replace the element with the new content.

ic-sse-src

This attribute allows you to bind an element to a given Server Sent Event endpoint and update the elements content or trigger Server Sent events on child elements.

ic-style-src

Like ic-src, this attribute allows you bind to a URL. However, this attribute binds a style attribute to a URL. The syntax is "style-attribute:url". For example, to bind the color of an element to "/color/random", you would say ic-style-src="color:/color/random"

ic-swap-style

Allows you to specify the swap mechanism that intercooler will use with content received from the server

ic-target

This attribute is often used with an action attribute (e.g. ic-post-to) in order to target the content of another element for replacement.

ic-transform-response

A javascript expression that transforms the given server response into HTML to be swapped into the DOM

ic-transition-duration

An amount of time to wait between starting a transition and executing a content swap.

ic-trigger-delay

This attributes delays the execution of a trigger and, if the trigger occurs again within the given interval, cancels the original trigger in favor of the new one, which will begin waiting for the interval again.

ic-trigger-from

This attribute can be used to listen for events on other elements in the DOM, or the document or window.

ic-trigger-on

This attributes changes the event on which the element is loaded via ic-src. It can be used to implement lazy loading of images or charts, infinite scrolling, etc.

ic-verb

This attribute allows you to override the HTTP verb to use in a request.

Request Parameters & Headers

Parameters

Parameter

Description

ic-request

This will always be true for intercooler requests.

_method

Because not all browsers support PUT and DELETE requests in AJAX, intercooler uses the Rails convention and adds a _method parameter to the request whose value will be the HTTP Method type (e.g. DELETE).

ic-element-id

The HTML id of the element that caused the request, that is the element that has the ic-post-to or similar attribute on it.

ic-element-name

The HTML name of the element that caused the request, that is the element that has the ic-post-to or similar attribute on it.

ic-target-id

The ID of the target element of the request. This can be used to figure out which bit of partial HTML to render, if a given URL is used to target different areas depending on the context.

ic-trigger-id

The ID of the target that initially triggered the request. This can be different than the element that caused the request: it could be a child element.

ic-trigger-name

The HTML name of the target that initially triggered the request. This can be different than the element that caused the request: it could be a child element.

ic-current-url

The current URL of the page.

ic-prompt-value

The user input from the javascript prompt if the ic-prompt attribute is used

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.

Response Headers

Header

Description

X-IC-Trigger

Allows you to trigger a JQuery event handler on the client side. The value of this header can either be a plain string for the event name, or a JSON object that satisfies the jQuery parseJSon() requirements, where each property is an event name to trigger, and the value of each property is an array of arguments to pass to that event.

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 or parent thereof.

X-IC-ResumePolling

Restarts any polling associated with the target element or parent thereof.

X-IC-SetPollInterval

Sets the polling interval to the given value for the target element or parent thereof.

X-IC-Open

Opens a new window at the given location.

X-IC-PushURL

Sets a new location for the page and saves the history of the element being replaced.

X-IC-Remove

Removes the target element. The value of this header can either be true in which case the element is removed immediately or a numeric time delay (e.g. 750ms or 2s) in which case it will be removed after the given amount of time. If there is a delay the ic-removing class will be added to the element, allowing for a CSS3 animation to be applied prior to the elements removal.

X-IC-Title

Sets the title of the page/document to the given header value.

X-IC-Set-Local-Vars

A JSON object that will be used to set values in the client side localStorage object. Can be used in conjunction with the ic-local-vars attribute to maintain client-side state across requests.

Javascript Events

Event

Description

log.ic(evt, msg, level, elt)

Event fired when log messages occur internally in intercooler (can be used to debug specific DOM elements.)

beforeAjaxSend.ic(evt, ajaxSetting, elt)

Fired on the document before every AJAX request, allowing you to modify the settings object (e.g. to add or remove parameter or headers, change content types, etc.) You can cancel the request by setting the cancel property of the ajaxSettings object to true.

beforeHeaders.ic(evt, elt, xhr)

Triggered before intercooler headers are processed.

afterHeaders.ic(evt, elt, xhr)

Triggered after intercooler headers are processed.

beforeSend.ic(evt, elt, data, settings, xhr, requestId)

Triggered before sending an intercooler AJAX request to the server. The second argument to the event is the data hash, and can be added or removed from to change the values sent to the server.

success.ic(evt, elt, data, textStatus, xhr, requestId)

Triggered after a successful intercooler request is received

after.success.ic(evt, elt, data, textStatus, xhr, requestId)

After headers are processed and the swapping mechanism has begun

error.ic(evt, elt, status, str, xhr)

Triggered after an error occurs during an intercooler request

complete.ic(evt, elt, data, status, xhr, requestId)

Triggered after an intercooler request completes, regardless of status. This event is triggered on the body tag.

onPoll.ic(evt, elt)

Triggered before a poll request is dispatched

handle.onpopstate.ic(evt)

Triggered when intercooler handles an onpopstate event. Triggered on the document body.

elementAdded.ic(evt)

Triggered on an element when it is processed by intercooler.

pushUrl.ic(evt, target, data)

Triggered when a URL is pushed

beforeHistorySnapshot.ic(evt, target)

Triggered before a snapshot is taken for history. Can be used to unwire javascript-based widgets that have messed the DOM up after insert.

Javascript API

Method

Description

Intercooler.refresh(eltOrPath)

If the argument is an element, it will issue a new AJAX request. If it is a string path, it will issue a request for all dependent elements.

Intercooler.triggerRequest(elt, handler)

Triggers an intercooler request for the given element. An optional handler can be used to handle processing the response, which can be useful for integrating with third party libraries that work with JSON. See the Twitter Typeahead Example

Intercooler.processNodes(elt)

This will wire in all intercooler behavior to the given element and its children. Useful if you've done an out of band content swap.

Intercooler.closestAttrValue(elt, attr)

Finds the value of the given attribute that is closest in the parent hierarchy of the given element, including the element. Null if none is found.

Intercooler.verbFor(elt)

Finds the associated HTTP verb for the element.

Intercooler.isDependent(elt1, elt2)

Returns true if elt2 depends on elt1

Intercooler.getTarget(elt1)

Returns the target of the given element.

Intercooler.processHeaders(elt, xhr)

Parses an XHR response for Intercooler headers and executes them on a given DOM element. This can be useful for integrating with third party libraries that issue their own Ajax requests.

Intercooler.ready(func(elt))

Takes a function that takes a single argument, elt, to be run on the top level of all content that is swapped into the DOM by intercooler. This is the Intercooler equivalent of the jQuery ready concept.

Intercooler.debug()

Launch the client-side debugger

Meta Tags

Meta Tag

Description

<meta name="intercoolerjs:use-data-prefix" content="true"/>

By setting this meta-tag value, you will be able to use the data-* prefix for all intercooler attributes, making your HTML validatable.

<meta name="intercoolerjs:use-actual-http-method" content="true"/>

By default intercooler uses the POST HTTP method for all non-GET actions, passing the actual method up with the _method parameter as well as the X-HTTP-Method-Override header, in order to support browsers with incomplete AJAX implementations. If you wish to use the actual HTTP method in the AJAX call (e.g. DELETE) and not worry about legacy browswers, you can set this meta-tag value to "true".


Created with the Personal Edition of HelpNDoc: Free Qt Help documentation generator