1 User Limit Plug-in

Contents

Introduction

This article introduces the 1 User Limit Plug-in, which is a plug-in version of the sample code introduced in the " Limit User Selection Fields to 1 User" article.
This plug-in limits only one user to be selected in the specified User Selection field. When a user tries to save a record with more than one person in the specified User Selection field, the error message that is written in the plug-in settings will be displayed and the record will not be saved. The plug-in settings page allows the user to choose which User Selection field will be used, as well as to write a custom error message.

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

Set your form up to support the plug-in by adding a User selection field in your App.

Relate the fields in the form with the options in the plug-in settings.
Also set an Error Message that will display, when the user tries to save 2 or more users in the User selection field.
Save the settings, and update the App.

Now, when saving a record, an error message will be displayed on the Record if there are 2 or more users selected in the specified User selection field.

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
13

plug-in/
├── html/
│       └──── config.html
├── css/
│       ├──── 51-modern-default.css
│       └──── config.css
├── js/
│       ├──── config.js
│       ├──── desktop.js
│       └──── kintone-config-helper.js
├── image/
│       └──── usericonicon.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.

Each "kintoneplugin-row" div contains HTML elements related to 1 config option.
The first "kintoneplugin-row" div contains the HTML of the first settings, where the user chooses which User selection field to limit to one user. 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

 <div class="kintoneplugin-row">
   <label class="kintoneplugin-label" for="select-user-field">
     User Selection Field
     <span class="kintoneplugin-require">*</span> </label>
   <p class="kintoneplugin-desc">Please select a user selection field</p>
   <div class="kintoneplugin-select-outer">
     <div class="kintoneplugin-select">
       <select id="select-user-field" name="js-select-user-field" required="">
         <option value="">-----</option>
       </select>
     </div>
   </div>
</div>

The second "kintoneplugin-row" div contains the HTML of the second settings, where the user inputs what text to display as an error message when a second user entry is attempted.

1
2
3
4
5
6
7
8

<div class="kintoneplugin-row">
  <label class="kintoneplugin-label" for="error-text">
    Error Message
    <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Please enter an error message</p>
  <input id="error-text" class="kintoneplugin-input-text" name="js-error-text" type="text" required>
</div>

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.
It is recommended that changes are not made to the 51-modern-default.css file. If changes such as styling additional elements, or over-riding the default styles are necessary, 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)

This file uses the kintone-config-helper library to help build out form elements for the plug-in config page.
The function setDropDown is called when the plug-in config page loads.

1

setDropDown();

This function calls the KintoneConfigHelper.getFields method from the kintone-config-helper library.
By passing 'USER_SELECT' as the parameter, an array of field information of all User Selection fields is returned.

1
2
3

return KintoneConfigHelper.getFields('USER_SELECT').then(function(resp) {
  // ...
});

The returned array is filtered out to create a list of User Selection fields, and is appended to the drop-down stored in $user.

1
2
3
4
5
6
7
8

var $user = $('select[name="js-select-user-field"]');
// ...
resp.forEach(function(field) {
  var $option = $('<option>');
  $option.attr('value', field.code);
  $option.text(escapeHtml(field.label));
  $user.append($option.clone());
});

If users have used this plug-in before, the CONF object should have some saved data stored inside. If so, the saved values are applied to the plug-in config page after the input form has been created.

1
2

$user.val(CONF.user_selection);
$error.val(CONF.error_message);

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. This file uses the sample code included in the article " Limit User Selection Fields to 1 User". The code used here is mostly the same, but it's wrapped in an immediate function with the plug-in ID value as the input parameter. 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 settings page using the setConfig API.

1

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 user_selection = CONFIG.user_selection; // Set the field code of the User Selection field
var error_message = CONFIG.error_message;

When a record submit event is triggered ( app.record.create.submit, app.record.edit.submit, or app.record.index.edit.submit), the code checks the current value of the user selection field that was specified in the plug-in settings. If the array of users has a length greater than 1, the error is displayed and the record is not saved.

kintone-config-helper.js (External link)

The kintone-config-helper.js file is a library that supports the development of the plug-in config page. View the Introduction to Kintone Config Helper article for more details.

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 and the kintone-config-helper library, so that they can be called on the plug-in config page.

1
2
3
4
5
6
7
8

"config": {
  "html": "html/config.html",
  "js": [
    "https://js.kintone.com/jquery/3.3.1/jquery.min.js",
    "js/kintone-config-helper.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": [
  "user_selection",
  "error_message"
]

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": "1 user limit plug-in"
},
"description": {
  "en": "This sample plug-in limits only one user to be selected in the specified User Selection field. When you choose 2 or more users, it displays the error message you set."
},
"homepage_url": {
  "en": "https://kintone.dev/en/plugins/simple-samples/1-user-limit-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)