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-enhance This attribute tells intercooler to enhance all anchor tags and form tags that it founds, adding the equivalent AJAX functionality to them.
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-global-indicator This attribute tells Intercooler to show the specified global indicator, in addition to whatever local indicators an element might want shown.
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-push-params This attribute tells Intercooler to include the given parameters in the URL that is pushed via the ic-push-url attribute.
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-switch-class Allows you to swap a class amongst sibling elements in a DOM when an intercooler event is triggered. This can be used, for example, to switch an active class between tabs without replacing the HTML.
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. Please note that only ASCII characters are guaranteed to work.
X-IC-Title-Encoded The same as X-IC-Title but the value is expected to be URI encoded
X-IC-Title-Encoded URI decodes the given header value and sets the title of the page/document to the decoded value. Use this header if you need to show UTF-8 characters in the title.
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.
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.
LeadDyno.startPolling(elt) Begins polling for the given element
LeadDyno.stopPolling(elt) Stops polling for the given element

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".