Installation

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.

Core Intercooler Attributes

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. POST)
  • 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 POST to /example and replace the body of the div with the HTML in the response.

Secondary Intercooler Attributes

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 POST to /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 targetDiv with no transition easement (e.g. no fading).

You can see all the intercooler attributes available on the Attributes Page

Macro Attributes

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-src, ic-verb="POST" and ic-trigger-on="default"
  • ic-put-to - a macro for ic-src, ic-verb="PUT" and ic-trigger-on="default"
  • ic-delete-from - a macro for ic-src, ic-verb="DELETE" and ic-trigger-on="default"

Using the 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 Explained

Intercooler requests are made up of three phases:

  1. The Request Phase
  2. The Response Phase
  3. The Dependencies Phase

Each phase is explained briefly below.

The Request Phase

The Request Phase is usually triggered by either a user action or a polling event. Intercooler will look at the ic-src, ic-verb, etc. attributes and issue an appropriate AJAX request, showing the request indicator (if any exists).

The Response Phase

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.

The Dependency Phase

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.

Examples

Here are some examples of intercooler in action.

Polling Update

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 GET every two seconds.

Here is an example of a returned fragment from GET /visitors/count_div/:

    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):

You have had 42 visitors today

A Trigger + Dependencies Example

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 , ic-post-to. 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 GET and swapping any new content into the div.

You have not yet clicked the button

Adding Input

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 ic-include attribute, which includes the input #a_name name and value in the POST that is submitted by the button.

No name entered

Switching To UL

In this example we will switch the target from a div swap to a list prepend, using intercooler's ic-prepend-from attribute

  <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 ic-limit-children attribute:

  • Placeholder

Implementing A Dynamic Progress Bar

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 width style attribute of the progress bar is tied to the /job/percent_complete URL using the ic-style-src directive, which it polls ever second. That URL will return values like 37% and 78%, 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:

Job Not Running...

On To The Docs...

That gives you a good overview of intercooler and what you can accomplish. You can read about all the attributes here, response tricks here, and the javascript API here.

Want more examples? Check out the tutorials →