How to Create Plug-ins

Contents

Overview

This article introduces how to create and upload a Kintone plug-in using plug-in packer and plug-in uploader.

It is recommended to read the following article and set up the environment before this current article:
Get Started with Developing Plug-ins

An "Input value check plug-in" will be created, which will validate data that users input into an App's record.

STEP 1: Create a Sample App

First, create a new Kintone App. From the Kintone Marketplace, choose Customer Database.

For more information on adding an App from the Kintone Marketplace, refer to the following article:
Adding a Sample App (External link)

STEP 2: Prepare the Plug-in Files

Next, prepare the necessary files for the Kintone plug-in. Create a directory with the following structure.

1
2
3
sample-plugin
├── image
└── js

The Plug-in Icon

Prepare an icon file for the plug-in. Set the image under the "image" directory with the file name "check.png".

The Desktop JavaScript Code

Prepare a JavaScript file that will run for desktop browsers. This is where the main Kintone customization codes will be written.

In the following sample code, the customization checks the values when a field value changes and the record is saved. Since this article aims to understand the process of creating a plug-in, the Plug-in settings page will not be configured in this sample. Therefore, the field codes are hard-coded.

Copy the sample code below, save the file as "desktop.js", and place it under the "js" directory.

 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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
(() => {
  'use strict';

  // field codes
  const telFieldCode = 'telephone_number';
  const mailFieldCode = 'email';

  // check the Telephone value
  const validateTel = (event) => {
    // set the telephone pattern, number must be 10 or 11 digits
    const telPattern = /^\d{10,11}$/;
    // get the record data
    const record = event.record;
    record[telFieldCode].error = null;

    // check the input value
    const telFieldValue = record[telFieldCode].value;
    if (telFieldValue) {
      if (!(telFieldValue.match(telPattern))) {
        // error if the input value does not match the pattern
        record[telFieldCode].error = 'Telephone number must be 10 or 11 digits.';
      }
    }
  };

  // check the Email value
  const validateMail = (event) => {
    // set the email pattern
    const mailPattern = /^([a-zA-Z0-9])+([a-zA-Z0-9._-])*@([a-zA-Z0-9_-])+([a-zA-Z0-9._-]+)+$/;
    const record = event.record;
    record[mailFieldCode].error = null;
    // check the input value
    const mailFieldValue = record[mailFieldCode].value;
    if (mailFieldValue) {
      if (!(mailFieldValue.match(mailPattern))) {
        // error if the input value does not match the pattern
        record[mailFieldCode].error = 'Invalid email address.';
      }
    }
  };

  // Telephone field change event
  kintone.events.on([
    'app.record.create.change.' + telFieldCode,
    'app.record.edit.change.' + telFieldCode,
    'app.record.index.edit.change.' + telFieldCode
  ], (event) => {
    validateTel(event);
    return event;
  });

  // Email field change event
  kintone.events.on([
    'app.record.create.change.' + mailFieldCode,
    'app.record.edit.change.' + mailFieldCode,
    'app.record.index.edit.change.' + mailFieldCode
  ], (event) => {
    validateMail(event);
    return event;
  });

  // record save events
  kintone.events.on([
    'app.record.create.submit',
    'app.record.edit.submit',
    'app.record.index.edit.submit'
  ], (event) => {
    validateTel(event);
    validateMail(event);
    return event;
  });
})();

The Manifest File

The manifest file is a configuration file that contains all the file information needed to create the plug-in. Save the following sample as "manifest.json" and place it under the "sample-plugin" directory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "manifest_version": 1,
  "version": "1.0.0",
  "type": "APP",
  "name": {
    "en": "Input value check plug-in"
  },
  "description": {
    "en": "This plug-in checks telephone number and e-mail address"
  },
  "icon": "image/check.png",
  "homepage_url": {
    "en": "https://kintone.dev/en/plugins/development-guide/how-to-create-plugins"
  },
  "desktop": {
    "js": [
      "js/desktop.js"
    ]
  }
}

Refer to the following article for other parameters in the manifest file:
The Manifest File

Directory Structure

Once all the files are prepared, the file tree should now look like the following structure:

1
2
3
4
5
6
sample-plugin
├── image
|    └── check.png
├── js
|    └── desktop.js
└── manifest.json

STEP 3: Package the Plug-in Files

  1. Install plugin-packer (External link) using npm.

    1
    
    npm install -g @kintone/plugin-packer
  2. Move up a directory from the "sample-plugin" directory. Run the following command to package the files.

    1
    
    kintone-plugin-packer sample-plugin

    If the packaging is successful, the following message will be displayed.

    1
    
    Succeeded: DIRECTORY_PATH/plugin.zip
  3. If the command execution succeeds, a plug-in file (plugin.zip) and a private key file (ppk file) will be generated. The private key file name "pluggemelniigegboedcjdggddigldbla" in the following example is the plug-in ID. This is a randomly assigned unique ID.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    work
    ├── plugin.zip
    ├── plggemelniigegboedcjdggddigldbla.ppk
    └── sample-plugin
        ├── image
        |    └── check.png
        ├── js
        |    └── desktop.js
        └── manifest.json
tips
Note

There is also a web version of plugin-packer to package plug-ins. For more information, refer to the following article:
Plugin-packer (web version)

STEP 4: Install the Plug-in into Kintone

information

Kintone Administrator permission is required to add plug-in files to Kintone. For more information, refer to the following article.
Kintone Administrator (External link)

  1. Install plugin-uploader using the following command.

    1
    
    npm install -g @kintone/plugin-uploader
  2. Run the following command to add the plug-in file to Kintone.

    1
    
    kintone-plugin-uploader plugin.zip
  3. Enter your Kintone subdomain, login name, and password.

    1
    2
    3
    4
    5
    6
    7
    8
    
    ? Input your kintone's domain (example.kintone.com): <subdomain>.kintone.com
    ? Input your username: <user name>
    ? Input your password: <user password>
    > Open https://<subdomain>.kintone.com/login?saml=off
    > Trying to log-in...
    > Navigate to https://<subdomain>.kintone.com/k/admin/system/plugin/
    > Trying to upload plugin.zip
    > plugin.zip has been uploaded!
  4. Next, navigate to Kintone on the browser and check if the plug-in has been uploaded. Open the Kintone Administration page and click on Plug-ins. "Input value check plug-in" should be added to the Imported Plug-ins list.

tips
Note

Plug-in files can also be added from the Kintone Administration page. For more information, refer to the following article on the Kintone Help site:
Adding plug-ins by importing plug-in files (External link) .

STEP 5: Add the Plug-in to the App

Add the plug-in to the Customer Database App created in STEP 1 .

  1. In the Customer Database App, go to App Settings and open Plug-ins.
  2. Click the Add Plug-in button.

  3. Check the box next to "Input value check plug-in" and click the Add button at the bottom right of the page.

  4. Navigate back to the App Settings page and click Update App.

Notes

If a plug-in with the same Plug-in ID is uploaded, it will automatically overwrite the plug-in, and will take effect on all apps that are using that plug-in.

STEP 6: Test the Plug-in

Go to the App and add a new record. Enter data into the Email and Telephone Number fields. The data will be validated, and will show field errors if the data is invalid.

Finally

Now that the plug-in has been created, the next tutorial will guide through the process of implementing its settings page. Follow the step-by-step guides in the following article for instructions on how to create plug-ins settings:

How to Create a Settings Page