はじめに
kintoneでは、「プラグイン」を利用して、JavaScriptカスタマイズと同等の機能拡張や他サービスとの連携を実現できます。
通常のカスタマイズではアプリに合わせてJavaScriptファイルを編集する必要がありますが、プラグインを使うと、プラグインの設定画面でそれぞれのアプリに合わせた設定ができます。
プラグインは、kintoneをカスタマイズするためのJavaScriptやCSSファイルをパッケージングしたものです。
この記事では、プラグインの作成手順とkintoneへのインストール方法について説明します。
プラグイン作成の流れ
プラグイン作成の手順は、以下のとおりです。
- プラグイン作成に必要なファイル(JavaScript, CSSファイルなど)を準備します。
- マニフェストファイル(manifest.json)を作成します。
- パッケージツール(plugin-packer)を利用して、プラグイン作成に必要なファイルをパッケージングします。
- 作成したプラグインファイルを kintone 環境にインストールします。
プラグイン作成に必要なファイルの準備
パッケージングするファイルを準備します。
パッケージングするファイルのフォルダ構成およびファイル名は自由です。以下は一例です。
アイコンファイル
プラグイン一覧、プラグイン設定画面で表示されるプラグインアイコン用のファイルです。
- 必須ファイルです。
- 利用可能なファイルタイプは、png/jpg/gif/bmp のいずれかです。
- ファイルサイズの上限値は、20MBです。
PC用JavaScriptファイル
PC画面用のJavaScriptファイルです。
- スマートフォン専用のプラグインの場合、省略可能です。
- 設定画面で設定した情報を使い、実装したい処理を記述します。
- 設定画面用のJavaScriptファイルで kintone.plugin.app.setConfig を利用して設定した情報は、kintone.plugin.app.getConfig を利用して取得します。
このとき必要なプラグインIDは、 kintone.$PLUGIN_ID という変数に出力されます。
※ プラグインID は、プラグイン作成時に各プラグインへ一意に割り当てられる32桁のIDです。
例:faabchdodajloackbgnipilddblmkejp - ファイルサイズの上限値は、20MBです。
プラグインIDの参照例
1アプリで複数のプラグインを利用する場合、kintone.$PLUGIN_ID は複数回代入されます。
そのため、以下のように即時実行関数でプラグインIDを補足して利用してください。
PC用CSSファイル
PC画面用の CSS ファイルです。
- スマートフォン専用のプラグインの場合、省略可能です。
- kintone のデザインに合わせたい場合は、スタイルシートの利用をご利用ください。
- ファイルサイズの上限値は、20MBです。
スマートフォン用JavaScriptファイル
スマートフォン用のJavaScriptファイルです。
- スマートフォンでプラグインを利用しない場合、省略可能です。
- 設定画面から設定した情報を使い、実装したい処理を記述します。
- 設定画面用のJavaScriptファイルで kintone.plugin.app.setConfig を利用して設定した情報は、kintone.plugin.app.getConfig を利用して取得します。
このとき必要なプラグインIDの参照方法は、プラグインIDの参照例をご参考ください。 - ファイルサイズの上限値は、20MBです。
スマートフォン用CSSファイル
スマートフォン画面用の CSS ファイルです。
- スマートフォンでプラグインを利用しない場合、省略可能です。
- ファイルサイズの上限値は、20MB です。
設定画面用JavaScriptファイル
設定画面用のJavaScriptファイルです。
- 省略可能です。
- プラグインIDの参照方法は、プラグインIDの参照例をご参考ください。
- kintone.plugin.app.setConfig を利用して、プラグインの設定値を保存できます。
- ファイルサイズの上限値は、20MBです。
- プラグイン設定画面を開いた際に発火する JavaScript ファイルです。
設定画面用CSSファイル
設定画面用のCSSファイルです。
- 省略可能です。
- kintone のデザインに合わせたい場合は、スタイルシートの利用をご利用ください。
- ファイルサイズの上限値は、20MBです。
- プラグイン設定画面に対し適用される CSS ファイルです。
設定画面用HTMLファイル
設定画面用のHTMLファイルです。
- 省略可能です。
- ファイルサイズの上限値は、64KB です。
- 下図の赤枠部分を構成する HTML ファイルです。
マニフェストファイルの作成
マニフェストファイル (manifest.json)を作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
このファイルは、kitoneプラグイン作成に必須です。
マニフェストファイルのフォーマット
マニフェストファイルは、JSON 形式のファイルです。各パラメータの詳細は以下のとおりです。
パラメータ名 | 型 | 必須 | 説明 | 制限 | 指定例 |
---|---|---|---|---|---|
type | String | 必須 | プラグインの種類 APP を指定してください。 |
なし |
"type": "APP" |
manifest_version | Number ※整数のみ |
必須 | プラグインのマニフェストバージョン 1 を指定してください。 ※現在有効なバージョンは 1 のみです。 |
なし |
"manifest_version": 1 |
version | Number ※整数のみ または String ※「x」「x.y」「x.y.z」の形式のみ |
必須 |
プラグインのバージョン |
なし |
"version": 1 "version": "1.0" "version": "1.0.0" |
name | Object <String> |
必須 | ロケール(ja/en/zh)をキーとする各言語のプラグイン名 | なし |
"name": { |
name.<locale> | String | 必須 | 指定されたロケールのプラグイン名 | 1文字以上64文字以下 name.en は必須です。 |
|
description | Object <String> |
省略可 | ロケール(ja/en/zh)をキーとする各言語の説明文 プラグイン一覧での説明文として表示されます。 |
なし |
"description": { |
description.<locale> | String | 必須 | 指定されたロケールの説明文 | 1文字以上200文字以下 description がある場合、description.en は必須です。 |
|
icon | String | 必須 | プラグインのアイコンファイル プラグイン一覧、プラグイン設定画面で表示されます。 |
プラグイン内のファイルのみ指定可能です。 |
"icon": "image/icon.png" |
homepage_url | Object <String> |
省略可 | ロケール(ja/en/zh)をキーとするWebサイトURL プラグイン一覧のプラグイン名横にナビゲーションアイコンが追加されます。アイコンをクリックすると、指定したWebサイトに遷移します。 |
なし |
"homepage_url": { |
homepage_url.<locale> | String | 省略可 | 指定されたロケールのWebサイトURL | なし | |
desktop | Object <String> |
省略可 | ファイルの種類 (js/css) をキーとするPC用カスタマイズファイル | なし |
"desktop": { |
desktop.js | Array <String> |
省略可 | PC用JavaScriptファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
desktop.css | Array <String> |
省略可 | PC用CSSファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
mobile | Object <String> |
省略可 | ファイルの種類 (js) をキーとするスマートフォン用カスタマイズファイル | なし |
"mobile": { |
mobile.js | Array <String> |
省略可 | スマートフォン用JavaScriptファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
mobile.css | Array <String> |
省略可 | スマートフォン用CSSファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
config | Object <String> |
省略可 | ファイルの種類 (js/css/html) をキーとする設定画面用カスタマイズファイルと設定情報 | なし |
"config": { |
config.html | String | 省略可 | 設定画面用HTMLファイル | プラグイン内のファイルのみ指定可能 | |
config.js | Array <String> |
省略可 | 設定画面用JavaScriptファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
config.css | Array <String> |
省略可 | 設定用CSSファイル URLの配列 |
30個まで ※同一名のファイルが有る場合、エラーになります |
|
config.required_params | Array <String> |
省略可 | 設定画面で設定必須とするパラメータの配列 | ASCIIで1文字以上64文字以下 |
マニフェストファイルの例
プラグインに必要なファイルのパッケージング
plugin-packer を利用してプラグインに必要なファイルをパッケージングし、プラグインファイルを生成します。
plugin-packer とは
plugin-packer は、プラグイン作成に必要なファイルをzipファイルにパッケージングする CLI ツールです。
plugin-packer の詳細は、plugin-packerを使ってプラグインファイルをパッケージングしよう!をご参照ください。
このツールを利用するには、Node.js バージョン 8 以上 が必要です。
Node.js のインストーラは、Node.js 公式サイトより入手してください。
インストール方法
以下のコマンドを実行し、plugin-packer をインストールします。
パッケージ手順
以下の手順で、プラグインファイルをパッケージングします。
- マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。
- パッケージングしたいファイルをまとめたディレクトリ(src)の、ひとつ上のディレクトリに移動します。
上記のファイル配置例の場合、「work」に移動します。 - 下記のコマンドを実行すると、自動でパッケージングが開始されます。
実行に成功すると、成功メッセージが表示されます。 - 実行したディレクトリに、プラグインファイル (plugin.zip) と秘密鍵ファイル (ppkファイル) が生成されます。
秘密鍵ファイルのファイル名は、プラグインIDと同じです。
下記の例では、プラグインIDが「faabchdodajloackbgnipilddblmkejp」です。
秘密鍵ファイルは、2回目以降のパッケージングで利用するので、なくさないようご注意ください。
2回目以降のパッケージング
2回目以降のパッケージングは、 --ppk オプション を使って、1回目のパッケージングで生成された秘密鍵ファイルを指定します。
同じ秘密鍵ファイルを使ってパッケージングすると、プラグインIDは同じになります。
プラグインファイルの出力先ディレクトリを変更したい場合や、ファイル監視しながらパッケージングしたい場合など、その他の機能については、オプション機能 をご参照ください。
kintone 環境へのインストール
作成したプラグインファイルを kintone へインストールします。
- 「kintoneシステム管理」を開きます。
- 「その他」の「プラグイン」をクリックします。
- 「読み込む」ボタンをクリックします。
- 「参照」ボタンをクリックし、パッケージ手順 4. で生成したプラグインファイル(plugin.zip)を選択します。
- 「読み込む」ボタンをクリックします。
- 「インストールされたプラグイン」に、作成したプラグインが表示されれば成功です。
補足
- インストールできるプラグインファイルのサイズ上限値は、100MB です。
- 同じプラグインIDを持つプラグインファイルをアップロードすると、自動的に上書きインストールされます。
そのプラグインを利用しているアプリにも即時適用されます。 - アプリに複数のプラグインを適用する場合、プラグイン同士が競合し意図しない挙動をすることがあります。
運用に支障がないことを検証した上で、プラグインを適用してください。
おわりに
今回は、パッケージツール(plugin-packer)を利用した kintone プラグインの作成手順と、kintone へのインストール方法について説明しました。
プラグインを使うと、kintone カスタマイズの内容を簡単に複数のアプリへ適用できます。
プラグインファイルのパッケージング手順も簡単なので、ぜひプラグイン作成に挑戦してみてください。
このTipsは、2019年1月版 kintoneで確認したものになります。
「customize.js.js 」と拡張しが二つ付いている箇所があります!
To Hosoya san
フォルダ構成の部分で、誤記がありましたので修正しました。
ご報告をいただきましてありがとうございます。
kintone.plugin.getConfig(PLUGIN_ID); の記述があります!
正しくは、「kintone.plugin.app.getConfig(PLUGIN_ID);」かなと思います!
Hosoya さま
PC用JavaScriptファイル > プラグインIDの参照例
の箇所で kintone.plugin.getConfig(PLUGIN_ID); の記述があったため、
「kintone.plugin.app.getConfig(PLUGIN_ID);」に修正いたしました。ご指摘をありがとうございます。
記事中段の
「取得したパッケージングツールを配置します。」
の”パッケージングツール”のリンク先が誤っています。
上記の箇所だけNot Foundになってしまうので修正していただければと。
kazuhisa ishidao 様
お世話になっております。
cybozu developer network事務局です。
ご指摘いただきありがとうございます。
内部にフィードバックし、修正いたします。
今後ともcybozu developer networkのほど、よろしくお願い致します。
kazuhisa ishidao 様
ご指摘いただいた内容を修正いたしました。
ご報告をいただきましてありがとうございます。
リンクの存在がわからないようなスタイル指定の箇所がありますので、改善いただけますでしょうか。具体的には以下のとおりです。
---
「設定画面用CSSファイル」の項に「kintone プラグインデザインのガイドラインをご利用ください」との記述があります。
マウスカーソルを「kintone プラグインデザインのガイドライン」に当てますと、アンダーラインが引かれ、リンクがあるのがわかります。しかし、通常は、他の平文と同じで黒く表示されており、リンクがあるのかどうかがわかりません。
少し調べてみますと、「kintone プラグインデザインのガイドライン」のリンクについては、なぜか「class="wysiwyg-color-black"」の指定がなされており、これが原因で黒い文字として表示されていることがわかりました。
このリンクを黒く表示しなければならない理由は無いように思いますので、他のリンク文と同様に青っぽく(上記クラス指定を除去)していただけないでしょうか。
Toshi Akazawa 様
お世話になっております。
cybozu developer network事務局です。
ご指摘いただいた点を修正いたしました。
ご報告いただきましてありがとうございます。
「パッケージ手順」の手順2で、次の説明書きがあります。
しかし、「上記の・・・」の上の図には、workというディレクトリは記載されていないため、何のことかわかりにくいです。cd src と書くべきところを typoしたのかなという印象でした。
図にも work ディレクトリを書き添えたものにされた方がよいのではないでしょうか。
あるいは、図はそのままとするのであれば、「パッケージングしたいファイルをまとめたディレクトリ src の、」というように、src も書き加え、続く一文も「上記のファイル配置の src のひとつ上のディレクトリが「work」であるとして、その「work」に移動します」としてはいかがでしょうか。
Toshi Akazawa 様
お世話になっております。cybozu developer network 運営局です。
フィードバックくださり、ありがとうございます。
ご指摘いただいた内容について、記事を修正いたしました。
今後とも、cybozu developer network をよろしくお願いいたします。