Kintone Coding Guidelines

Contents

Overview

By using Kintone's "JavaScript / CSS Customization" features, the UI and features of Kintone and it's Applications can be customized.
This page introduces guidelines for Kintone JavaScript customization that you should read before you start coding for Kintone customizations.
Please refer to our Kintone Help Pages for details on how to apply JavaScript customization to your Apps.

Coding Guidelines

Character Encoding

Always use UTF-8 without BOM.

Namespaces and Variables

Do not overwrite existing global objects.
Declare local variables inside the scope of anonymous functions or within block scope. Do not declare variables as global variables.
Use a namespace object if a variable needs to be used between function scopes.

Avoid Using or Overwriting Global Variables
1
2
3
4
(() => {
  globalVariable = 1; // Do not declare global variables.
  const localVariable = 1; // Instead declare your local variables within the immediately invoked function.
})();

Declare Variables Within the Scope of Blocks

1
2
3
4
5
6
7
8
{
  // Bad Practice: globalVariable is overwritten due to overlapping scope and using var to declare.
  globalVariable1 = 1;
  var globalVariable2 = 1;
  // Good Practice: Variables are declared locally, within the block scope, as declaring variables with let respects block scope.
  const localVariable1 = 1;
  let localVariable2 = 1;
}
Add to or Reference Existing Objects Rather than Editing
1
2
3
4
5
6
7
8
(() => {
  // Bad Practices:
  kintone.foo = 'bar'; // Do not edit the existing global object.
  const foo = kintone.foo; // Avoid referencing global objects.
  // Good Practices:
  myNameSpace = {}; // Create a new object instead.
  myNameSpace.foo = 'bar'; // Add the desired properties to that object.
})();

id/class Attributes that are Used in Kintone

The id/class attributes of each element used in Kintone may be changed without any notice.
The DOM structure may also change without any notice.

When creating Kintone customizations, refrain from editing the following:

  • id or class of HTML elements
  • The DOM structure of any elements not obtained via the Kintone JavaScript API

When editing the DOM, it is highly recommended to utilize the Kintone JavaScript API, as the classname, id or other DOM properties may be changed at any time without warning by Kintone.

Customization on Elements retrieved with JavaScript APIs

As Kintone's CSS may affect the elements, they may not always look the same.
For APIs that can get elements, refer to Kintone JavaScript API.

Retrieving the URL

Use the kintone.api.url() or the kintone.api.urlForGet() method to retrieve the Kintone URL.

Consider the Effect to the Kintone Service

Avoid sending large amounts of requests within a short time period

Programs that automatically send large amounts of requests, and those that run multiple requests in parallel, can both lead to performance degradation and slow responses. Be aware that we may limit your Kintone environment's access if you are sending requests that place high load onto our servers and use up a high amount of our resources.

Check Operations on Several Web Browsers

Depending on the JavaScript program that is uploaded onto Kintone, some features of Kintone may not function correctly.
Check that the customizations that you have made are working correctly on different web browsers.
For Kintone’s system requirements, refer to the System Requirements (External link) page.

Set an appropriate user agent

Please set an appropriate value in the User-Agent header, so that we can identify what services or tools the requests are coming from.
Refer to the guidelines on user-agents through the below link:

Effects of Kintone Updates

After Kintone has an update, there may be a possibility that the JavaScript and CSS files that you uploaded do not function correctly. In this case, please edit the file contents and re-upload them.
To greatly reduce the chance of this happening, please make sure to read through the JavaScript API documents and use the Kintone JavaScript API in your codes.

Change Policy for Public API Specifications

Security

To prevent security issues from your JavaScript programs, please create your programs following the Secure Coding Guidelines.