Garoon プラグイン開発手順

目次

はじめに

Garoon では、「プラグイン」を利用して、JavaScript カスタマイズと同等の拡張機能や他サービスとの連携を実現できます。
通常のカスタマイズではアプリケーションに合わせて JavaScript ファイルを編集する必要がありますが、プラグインを使うと、プラグインの設定画面でそれぞれのアプリケーションに合わせた設定ができます。

プラグインは、Garoon をカスタマイズするための JavaScript や CSS をパッケージングしたものです。
この記事では、プラグインの作成手順と Garoon への追加方法について説明します。

プラグイン作成の流れ

プラグインの作成の手順は以下のとおりです。

  1. プラグイン作成に必要なファイル(JavaScript, CSS ファイルなど)を準備します。
  2. マニフェストファイル(manifest.json)を作成します。
  3. パッケージツール(garoon-plugin-packer)を利用して、プラグイン作成に必要なファイルをパッケージングします。
  4. 作成したプラグインファイルを Garoon 環境に追加します。

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

パッケージングするファイルを準備します。
パッケージングするファイルの上限値は 100MB です。
パッケージングするファイルのディレクトリー構成およびファイル名は自由です。以下は一例です。

各ファイルについて説明します。

アイコンファイル

「プラグインの設定画面」や「プラグインの詳細画面」に表示されるプラグインアイコン用のファイルです。

  • 必須ファイルです。
  • 利用可能なファイルフォーマットは、png / jpg / jpeg / jpe / gif / bmp です。
  • 推奨する画像サイズは 224 x 224[px]です。

JavaScript ファイル

アプリケーション画面で動作するカスタマイズファイルです。

  • 設定画面で設定した情報を使い、実装したい処理を記述します。
  • 設定画面用の JavaScript ファイルで garoon.plugin.setConfig() を利用して設定した情報は、 garoon.plugin.getConfig() を利用して取得します。
    このとき必要なプラグイン ID は、$PLUGIN_ID という変数に出力されます。
プラグイン ID の参照例

アプリケーションで複数のプラグインを使用する場合、$PLUGIN_ID は複数回代入されます。
そのため、以下のように即時実行関数でプラグイン ID を渡して利用してください。

1
2
3
(function(PLUGIN_ID) {
  garoon.plugin.getConfig(PLUGIN_ID);
})($PLUGIN_ID);

CSS ファイル

アプリケーション画面で動作するカスタマイズファイルです。

Garoon html/css/image-Kit for Customize 使用時のポイント

Garoon html/css/image-Kit for Customize 内の CSS を変更すると、他のプラグインに影響する場合があります。
そのため、Garoon html/css/image-Kit for Customize の CSS のプロパティを変更したい場合は、次のようにプラグインごとにユニークな要素でラップし、別ファイルとして適用することを推奨します。
作成したユニークな要素のクラス名を「sample_plugin」と設定した場合、以下のように記述してください。

1
2
3
.sample-plugin .fontcolor_sub_grn_kit {
  color: #333;
}

設定画面用 JavaScript ファイル

設定画面用の JavaScript ファイルです。

  • 省略可能です。
  • プラグイン設定画面を開いた際に実行される JavaScript ファイルです。
  • garoon.plugin.setConfig() を利用して、プラグインの設定値を保存できます。
    • 設定値が保存されると、「プラグインの詳細」画面の「詳細設定」が「未設定」から「設定済み」に変わります。

  • プラグイン ID の参照方法は、 プラグイン ID の参照例 をご参考ください。

設定画面用の CSS ファイル

設定画面用の CSS ファイルです。

  • 省略可能です。
  • Garoon のデザインに合わせたい場合は、 Garoon html/css/image-Kit for Customize を利用してください。
    利用するときのポイントは CSS ファイル の「Garoon html/css/image-Kit for Customize 使用時のポイント」を参照してください。
  • プラグイン設定画面に対して適用される CSS ファイルです。

設定画面用の HTML ファイル

設定画面用の HTML ファイルです。

下図の赤枠部分を構成する HTML ファイルです。

2. マニフェストファイルの作成

マニフェストファイル(manifest.json)を作成します。
マニフェストファイルは、プラグイン作成に必要なファイル情報をまとめた設定ファイルです。
このファイルは、Garoon プラグイン作成に必須です。

マニフェストファイルのフォーマット

マニフェストファイルは、JSON 形式のファイルです。各パラメーターの詳細は以下のとおりです。

パラメーター名 必須 説明
manifest_version 整数 必須 プラグインのマニフェストのバージョンです。
「1」を指定してください。
現在有効なバージョンは「1」のみです。

例:
"manifest_version": 1
version 文字列 必須 プラグインのバージョンです。
Semantic Versioning の書式(X.Y.Z)に従います。

例:
"version": "1.0.0"
target_applications 配列(文字列) 必須 プラグインの JavaScript のカスタマイズが適用されるアプリケーションを指定します。
指定できる値は次のとおりです。
  • ALL:Garoon 全体
今後のアップデートで「ALL」以外の識別子を指定できるようになる予定です。

例:
"target_applications":["ALL"]
impacted_applications 配列(文字列) 必須 カスタマイズが適用されるアプリケーションや影響を受けるアプリケーションを指定します。

例:スケジュール画面でワークフローを取得するプラグインの場合、「SCHEDULER」や「WORKFLOW」を指定します。
この値を設定することで、適用したプラグインで影響を受けるアプリケーションを Garoon 管理者が把握できます。


指定できる値は次のとおりです。
  • ALL : Garoon 全体
  • PORTAL : ポータル
  • SPACE : スペース
  • BOOKMARKS : リンク集
  • SCHEDULER : スケジュール
  • MESSAGES : メッセージ
  • BULLETIN_BOARD : 掲示板
  • CABINET : ファイル管理
  • MEMO : メモ
  • PHONE_MESSAGES : 電話メモ
  • TIMESHEET : タイムカード
  • ADDRESS_BOOK : アドレス帳
  • EMAIL : メール
  • WORKFLOW : ワークフロー
  • MULTI_REPORT : マルチレポート
  • PRESENCE_INDICATORS : 在席確認
  • FAVORITE : お気に入り
  • NOTIFICATIONS : 通知一覧
  • RESPOND : リアクション


例:
"impacted_applications":["SCHEDULER"]
plugin_code 文字列 省略可 プラグインの識別コードを設定します。
1 文字以上 128 文字以下で指定します。
半角英数字と、ドット(.)が使用できます。

例:
"plugin_code": "sample.plugin.code"
name オブジェクト 必須 ロケール(ja / en / zh / zh-tw)をキーとする各言語のプラグイン名です。

例:
"name": {
"ja": "サンプルプラグイン",
"en": "sample plugin",
"zh": "示例插件",
"zh-tw": "示例插件"
}
name.<locale> 文字列 必須 指定されたロケールのプラグイン名を指定します。
1 文字以上 64 文字以下で指定します。
name.en は必須です。
description オブジェクト 省略可 ロケール(ja / en / zh / zh-tw)をキーとする各言語のプラグインの説明です。

例:
"description": {
"ja": "これはサンプルプラグインです。",
"en": "This is sanple plugin.",
"zh": "这是示例插件。",
"zh-tw": "这是示例插件。"
}
description.<locale> 文字列 必須 指定されたロケールのプラグインの説明を指定します。
1 文字以上 200 文字以下で指定します。
description がある場合、
description.en は必須です。
icon 文字列 必須 プラグインのアイコンの画像ファイルのパスを設定します。
manifest.json のあるディレクトリー(以降、ルートディレクトリー)からの相対パスを指定してください。
パスに ./ または ../ を含むとエラーになります。

例:
"icon": "image/sample_plugin_icon.png"
homepage_url オブジェクト 省略可 ロケール(ja / en / zh / zh-tw)をキーとする各言語のプラグインの紹介ページの URL を設定します。

例:
"homepage_url": {
"ja": "https://example.com/jp_JP/",
"en": "https://example.com/en_US/",
"zh": "https://example.com/zh_CN/",
"zh-tw": "https://example.com/zh_TW/"
}
homepage_url.<locale> 文字列 省略可 指定されたロケールのプラグインの紹介ページの URL を指定します。
「https://」始まりの URL のみ指定できます。
provider オブジェクト 省略可 ロケール(ja / en / zh / zh-tw)をキーとする、各言語のプラグインの提供元の説明です。

例:
"provider": {
"ja": {
"name": "提供元(サンプル)",
"url": "https://example.com/provider/jp_JP/"
},
"en": {
"name": "Provider(Sample)",
"url": "https://example.com/provider/en_US/"
},
"zh": {
"name": "提供商(示例)",
"url": "https://example.com/provider/zh_CN/"
},
"zh-tw": {
"name": "提供商(示例)",
"url": "https://example.com/provider/zh_TW/"
}
}
provider.<locale> オブジェクト 必須 指定されたロケールのプラグインの提供元の名前と URL を指定します。
provider.<locale>.name 文字列 必須 指定されたロケールのプラグインの提供元の名前を指定します。
1 文字以上 100 文字以下を指定します。
provider.en.name は必須です。
provider.<locale>.url 文字列 必須 指定されたロケールのプラグインの提供元の URL を指定します。
「https://」始まりの URL のみ指定できます。
provider.en.url は必須です。
desktop オブジェクト 省略可 ファイルの種類(js / css)をキーとするカスタマイズファイルを設定します。

例:
"desktop": {
"js":[
"js/customize.js",
"https://example.com/js/customize.js"
],
"css":[
"css/customize.css",
"https://example.com/css/customize.css"
]
}
desktop.js 配列(文字列) 省略可 JavaScript ファイルを指定します。
ルートディレクトリーからの相対パスか URL を指定してください。
30 個までファイルを指定できます。
同じ名前のファイルを指定した場合、エラーになります。
パスに ./ または ../ を含むとエラーになります。
desktop.css 配列(文字列) 省略可 CSS ファイルを指定します。
ルートディレクトリーからの相対パスか URL を指定してください。
30 個までファイルを指定できます。
同じ名前のファイルを指定した場合、エラーになります。
パスに ./ または ../ を含むとエラーになります。
config オブジェクト 省略可 設定画面用のファイルを指定します。

例:
"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 文字列 省略可 設定画面用の HTML ファイルを指定します。
ルートディレクトリーからの相対パスを指定してください。
config の項目が存在する場合、必須です。
パスに ./ または ../ を含むとエラーになります。
config.js 配列(文字列) 省略可 設定画面用の JavaScript ファイルか URL を指定します。
ルートディレクトリーからの相対パスか URL を指定してください。
30 個までファイルを指定できます。
同じ名前のファイルを指定した場合、エラーになります。
パスに ./ または ../ を含むとエラーになります。
config.css 配列(文字列) 省略可 設定画面用の CSS ファイルまたは URL を指定します。
ルートディレクトリーからの相対パスか URL を指定してください。
30 個までファイルを指定できます。
同じ名前のファイルを指定した場合、エラーになります。
パスに ./ または ../ を含むとエラーになります。
config.required_params 配列(文字列) 省略可 設定項画面で設定必須とするパラメーターの配列を指定します。
ASCII コードで、1 文字以上、64 文字以下で指定してください。

マニフェストファイルの例

 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
{
{
  "manifest_version": 1,
  "version": "1.0.0",
  "target_applications": ["ALL"],
  "impacted_applications": ["SCHEDULER"],
  "plugin_code": "sample.plugin.code",
  "name": {
    "ja": "サンプルプラグイン",
    "en": "sample plugin",
    "zh": "示例插件",
    "zh-tw": "示例插件"
  },
  "description": {
    "ja": "サンプルプラグインです。",
    "en": "This is sample plugin.",
    "zh": "这是示例插件。",
    "zh-tw": "这是示例插件。"
  },
  "icon": "image/sample_plugin_icon.png",
  "homepage_url": {
    "ja": "https://example.com/jp_JP/",
    "en": "https://example.com/en_US/",
    "zh": "https://example.com/zh_CN/",
    "zh-tw": "https://example.com/zh_TW/"
  },
  "provider": {
    "ja": {
      "name": "提供元(サンプル)",
      "url": "https://example.com/provider/jp_JP/"
    },
    "en": {
      "name": "Provider (Sample)",
      "url": "https://example.com/provider/en_US/"
    },
    "zh": {
      "name": "提供商(示例)",
      "url": "https://example.com/provider/zh_CN/"
    },
    "zh-tw": {
      "name": "提供商(示例)",
      "url": "https://example.com/provider/zh_TW/"
    }
  },
  "desktop": {
    "js": ["js/customize.js", "https://example.com/js/customize.js"],
    "css": ["css/customize.css", "https://example.com/css/customize.css"]
  },
  "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"]
  }
}

3. プラグインに必要なファイルのパッケージング

garoon-plugin-packer を利用してプラグインに必要なファイルをパッケージングし、プラグインファイルを生成します。

garoon-plugin-packer とは

garoon-plugin-packer は、プラグイン作成で必要なファイルを zip ファイルにパッケージングする CLI ツールです。
garoon-plugin-packer の詳細は、 GitHub (External link) を参考にしてください。

このツールを利用するには、Node.js バージョン 10.0.0 以上が必要です。
Node.js のインストーラーは、 Node.js 公式サイト (External link) より入手してください。

garoon-plugin-packer のインストール方法

以下のコマンドを実行し、garoon-plugin-packer をインストールします。

1
npm install -g @garoon/plugin-packer

パッケージング

以下の手順で、プラグインファイルをパッケージングします。

  1. マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。

  2. パッケージングしたいファイルをまとめたディレクトリー(plugin_sample)の、ひとつ上のディレクトリーに移動します。
    上記のファイルの配置例の場合、「work」に移動します。

    1
    
    cd work
  3. 次のコマンドを実行すると、自動でパッケージングが開始されます。
    実行に成功すると、成功メッセージが表示されます。

    1
    2
    3
    4
    5
    6
    
    garoon-plugin-packer sample_plugin 
    
    Succeeded: Validate manifest.json.
    Succeeded: Check package resources.
    Info: plugin.zip 5802 bytes
    Succeeded: Create ZIP file.
  4. 実行したディレクトリーに、プラグインファイル(plugin.zip)が生成されます。

4. Garoon 環境への追加

作成したプラグインファイルを以下の手順で Garoon へ追加します。

  1. Garoon システム管理を開きます。

  2. 「基本システムの管理」内の「プラグイン」を開きます。

  3. 「プラグインの設定」をクリックします。

  4. 「プラグインを追加する」をクリックします。

  5. 「ファイルを添付」をクリックし、生成したプラグインファイル(plugin.zip)を選択します。

  6. 「追加する」をクリックします。

  7. 読み込んだプラグインが表示されれば、読み込みは成功です。
    デフォルトではプラグインが「無効」になっているので、追加したプラグインをクリックします。

  8. 「変更する」をクリックします。

  9. 「プラグインの利用」を「有効にする」を選択し、「変更する」をクリックします。

  10. 開発したプラグインで設定画面を開発した場合は、「設定する」をクリックし、設定詳細画面から設定します。

プラグインをアップデートする場合

不具合の修正やプラグインの改修など、すでに Garoon に追加しているプラグインのアップデートを行いたい場合、
アップデートしたいプラグインの「プラグインの詳細」画面内にある「アップデート」より zip ファイルを追加し直してください。

補足

  • 追加できるプラグインファイルの上限値は、100MB です。
  • 同じプラグイン ID をもつプラグインファイルをアップロードすると、自動的に上書きインストールされます。
    プラグインを利用しているアプリケーションにも即時適用されます。
  • 複数のプラグインを設定している場合、プラグイン同士が競合し、意図しない挙動をすることがあります。
    たとえば、プラグインで jQuery を利用する場合は jQuery の読み込み方 に注意する必要があります。

おわりに

パッケージツール「garoon-plugin-packer」を利用した、Garoon プラグインの作成手順と、Garoon への追加方法について説明しました。
garoon-plugin-packer の利用も合わせて、Garoon プラグインの作成にぜひ挑戦してみてください。

information

この Tips は、2021 年 3 月版 Garoon で動作を確認しています。