Intercooler depends on jQuery being installed, and can be installed like so:
<script src="https://code.jquery.com/jquery-1.10.2.min.js"></script> <script src="https://s3.amazonaws.com/intercoolerjs.org/release/intercooler-0.4.6.min.js"></script>
You can grab the latest code from the Downloads page.
Intercooler consists of a set of attributes that can be used to specify where to submit AJAX requests to, when to do so, and how to handle the responses from the server. There are three core attributes:
ic-src- Where to send and AJAX request to (i.e. the path to submit to)
ic-verb- What HTTP verb to use for the request (e.g.
ic-trigger-on- When to issue the request (e.g. "click" means "Issue the AJAX request when this element is clicked")
Here is an example
div with each of these attributes:
<div ic-trigger-on="click" ic-verb="POST" ic-src="/example"> Click Me! </div>
The attributes on this div tell intercooler:
When this div is clicked, issue a
/exampleand replace the body of the div with the HTML in the response.
There are a few secondary attributes that you will often find useful when you are using intercooler:
ic-target- A CSS selector specifying Who (i.e. which element besides this one) to replace the content of.
ic-include- A CSS selector specifying What Other elements to include (as parameters) with the AJAX request
ic-indicator- What indicator element to make visible while the AJAX request is in flight (e.g. a spinner)
ic-transition- How to swap in the new content (e.g. "none" to have no transition easements)
Extending the example above, we could have this
<div id="targetDiv">Results Div...</div> <i id="indicator" style="display:none" class="fa fa-spinner fa-spin"> <input id="hiddenInput" type="hidden" name="hidden" value="42"/> <div ic-trigger-on="click" ic-verb="POST" ic-src="/example" ic-include="#hiddenInput" ic-indicator="#indicator" ic-target="#targetDiv" ic-transition="none"> Click Me! </div>
This more complicated setup tells intercooler:
When this div is clicked, issue a
/example, including the value of the input with the ID
hiddenInput. While the AJAX request is in flight, show the spinner with the ID
indicator. When the response returns, replace the body of the div with the id
targetDivwith no transition easement (e.g. no fading).
You can see all the intercooler attributes available on the Attributes Page
A few intercooler attribute are macros that combine other attributes and can be used to simplify code. Here are a few macro attributes useful for buttons and forms:
ic-post-to- a macro for
ic-put-to- a macro for
ic-delete-from- a macro for
ic-post-to attribute, our first example can be simplified to:
<div ic-post-to="/example"> Click Me! </div>
That's a bit more civilized.
Intercooler requests are made up of three phases:
Each phase is explained briefly below.
The Request Phase is usually triggered by either a user action or a polling event. Intercooler will look
ic-verb, etc. attributes and issue an appropriate AJAX request,
showing the request indicator (if any exists).
When the server responds, Intercooler will first examine the response headers to see if there are any directives to execute. Then, if the body of the response is non-empty, it will swap the new content into the targeted element using the specified transition (or the default one if none was specified.) At this point the request indicator will be re-hidden.
Finally, if the request was due to human input, intercooler will enter the dependency phase. It will look for
other elements on the page that have an
ic-src that depends
(as defined here) on the URL that was uses in the Request Phase AND
that are a
GET, and will issue requests for updated content for them. Dependency propagation
terminates here: no further requests will be issued automatically.
Here are some examples of intercooler in action.
This example shows a div that polls a URL for updates.
<div ic-src="/visitors/count_div" ic-poll="2s"> You have had 42 visitors today </div>
It will poll the given URL,
/visitors/count_div/ by issuing an AJAX
every two seconds.
Here is an example of a returned fragment from
You have had 103 visitors today
Here is the div in action (be patient, sometimes no new visitors show up so it won't update on every 2 second interval):
The example above is passive: it polls the URL without any user input. Let's make it respond to a button click instead, and introduce our first dependency example:
<div ic-src="/example/click"> You have not yet clicked the button </div> <button ic-post-to="/example/click"> Click Me! </button>
Here we've removed the
ic-poll attribute and introduced a button with a ,
The server receives the post and increments a server-side counter of the number of times
you have clicked the button.
When the button is clicked, Intercooler detects that the div depends
on the URL that the button posted to, and so it automatically does a refresh, issuing a
and swapping any new content into the div.
In this example we will make things a bit more interactive by allowing the user to enter an item name that will be uploaded to the server.
<div ic-src="/name"> No name entered </div> <input id="a_name" type="text" name="name" placeholder="Enter A Name"/> <button ic-post-to="/name" ic-include="#a_name"> Upload Name </button>
We are targeting a new URL,
/name and we've added the
attribute, which includes the input
#a_name name and value in the POST that is
submitted by the button.
In this example we will switch the target from a div swap to a list prepend, using intercooler's
<input id="item_name" type="text" name="item_name" placeholder="Enter Item Name"/> <button ic-post-to="/items" ic-include="#item_name">Upload Name</button> <ul ic-prepend-from="/items" ic-limit-children="3"> <li>Placeholder</li> </ul>
As before, we are passing up the item
name via the
ic-include attribute, and we are limiting the number of children in the list
to a total of 3 with the
Finally, lets finish with a relatively complicated example: a job-monitoring UI
To do this, we will use Intercooler's
ic-style-src attribute, which allows us to bind
a style property to a URL. The UI will first start of with a placeholder div. When the button is clicked,
the job will start, replacing the div with a progress bar. When the job completes, the original placeholder
div will return.
We will start with the following code:
<button class="btn btn-primary" ic-post-to="/job">Start Job</button> <div ic-src="/job">Job Not Running...</div>
Pretty simple: a div and a button that are both tied to the same URL. Remember, this means that the div depends on the button, and it will be refreshed after the button is clicked.
When the button is clicked a (simulated) job is kicked off. When a request for the div is made, the following HTML fragment is returned:
Job Running: <div class="progress progress-striped active"> <div class="progress-bar" ic-style-src="width:/job/percent_complete" ic-poll="1s" style="width:0%"></div> </div>
This HTML is swapped in for the body of the div, and includes a Bootstrap-based progress bar. The
style attribute of the progress bar is tied to the
/job/percent_complete URL using the
directive, which it polls ever second. That URL will return values like
which will update the width of the progress bar.
When the job is finished the request to
/job/percent_complete includes a
Intercooler HTTP Header directive telling Intercooler to refresh all elements that
depend on the
/job path, which refreshes the parent div and removes the progress bar.
Here is the code in action: