Progressive enhancement with handlers and enhancers

Published 03 April 2015 category: code

Recently I adopted a different way to manage bits of JavaScript in websites I was building. It exercises progressive enhancement (PE) by declaring handler and enhancer functions on HTML elements.

TL;DR: When JavaScript is used to handle user interactions like clicks, or enhance the page by manipulating the DOM, traditionally you’d have JavaScript find that HTML element in your page, and hook some code into it. But what if you’d switch that around, and have the HTML element “tell” JavaScript what function to execute?

How? I declare JavaScript functions on HTML elements. Separating them to functions that happen on click and those that happen on page load, I use two attributes (data-handler and data-enhancer) that both get space-separated function names as their values. Then, with a little bit of JavaScript, I make sure the functions execute when they need to.

Note that this works best for websites for which the mark-up is rendered on the server, to which JavaScript is added as an extra layer. Websites that rely on JavaScript for rendering content will probably have options to do the same within the framework they are built with.

Separating to handlers and enhancers

On many small to medium sized websites, the required JavaScript can be drilled down to two types of usage:

  1. things that need to happen on a click
  2. enhancements after the inital page load

Surely, there are often other events we want to use for triggering JavaScript (scroll, anyone?), but let’s focus on these two types first.

Many simple websites will have both types of script in a single scripts.js file, which is also used to query the nodes interactions need to happen on, and to add click handlers to those nodes.

This year, Krijn and Matijs introduced me to a new way to go about this. It has proven to be a very powerful pattern in some of my recent projects, which is why I’d like to share it here. Credits for the pattern, and for the initialisation functions I will discuss later, go to them.

Including JavaScript functions to the declarative model

The pattern starts from the idea that web pages have three layers to them: structure (HTML), lay-out (CSS) and enhancement (JavaScript). HTML is a declarative language: as an author, you declare what you’d like something to be, and that is what it will be.

Let this be a header, let this be a list item, let this be a block quote.

This is great, browsers can now know that ‘this’ is a list item, and treat it as such. Screenreaders may announce it as a list, your RSS reader or mobile Safari “reader view” can view it as a list, et cetera.

With CSS we declare what things look like:

Let headers be dark blue, let list items have blue bullets and let block quotes render in slightly smaller type.

This works rather well for us, because now we don’t need to think about what will happen if we add another list item. It being a list item, it will have the CSS applied to it, so it will have blue bullets.

The idea I’d like to share here, is that of making JavaScript functions part of this declarative model. If we can declare what something looks like in HTML, why not declare what its behaviour is, too?

Handlers: things that happen on a click

The idea is simple: we introduce a data-handler attribute to all elements that need to trigger function execution. As their value, we add one or more functions name(s) that need(s) to execute on click.

For example, here’s a link:

<a href="#punk-ipa">More about Punk IPA</a>

This is an in-page link to a section that explains more about Punk IPA. It will work regardless of JavaScript, but can be improved with it.

Cooler than linking to a section about Punk IPA, is to have some sort of overlay open, with or without a fancy animation. We add a data-handler attribute:

<a href="#punk-ipa" data-handler="overlay">More about Punk IPA</a> 

In the data-handler, the value holds a function name, in this case ‘overlay’. The idea is that the overlay function executes when the link is clicked. Naturally, you would be able to add more than one function name, and separate function names by spaces. This works just like class="foo bar".

Within the function declaration, we will know which element was clicked, so we can access attributes. We can access the href or any data attribute. With that, it can grab the content that’s being linked to, append it into some sort of overlay, and smoothly transition the overlay into the page.

Note that this is similar to doing <a onclick="overlayfunction(); anotherfunction();">, but with the added benefit that a data-handler only gets meaning once JavaScript is active and running, and that it contains strings like CSS classes, instead of actual JavaScript code. This way, the scripting is separated in the same way as the style rules are.

Also note that is best practice to only add handlers to HTML elements that are made for click behaviour, like <button>s and <a>.

Adding function definitions

In our JavaScript (e.g. an included scripts.js file), we add all functions for click behaviour to one object:

var handlers = {
	'function-name' : function(e) {
		 // This function is executed on click of any element with 
         // 'function-name' in its data-handler attribute.
         // The click event is in 'e', $(this).attr('data-foo') holds the
         // value of data-foo of the element the user clicked on 
    'another-function-name' : function(e) {}

Those working in teams could consider making the handler object global. That way functions can have their own files, making collaboration through version control easier.

Adding click handling: one handler to rule them all

If we set all our click-requiring functionality up within data-handler attributes, we only need to attach one click handler to our document. Event delegation can then be used to do stuff to the actual element that is clicked on, even when that actual element did not exist on page load (i.e. was loaded in with AJAX).

This function (jQuery) can be used to handle clicks, then search through the handler functions and apply the ones specified in the data-handler function:

$(function() {
    'use strict';
    // generic click handler
    $(document).on('click', '[data-handler]', function(event) {
        var handler = this.getAttribute('data-handler');
        // honour default behaviour when using modifier keys when clicking
        // for example:
        // cmd + click / ctrl + click opens a link in a new tab
        // shift + click opens a link in a new window
        if (this.tagName === 'A' && (event.metaKey || event.ctrlKey || event.shiftKey)) {
        if (handlers && typeof handlers[handler] === 'function') {
            handlers[handler].call(this, event);
        else {
            if (window.console && typeof console.log === 'function') {
                console.log('Non-existing handler: "%s" on %o', handler, this);

(Source; see also its vanilla JavaScript version)

Enhancers: things that happen after page load

We can run functions to enhance elements in a similar way, by adding their function names to a data-enhancer attribute. The corresponding functions go into a enhancers object, just like the handlers object above.

For example, a page element that needs to display tweets. Again, here’s a link:

<a href="">Tweets of the BBC</a>

To enhance this link to the BBC’s tweets, we may want to load a widget that displays actual tweets. The function to do that may add some container <div>s, and run some calls to the Twitter API to grab tweets. To trigger this function:

<a href="" data-enhancer="twitter-widget">
Tweets of the BBC</a>

To find out whose Twitter widget to display, our function could analyse the URL in the href attribute, or we can add an extra attribute:

<a href="" data-enhancer="twitter-widget" 
data-twitter-user="bbc">Tweets of the BBC</a>

Another example: of a large amount of text, we want to hide all but the first paragraph, then add a “Show all” button to show the remainder. The HTML will contain all of the content, and we will hide the remainder with JavaScript.

    <p>Some text</p>
    <p>Some more text</p>
    <p>Some more text</p>

To the block of text we add a data-enhancer function that makes sure everything but the first paragraph is hidden, and a “Show all” button is added.

<section data-enhancer="only-show-first-paragraph">
    <p>Some text</p>
    <p>Some more text</p>
    <p>Some more text</p>

A function named ‘only-show-first-paragraph’ could then take care of removing the content, and adding a button that reveals it (this button could have a data-handler for that behaviour).

Running all enhancements

Assuming all our enhancer functions are in one enhancer object, we can run all enhancers on a page with one function. The function looks for all elements with a data-enhancer attribute, and calls the appropriate functions.

$(function() {
    'use strict';
    // kick off js enhancements
    $('[data-enhancer]').each(function() {
        var enhancer = this.getAttribute('data-enhancer');
        if (enhancers && typeof enhancers[enhancer] === 'function') {
        else {
            if (window.console && typeof console.log === 'function') {
                console.log('Non-existing enhancer: "%s" on %o', enhancer, this);


So the basic idea is: functions for click behaviour are handlers, and those that happen on page load are enhancers. They are stored in a handlers and enhancers object respectively, and triggered from HTML elements that have data-handler and data-enhancer attributes on them, to declare which functions they need.

In summary:

  1. All functions that need to execute on click (or touch or pointer events), are declared on the HTML element that should trigger the click, in a data-handler attribute
  2. All functions that need to change/enhance stuff on the DOM, are declared on the HTML element they need to change, in a data-enhancer attribute
  3. Two JavaScript functions run through data-handler and data-enhancer attributes respectively, and execute all functions when they are required


This pattern is not new, similar things have been done by others. Rik Schennink wrote about controlling behaviour before, and his conditioner.js deserves special mention. It is a library that not only manages modules of JavaScript, it also activates them based on responsive breakpoints, something the pattern described here does not do out of the box (it could).

For me and teams I worked in, the above has proven to be a useful way to declare actions and enhancements within pages. It adds maintainability, because it helps keeping functions organised. It also promotes reusability: although new functions can be added for each use, multiple elements can make use of the same function.

The method is not perfect for every project, and it can definitely be improved upon. For example, we could add the function that triggers all data-handler functions to an enhancer (<html data-enhancer="add-handlers">), as it is an enhancement (of the page) by itself. In big projects with many people working on the same codebase, it may be useful to have all functions in separate files and have a globally available handlers object.

Update 07/04/2015: I have opened comments, would love to hear any feedback

Comments & mentions (14)

Šime Vidas 08 Apr 2015 02:15:14

Using data-* attributes, instead of CSS classes, as hooks for JavaScript sounds like an solid approach. As for the JavaScript part, a few things:

1. I’m not sure that a global document click handler is best. It feels rather limiting, e.g. maybe a developer would like to conditionally stop event propagation (or cancel the event completely) in some scenario?

2. Having enhancer functionality mapped to single elements might also be too limiting. What if I have an enhancement that targets a group of elements? Which element should get the data-enhancer attribute?

3. What if my enhancement needs to bind click handlers? Do I use data-handler? Or do I bind the handlers inside the enhancer function?

I don’t use a framework (for my simple site) but if I had to, I’d rather go “all in” with a well established framework like Ember, than to try to improvise with a simpler approach like the one described here.

Hidde de Vries 08 Apr 2015 07:04:20

@Šime Thanks for your comment and feedback.

1. I recommend only adding handlers to elements that are clickable by default (like <a/> and <button>), which don’t allow nesting so would not need propagation stopped. preventDefault() from within a handler function can be done. This is what I do, it is in most of my handler functions.

2. If a group of elements is to be targeted, the data-enhancer simply goes onto the containing element (pretty much like descendant selectors in CSS). To get to each element in the group, your enhancer function can perform a search within the containing element. Eg, if a carousel has five slides within a container, the data-enhancer would go onto the container, the enhancer function would then be able to search for the slides from the containing element.

3. The former — in my enhancements, I also rely on data-handler for binding click handlers. To use the carousel example again, the previous/next buttons would have a data-handler attribute with the previous/next behaviour. The ‘change slide’ behaviour can then be in one function, which could even be reusable across different types of carousels.

qll 08 Apr 2015 10:53:08

While I find the approach interesting, I am afraid of the potential this has to undermine a good Content Security Policy. I know, most client-side frameworks do this to some extend, but this really allows attackers to execute your functions in an arbitrary order – making an attack possible again. What are your thoughts about this?

Hidde de Vries 08 Apr 2015 12:42:40

@qll Good point. Any attackers would only be able to execute my functions, so it is only going to be as dangerous as my functions, but you are right anyone taking this approach should consider which functionality they add through it.

Todd 09 Apr 2015 11:26:47

I think this idea is pretty cool… but I have to ask: Is that your normal brace formatting for else statements? – yikes!

I’m Baffled why some folks don’t use K&R style, I accept that some insist to have all braces on their own line but you’ve got an odd combo of K&R style with the exception of a line break after the closing if brace?… I’ve never seen anyone do this before.

Max Wheeler 09 Apr 2015 11:30:32

+1 to this approach. I’ve been using a tiny jQuery library called Viewloader (and a vanilla rewrite I’ve been meaning to release) for a while that does essentially the same thing you describe in your ‘enhancer’ pattern.

Have a consistent interface between how DOM-interested JavaScript is invoked makes it incredibly easy to understand why particular methods are being called.

It also means you can’t forget invoke the associated JavaScript for a particular page — the HTML element’s presence ensures its function is invoked.

Gaël Poupard likes this
jalbertbowdenii likes this
Bart Vandeputte likes this
geertmelotte likes this
Chris Ferdinandi ⚓️ reposted this
Chris Ferdinandi ⚓️ replied: Nice! I'll be sharing my technique for this tomorrow. Thanks for this!
Chris Ferdinandi ⚓️ replied: I've seen something like this before, but never so clearly described. Love it! Thanks!
Astrolabit replied: Progressive enhancement with handlers and enhancers…
Leave a comment
Posted a response to this?

This website uses Webmentions. You can manually notify me if you have posted a response, by entering the URL below.