Plug-in Development Specifications

Overview
Files That Can Be Packaged

Image Files
JavaScript Files
CSS Files
HTML Files
The Manifest File

Packaging Plug-in Files

Overview

"Plug-ins" are packaged JavaScript and CSS customizations for Kintone Apps.

Kintone allows users to install plug-ins to expand on functionality of Apps via JavaScript. When enhancing Apps with JavaScript, users need to update and re-upload their JavaScript files when making updates to their customization. Plug-ins however allow users to make updates to the customization via the plug-in settings page.

This article explains the specifications for plug-in development.

Files That Can Be Packaged

The following files can be included for the development of the plug-in. The * indicates the required files.

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


src
├── image 
|    └── icon.png *
├── js
|    └── customize.js
|    └── mobile-customize.js
|    └── config.js
├── css
|    └── customize.css
|    └── mobile-customize.css
|    └── config.css
├── html
|    └── config.html
└── manifest.json *

Image Files

icon.png

The icon image for the Plug-in.

This file is required.
The following file types can be set: png, jpg, gif, bmp
The maximum file size is 20MB.

JavaScript Files

customize.js

The JavaScript file that runs on desktop browsers. This is where the main Kintone customization codes are written.

The file can use data stored in the Plug-in Settings page.
The maximum file size is 20MB.

Note

kintone.plugin.app.getConfig() can be used to retrieve data stored in the Plug-in Settings page. This data needs to be initially set by the config.js file using kintone.plugin.app.setConfig().

Note

Developers are advised to write their code within the following immediately invoked function expression.

1
2
3


(function(PLUGIN_ID) {
  kintone.plugin.getConfig(PLUGIN_ID);
})(kintone.$PLUGIN_ID);

This ensures that the JavaScript code will use the settings of its related plug-in, even when there are multiple plug-ins added to the Kintone App.

mobile-customize.js

The JavaScript file that runs on mobile browsers.

This file is optional, and can be ignored.
The maximum file size is 20MB.

config.js

The JavaScript file that creates the settings page of the Plug-in.

This file is optional, and can be ignored.
The maximum file size is 20MB.

kintone.plugin.app.setConfig() is used to save variables to the plug-in.

CSS Files

customize.css

The CSS file that runs on Desktop browsers.

This file is optional, and can be ignored.
The maximum file size is 20MB.

Note

To use the Kintone design, follow the guide in the following article:
Plug-in Stylesheet Guide

mobile-customize.css

The CSS file that runs on mobile browsers.

This file is optional, and can be ignored.
The maximum file size is 20MB.

config.css

The stylesheet that runs on the settings page of the Plug-in.

This file is optional, and can be ignored.
The maximum file size is 20MB.

Note

To use the Kintone design, follow the guide in the following article:
Kintone stylesheet

HTML Files

config.html

The HTML file that displays the settings of the Plug-in, on the Plug-in Settings page.

This file is optional, and can be ignored.
The maximum file size is 64KB.

The Manifest File

The manifest file stores various parameters for the plug-in, and is a required file.

Manifest file format

The manifest file format is as below. Specify each parameter in a JSON format.

PARAMETER	TYPE	REQUIRED	DETAILS
manifest_version	Integer	Yes	The manifest version of the plug-in. Specify the integer `1`.
version	Integer or String	Yes	The plug-in version.
type	String	Yes	The type of the plug-in. Specify the string `APP`.
name	Object	Yes	An object including data of localized plug-in names. The following language codes can be specified: `en`: English `ja`: Japanese `zh`: Simplified Chinese `es`: Spanish
name.<locale>	String	Yes	The localized name of the plug-in. Must be between 1 to 64 characters. `name.en` is required.
description	String	Optional	An object including data of localized plug-in descriptions. The following language codes can be specified: `en`: English `ja`: Japanese `zh`: Simplified Chinese `es`: Spanish
description.<locale>	String	Yes	The localized description of the plug-in. Must be between 1 to 200 characters. `description.en` is required.
icon	String	Yes	The plug-in icon file. Only files within the plug-in can be specified.
homepage_url	Object	Optional	An object including data of website links for various Locales. The following language codes can be specified: `en`: English `ja`: Japanese `zh`: Simplified Chinese `es`: Spanish By settings this parameter, a navigation icon will be displayed next to the plug-in name in the plug-in list. Clicking the icon will navigate users to the specified website. The icon is only displayed if the specified locale matches the locale in the `name` parameter.
homepage_url.<locale>	String	Optional	The website link of the plug-in for the user's locale.
desktop	Object	Optional	The JavaScript and CSS files for the Desktop.
desktop.js	Array of Strings	Optional	An array of JavaScript file URLs for the Desktop. Up to 30 files can be set. If multiple files have the same name, an error will occur.
desktop.css	Array of Strings	Optional	An array of CSS file URLs for the Desktop. Up to 30 files can be set. If multiple files have the same name, an error will occur.
mobile	Object	Optional	The JavaScript and CSS files for the mobile.
mobile.js	Array of Strings	Optional	An array of JavaScript file URLs for the Mobile. Up to 30 files can be set. If multiple files have the same name, an error will occur
mobile.css	Array of Strings	Optional	An array of CSS file URLs for the Mobile. Up to 30 files can be set. If multiple files have the same name, an error will occur.
config	Object	Optional	The HTML, JavaScript and CSS files for the Plug-in Settings page.
config.html	String	Optional	The HTML file for the Plug-in Settings page. Only files within the plug-in can be specified.
config.js	Array of Strings	Optional	An array of JavaScript file URLs for the Plug-in Settings page. Up to 30 files can be set. If multiple files have the same name, an error will occur.
config.css	Array of Strings	Optional	An array of CSS file URLs for the Plug-in Settings page. Up to 30 files can be set. If multiple files have the same name, an error will occur.
config.required_params	Array of Strings	Optional	An array of key names for the required fields in the Plug-in Settings page. Must be between 1 to 64 ASCII characters.

Manifest file sample

 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


{
  "manifest_version": 1,
  "version": 1,
  "type": "APP",
  "name": {
    "en": "sample plugin",
    "ja": "サンプルプラグイン",
    "zh": "插件的例子",
    "es": "Complemento de ejemplo"
  },
  "description": {
    "en": "This is sample plugin.",
    "ja": "これはサンプルプラグインです。",
    "zh": "这是插件的例子",
    "es": "Este es un complemento de ejemplo."
  },
  "icon": "image/icon.png",
  "homepage_url": {
    "en": "https://example.com/en/",
    "ja": "https://example.com/ja/",
    "zh": "https://example.com/zh/",
    "es": "https://example.com/es/"
  },
  "desktop": {
    "js": ["js/customize.js", "https://example.com/js/customize.js"],
    "css": ["https://example.com/css/customize.css", "css/customize.css"]
  },
  "mobile": {
    "js": ["js/mobile-customize.js", "https://example.com/js/mobile-customize.js"]
  },
  "config": {
    "html": "html/config.html",
    "js": ["https://example.com/js/config.js", "js/config.js"],
    "css": ["css/config.css", "https://example.com/css/config.css"],
    "required_params": ["Param1", "Param2"]
  }
}

Packaging Plug-in Files

Once the files are ready, the Plugin-packer tool is used to package the customization. Read through the following article for steps on how to use the plug-in packer tool.
Package Plug-in Files using plugin-packer