Profile Tooltip Plug-in

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.

tooltipexample.PNG

This plug-in uses Tippy.js, 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 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. 

Profile_tooltip_Plug-in_form.png

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.


Profile_tooltip_Plug-in_setting.png

 

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.


Profile_tooltip_plug-in.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
│            └──── desktop.css
├── js/
│            ├──── config.js
│            └──── desktop.js
│            └──── kintone-config-helper.js
├── image/
│            └──── comment.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.

04tool.png

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.

<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

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

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

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

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

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

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.

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

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

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.

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.

// 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 function from the Tippy.js library to create the tooltips.

// 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(reference) { return htmlContainer[reference.getAttribute('data-template')]; } }); }, function(error) { // error console.log(error); });

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.

For the desktop pages, the Tippy.js library, desktop.js and desktop.css files are specified.

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

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


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

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

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.

 

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!