R2132: Questetra Form JavaScript API

 

タスク処理画面（入力フォーム）にて、入力フィールドから値を取得したり、値を代入したりする際に利用できる API です。イベントハンドラを登録することもできます。
なお、製品特性として「DOMツリーの構築」には一定の時間を要してしまいます。イベント発火のタイミングは、ご配慮いただく必要があります。

1. 入力フィールドの値の取得／代入

1-1. Script の形式

値の取得

qbpms.form.get(フィールド名)

• フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
• フォームでの編集許可設定が、「読み書き」「表示のみ」で利用できます

値の代入

qbpms.form.set(フィールド名, データ型に応じた形式の値)

• フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
• データ型に応じた形式の値: （下記、「値の取得／設定時のオブジェクト」参照）
• フォームでの編集許可設定が、「読み書き」で利用できます
• フォームの表示上の値を変更するだけで、タスクの保存や完了をしない限りサーバ上の値は更新されません

1-2. 値の取得／代入時のオブジェクト

件名・文字型

• 取得：文字列
  • 値が未設定の場合、「読み書き」では "空文字列" 、「表示のみ」では null となります
• 代入：文字列
  • null をセットすると値がクリアされます

数値型

• 取得：Big オブジェクト
  • 値が未設定の場合、null となります
• 代入：Big オブジェクト / 文字列 / Number オブジェクト / 数値
  • 文字列の場合、設定値がそのまま入力フィールドにセットされます
  • 文字列以外の場合、設定値がデータ項目定義のフォーマットに従って変換された文字列が入力フールドにセットされます
  • null をセットすると値がクリアされます

Big オブジェクトについて

• new Big("文字列") でオブジェクトを生成できます
• toString() メソッドにて、文字列形式での値を取得できます
  • 文字列の形式：小数点ピリオド、桁区切り文字なし（例："1234.56"）
• 詳細は、big.js のドキュメントを参照ください

選択型

• 取得：オブジェクトの配列
  • オブジェクトは、value（選択肢ID）、display（表示ラベル）のプロパティを持ちます
  • 未選択の場合、空の配列となります
• 代入：文字列、または文字列の配列
  • 文字列は、選択肢ID
  • 単一選択（チェックボックス以外）で複数要素の配列を渡した場合は、先頭の値がセットされます
  • 空の配列、または null をセットすると値がクリア（選択が解除）されます

ユーザ型　（Ver. 14.0〜）

• 取得：ユーザを表すオブジェクト
  • id (数値)、name (名前：文字列)、email (メールアドレス：文字列) を属性として持ちます
  • 未選択の場合、null となります
• 代入：文字列
  • 文字列は、メールアドレス
  • 指定されたメールアドレスを持つユーザが値にセットされます
  • null をセットすると値がクリア（選択が解除）されます

組織型　（Ver. 14.0〜）

• 取得：組織を表すオブジェクト
  • id (数値)、name (名前：文字列)、email (メールアドレス：文字列) を属性として持ちます
  • 未選択の場合、null となります
  • 保持されている値が削除済みの組織の場合は、id が null となります
• 代入：文字列
  • 文字列は、組織名（名前）
  • 指定された名前を持つ組織が値にセットされます
  • null をセットすると値がクリア（選択が解除）されます

上記以外のデータ型

（利用いただけません）

1-3. Scriptのサンプル

件名

値取得のサンプル

let title = qbpms.form.get("title");

値代入のサンプル

let strTitle = "プロセスの件名";
qbpms.form.set("title", strTitle);

文字型

値取得のサンプル

let string = qbpms.form.get("q_string");

値代入のサンプル

qbpms.form.set("q_string1", "文字列");
qbpms.form.set("q_string2", "複\n数\n行\nの\n文字列");  //複数行

数値型

値取得のサンプル

let strNum = "null";
let obj = qbpms.form.get("q_numeric");
if (obj !== null) {
  strNum = obj.toString();
}

値代入のサンプル

qbpms.form.set("q_numeric1", "1001.101");
qbpms.form.set("q_numeric2", new Number("1002.102"));
qbpms.form.set("q_numeric3", new Big("1003.103"));
qbpms.form.set("q_numeric4", 1004.104);

選択型

値取得のサンプル

let array1 = qbpms.form.get("q_radioButton");
let display1 = array1[0].display; //表示ラベル

let array2 = qbpms.form.get("q_checkBox");
let value2 = array2[1].value; //2つ目の選択肢の選択肢ID

値代入のサンプル

qbpms.form.set("q_radioButton", "true");
qbpms.form.set("q_selectBox", ["true", "false"]); // ひとつ目 "true" がセットされる
qbpms.form.set("q_checkBox", ["true", "false"]);

ユーザ型　（Ver. 14.0〜）

値取得のサンプル

let userName = qbpms.form.get("q_user").name;

値代入のサンプル

qbpms.form.set("q_user", "[e-mail]");

組織型　（Ver. 14.0〜）

値取得のサンプル

let orgId = qbpms.form.get("q_org").id;

値代入のサンプル

qbpms.form.set("q_org", "営業部");

上記以外のデータ型

（利用いただけません）

2. イベントハンドラの登録と削除

* Questetra で利用しているものとの競合を避けるため、独自の関数の名前／要素の ID は "user_" ではじまるように定義してください

2-1. フォーム全体のイベント

2-1-1. Script の形式

イベントハンドラの登録

qbpms.form.on(イベントタイプ, イベントハンドラ)

イベントハンドラの削除

qbpms.form.off(イベントタイプ, イベントハンドラ)

• イベントタイプ: "ready"
• イベントハンドラ: function（パラメータは一つでイベントオブジェクト）

2-1-2. イベントタイプ

ready

• フォームが表示され、フォーム API が利用できる状態になれば発火する
• フォーム表示後に登録した場合は、即座にイベントハンドラが実行される
• イベントオブジェクトは固定

2-1-3. Script のサンプル

処理フォーム画面表示時にメッセージダイアログに「Hello world!」を表示

function user_readyHandler(e) {
  window.alert("Hello world!");
}

qbpms.form.on('ready', user_readyHandler);

2-2. データ項目のイベント

2-2-1. Script の形式

イベントハンドラの登録

qbpms.form.on(イベントタイプ, フィールド名, イベントハンドラ)

イベントハンドラの削除

qbpms.form.off(イベントタイプ, フィールド名, イベントハンドラ)

• イベントタイプ: "change"
• フィールド名: "title" or "q_field_name"（データ項目のフィールド名）
• イベントハンドラ: function（パラメータは一つでイベントオブジェクト）

2-2-2. イベントタイプ

change

• 読み書きのデータ項目で、入力フィールドの値が変更されたら発火する
• 手動での値変更に加え、qbpms.form.set() で値を更新した場合にも発火する
• 対応しているデータ型
  • 件名 / 文字型 / 数値型 / 選択型 / ユーザ型* / 組織型*
  • *: Ver. 14.0〜
• イベントオブジェクトのプロパティ
  • type: "change"
  • varName: フィールド名
  • value: 更新後の値（qbpms.form.get() で取得されるものと同じ）

2-2-3. Script のサンプル

対象のデータ項目の値が変更されたときにメッセージダイアログを表示

function user_addedQbpmsEvent(e) {
  window.alert("値が更新されました：" + e.value);
}

qbpms.form.on('change', 'q_string1', user_addedQbpmsEvent);

---

Notes

参照：選択した社員の情報を複数のデータ項目に自動入力する―Questetra Professional エディションで実現する場合