Overview

This article introduces the Kintone Config Helper . This tool helps developers retrieve necessary fields for building components for config pages in Kintone plug-ins.

Information Needed to Create the Plug-in Config Page

When creating plug-ins, various Kintone REST APIs need to be called in the config.js file to retrieve field information from the Kintone App. This field information is commonly used to build out drop-down lists on the plug-in config page. The below screenshot shows a drop-down list created in the plug-in config page, containing options of Date fields that exist inside the App.

This allows Kintone users to relate the settings within the plug-in with fields that exist in their Kintone App. For developers to create this list though, the "Field Type", "Field Name" and "Field Code" all need to be retrieved by multiple Kintone REST APIS. These include the usage of Get Form Fields API and the Get Form Layout API.

As an example, consider the information needed when creating a drop-down list of Date fields in the plug-in config page:

1. The Field Types of the responded fields need to be retrieved. This allows the developer to filter out the choices needed for the drop-down list.

   

2. The Field Names of the responded fields need to be retrieved. They are used as the labels of the choices in the drop-down list.

   

3. The Field Codes of the responded fields need to be retrieved. They are used as the values of the options in the drop-down list.

   

Retrieve field data without Kintone Config Helper

This section looks through how a drop-down list of Date fields is created in the Date Input Button plug-in. The code for creating the drop-down list of dates in the config.js file is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

function setDropDownForDate() {
  // Retrieve all fields from the form and extract all Date fields.
  // Create a dropdown menu containing a list of Date fields in the config.
  return kintone.api(kintone.api.url('/k/v1/preview/app/form/fields', true), 'GET',
    {'app': kintone.app.getId()}).then(function(resp) {

    for (var key in resp.properties) {
      if (!Object.prototype.hasOwnProperty.call(resp.properties, key)) {
        continue;
      }
      var prop = resp.properties[key];
      var $option = $('<option>');

      switch (prop.type) {
        // Only pick Date field
        case 'DATE':
          $option.attr('value', prop.code);
          $option.text(escapeHtml(prop.label));
          $('#select_date_field').append($option.clone());
          break;
        default:
          break;
      }
    }
    // Set default values
    $('#select_date_field').val(CONF.date);
  }, function(resp) {
    return alert('Failed to retrieve field information of the Kintone App.');
  });
}

The response data from the Get Form Fields API request includes a list of fields in the App. The list is processed in a loop, where field data with properties of field type "DATE" are extracted. The extracted list is used to create the drop-down list of Date fields. The code to process this function is long, and may not be easy for some developers to read at first glance. Also, this method cannot retrieve data of Blank space fields, as the Get Form Fields API does not include any Blank space fields in its response. The Get Form Layout API must be used in a similar way to retrieve data of Blank space fields since.

Retrieve Field Data Using Kintone Config Helper

Kintone Config Helper makes it easier to create the drop-down list of Date fields.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

KintoneConfigHelper.getFields('DATE').then(function(resp) {
  var $dateDropDown = $('#select_date_field');
  for (var i = 0; i < resp.length; i++) {
    var $option = $('<option></option>');
    $option.attr('value', resp[i].code);
    $option.text(resp[i].label);
    $dateDropDown.append($option);
  }
  if (CONF.date) {
    $dateDropDown.val(CONF.date);
  }
});

A Field Type can be stated as the parameter for KintoneConfigHelper's getFields function This returns a filtered array of field data of the specified Field Type containing the Field Name, Field Code and the Field Type. In this case, DATE was specified as the parameter. The response is a list of Date fields in the App, which is used to create the drop-down list of Date fields. The code to process this function is significantly shorter, and easier to ready. This method can also retrieve data of Blank space fields with the same method.

How to use

Download the kintone-config-helper.js code from GitHub. Refer to the following file structure, and place the kintone-config-helper.js in the plug-in directory.

Add "js/kintone-config-helper.js" to the manifest.json file, so that the library can be called in the other JavaScript files.

Reference

• README
• License