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

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

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

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

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

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

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

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

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

• 設定画面で設定した情報を使い、実装したい処理を記述します。
• 設定画面用の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);

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

• 省略可能です。
• Garoonのデザインに合わせたい場合は、 Garoon html/css/image-Kit for Customize を利用してください。

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ファイルです。
• garoon.plugin.setConfig() を利用して、プラグインの設定値を保存できます。
  • 設定値が保存されると、「プラグインの詳細」画面の「詳細設定」が「未設定」から「設定済み」に変わります。
    

    

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

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

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

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

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

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

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

"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 sanple 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"]
}

 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"]
  }
}

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

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

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

以下のコマンドを実行し、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）が生成されます。
   

   

作成したプラグインファイルを以下の手順で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プラグインの作成にぜひ挑戦してみてください。

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