1 User Limit Plug-in

Introduction

This article introduces the 1 User Limit Plug-in, which is a plug-in version of the sample code introduced in the "Allow only 1 user for User Selection fields" 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 on GitHub.
Install the plug-in into your domain by following the plug-in installation guide on the Help page.
You can then add the plug-in to a specific App by following the plug-in adding guide on the Help page.

Overview

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

Image_36.png

 

 

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.

Image_37.png

 

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.

US_1.gif

File structure

The sample codes used in the plug-in are listed under the src file in our GitHub repository.

The plug-in is created with the following file structure:

 

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

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.

01user.png


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.

 <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.

<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

This CSS file is provided on GitHub. 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

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

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.

 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.

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.

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.

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

desktop.js

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 "Allow only 1 user for User Selection fields". 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.

var CONFIG = kintone.plugin.app.getConfig(PLUGIN_ID);

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

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

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

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.

"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. 

"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.

"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://developer.kintone.io/hc/en-us/articles/360010088694"
}

Finally

Licenses

This plug-in is open sourced under the MIT License. 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 network community.

Contribution

This sample plug-in was created with the contribution of Fuji Business International
https://www.linkedin.com/in/mfujinoki/

Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!