This article introduces how to code an Automatic Numbering customization, that initiates a Kintone REST API within the code using one of the following two methods:
- by using Synchronous XMLHttpRequest (synchronous XHR)
- by using the Kintone REST API Request method and promises
The aim of this article is to guide developers to use the Kintone REST API Request method in their customizations instead of using synchronous XMLHttpRequests which causes negative effects to the user experience.
Although synchronous XMLHttpRequests can be used to call Kintone REST APIs, it has the following issues:
- synchronous requests block the executions of codes, causing the screen to be unresponsive until the request is finished
- synchronous XMLHttpRequest is deprecated in major browsers, displaying warnings in the console
With the use of the Kintone REST API Request method and promises, developers can write code that initiates a similar process, but without the need for using synchronous XMLHttpRequests.
Promise objects can be returned as the return value for the above events.
Promise objects will be returned when calling the above methods, if the callback is ignored.
By utilizing the Promise objects, developer can write asynchronous processes in their code, and can call REST APIs without the need of using synchronous XMLHttpRequests.
Preparing the App
First, prepare a Kintone App where the customization for this article will be uploaded to.
This article uses the sample App "Quotes" from the Kintone Marketplace. Refer to Creating an App from the Marketplace from the Kintone Help for directions on creating Apps from the Kintone Marketplace.
After adding the Quotes App, update the "Quote #" text field of the App with the following:
- Check the "Required field" setting
- Check the "Prohibit duplicate values" setting
Save the form, and update the App when done.
Preparing the Customization
The customization in this article will generate a custom Quote number for a quote form and will confirm the Quote number in an alert dialog (shown below) before storing the value into a text field named "Quote #".
When saving a new record, the code first retrieves the Record ID of the last created record, then adds 1 to that ID if it exists. If a previous record does not exist, the Record ID is automatically assumed to be 1.
After retrieving the Record ID, a custom string is added in front of the Record ID to make a unique Quote number string, which is displayed in an alert dialog.
Finally, the string is inserted into the "Quote #" field as its value.
The REST API in this customization is called when using the Get Records API to retrieve the Record ID of the last created record.
This process can be written by using either synchronous XMLHttpRequest or Promises - this article will show how to write both examples.
The code samples also uses Moment.js. Follow the instructions in the How to use the CDN article for steps on how to include libraries for Kintone customization. Note that the Moment.js link must be set above the main sample code, as this order determines which code will run first.
Customizing using Synchronous XMLHttpRequests
The following is the customization code that is written using synchronous XMLHttpRequests:
Sample.js (XMLHttpRequest version)
Add a new record into the App to initiate the Automatic Numbering customization.
Note that the console of some browsers will show a warning stating that synchronous XMLHttpRequest has been deprecated.
Customizing using Promises
The following code uses Promises, and performs the same functions as the previous code that used synchronous XMLHttpRequests.
Sample.js (using kintone.Promise)
Notable changes are as follows:
- The code uses events that support Promises, and returns a Promise object for the return value
- The asynchronous process by kintone.api can be run because the code waits for the Promise object returned by the event handler to be resolved
- A synchronous XMLHttpRequest no longer needs to be written
The codes changed from the previous synchronous XMLHttpRequest example has been extracted below. It uses kintone.Promise to create a new Promise object instead of using synchronous XMLHttpRequests:
Although Internet Explorer does not support regular Promise objects, kintone.Promise is implemented in a way so that Internet Explorer can handle Promises in Kintone.
This sample can be re-written as follows based on the specification that it will return the Promise object if the callback of the kintone.api method is omitted:
Sample.js (omitting the callback of the kintone.api method)
Notable changes are as follows:
- The callback of the kintone.api method is omitted, resulting in a Promise object to be returned
- A Promise object no longer needs to be created using "new kintone.Promise()” every time kintone.api is used
The codes changed from the previous Promises example has been extracted below. Instead of kintone.Promise, it uses the .then function:
* Note that the default field code of the "Quote #" field of the Quotes App is "Single_line_text". If the field code is changed, the value of the variable, "QUOTE_NUMBER", in the sample code will also need to be changed.
Developers that are currently using synchronous XMLHttpRequests in their Kintone customization are advised to switch over to using promises in their code to remove the negative effects to the user experience. Kintone makes this transition smoother by supporting Promises inside Kintone events and Kintone API methods.