Profile Tooltip Plug-in

Contents

Introduction

This article introduces the Profile Tooltip Plug-in.
The Profile Tooltip plug-in displays a tooltip when the user hovers over the User selection field.
This tooltip includes some information of the user that are recorded in their user profile page.

Image of this plugin

This plug-in uses Tippy.js (External link), a highly customizable tooltip, to create and display tooltips.

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.

Overview

There is only one setting on the config page.
For this setting, select a User selection field from the drop-down list where you want the tooltip to be displayed.

Config page screenshot

Save the settings, and update the App.
When you hover over users listed in the specified User selection field on the Record Details page, a tooltip will be shown containing their Email, phone numbers and timezone.

Image of this plugin

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 settings page.
Each <div> tag with the “block” class represents 1 row of related HTML elements.

Related HTML elements

The first “block” contains the HTML of the first (an only) setting, where the user chooses which User selection field where the tooltip feature will be applied to. 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-name-field">
        Tooltip Display Area
        <span class="kintoneplugin-require">*</span>
      </label>
      <p class="kintoneplugin-desc">Select a User Selection field to display tooltips on.</p>
      <div class="kintoneplugin-select-outer">
        <div class="kintoneplugin-select">
          <select id="select-name-field" name="js-select-name-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>

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 JavaScript file runs on the plug-in config page. This file uses the kintone-config-helper library to help build out form elements for the plug-in settings.
The function setDropDown is called when the plug-in config page loads.

1
2
// Set drop-down list
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 are returned.

1
2
3
4
5
6
7
8
9
function setDropDown() {
  // Retrieve field information, then set drop-down
  KintoneConfigHelper.getFields('USER_SELECT').then(function(resp) {
    // ....

  }).catch(function(resp) {
    alert('Failed to retrieve field(s) information');
  });
}

desktop.css (External link)

This file styles the regular pages of the App such as the record list page and the record details page.
For this plug-in, this file adds style to the tooltips that are displayed when the user hovers over user names in the User selection field.

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 getConfig API is first called to store data that was saved in the plug-in config page to a variable.

1
2
3
4
5
6
7
// Get plug-in configuration settings
var CONFIG = kintone.plugin.app.getConfig(PLUGIN_ID);
if (!CONFIG) {
  return false;
}
// Get each setting
var CONFIG_NAME = CONFIG.name;

An object is then created containing the titles of the tooltip contents. The keys in this object relate to the response parameter properties of the Get Users API that is later called in the code.

1
2
3
4
5
6
7
// Keys and titles of user data to display
var INFOLIST = [
  {key: 'email', title: 'Email'},
  {key: 'phone', title: 'Phone'},
  {key: 'mobilePhone', title: 'Mobile Phone'},
  {key: 'timezone', title: 'Time Zone'}
];

The rest of the code runs when the app.record.detail.show event (when the Record Details page loads) is triggered.

1
2
3
kintone.events.on('app.record.detail.show', function(event) {
  // ...
});

The current value of the User selection Field (specified in the config page) is placed into a variable. As User selection Fields can hold information of multiple users, User selection Field values are arrays by default. If the length of this array is 0 (i.e. no user information is saved in this User selection Field), no further codes are executed.

1
2
3
4
5
var record = event.record;
var userFieldVal = record[CONFIG_NAME].value;
if (userFieldVal.length === 0) {
  return event;
}

The kintone.app.record.getFieldElement method is called to retrieve the field element of the User selection field. In this plug-in, we want to be able to hover over each user name to produce separate tooltips, rather than hovering over any part of the User selection Field to display all tooltips. To do this, we need to dig a little deeper in the DOM - the targetLink variable stores a list of element nodes for each user within the User selection Field.

1
2
3
// Get the element of the specified User Selection field
var targetField = kintone.app.record.getFieldElement(CONFIG_NAME);
var targetLink = targetField.querySelectorAll('a');

The variable fieldValCodeList then stores an array of User codes (the log in names) of the users in the User selection field. The User codes are used for the parameters of the Get Users API to get a list of User related data. The obtained data is sorted, and used together with the tippy (External link) function from the Tippy.js (External link) library to create the tooltips.

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// Get the code (login name) from the user data
var fieldValCodeList = userFieldVal.map(function(value) {
  return value.code;
});

var body = {'codes': fieldValCodeList};
kintone.api(kintone.api.url('/v1/users', true), 'GET', body, function(resp) {
  var respUserData = resp.users;

  function createTableTag(userData) {
    var table = '<table class="Tooltip-table">';
    INFOLIST.forEach(function(userInfoType) {
      table += '<tr>'
      + ' <td>' + userInfoType.title + '</td>'
      + ' <td>: ' + userData[userInfoType.key] + '</td>'
      + '</tr>';
    });
    table += '</table>';
    return table;
  }

  // Sort the retrieved user data in order of how they are listed in the User Selection field
  respUserData.sort(function(x, y) {
    return fieldValCodeList.indexOf(x.code) - fieldValCodeList.indexOf(y.code);
  });
  // Create the HTML to display in the tooltip
  var htmlContainer = respUserData.map(function(value, index) {
    // Add an identifier to each node
    targetLink[index].setAttribute('data-template', index);
    return createTableTag(value);
  });
  tippy(targetLink, {
    arrow: true,
    arrowType: 'round',
    animation: 'scale',
    interactive: true,
    placement: 'right',
    content: function(reference) {
      return htmlContainer[reference.getAttribute('data-template')];
    }
  });
}, function(error) {
  // error
  console.log(error);
});

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.
For the desktop pages, the Tippy.js (External link) library, desktop.js and desktop.css files are specified.

1
2
3
4
5
6
7
8
9
"desktop": {
  "js": [
    "https://unpkg.com/tippy.js@3/dist/tippy.all.min.js",
    "js/desktop.js"
  ]
  "css": [
    "css/desktop.css"
  ]
}

For the config pages, it links to the jQuery library hosted on the Kintone CDN and the kintone-config-helper library.

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
"required_params": [
  "name"
]

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": "Profile Tooltip Plug-in"
},
"description": {
  "en": "This plug-in displays tooltips next to users listed in the User Selection field when they are hovered over with a mouse."
},
"homepage_url": {
  "en": "https://kintone.dev/en/plugins/simple-samples/profile-tooltip-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).