はじめようkintoneプラグイン

プラグインを作成してみよう

著者名：花塚 愛子（ サイボウズ株式会社 (External link) ）

目次

前回のイントロダクションでは、kintoneプラグインを開発するための環境を構築しました。
今回は、その環境を使って、実際にプラグインを作りながらプラグイン作成の流れを学びます。

作成するプラグイン

固定リンクがコピーされました

顧客リストの郵便番号、TEL、メールの入力をチェックする のサンプルコードをプラグインとして作成します。
この記事では、プラグインを作る流れを学ぶことを目的にしているため、プラグインの設定画面は作らず最もシンプルな例で説明していきます。

STEP1 動作確認用のアプリの準備

固定リンクがコピーされました

はじめに、プラグインの動作を確認するためのkintoneアプリを準備しましょう。
今回は、 kintoneアプリストア (External link) にある 顧客リスト (External link) アプリを利用します。

kintoneアプリストアから「顧客リスト」アプリを追加します。

顧客リストアプリの一覧画面が表示されれば準備完了です。

STEP2 プラグイン作成に必要なファイルの準備

固定リンクがコピーされました

それでは、プラグイン作成に必要なファイルを準備します。
プラグインのファイルを置くための作業ディレクトリとして「sample-plugin」を作成し、次の構成でディレクトリを作成します。

1
2
3

sample-plugin
├── image 
└── js

プラグインのアイコンファイル

固定リンクがコピーされました

プラグインのアイコンファイルを準備します。
今回は、サンプルとして次の画像を「check.png」というファイル名で、「image」ディレクトリ配下に保存します。

カスタマイズファイル

固定リンクがコピーされました

PC用JavaScriptファイルを準備します。
次の内容は、 顧客リストの郵便番号、TEL、メールの入力をチェックする のサンプルコードと同じです。
レコードのフィールドの値変更時およびレコードの保存実行時に、入力された値をチェックするカスタマイズです。
今回は、プラグインを作る流れを理解することが目的のため、プラグインの設定画面は作りません。
そのため、フィールドコードをハードコーディングしています。

サンプルコードをコピーし、「desktop.js」というファイル名で、文字コードを「UTF-8」にして保存します。
作成したファイルは、「js」ディレクトリ配下に置きましょう。

  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
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

/*
 * 顧客リストの郵便番号、TEL、メールの入力をチェックするサンプルコード
 * Copyright (c) 2024 Cybozu
 *
 * Licensed under the MIT License
 */

(() => {
  'use strict';

  // 郵便番号のフィールドコード
  const zipFieldCode = '郵便番号';
  // TELのフィールドコード
  const telFieldCode = 'TEL';
  // FAXのフィールドコード
  const faxFieldCode = 'FAX';
  // メールアドレスのフィールドコード
  const mailFieldCode = 'メールアドレス';

  // 郵便番号の入力チェック
  const validateZip = (event) => {
    // 郵便番号の定義(7桁の半角数字)
    const zipPattern = /^\d{7}$/;
    // eventよりレコード情報を取得します
    const record = event.record;
    // エラーの初期化
    record[zipFieldCode].error = null;
    // 郵便番号が入力されていたら、入力値を確認する
    const zipFieldValue = record[zipFieldCode].value;
    if (zipFieldValue) {
      // 定義したパターンにマッチするか確認する
      if (!(zipFieldValue.match(zipPattern))) {
        // マッチしない場合は、郵便番号フィールドにエラーの内容を表示する
        record[zipFieldCode].error = '郵便番号は7桁の半角数字で入力して下さい。';
      }
    }
  };

  // 電話番号の入力チェック
  const validateTel = (event) => {
    // TELの定義(10桁または11桁の半角数字)
    const telPattern = /^\d{10,11}$/;
    // eventよりレコード情報を取得する
    const record = event.record;
    // エラーの初期化
    record[telFieldCode].error = null;

    // TELが入力されていたら、入力値を確認する
    const telFieldValue = record[telFieldCode].value;
    if (telFieldValue) {
      // 定義したパターンにマッチするか確認する
      if (!(telFieldValue.match(telPattern))) {
        // マッチしない場合は、TELに対してエラーの内容を記載する
        record[telFieldCode].error = '電話番号は10桁 または11桁の半角数字で入力して下さい。';
      }
    }
  };

  // FAXの入力チェック
  const validateFax = (event) => {
    // FAXの定義(10桁または11桁の半角数字)
    const faxPattern = /^\d{10,11}$/;
    // eventよりレコード情報を取得する
    const record = event.record;
    // エラーの初期化
    record[faxFieldCode].error = null;
    // FAXが入力されていたら、入力値を確認する
    const faxFieldValue = record[faxFieldCode].value;
    if (faxFieldValue) {
      // 定義したパターンにマッチするか確認する
      if (!(faxFieldValue.match(faxPattern))) {
        // マッチしない場合は、FAXに対してエラーの内容を記載する
        record[faxFieldCode].error = 'FAX番号は10桁 または11桁の半角数字で入力して下さい。';
      }
    }
  };

  // メールアドレスの入力チェック
  const validateMail = (event) => {
    // メールアドレスの定義 (簡易的な定義です。さらに詳細に定義する場合は下記の値を変更して下さい)
    const mailPattern = /^([a-zA-Z0-9])+([a-zA-Z0-9._-])*@([a-zA-Z0-9_-])+([a-zA-Z0-9._-]+)+$/;
    // eventよりレコード情報を取得する
    const record = event.record;
    // エラーの初期化
    record[mailFieldCode].error = null;
    // メールアドレスが入力されていたら、入力値を確認する
    const mailFieldValue = record[mailFieldCode].value;
    if (mailFieldValue) {
      // 定義したパターンにマッチするか確認する
      if (!(mailFieldValue.match(mailPattern))) {
        // マッチしない場合は、メールアドレスに対してエラーの内容を記載する
        record[mailFieldCode].error = 'メールアドレスとして認識されませんでした。値を確認して下さい。';
      }
    }
  };

  // 変更イベント（郵便番号)
  kintone.events.on([
    'app.record.create.change.' + zipFieldCode,
    'app.record.edit.change.' + zipFieldCode,
    'app.record.index.edit.change.' + zipFieldCode
  ], (event) => {
    validateZip(event);
    return 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;
  });

  // 変更イベント(FAX)
  kintone.events.on([
    'app.record.create.change.' + faxFieldCode,
    'app.record.edit.change.' + faxFieldCode,
    'app.record.index.edit.change.' + faxFieldCode
  ], (event) => {
    validateFax(event);
    return 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;
  });

  // 追加・更新イベント
  kintone.events.on([
    'app.record.create.submit',
    'app.record.edit.submit',
    'app.record.index.edit.submit'
  ], (event) => {
    validateZip(event);
    validateTel(event);
    validateFax(event);
    validateMail(event);
    return event;
  });
})();

マニフェストファイル

固定リンクがコピーされました

最後に、マニフェストファイルを作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
次の内容を「manifest.json」というファイル名で、「sample-plugin」ディレクトリ直下に保存してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "manifest_version": 1,
  "version": "1.0.0",
  "type": "APP",
  "name": {
    "ja": "入力値チェックプラグイン",
    "en": "Input value check plug-in"
  },
  "description": {
    "ja": "郵便番号、電話番号、FAX番号、メールアドレスの入力値をチェックするプラグインです。",
    "en": "This plugin checks zip code, telephone number, FAX number, e-mail address"
  },
  "icon": "image/check.png",
  "homepage_url": {
    "ja": "https://cybozu.dev/ja/tutorials/hello-kinplugin/",
    "en": "https://cybozu.dev/ja/tutorials/hello-kinplugin/"
  },
  "desktop": {
    "js": [
      "js/desktop.js"
    ]
  }
}

マニフェストファイル内の各パラメーターについては、 マニフェストファイルのフォーマット を参考にしてください。

最終的なディレクトリ構成

固定リンクがコピーされました

ファイルをすべてそろえたら、次のディレクトリ構成になっていることを確認してください。

1
2
3
4
5
6

sample-plugin
├── image 
|    └── check.png
├── js
|    └── desktop.js
└── manifest.json

STEP3 プラグインファイルの生成

固定リンクがコピーされました

イントロダクション でインストールした plugin-packer を利用して、作成したファイルをパッケージングし、プラグインファイルを生成します。

  1. 「sample-plugin」ディレクトリのひとつ上のディレクトリに移動します。
    たとえば、「work」というディレクトリに「sample-plugin」ディレクトリがある場合、「work」に移動します。

    1

    cd work

  2. 次のコマンドを実行すると、自動でパッケージングが開始されます。

    1

    kintone-plugin-packer sample-plugin

    パッケージングに成功すると、次のメッセージが表示されます。

    1

    Succeeded: DIRECTORY_PATH/work/plugin.zip

  3. コマンド実行に成功すると、プラグインファイル（plugin.zip）と秘密鍵ファイル（ppkファイル）が生成されます。
    秘密鍵ファイルのファイル名「plggemelniigegboedcjdggddigldbla」はプラグインIDです。
    この値は、プラグインによってランダムに一意な値が割り振られます。

    1
2
3
4
5
6
7
8
9

    work
├── plugin.zip
├── plggemelniigegboedcjdggddigldbla.ppk
└── sample-plugin
    ├── image 
    |    └── check.png
    ├── js
    |    └── check-sample.png
    └── manifest.json
tips
補足

Web版のplugin-packerを利用してプラグインをパッケージングする方法もあります。
詳細は、 Web版のplugin-packer を参考にしてください。

STEP4 kintoneにプラグインファイルを追加する

固定リンクがコピーされました

イントロダクション でインストールした plugin-uploader を使って、作成したプラグインファイルを、kintoneに追加します。

information

プラグインファイルをkintoneに追加するには、 kintoneのシステム管理者 (External link) の権限が必要です。

  1. kintoneにプラグインファイルを追加するコマンドを実行します。

    1

    kintone-plugin-uploader plugin.zip

  2. kintoneのベースURL、ログイン名、パスワードの入力が求められます。
    自分の環境に沿って情報を入力して、Enterキーを押します。

    1
2
3

    ? kintoneのベースURLを入力してください (https://example.cybozu.com): https://example.cybozu.com
? ログイン名を入力してください: hoge
? パスワードを入力してください: [hidden]

    成功すると、「plugin.zipをアップロードしました！」と表示されます。

    1
2

    Trying to upload plugin.zip
plugin.zipをアップロードしました!

  3. では、kintoneを開き、プラグインのアップロードが無事に成功しているか確認してみましょう。
    kintoneシステム管理画面を開き、「その他」の「プラグイン」をクリックします。
    読み込んだプラグインの欄に、「入力値チェックプラグイン」が追加されていればアップロード成功です。

tips
補足

プラグインファイルの追加は、kintoneシステム管理画面からもできます。
詳細は、 ファイルからプラグインを読み込む (External link) を参考にしてください。

STEP5 アプリに適用

固定リンクがコピーされました

STEP1 で作成した「顧客リスト」アプリにプラグインを適用しましょう。

  1. STEP4 で追加したプラグインを「顧客リスト」アプリに適用します。
    「顧客リスト」アプリで、「アプリの設定」から「プラグイン」を開きます。
  2. 「追加する」ボタンをクリックします。

  3. 「入力値チェックプラグイン」横のチェックをつけ、画面右下の「追加」ボタンを押下します。

    アプリの設定画面に戻って、「アプリを更新」をクリックすれば、プラグインの適用は完了です。

STEP6 動作確認

固定リンクがコピーされました

最後に、アプリの動作確認をしましょう。
顧客リストの郵便番号、TEL、メールの入力をチェックする のサンプルコードと同じ動きをしているか確認します。

「顧客リスト」アプリのレコード編集画面を開き、郵便番号、TEL、FAX、メールアドレスに次のような入力をして、エラーが表示されることを確認できれば完了です。

おわりに

固定リンクがコピーされました

kintoneプラグインの基本的な作り方を学びました。
次回は、 プラグインの設定画面を作成してみよう で、プラグインの設定画面の作り方を学びます。

information

このTipsは、2024年4月版kintoneで動作を確認しています。