Custom JavaScript up.compiler(selector, [options], compiler) function

Registers a function to be called whenever an element with the given selector is inserted into the DOM.

Use compilers to activate your custom Javascript behavior on matching elements.

You should migrate your jQuery ready callbacks to compilers.

Example

Let's say that any element with the action class should alert a message when clicked. We can implement this behavior as a compiler function that is called on all elements matching the .action selector:

up.compiler('.action', function($element) {
  $element.on('click', function() {
    alert('Action was clicked!');
  });
});

The compiler function will be called once for each matching element when the page loads, or when a matching fragment is inserted later.

Integrating jQuery plugins

up.compiler() is a great way to integrate jQuery plugins. Let's say your JavaScript plugin wants you to call lightboxify() on links that should open a lightbox. You decide to do this for all links with an lightbox class:

<a href="river.png" class="lightbox">River</a>
<a href="ocean.png" class="lightbox">Ocean</a>

This JavaScript will do exactly that:

up.compiler('a.lightbox', function($element) {
  $element.lightboxify();
});

Custom elements

You can use up.compiler() to implement custom elements like this:

<clock></clock>

Here is the JavaScript that inserts the current time into to these elements:

up.compiler('clock', function($element) {
  var now = new Date();
  $element.text(now.toString()));
});

Cleaning up after yourself

If your compiler returns a function, Unpoly will use this as a destructor to clean up if the element leaves the DOM. Note that in Unpoly the same DOM ad JavaScript environment will persist through many page loads, so it's important to not create memory leaks.

You should clean up after yourself whenever your compilers have global side effects, like a setInterval or event handlers bound to the document root.

Here is a version of <clock> that updates the time every second, and cleans up once it's done. Note how it returns a function that calls clearInterval:

up.compiler('clock', function($element) {

  function update() {
    var now = new Date();
    $element.text(now.toString()));
  }

  setInterval(update, 1000);

  return function() {
    clearInterval(update);
  };

});

If we didn't clean up after ourselves, we would have many ticking intervals operating on detached DOM elements after we have created and removed a couple of <clock> elements.

Attaching structured data

In case you want to attach structured data to the event you're observing, you can serialize the data to JSON and put it into an [up-data] attribute. For instance, a container for a Google Map might attach the location and names of its marker pins:

<div class='google-map' up-data='[
  { "lat": 48.36, "lng": 10.99, "title": "Friedberg" },
  { "lat": 48.75, "lng": 11.45, "title": "Ingolstadt" }
]'></div>

The JSON will parsed and handed to your compiler as a second argument:

up.compiler('.google-map', function($element, pins) {

  var map = new google.maps.Map($element);

  pins.forEach(function(pin) {
    var position = new google.maps.LatLng(pin.lat, pin.lng);
    new google.maps.Marker({
      position: position,
      map: map,
      title: pin.title
    });
  });

});

Migrating jQuery event handlers to up.compiler()

Within the compiler, Unpoly will bind this to the native DOM element to help you migrate your existing jQuery code to this new syntax.

So if you had this before:

$(function() {
  $('.action').on('click', function() {
    $(this).something();
  });
});

… you can reuse the callback function like this:

up.compiler('.action', function($element) {
  $element.on('click', function() {
    $(this).something();
  });
});