プラグインクイックスタート

コラボフロープラグインを作成する簡易な手順をご紹介します。

事前準備

コラボフロープラグインは、コラボフローの申請書で発生する様々なイベントに対して、独自の処理を指定できるようにするカスタマイズです。そのため、コラボフロープラグインを使用する前には必要な フォーム や経路があらかじめ作成されている必要があります。

このチュートリアルではフォームと経路が作成済みの環境を前提に解説をおこないます。
フォーム設定や経路設定については以下を参照ください。

デモプラグインのダウンロード

デモプラグインは、設定で指定した テキスト（一行）パーツ に入力されたメールアドレスを検証するプラグインです。このプラグインを参考にファイルの追加、削除をすることでプラグインの開発が可能です。

デモプラグインは、以下のリンクよりダウンロードください。
ダウンロード後、ファイルを任意のフォルダーに展開してください。

デモプラグインダウンロード

展開したフォルダーは以下の構造となっています。

任意のフォルダー/
 ├─ manifest.json  (マニフェストファイル)
 ├─ index.html     (設定画面用HTML)
 └─ js/
     ├─ index.js   (申請書画面用JS)
     └─ settings/
         └─ settings.js (設定画面用JS)

マニフェストファイルの編集

マニフェストファイルは、プラグインの設定を記述しているファイルです。以下の内容となっています。
必要に応じて、nameやdescription等の修正をしてください。

{
  "package": {
    "name": "クイックスタートのサンプルプラグイン",
    "description": "メールアドレスの検証をおこなうプラグインです。",
    "plugin_code": "jp.co.collabo-style.demo_plugin",
    "version": "1.0.0",
    "author": "株式会社コラボスタイル",
    "type": "form",
    "help": "https://collaboflow.zendesk.com/hc/ja/sections/360000040276"
  },
  "config": {
    "path": "index.html"
  },
  "customize": {
    "js": [
      {
        "type": "file",
        "path": "js/index.js"
      }
    ],
    "css": []
  }
}

マニフェストの項目一覧

プラグインの基本情報(package)

項目名	説明
name	プラグインの一覧などで表示されるプラグイン名です。
description	プラグインの概要を説明です。
plugin_code	プラグインを判別するためのコードです。プラグインを更新する際に同一のプラグインかのチェックのために利用します。
version	バージョン番号です。
author	開発者名です。
type	固定で `form` を入力します。
help	プラグイン変数設定画面からリンクをされるプラグインのヘルプページのURLです。

設定(config)

項目名	説明
path	プラグイン変数の設定画面のHTMLファイルのパスです（独立したページとして表示されます）。

リソース(customize)

項目名説明

js 申請書画面で読み込まれるカスタムJavaScriptファイルを配列で指定します。
※typeには file または URL と記述してください。
※pathにはプラグインのルートフォルダーからのパス、または https://... から記述してください。
※カスタムファイルが存在しない場合には空の配列 [] で定義をしてください。

css 申請書画面で読み込まれるカスタムCSSファイルを配列で指定します。
記述方法については、jsと同じです。

JavaScriptファイルの作成

マニフェストファイルで定義したJavaScriptファイルを作成します。このJavaScriptファイルは、実際に新規申請時などの申請画面で実行されるファイルです。デモプラグインではjsフォルダーに保存されているindex.jsというJavaScriptファイルです。
JavaScriptファイルでは、JavaScript APIが利用できます。JavaScript APIについては、JavaScript APIの記事をご参照ください。

コラボフロー JavaScript API を利用する

プラグインでは、フォーム毎に設定を持つことができます。申請書画面ではその設定値を取得する関数などが利用可能です。

(function() {
    "use strict";
    /**
      * 有効なメールアドレスかチェックします。
      *
      * @param {*} mailAddress
    */
    function isValidMailAddress(mailAddress) {
        const validMailRegex = /^[a-zA-Z0-9!#$%&'*+\/=?^_`{|}~-]+(\.[a-zA-Z0-9!#$%&'*+\/=?^_`{|}~-]+)*@[a-zA-Z0-9_.-]+\.[a-zA-Z0-9]+$/;

        if (!validMailRegex.test(mailAddress)) {
            return false;
        }
        // 連続するドットが含まれる場合は無効
        if (mailAddress.indexOf('..') !== -1) {
            return false;
        }

        return true;
    }

    // プラグイン関数のインスタンスの作成
    const pluginInstance = new collaboflow.plugin();

    // 申請内容確認ボタンクリックイベント
    collaboflow.events.on('request.input.check', function (e) {
        // プラグインの設定値を取得
        pluginInstance.getSetting("common").then((response) => {
            const target = response.settings.plugin_settings.target;
            const mailAddress = e.parts[target].value;
            if (isValidMailAddress(mailAddress)){
                return true;
            }
            alert('項目「メールアドレス」に入力されたメールアドレスが不正です。');
            return false;
        });
    });
})();

申請書画面で呼び出せる関数一覧

プラグイン

項目名	説明	戻り値
collaboflow.plugin.getSettings()	プラグイン変数をすべて取得します。	Promise<Object>
collaboflow.plugin.getSetting(formVersion)	指定した版のプラグイン変数を取得します。パラメータとしてフォームの版番号を指定すると、版に紐づいたプラグイン変数を取得できます。	Promise<Object>

フォーム

項目名	説明	戻り値
collaboflow.form.getFormID()	現在開いているフォームのIDを取得します。	string
collaboflow.form.getFormVersion()	現在開いている申請書のフォーム版番号を取得します	number

プラグイン変数の設定画面を作成

プラグイン設定画面のページを作成します。HTMLファイルとJavaScriptファイルを作成します。デモプラグインでは、マニフェストファイルと同じフォルダに保存をされているindex.htmlというHTMLファイルと、js/settigsフォルダーに保存されているsettings.jsというJavaScriptファイルです。

HTMLファイル

表示するHTMLファイルを作成します。HTMLファイル内にscriptを直接記述するのではなく、外部スクリプトの参照指定をします。

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>プラグイン設定エディター</title>
    <script src="js/settings/settings.js"></script>
    <style>
        .plugin-editor {
            height: 50px;
            width: 100%;
        }
    </style>
</head>
<body>
    <h2>メールアドレス検証プラグイン設定</h2>
    <div class="plugin-editor">
        <select id="select-box"></select>
        <button id="save-button">保存</button>
    </div>
</body>
</html>

JavaScriptファイル

HTMLファイルで実行するJavaScriptファイルを作成します。
プラグイン変数はcollaboflow.plugin.saveSettings()関数で保存できます。対象とするフォームのパーツ情報を取得する場合はcollaboflow.form.getFormItems()関数で取得をすることができます。

設定画面のJavaScriptファイルでは、DOMContentLoadedイベントが実行された後にプラグインライブラリが利用可能となります。

/**
 * プラグイン設定画面の初期化処理
 * フォームのパーツ一覧を取得し、設定済みの値をセレクトボックスに反映します。
 */
async function initializePlugin() {
  // 1. 操作対象となるUI要素（DOM）を取得
  const saveButton = document.getElementById('save-button');
  const targetSelect = document.getElementById('select-box');

  // 要素が存在しない場合はエラーを避けるため処理を中断
  if (!saveButton || !targetSelect) return;

  try {
    // 2. フォームのパーツ一覧を取得し、選択肢を構築
    const formItems = await collaboflow.form.getFormItems();
    const fragment = document.createDocumentFragment();

    for (const [fieldId, field] of Object.entries(formItems.parts)) {
      // テキスト形式のパーツのみを選択肢に追加
      if (field.type === 'text') {
        const option = new Option(field.name, fieldId); // (表示名, 値)
        fragment.appendChild(option);
      }
    }
    targetSelect.appendChild(fragment);

    // 3. 保存されている設定を取得してUIに反映
    const configResponse = await collaboflow.plugin.getSetting("common");
    // APIレスポンスから、保存されていたターゲットIDを安全に抽出
    const savedFieldId = configResponse?.settings?.plugin_settings?.target;

    if (savedFieldId) {
      targetSelect.value = savedFieldId;
    }

    // 4. 保存ボタンクリック時のアクションを定義
    saveButton.addEventListener('click', async () => {
      const selectedId = targetSelect.value;
      const selectedName = targetSelect.selectedOptions[0]?.text;

      try {
        // 設定を保存
        await collaboflow.plugin.saveSettings({ target: selectedId });
        alert(`「${selectedName}」を対象として保存しました。`);
      } catch (error) {
        alert('保存に失敗しました。');
        console.error('Save failed:', error);
      }
    });

  } catch (error) {
    console.error('Initialization failed:', error);
  }
}

// ページの読み込みが完了したタイミングで初期化を実行
document.addEventListener('DOMContentLoaded', initializePlugin);

プラグイン変数設定画面で呼び出せる関数一覧

ユーザー

項目名	説明	戻り値
collaboflow.getLoginUser()	現在操作をしているユーザーの情報を取得します。	Promise<Object>

プラグイン

項目名	説明	戻り値
collaboflow.plugin.getSettings()	プラグイン変数をすべて取得します。	Promise<Object>
collaboflow.plugin.getSetting(formVersion)	指定した版のプラグイン変数を取得します。パラメータとしてフォームの版番号を指定すると、版に紐づいたプラグイン変数を取得できます。	Promise<Object>
collaboflow.plugin.saveSettings(settigs,formVersion)	プラグイン変数の保存をします。パラメーターのformVersionは省略が可能です。省略した場合には、版に紐づかない設定として保存されます。	Promise<Object>

フォーム

項目名	説明	戻り値
collaboflow.form.getFormItems(formVersion)	現在開いているフォームのパーツ情報を取得します。パラメーターformVersionは省略可能です。省略した場合には最新版のフォームのパーツ情報を取得します。	string
collaboflow.form.getFormVersion()	現在開いている申請書のフォーム版番号を取得します	number

プラグインのパッケージ化

マニフェストファイルなど必要なファイル、フォルダーを選択してZIP形式に圧縮をおこないます。
その際に、マニフェストファイルなどを含むフォルダーごとの圧縮ではなく、以下の画像のようにファイル・フォルダーを選択して圧縮してください。
ファイルの全選択

プラグインの利用

圧縮したファイルをコラボフローに登録し、フォーム側で設定をすることで利用可能となります。
詳しい設定方法はコラボフロープラグインのご利用方法をご参照ください。

制限事項

コラボフロープラグインは、コラボフロー JavaScript APIを利用しております。
このため、コラボフロー JavaScript APIでイベントの操作対象外のパーツは、コラボフロープラグインでも対象外となります。
該当するパーツについては、以下の記事をご参照ください。

パーツのデータと状態の操作

コラボフロープラグインのご利用方法

quickstart.zip
3 KB Download

事前準備

デモプラグインのダウンロード

マニフェストファイルの編集

マニフェストの項目一覧

プラグインの基本情報(package)

設定(config)

リソース(customize)

JavaScriptファイルの作成

申請書画面で呼び出せる関数一覧

プラグイン

フォーム

プラグイン変数の設定画面を作成

HTMLファイル

JavaScriptファイル

プラグイン変数設定画面で呼び出せる関数一覧

ユーザー

プラグイン

フォーム

プラグインのパッケージ化

プラグインの利用

制限事項

関連記事

コメント

この記事の内容