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 "
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
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.
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
.
The plug-in is created with the following file structure:
|
|
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.
|
|
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.
|
|
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.
This supporting CSS file is used to style some areas of the plug-in config page that 51-modern-default.css doesn't cover.
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.
|
|
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.
|
|
The returned array is filtered out to create a list of User Selection fields, and is appended to the drop-down stored in $user.
|
|
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.
|
|
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 .
|
|
Data retrieved with the kintone.plugin.app.getConfig(PLUGIN_ID) method are allocated to variables.
|
|
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.
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.
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.
|
|
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.
|
|
The name, description, and homepage_url key-value pairs are labels and links displayed in the plug-in settings.
|
|
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 Program Community Forum
.
Contribution
This sample plug-in was created with the contribution of
Fuji Business International
Mamoru Fujinoki - LinkedIn