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.

If a variable needs to be used between function scopes, use one of the following:

  • Use JavaScript bundlers such as webpack
  • Use a namespace object
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.

Contents that cannot be customized with JavaScript API and CSS

The following App pages will not run their JavaScript/CSS customizations if attached to bodies of Spaces/Threads/Announcements:

  • Record list
  • Graph

Check Operations on Several Web Browsers

It is recommended to use different Web browsers to test the customization.
Depending on the JavaScript program that is uploaded onto Kintone, some features of Kintone may not function correctly.
Check that the customization works correctly in different browser types and versions.
For Kintone’s system requirements, refer to the System Requirements (External link) page.

Consider the Effect to the Kintone Service

Avoid sending large amounts of requests within a short time period

Automated programs sending numerous requests or running multiple parallel requests can degrade performance and slow responses. Please note that excessive requests imposing a heavy load on our servers may result in access restrictions on your Kintone environment.

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.