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

Profile_tooltip_Plug-in_setting2.png

The first "block" contains the HTML of the first settings, 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.

<div class="block">
<label class="kintoneplugin-label">
<span id ="container_label">Tooltip Display Area</span>
<span class="kintoneplugin-require">*</span>
</label>
<div class="kintoneplugin-row">Select a User Selection field to display tooltips on.</div>
<div class="kintoneplugin-select-outer">
<div class="kintoneplugin-select">
<select id="select_name_field" name="select_name_field">
<option value="">-----</option>
</select>
</div>
</div>
</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.
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.


The function setDropDown is called when the plug-in config page loads.

// Set drop-down list
setDropDown();

This function is called to create a list of User selection fields, that are added into the drop-down of the setting in the config page. 

 function setDropDown() {
// Retrieve field information, then set drop-down
return kintone.api(kintone.api.url('/k/v1/preview/app/form/fields', true), 'GET',
{'app': kintone.app.getId()}).then(function(resp) {

....

....

....

}, function(resp) {
return alert('Failed to retrieve field(s) information');
});
}

The function calls the Get Form Fields REST API endpoint, which returns an object that contains the form fields of the App. Fields with type value of USER_SELECT (the User selection field) are extracted from the returned object and are then appended to the element with the ids of select_name_field to make a drop-down list of User selection fields in the App.

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);
});

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, the jQuery library hosted on the Kintone CDN and config.js are specified

"config": {
"html": "html/config.html",
"js": [
"https://js.kintone.com/jquery/3.3.1/jquery.min.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!