Default Choice Restriction Plug-in

Contents

Introduction

This article introduces the Default Choice Restriction Plug-in.
This plug-in restricts the user from choosing the default value of a Radio button field.

Plug-in file

The packaged sample plug-in zip file can be downloaded from the Releases page (External link) on GitHub.
Install the plug-in into your domain by following the plug-in installation guide on the Help page (External link) .
You can then add the plug-in to a specific App by following the plug-in adding guide on the Help page. (External link) .

Overview

To set up the plug-in, the Kintone App must have a Radio button field in its form.

There is only one setting for this plug-in, which is to choose which field in the App form will be restricted from having its default value selected. This sample lets users to only select the Radio button field from the drop-down list.

After saving the plug-in settings and updating the App, the plug-in's features will run when a record is saved. If the user has left the specified Radio Button value as its default value, errors will be displayed on both below the field and at the top of the record. The record will also not be saved until the issue is solved.

File structure

The sample codes used in the plug-in are listed under the src file in our GitHub repository (External link) .
The plug-in is created with the following file structure:

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

plug-in/
├── html/
│       └──── config.html
├── css/
│       ├──── 51-modern-default.css
│       └──── config.css
├── js/
│       ├──── config.js
│       └──── desktop.js
├── image/
│       └──── clock.png
└── manifest.json

config.html (External link)

This file builds the HTML of the plug-in settings page.
Each <div> tag with the "block" class represents 1 row of related HTML elements.

The first "block" contains the HTML of the first (and only) setting, where the user chooses which Radio Button to place restrictions on. A select tag is stated in the HTML, that creates a drop-down field with a value of "-----". This drop-down field is later populated by the config.js file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<section>
  <form class="js-submit-settings">
    <div class="kintoneplugin-row">
      <label class="kintoneplugin-label" for="select-radio-button-field">
        Field to restrict
        <span class="kintoneplugin-require">*</span>
      </label>
      <p class="kintoneplugin-desc">Please select a Radio Button field that will be restricted from having its initial value being selected.</p>
      <div class="kintoneplugin-select-outer">
        <div class="kintoneplugin-select">
          <select id="select-radio-button-field" name="js-select-radio-button-field" required>
            <option value="">-----</option>
          </select>
        </div>
      </div>
    </div>
    <p class="kintoneplugin-row">
      <button class="js-cancel-button kintoneplugin-button-dialog-cancel" type="button"> Cancel </button>
      <button class="kintoneplugin-button-dialog-ok"> Save </button>
    </p>
  </form>
</section>

The drop-down fields have ids allocated to them, which are later specified by the config.js file so that they can be populated with other drop-down choices.

51-modern-default.css (External link)

This CSS file is provided on GitHub (External link) . This file styles HTML elements on the plug-in config page to fit in with Kintone's UI.
We recommend that you do not make changes to 51-modern-default.css. If you need to style additional elements, or over-ride the default styles, those changes should be added into config.css

config.css (External link)

This supporting CSS file is used to style some areas of the plug-in config page that 51-modern-default.css doesn't cover.

config.js (External link)

The function setDropDown is called when the plug-in setting page loads. It uses the kintone.api() wrapper from the JavaScript API to call the REST API endpoint Get Form Fields. Get Form Fields returns an object that contains the form fields for the specified App.
Depending on the endpoint called, Get Form Fields can return either the deployed form fields (the user has clicked Update App in the App Settings and the changes have been committed) or the preview form fields (the form has been saved in the App settings, but the user has not clicked Update App and committed them). This function uses the preview endpoint as users may access the plug-in settings page before they are ready to commit their changes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

function setDropDown() {
  // Retrieve field information, then set dropdown
  return kintone.api(kintone.api.url('/k/v1/preview/app/form/fields.json', true), 'GET', {'app': kintone.app.getId()}).then(function(resp) {
    // ...
    // run rest of code here after retrieving preview form information from the App
    // resp contains the response data
    // ...
  }, function(resp) {
    return alert('Failed to retrieve field(s) information');
  });
}

As this plug-in needs to use the Radio Button fields to populate the drop-down fields in the plug-in settings, the fields with type value of RADIO_BUTTON (the Radio Button field) are extracted from the returned object. The extracted selections are then appended to the element with the id of select_radio_button_field to create a drop-down list of Radio Button fields in the App.
The default value of the Radio Button fields are also extracted by identifying the value held in the defaultValue property of the fields.

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

var keys = Object.keys(resp.properties);
keys.forEach(function(key) {
  var prop = resp.properties[key];
  var $option = $('');
  switch (prop.type) {
    case 'RADIO_BUTTON':
      $option.attr('value', prop.code);
      $option.text(escapeHtml(prop.label));
      $radioBtn.append($option.clone());
      DEFAULT[prop.code] = prop.defaultValue;
      break;
    default:
      break;
  }
});

At the end of the setDropDown function, the code looks through the CONF object where any saved setting data are stored. If it's the first time for the user to use the plug-in, there are no saved values, thus no values are placed in the settings of the plug-in settings page. If the user has previously saved any settings before in the plug-in (which are stored using Kintone's setConfig API), then those saved values (the specified Radio Button field) are inserted into the designated plug-in configuration settings.

1
2

// Set default values
$radioBtn.val(CONF.radio_button);

When the Save button is clicked in the plug-in config page, the selected Radio Button value and the default value of that Radio Button are stored into Kintone using the setConfig API.

1
2
3
4
5
6

config.radio_button = radio_button;
config.default_value = DEFAULT[radio_button];
kintone.plugin.app.setConfig(config, function() {
  alert('The plug-in settings have been saved. Please update the app!');
  window.location.href = '/k/admin/app/flow?app=' + kintone.app.getId();
});

desktop.js (External link)

This file runs on the regular pages of the App, such as the Record List and Record Details pages, but not on the plug-in config page. The plug-in ID value is needed for several JavaScript API calls, such as Kintone's getConfig API that retrieves data that was saved in the plug-in config page using the setConfig API.

1
2

// Get plug-in configuration settings
var CONFIG = kintone.plugin.app.getConfig(PLUGIN_ID);

Data retrieved with the kintone.plugin.app.getConfig(PLUGIN_ID) method are allocated to variables.

1
2

var RADIOBUTTON = CONFIG.radio_button;
var RADIO_VALUE = CONFIG.default_value;

These variables are used when the user clicks on the Save button of the record, which triggers the app.record.create.submit or app.record.edit.submit or app.record.index.edit.submit event.
The code checks the current selected value of the specified Radio Button field, and sees if it matches the value stored in the RADIO_VALUE variable (the default value of the specified Radio Button field). If it does, strings that contain error messages are inserted into the error property of the specified Radio Button field and the error property of the event object. As the error properties where updated in the event object, returning the event object results in cancelling the saving of the record, and displays error messages both underneath the field and at the top of the record.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

var ev = ['app.record.create.submit', 'app.record.index.edit.submit', 'app.record.edit.submit'];
kintone.events.on(ev, function(event) {
  // Get record data
  var record = event.record;
  var selection = record[RADIOBUTTON].value;
  var params = {
    app: kintone.app.getId()
  };
  return kintone.api('/k/v1/app/form/fields', 'GET', params).then(function(resp) {
    // Obtain label name of Radio Button field
    var name = resp.properties[RADIOBUTTON].label;
    if (selection === RADIO_VALUE) {
      var errMessage = 'Please select other than "' + selection + '"';
      // Show message underneath field
      record[RADIOBUTTON].error = errMessage;
      // Show message at top of record
      event.error = errMessage + ' for the field "' + name + '"';
    }
    return event;
  });
});

manifest.json (External link)

The manifest file states the paths of the files that will be used in the plug-in. It also links to the jQuery library hosted on the Kintone CDN, so that it can be called on the config page.

1
2
3
4
5
6
7

"config": {
  "html": "html/config.html",
  "js": [
    "https://js.kintone.com/jquery/3.3.1/jquery.min.js",
    "js/config.js"
  ]
}

The array in the value of the required_params key states which settings in the plug-in config page are required. If these settings are not saved using the setConfig API, errors will be displayed on other pages of the App, stating that the plug-in settings have not been configured yet.

1
2
3
4

"required_params": [
  "radio_button",
  "default_value"
]

The name, description, and homepage_url key-value pairs are labels and links displayed in the plug-in settings.

1
2
3
4
5
6
7
8
9

"name": {
  "en": "Default Choice Restriction Plug-in"
},
"description": {
  "en": "This sample plug-in prevents the user from choosing the default value in the Radio Button field, and displays an error message on the record."
},
"homepage_url": {
  "en": "https://kintone.dev/en/plugins/simple-samples/default-choice-restriction-plug-in/"
}

Finally

Licenses

This plug-in is open sourced under the MIT License (External link) . It allows open- or closed-sourced distribution, including commercial use.
If you would like to add more functionality to the plug-in, you are welcome to clone our repository to make your own changes and redistribute it. We generally do not accept external pull requests for the sample plug-in as this repository exists for educational purposes.
If you have any questions related to building Kintone plug-ins, please post your question in the Kintone Developer Program Community Forum (External link) .

Contribution

This sample plug-in was created with the contribution of Fuji Business International (External link)
Mamoru Fujinoki - LinkedIn (External link)