How to avoid unrecommended customizations

Introduction

Kintone is updated monthly for maintenance and to bring new features to the product. However, if Kintone customizations have been created using methods not included in the Kintone API documentation, there is the risk that the customization will not work in the future due to changes or additions to features.

 

For example, making changes to Kintone pages using DOM manipulation is not recommended because it directly makes references and edits to HTML elements that could be changed due to product updates.

 

This article introduces an example of a customization that does not function as expected when Kintone is updated to provide clarity on why it is necessary to be careful when choosing how to implement customizations.

Examples

The following section explains two broad categories of customization that are the most at-risk for having negative effects due to Kintone updates. These are DOM manipulation, and use of URLs. A workaround for the risk is also explained if it exists.

DOM manipulation

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 (refer to the Get Space Element documentation for details) or the Record Header Menu Space element with the Get Record Header Menu Element API (refer to the Get Record Header Menu Element documentation for details).

 

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

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.

 

In other words, adding elements to places other than those retrievable by a Kintone API is 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, problems may occur due to the possibility of the style of the parent element changing and is not recommended. The following code shows an example of this.

HTML element operations

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

 

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.

 

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. Use inputted values at the necessary timing
    Example: In the case of a text box, enter the inputted value to a Kintone field at the event of when the record's Save button is clicked.

Use of URLs

URL references

The Kintone URL is subject to change.
For example, it is possible to implement a customization only to a specified Kintone Space (the Kintone Space feature, 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 future Kintone 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 future update.

Using a URL parameter (Query String)

It is possible to pass data to Kintone from outside the subdomain by using a URL parameter when opening the Kintone page, but again, there is a possibility that this method will not work due to a future 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.

Finally

The unrecommended customizations described in this article are just examples, and others exist as well. Hopefully, this article provided some idea of the risks of some common customization implementation that can be avoided or used with caution. Have fun customizing!

Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!