Steps for Plugin Development

Overview

Read through Plugin Development Environment before starting to develop your own kintone plugin.
Below are the 4 steps to develop your plugin.

1. Create files for the kintone plugin customization.
2. Create a manifest file.
3. Package your files using a packaging tool https://github.com/kintone/plugin-sdk/blob/master/package.sh
4. Import the plugin into your kintone environment.

Creating each file

First, you'll need to get the files ready to be packaged.

  css/
  - customize.css //Stylesheet for desktop view
  - config.css //Stylesheet for Plugin Settings
  
  html/
  - config.html //HTML for Plugin Settings
  
  image/
  - icon.png //Plugin Icon
  
  js/
  - customize.js //App customization for Desktop
  - mobile-customize.js //App customization for Desktop
  - config.js //JavaScript initiated on Plugin Settings

Plugin Icon icon.png

The icon image for the Plugin

  • This file is optional
  • Use the following file types: png、jpg、gif or bmp
  • The maximum file size is 512KB

App customization for Desktop customize.js

The JavaScript file that is initiated on Desktop browsers.
This is where the main kintone customization codes will be written.
If you're planning on making a mobile-only plugin, you can skip this file.
The file can pull information from the Plugin Settings page.
The maximum file size is 512KB.
kintone.plugin.app.getConfig() can be used to pull information from the Plugin Settings page. These information though need to be initially set by the config.js file using kintone.plugin.app.setConfig(). The variable kintone.$PLUGIN_ID will hold the Plugin ID which will be needed.
*The Plugin ID is an ID with 32 characters e.g. qrhfefwgeehqkanwmjwmhbgecsfgalbf

Sample code for retrieving the Plugin ID

Apps can have hold multiple plugins. In this case, variables may set into the kintone.$PLUGIN_ID more than twice. For this reason, use the code below to hold the plugin ID variable.

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

Stylesheet for desktop view customize.css

The CSS file that is initiated on Desktop browsers.
You can follow the kintone stylesheet if you want to use the kintone design.
The maximum file size is 512KB.

App customization for Desktop mobile-customize.js

The JavaScript file initiated on the mobile.
This is optional, and can be left out if you will be using the plugin on only desktop browsers. kintone.plugin.app.getConfig() can be used to pull information from the Plugin Settings page. These information though need to be initially set by the config.js file using kintone.plugin.app.setConfig(). Follow the Sample code for retrieving the Plugin ID.
The maximum file size is 512KB.

HTML for Plugin Settings config.html

The HTML file that is used to display the settings page of the Plugin.
This is optional, and can be ignored.
The maximum file size is 64KB.

JavaScript initiated on Plugin Settings config.js

The JavaScript file that is initiated on the settings page of the Plugin.
This is optional, and can be ignored.
Follow the Sample code for retrieving the Plugin ID.
The maximum file size is 512KB.
kintone.plugin.app.setConfig() is used to save variables to the Plugin.

Stylesheet for Plugin Settings config.css

The stylesheet initiated on the settings page of the Plugin
This is optional, and can be ignored.
You can follow the kintone stylesheet if you want to use the kintone design.
The maximum file size is 512KB.

The Manifest file

You'll need a manifest file to create your plugin.

Manifest file format

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

PARAMETER TYPE REQUIRED DETAILS SAMPLE
manifest_version Number Yes The manifest version of the Plugin
"manifest_version": 1
version Number Yes The Plugin version
"version": 1
type String Yes The type of the Plugin.
Specify the string "APP".
"type":"APP"
name Object.<String> Yes Contains a list of localized Plugin names, that will be displayed in the user's locale (en, ja, zh).
"name": { 
     "en": "sample plugin",
     "ja": "サンプルプラグイン",
     "zh": "插件的例子"
    }
name.<locale> String Yes The localized name of the plugin.
Must be between 1 to 64 characters.
name.en is required.
description Object.<String> Optional Contains a list of localized Plugin descriptions, that will be displayed in the user's locale (en, ja, zh).
"description": { 
     "en": "This is sample plugin.",
     "ja": "これはサンプルプラグインです。",
     "zh": "这是插件的例子"
    }
description.<locale> String Yes The localized description of the plugin.
Must be between 1 to 200 characters.
description.en is Required.
icon String Yes The Plugin icon file
Only files within the plugin can be specified.
"icon": "image/sample.png"
homepage_url Object.<String> Optional Contains a list of different Website URLs, that will be displayed in the user's locale (en, ja, zh).
"homepage_url": { 
     "en": "http://plugin_description.com",
     "ja": "http://plugin_description.jp",
     "zh": "http://plugin_description.cn"
    }
homepage_url.<locale> String Optional The Website of the plugin for the user's locale.
desktop Object.<String> Optional The JavaScript and CSS files for the Desktop
"desktop": {
     "js": [
     "js/customize.js",
     "https://example.com/js/customize.js"
     ],
     "css": [
     "https://example.com/css/customize.css",
     "css/customize.css"
     ]
    }
desktop.js Array.<String> Optional An array of JavaScript file URLs for the Desktop
Upto 30 files can be set.
If multiple files have the same name, an error will occur
desktop.css Array.<String> Optional An array of CSS file URLs for the Desktop.
Upto 30 files can be set.
If multiple files have the same name, an error will occur
mobile Object.<String> Optional The JavaScript and CSS files for the mobile
"mobile": {
     "js": [
     "js/mobile-customize.js",
     "https://example.com/js/mobile-customize.js"
     ]
    }
mobile.js Array.<String> Optional An array of JavaScript file URLs for the Mobile.
Upto 30 files can be set.
If multiple files have the same name, an error will occur
config Object.<String> Optional The html, js and css files for the Plugin Settings page.
"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"]
    }
   }
config.html String Optional The HTML file for the Plugin Settings page.
Only files within the plugin can be specified.
config.js Array.<String> Optional An array of JavaScript file URLs for the Plugin Settings page.
Upto 30 files can be set.
If multiple files have the same name, an error will occur
config.css Array.<String> Optional An array of CSS file URLs for the Plugin Settings page.
Upto 30 files can be set.
If multiple files have the same name, an error will occur
config.required_params Array.<String> Optional An array of parameters that are requried to be filled in in the Plugin Settings page.
Must be between 1 to 64 ASCII characters.

Sample Manifest file

{
  "manifest_version": 1,
  "version": 1,
  "type": "APP",
  "name": { 
 "en": "sample plugin",
    "ja": "サンプルプラグイン",
    "zh": "插件的例子"
  },
  "description": { 
 "en": "This is sample plugin.",
    "ja": "これはサンプルプラグインです。",
    "zh": "这是插件的例子"
  },
  "icon": "image/icon.png",
  "homepage_url": { 
 "en": "http://plugin_description.com",
    "ja": "http://plugin_description.jp",
    "zh": "http://plugin_description.cn"
  },
  "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

Layout the created files and the manifest files so that it can be packaged.

Sample layout

  css/
  - customize.css //Stylesheet for desktop view
  - config.css //Stylesheet for Plugin Settings

  html/
  - config.html //HTML for Plugin Settings
  
  image/
  - icon.png //Plugin Icon
  
  js/
  - customize.js //App customization for Desktop
  - mobile-customize.js //App customization for Desktop
  - config.js //JavaScript initiated on Plugin Settings

Next, the packaging tool https://github.com/kintone/plugin-sdk/blob/master/package.sh will be used with the below steps.

Place the packaging tool in your directory

Example:

  /work/

Move to the directory

Example:

  $cd /work/

Run the Packaging tool

Run the packaging tool, and specify the folder with the manifest file as the argument.

Example:

  $package.sh /mysftuff/manifest.json

If succeeded, the below folder and files will be created under the folder it was run in.

Example:

  keys/
  - check_plugin.qrhfefwgeehqkanwmjwmhbgecsfgalbf.ppk //Secret key file
  
  plugins/
    /qrhfefwgeehqkanwmjwmhbgecsfgalbf
    - plugin.zip //Packaged file

Make sure to keep the secret key file. This will be used when you're packinging a second time.

Repackaging

If you need to package your data again, use the secret key file.

Example:

  $package.sh /mysftuff/manifest.json check_plugin.qrhfefwgeehqkanwmjwmhbgecsfgalbf.ppk

Importing

Now that you have the zip file, you're nearly done!

Log into your kintone environment with an Administrator level account, and go to the kintone Administration page, which is an option you can find from the top right cog wheel near your name. Click on "Plug-ins", and then on "Import". Here, you can import your plugin (your zip file) into your kintone environment.

Notes

If a plugin with the same Plugin ID is uploaded, it will automatically overwrite the plugin, and will take effect on all apps that are using that plugin.

Was this article helpful?
0 out of 0 found this helpful
Comments
  • Avatar
    Nim

    What are the height x width dimensions for the icon?

Please sign in to leave a comment.