cybozu developer network

Enhanced by Google

カテゴリー内の他の記事

Garoon プラグイン開発手順

作成日
更新日

Index

はじめに

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

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

プラグイン作成の流れ

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

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

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

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

Gr________.png

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

アイコンファイル

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

  • 必須ファイルです。
  • 利用可能なファイルフォーマットは、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 を渡して利用してください。

CSS ファイル

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

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

設定画面用 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 ファイルです。
    setting_html-00.png

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 管理者が把握できるようになります。

impacted-app.png

 指定できる値は下記のとおりです。
  • 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/confi.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 文字以下で指定してください。

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

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

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

garoon-plugin-packer とは

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

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

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

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

パッケージング手順

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

  1. マニフェストファイルに沿って、作成した各ファイルとマニフェストファイルを配置します。
    Gr_manifest.png
  2. パッケージングしたいファイルをまとめたディレクトリ（plugin_sample）の、ひとつ上のディレクトリに移動します。
    上記のファイルの配置例の場合、「work」に移動します。
  3. 下記のコマンドを実行すると、自動でパッケージングが開始されます。
    実行に成功すると、成功メッセージが表示されます。
  4. 実行したディレクトリに、プラグインファイル（plugin.zip）が生成されます。
    Gr_______.png

4. Garoon 環境への追加

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

  1. Garoon システム管理を開きます。
    installToGaroon-00.png

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

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

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

  5. 「ファイルを添付」をクリックし、生成したプラグインファイル（plugin.zip）を選択します。
    installToGaroon-04.png

  6. 「追加する」をクリックします。
    installToGaroon-05.png

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

  8. 「変更する」をクリックします。
    installToGaroon-07.png

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

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

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

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

補足

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

おわりに

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

このTipsは、2021年3月版 Garoonで確認したものになります。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

サインインしてコメントを残してください。