Best practices for registering event handlers

Contents

Introduction

For Kintone customizations, there are cases where Kintone cannot trigger an event when the page loads, if the event handler is registered too late.

In this article we will go through:

  • Timing for events triggered when a page loads in Kintone
  • Warnings displayed in the console
  • How to write event handlers with appropriate timing

Timing for events triggered when a page loads in Kintone

When the browser loads a page in Kintone, HTML and various JavaScripts are loaded with different timing, in the following order:

  1. The browser starts loading the HTML of the page
  2. Kintone's JavaScript APIs are initialized
  3. Customization scripts added to Kintone by users are loaded
  4. The Kintone platform's JavaScript initializes the page in Kintone
  5. The browser finishes reading the HTML of the page and triggers the DOMContentLoaded event (* 1)
  6. The browser generates the load event (* 2) , after loading resources (such as images) specified in the HTML

With common JavaScript coding approaches, such as by using jQuery, the main function starts processing with the event handlers of the DOMContentLoaded event (timing 5) or the load event (timing 6).

The Kintone platform itself starts processing the page at an earlier timing (timing 4), which may result in Kintone's onload event to start before the DOMContentLoaded event (* 3).

If an event is triggered earlier than the registration of the event handler, the event handler will not be called.
Therefore, if you register event handlers in Kintone within the DOMContentLoaded or load event, the event handlers may not be called. Specifically, this applies to the following Kintone events:

In order to reliably handle these onload events, register the event handlers synchronously, using kintone.events.on() at timing 3 when the customization scripts for Kintone are loaded.

(* 1) Reference: https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event (External link)

(* 2) Reference: https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event (External link)

(* 3) Kintone generates many components on the screen using JavaScript. Therefore, there is no direct relation between the timing of the DOMContentLoaded and load events completion generated by the browser, and the timing of Kintone's DOM construction completion.

Warnings displayed in the console

If the registration of the event handler using kintone.events.on() is not processed synchronously when the customization JavaScript at timing 3 is loaded, the following warning may be displayed in the browser's developer console (* 4).

If this warning is displayed, please correct the registration timing of the event handler in your code by referring to the example in this article.

(* 4) This message is shown after the July 2018 update. It is not displayed if app.record.create.show, app.record.edit.show, app.record.edit.show, app.record.detail.show are not registered, or if they are registered at the appropriate timing.

How to write event handlers with appropriate timing

jQuery Examples

Bad examples

One common way of using jQuery is to write the entire script wrapped with $(function() {...});

1
2
3
4
5
$(function() {
  kintone.events.on('app.record.create.show', function(event) {
    window.alert('Onload Record Create Event');
  });
});

This is equivalent to processing the ... part of the script in the event handler of the DOMContentLoaded event.

1
2
3
4
5
document.addEventListener('DOMContentLoaded', function(loadedEvent) {
  kintone.events.on('app.record.create.show', function(event) {
    window.alert('Onload Record Create Event');
  });
});

As mentioned earlier, the DOMContentLoaded event is processed after the initialization of the page by the Kintone platform's JavaScript. Therefore, writing your script this way will result in registering the event handler using kintone.events.on() after the app.record.create.show event is triggered, and the event handler will not be called.

Good example

Wrap the script in an anonymous function and pass in jQuery to be mapped to $.

1
2
3
4
5
6
7
(function($) {
  'use strict';

  kintone.events.on('app.record.create.show', function(event) {
    window.alert('Onload Record Create Event');
  });
})(jQuery);

There may be cases where you would want to start processing your script after the DOMContentLoaded event is triggered. In this case, separate (1) the event handler registration via kintone.events.on(), and (2) the process wrapped with $(function() {...}; .

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
(function($) {
  'use strict';

  kintone.events.on('app.record.create.show', function(event) {
    window.alert('Onload Record Create Event');
  });

  $(function() {
    // If you need to wait for the DOMContentLoaded event, write your code here
    // ...
  });
})(jQuery);

Common JavaScript examples

Even when not using jQuery, make sure to register event handlers of the Kintone onload events so that they are processed synchronously when customization scripts are loaded.

Bad examples
  • Registering the event handler for app.record.create.show in the event handler of the DOMContentLoaded event.
1
2
3
4
5
6
7
8
9
(function() {
  'use strict';

  document.addEventListener('DOMContentLoaded', function(loadedEvent) {
    kintone.events.on('app.record.create.show', function(event) {
      window.alert('Onload Record Create Event');
    });
  });
})();
  • Registering the event handler for app.record.create.show in the event handler of the load event.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    (function() {
      'use strict';
    
      document.addEventListener('load', function(loadedEvent) {
        kintone.events.on('app.record.create.show', function(event) {
          window.alert('Onload Record Create Event');
        });
      });
    })();
  • Registering the event handler for app.record.create.show in the callback of an asynchronous request or process.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    (function() {
      'use strict';
    
      kintone.api('/k/v1/records', 'GET', {app: appId}, function(result) {
        kintone.events.on('app.record.create.show', function(event) {
          window.alert('Onload Record Create Event');
        });
      });
    })();
Good example
1
2
3
4
5
6
7
(function() {
  'use strict';

  kintone.events.on('app.record.create.show', function(event) {
    window.alert('Onload Record Create Event');
  });
})();

Conclusion

In this article, we introduced the timings of the various events that Kintone triggers when the page loads, and recommended approaches for registering event handlers at the appropriate timing.

You may find that your script works without any issues even though the warning is displayed in the console. However, note that this may lead to issues in the future, as asynchronously registered event handlers are greatly affected by network delay, client PC performance, and other running customization scripts.

Make sure to follow the good examples in this article for a more reliable customization experience.