Add Yourself Plug-in

Contents

Introduction

This article introduces the Add yourself plug-in, which is a plug-in version of the sample code introduced in the " Add Users to the User Field with One Click" article. This plug-in displays a button on the Record details page, which when clicked adds the user to the specified User Selection field. This removes the need for the user to go through the process of clicking the Edit icon, searching for their name in the User Selection field, and clicking on the Save button.

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 User Selection field and a Blank Space field in its form. The Blank Space field must have an Element ID allocated to it through the Blank Space field's settings.

There are three settings to set up on the config page of the plug-in.

For the first setting, select a Blank Space field from the drop-down list where a button will be displayed for the end user.

For the second setting, input a label of your choice that will be displayed on the button.

For the third setting, choose a User selection field where the User's name will be inserted into after clicking the button.

Save the settings and update the App. A button will be displayed on the Record details page. When the button is clicked, the name of the User who clicked the button will be added into the specified User Selection field. If there are other users already listed in the User Selection field, the User's name will be added to the end of the list.

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/
│       └──── person.png
└── manifest.json

config.html (External link)

This file builds the HTML of the plug-in config page. A form tag is used to contain the config options and the Save/Cancel buttons.

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 Blank Space field to display the button in. 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

<div class="kintoneplugin-row">
  <label for="select-space-field" class="kintoneplugin-label">
    Button Space Field
    <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Please select a Space field where the button will be placed.</p>
  <div class="kintoneplugin-select-outer">
    <div class="kintoneplugin-select">
      <select name="js-select-space-field" id="select-space-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 on the button that will be created in the config.js file.

1
2
3
4
5
6
7
8

<div class="kintoneplugin-row">
  <label for="text-button-label" class="kintoneplugin-label">
    Button Label
   <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Please input a label for the button.</p>
  <input type="text" name="js-text-button-label" class="kintoneplugin-input-text" id="text-button-label" required>
</div>

The third "kintoneplugin-row" div contains the HTML of the third settings, where the user chooses which User Selection field to add themselves to when they click the button. 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

<div class="kintoneplugin-row">
  <label for="select-user-field" class="kintoneplugin-label">
    Target User Field
    <span class="kintoneplugin-require">*</span>
  </label>
  <p class="kintoneplugin-desc">Please select a User Selection field where the user will be added into.</p>
  <div class="kintoneplugin-select-outer">
    <div class="kintoneplugin-select">
      <select name="js-select-user-field" id="select-user-field" required>
        <option value="">-----</option>
      </select>
    </div>
  </div>
</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.
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)

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' and 'SPACER' as the parameters, an array of field information of all User Selection fields and all Blank Space fields are returned.

1
2
3

return KintoneConfigHelper.getFields(['USER_SELECT', 'SPACER']).then(function(resp) {
  // ...
});

The returned array is filtered out to create lists of User Selection fields and Blank Space fields, and are appended to the drop-down stored in $space and $user respectively.

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

var $userDropDown = $user;
var $spaceDropDown = $space;
resp.forEach(function(respField) {
  var $option = $('<option></option>');
  switch (respField.type) {
    case 'USER_SELECT':
      $option.attr('value', respField.code);
      $option.text(respField.label);
      $userDropDown.append($option.clone());
      break;
    case 'SPACER':
      if (!respField.elementId) {
        break;
      }
      $option.attr('value', respField.elementId);
      $option.text(respField.elementId);
      $spaceDropDown.append($option.clone());
      break;
    default:
      break;
  }
});

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
3
4
5
6
7

// Set default values
if (CONF.user) {
  $userDropDown.val(CONF.user);
}
if (CONF.space) {
  $spaceDropDown.val(CONF.space);
}

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 " Add Users to the User Field with One Click" article. The code used in this plug-in 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 config 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
3

var CONFIG_SPACE = CONFIG.space;
var CONFIG_LABEL = CONFIG.label;
var CONFIG_USER = CONFIG.user;

When the app.record.detail.show event is triggered (when the Record Details page loads), the kintone.app.record.getSpaceElement() method is used to get the element of the Blank Space field that was specified in the Plug-in config page. A button is created, and appended onto this element. The Label settings obtained earlier are also applied to the button.

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

kintone.events.on('app.record.detail.show', function(event) {
  member = event.record[CONFIG_USER].value;

  // Get the element of the Blank space field
  var se = kintone.app.record.getSpaceElement(CONFIG_SPACE);

  // Create a button
  var btn = document.createElement('button');
  btn.appendChild(document.createTextNode(' ' + CONFIG_LABEL + ' '));
  btn.id = 'btnAddMine';
  btn.name = 'btnAddMine';
  se.appendChild(btn);
  btn.style.marginTop = '30px';
  btn.addEventListener('click', addMemberMine);
});

When the button is clicked, it calls the addMemberMine function.

This process starts off by inserting the logged in user's information (i.e. the user who clicked the button) into the variable loginuser using the kintone.getLoginUser method.
An object objParam is created, so that it can be later used as the parameter for the Update Record REST API. This object is initially allocated with the App ID and Record ID of the record where the code is run.

The objParam object runs through a loop to be populated with user information that already exists inside the User Selection field. After the loop, the user information of the logged in user is also added to the objParam object. If this process is not carried out, and the field is updated with a single user such as "User A", then all existing user information in that User Selection field will be deleted, and replaced by "User A".

The objParam object is then finally used as the parameter for the Update Record REST API call. The page is refreshed after the call, so that the result of the call can be seen on the User Selection field.

 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

function addMemberMine() {
  var loginuser = kintone.getLoginUser();

  var objParam = {};
  objParam.app = kintone.app.getId(); // The App ID
  objParam.id = kintone.app.record.getId(); // The Record ID
  objParam.record = {};
  objParam.record[CONFIG_USER] = {};
  objParam.record[CONFIG_USER].value = [];

  // If there are other users in the User Selection field, also add those users
  for (var i = 0; i < member.length; i++) {
    objParam.record[CONFIG_USER].value[i] = {};
    objParam.record[CONFIG_USER].value[i].code = {};
    objParam.record[CONFIG_USER].value[i].code = member[i].code;
  }

  // Add the logged-in user
  objParam.record[CONFIG_USER].value[member.length] = {};
  objParam.record[CONFIG_USER].value[member.length].code = {};
  objParam.record[CONFIG_USER].value[member.length].code = loginuser.code;

  // Refresh the page
  kintone.api('/k/v1/record', 'PUT', objParam, function(resp) {
    // Refresh the page on success
    location.reload(true);
  });
}

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 it 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/config.js",
    "js/kintone-config-helper.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
5

"required_params": [
  "space",
  "label",
  "user"
]

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

1
2
3
4
5
6
7
8
9

"name": {
  "en": "Add Yourself Plug-in"
},
"description": {
  "en": "This sample plug-in adds yourself to a User Selection field with the click of a button in the record details page."
},
"homepage_url": {
  "en": "https://kintone.dev/en/plugins/simple-samples/add-yourself-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)