Dojo in XPages – 16: Attaching Event Handlers with dojo.on()

In this post, I’ll show how to dynamically add event handlers to one or more events on one or more DOM elements with dojo.on().

Dojo in XPages Series

Dojo in XPages — All Blog Posts

Including the dojo.on module

The dojo.on module is not automatically available, so you need to add it either to the page/custom control as a resource or to the entire application via the theme. (See this post for more information).

This allows you to dynamically add event handlers as needed.

Using dojo.on()

To attach an event handler, you use the method in this form: dojo.on(DOM element, event, function)

For example, to add an event handler when the user clicks a button with the id of myButton, you could use this code:

dojo.on(dojo.byId('myButton'), 'click', function() {
  console.log('clicked button');

You could also define the function by name rather than inline.

function logClick() {
  console.log('clicked button');

dojo.on(dojo.byId('myButton'), 'click', logClick);

This allows you to refer to more complex functions or functions that exist in libraries or elsewhere on the page.

Adding Event Handlers to Multiple Elements

You can also add event handlers to multiple elements at the same time by chaining the on() event to a dojo.query().

This code will add a click event handler to all table rows on the page:

dojo.query('tr').on('click', function() {
  console.log('clicked table row');

Since you’re chaining this to a query that’s selecting the elements, you only have to specify the event and the function when calling the on() method.

Event Handler Timing

The timing of connecting events is very important. If you run this code immediately as the page loads, the DOM elements may not be available for attaching event handlers.

If you need the code to run right away, put it in the onClientLoad event of the page or custom control. This is the dojo event that fires once the page is fully loaded.

Otherwise, you can run it dynamically when triggered by some other page event.

Adding Handlers to Multiple Events

You can attach an event handler to multiple event types with a single call by comma-delimiting the event names.

This code will attach an event handler to the click, double-click, and mouseover events and also demonstrate how to determine the type of event that was triggered:

dojo.on(dojo.byId('myButton'), 'click, dblclick, mouseover', function() {
  console.log('triggered button event');

We’ll look more at dealing with event info in the next post.

Disconnecting an Event Handler

If you want to disconnect an event handler, you can keep a handle to it at the time you attach it and then use remove() method to drop it.

This code will set up an event handler and store it in a variable.

var handle = dojo.on(dojo.byId('myButton'), 'click', function() {
  console.log('clicked button');

This code will remove the event handler:


Firing an Event Handler Once, then Automatically Disconnecting

If you want to attach an event handler that will only fire one time and then remove itself, you can use the dojo.on.once() method.

This code will add an event handler to write a message to the console on the first click and then stop listening for the event.

dojo.on.once(dojo.byId('myButton'), 'click', function() {
  console.log('clicked button');

Backwards Compatibility Note

The dojo.on() method is new as of Dojo 1.7, so it’ll work in Notes 9.

The previous method is dojo.connect(), which still works for now, but is deprecated and may be removed when dojo 2 is released. (Although this is not really a concern for an XPages application until Notes starts including Dojo 2.)


5 responses to “Dojo in XPages – 16: Attaching Event Handlers with dojo.on()”

  1. Richard Moy says :

    Brad. With the migration dojo from 1.x to 2, write as much as possible your code as classes and it will be easier to migrate from 1.x to 2.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: