Overview

This article introduces example customizations that should be avoided on Kintone. Kintone allows developers to customize the UI of Kintone through JavaScript. There are cases though, where regressions may occur after Kintone updates, as HTML elements of the Kintone product may also be updated. This article will run through DOM manipulations and URL Usages which are the most at-risk for causing regressions.

DOM Manipulation Examples

HTML element references

When adding display elements such as buttons to a page in Kintone, the element should be added to a Space field element with the Get Space Element API or the Record Header Menu Space element with the Get Record Header Menu Element API.

1
2
3
4
5
6

var newDiv = document.createElement('div');
var newContent = document.createTextNode('Hello');
newDiv.appendChild(newContent);

var element = kintone.app.record.getHeaderMenuSpaceElement();
element.appendChild(newDiv);

Elements should be added using a Space element and a Kintone API that retrieves Space elements. Specifying ID and class names of elements directly is not recommended due to possible changes to the HTML structure after product updates. For example, the following code is not recommended.

1
2
3
4
5
6

var newDiv = document.createElement('div');
var newContent = document.createTextNode('Hello');
newDiv.appendChild(newContent);

var currentDiv = document.getElementsByClassName('recordlist-cell-gaia')[0]; // Not recommended
currentDiv.appendChild(newDiv);

The class name recordlist-cell-gaia is retrieved directly and has changes made to the element. Should there be a Kintone update where this class name in the HTML of the page is changed, the customization would no longer work. The same rule applies to using jQuery. For example, code specifying jQuery('.recordlist-cell-gaia') is also not recommended.

Referring to HTML tags as follows is also not recommended.

1
2

var element = kintone.app.record.getFieldElement('Text');
var span = jQuery(element).find('span')[0]; // Not recommended

In conclusion, adding elements to places other than those retrievable by Kintone APIs are strongly discouraged.

Positioning elements using positioning CSS

As stated in the HTML element references section, HTML elements should be added to a Kintone page by retrieving a Space element with a Kintone API and adding the HTML element there. However, when adding position CSS properties to an HTML element, issues may occur due to the possibility of the style of the parent element changing. The following code shows an example.

1
2

var element = kintone.mobile.app.getHeaderSpaceElement();
jQuery(element).append('<div>Hello</div>').css({position: 'fixed', top: '80%', left: '50%'}); // Not recommended

HTML element operations

The Get Record Field Element API is a method used primarily for making styling changes to Kintone fields like the following.

1
2

var element = kintone.app.record.getFieldElement('Text');
jQuery(element).css('color', 'red');

On the other hand, this API may not work for making changes other than styling changes. For example, attaching an event handler directly to the retrieved Space field element is not recommended.

1
2

var element = kintone.app.record.getFieldElement('Text');
jQuery(element).on('click', console.log); // Not recommended

For using mouse or keyboard input events, the following steps are recommended.

1. Retrieve the Space field element
2. Add the required element such as a text box to the retrieved element
3. Use the events for the created text box element
4. Input the text box values into a Kintone field (such as after the Save buton is clicked)

URL Usage Examples

URL references

The Kintone URL is subject to change after a product update. For example, it is possible to implement a customization only to a specified Kintone Space (not to be confused with a Space field element or Record Header Menu Space element mentioned previously) by referencing the URL of the Kintone Space in the code uploaded to the System-wide JavaScript Customization settings (refer to the Customizing the Whole Kintone with JavaScript and CSS article from the Kintone Help Center for more information). However, should the URL change in a product update, the customization will run into errors.

URL specification

Similarly, there is a possibility that the following URL specifications will not work due to a product update.

1

window.location.href = '/k/' + kintone.app.getId() + '/';

Using URL parameters (Query Strings)

It is possible to pass data to Kintone from outside the subdomain by using a URL parameter when opening the Kintone page. There is a possibility though that this method will not work due to a product update. To use external data, use the external service's REST API to retrieve data along with Kintone events such as the Record List Onload event. For more information on Kintone events, refer to the Event Handling article.