Introduction to Kintone Config Helper

Contents

Overview

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

What is Kintone Config Helper

Kintone Config Helper is a library that helps build the Plug-in Config pages, by retrieving fields and layout information from Kintone Apps. With Kintone Config Helper, users can retrieve field information and layout information that matches the specified field type in one step.

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

To do this, the "Field Type", "Field Name" and "Field Code" all need to be retrieved by calling multiple Kintone REST APIs. These include the usage of Get Form Fields API and the Get Form Layout API. Kintone Config Helper simplifies this process, by retriving all of these information with one call.

GitHub

https://github.com/kintone-labs/config-helper/ (External link)

License

MIT License (External link)

Documentation

https://github.com/kintone-labs/config-helper/blob/master/README.md (External link)

Quickstart

Step 1: Create the App

Add 3 Date fields to the form. Then update the field title for each field in the form to "Start Date", "Reminder Date", and "End Date". Save the form when finished.

Step 2: Create the plug-in

Follow the steps listed in the Create Plug-in Templates using create-plugin article to install create-plugin and create a plug-in template using the command below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
$ create-kintone-plugin KintoneConfigHelper
  
Please answer some questions to create your Kintone plug-in project :)
Let's start!
  
? Input your plug-in name in English [1-64chars] KintoneConfigHelper
? Input your plug-in description in English [1-200chars] KintoneConfigHelper
? Does your plug-in support Japanese? No
? Does your plug-in support Chinese? No
? Input your home page url for English (Optional) 
? Does your plug-in support mobile views? No
? Would you like to use @kintone/plugin-uploader? Yes

Step 3: Set up the customization

Edit the HTML and JavaScript files inside the KintoneConfigHelper directory as shown below:

  1. src/js/config.js

     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
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    
     (async (PLUGIN_ID) => {
       'use strict';
       const buildDropDownForDate = async () => {
         const dropdown = document.createElement('select');
         dropdown.id = 'message';
         // retrieve all date fields from the form using kintone-config-helper
         const dateFields = await KintoneConfigHelper.getFields('DATE');
         dateFields.forEach((dataField) => {
           const option = document.createElement('option');
           option.value = dataField.code;
           option.textContent = dataField.label;
           dropdown.appendChild(option);
         });
         return dropdown;
       };
       try {
         const form = document.getElementById('js-submit-setting');
         const cancelButton = document.getElementById('js-cancel-button');
         const fields = document.getElementById('js-select-fields');
         // create a dropdown menu containing a list of Date fields
         const dropdown = await buildDropDownForDate();
         fields.appendChild(dropdown);
         const config = kintone.plugin.app.getConfig(PLUGIN_ID);
         if (config.message) {
           dropdown.value = config.message;
         }
         form.addEventListener('submit', (e) => {
           e.preventDefault();
           kintone.plugin.app.setConfig({message: dropdown.value}, () => {
             window.alert(
               'Plugin Setting changes are saved. To apply setting changes to the app, update the app.'
             );
             window.location.href = `/k/admin/app/${kintone.app.getId()}/plugin/`;
           });
         });
         cancelButton.addEventListener('click', () => {
           window.location.href = `/k/admin/app/${kintone.app.getId()}/plugin/`;
         });
       } catch (err) {
         window.alert(err);
       }
     })(kintone.$PLUGIN_ID);
  2. src/html/config.html

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    
     <section class="settings">
       <h2 class="settings-heading">kintone-config-helper sample</h2>
       <p class="kintoneplugin-desc">kintone-config-helper is a library that helps retrieving necessary fields from a Kintone App.</p>
       <form id="js-submit-setting">
         <div class="kintoneplugin-row">
           <label for="fields" class="kintoneplugin-title" style="display: block;">Date Field</label>
           <div class="kintoneplugin-select-outer">
             <div id="js-select-fields" class="kintoneplugin-select"></div>
           </div>
         </div>
         <div class="kintoneplugin-row">
           <button type="button" id="js-cancel-button" class="kintoneplugin-button-dialog-cancel">Cancel</button>
           <button class="kintoneplugin-button-dialog-ok">Save</button>
         </div>
       </form>
     </section>

Step 4: Download the JavaScript file

Download the kintone-config-helper.js (External link) code from GitHub.

Refer to the following file structure, and place the kintone-config-helper.js in the js directory.

Step 5: Set up the manifest.json

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

1
2
3
4
5
6
"config": {
  "html": "html/config.html",
  "js": [
    "js/kintone-config-helper.js",
    "js/config.js"
  ],

Step 6: Package the plugin

Package the plug-in using the command below.

1
2
$ cd KintoneConfigHelper
$ kintone-plugin-packer src

For more information, refer to the Package Plug-in Files using plugin-packer article.

Step 7: Upload the plug-in

Upload the plug-in to the Kintone App by following the steps listed in the help articles below:

  1. Adding/Deleting Plug-Ins (Kintone Administration) (External link)
  2. Adding/Deleting Plug-Ins (App Settings) (External link)

Step 8: Test the App

  1. Navigate to the App Settings, and click Plug-ins to open the plug-in settings.
  2. Click the setting icon.

  3. In the dropdown menu, "Start Date", "Reminder Date", and "End Date" are displayed.

tips
Note

The contents of this article were checked with the Feb 2024 version of Kintone.