フォーム画面で「Questetra Form JavaScript API」を利用する

PAGE UPDATED

本記事の内容は、次の3つの記事に分割・再編集されております。新しい記事を参照ください。

PAGE UPDATED
1. フォーム画面をカスタマイズする
2. Questetra Form JavaScript API を利用する
3. まとめ

1. フォーム画面をカスタマイズする

Questetra BPM Suite では、HTML / JavaScript を利用して、フォーム画面をデコレーションしたり、カスタマイズしたりすることができます。

データ入力時の注意事項など説明文を表示する
表示する文字を装飾する
参考にするサイトへのリンクを表示する
入力文字数を自動でカウントする
オリジナルの入力チェックを追加する　　　　　　　etc.

フォーム画面のデコレーションやカスタマイズは、（ガイドパネル型を含む）データ項目設定の［説明］欄に、HTMLやJavaScriptを記述することで行います。JavaScript を用いたカスタマイズでは、「Questetra Form JavaScript API」を利用することが可能です（ Professional 以上）。

「Questetra Form JavaScript API」を利用すると、次のことを実現できます。

入力フィールドの値の取得／代入
入力フィールドへの change イベントハンドラの登録／削除
フォームへの ready イベントハンドラの登録／削除

次章ではサンプルコードを通じて、「Questetra Form JavaScript API」の実際の使い方を説明します。

「Questetra Form JavaScript API」は動作保証されていますが、それ以外の JavaScript コードの動作は保証されておりません。将来バージョンにおいて動作や振る舞いが変わる可能性もございますので、利用される際には、将来のメンテナンス（保守）の必要性も考慮のうえ、ご利用ください。

2. Questetra Form JavaScript API を利用する

2.0. 事前準備）ワークフローアプリを新規作成する

ワークフローアプリを新規作成し、編集画面を開いてください。

2.0.1.　ワークフロー図の設定

「ワークフロー図」タブで、1つのスイムレーンと、開始イベント・ヒューマンタスク・終了イベントを1つずつ配置してください。ヒューマンタスクは「H1. Input」とタスク名を変更しておきましょう。

2.0.2. データ項目の設定

データ項目を、次のように追加・設定します。

データ項目名	タイプ	データフィールド名	必須	「H1. Input」工程	備考
テキスト入力	文字 (複数行)	q_Input_Text	‐	編集可	ここに文字を入力します。
文字数	文字 (単一行)	q_Characters_Count	‐	編集可	入力文字数のカウント結果を表示します。

2.0.3. 設定後の確認

［フォームプレビュー］ボタンを押して、フォームプレビュー画面を開いてください。
プレビュー画面でデータ項目［テキスト入力］［文字数］がそれぞれ、入力フィールドとして画面表示されていれば、設定完了です。

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

この節では、ボタンがクリックされると入力された文字数がカウントされる処理を、フォーム画面に組み込みます。この実装を通して、「入力フィールドの値の取得／代入」方法を学びます。

「Questetra Form JavaScript API」を用いた記述方法は、下記になります。

入力フィールドから値を取得する
- const value = qbpms.form.get( ‘{データ項目のフィールド名}’ );
入力フィールドへ値を代入する
- qbpms.form.set( ‘{データ項目のフィールド名}’, {代入したい値} );

※値の取得／代入に対応するデータ型、取得した／代入したい値のデータ型や制限などの詳細は、リファレンス「R2132: Questetra Form JavaScript API」をご確認ください。

2.1.1. コードの設定

データ項目［文字数］の設定画面にて、［説明］欄に下記のコードを貼り付け、［適用して保存］してください。

<button type="button" onclick="user_countInputText()">文字数カウント</button> 
<script>
// 文字数カウント処理
function user_countInputText(){

  // 「テキスト入力」データ項目の値の取得
  const strInputText = qbpms.form.get('q_Input_Text');

  // 文字数のカウントと、文字数の値を「文字数」データ項目へ設定
  qbpms.form.set('q_Characters_Count', strInputText.length);
}
</script>

このコードでは、次の処理を行っています。

ボタン［文字数カウント］の追加と、ボタンクリック時処理の設定
［文字数カウント］ボタンクリック時処理の関数「user_countInputText()」の定義
- 入力フィールド［テキスト入力］から入力された値を取得する
- 入力された文字数をカウントし、入力フィールド［文字数］へ設定する

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

コードを設定すると、入力フィールド［文字数］の下に［文字数カウント］ボタンが追加されます。フォームプレビュー画面を再読込して確認してください。

［文字数カウント］ボタンが追加されたことまで確認したら、ここで一度、ワークフローアプリの［リリース］を行ってください。

2.1.2. 動作確認

組み込んだコードの動作確認を行いましょう。ワークフローアプリのプロセスを「新規開始」し、「H1. Input」タスク処理画面を開いてください。

入力フィールド［テキスト入力］に適当な文字を入力し、［文字数カウント］ボタンをクリックしてください。入力フィールド［文字数］に、入力フィールド［テキスト入力］に入力した文字の数が表示されました。

［文字数カウント］ボタンをクリックするたび入力した文字数が表示されるように、処理を追加することができました。

2.2. 入力フィールドへのイベントハンドラの登録／削除

この節では、入力された文字数をカウントする処理を、入力フィールドの change イベント発生時に動作するようにします。この実装を通じて、「入力フィールドへのイベントハンドラの登録／削除」方法を学びます。

「Questetra Form JavaScript API」を用いた記述方法は、下記になります。

入力フィールドへイベントハンドラを登録する
- qbpms.form.on(
  ‘change’,
  ‘{データ項目のフィールド名}’,
  {イベント発生時に呼び出すFunction} );
入力フィールドからイベントハンドラを削除する
- qbpms.form.off(
  ‘change’,
  ‘{データ項目のフィールド名}’,
  {イベント発生時に呼び出すFunction} );

※ get/set ではなく、on/off であることに注意してください。

2.2.1. コードの設定

データ項目［文字数］の［説明］欄に、下記のコードを上書きで貼り付け、［適用して保存］してください。

<button type="button" onclick="user_registerHandlers()">イベント登録</button>
<button type="button" onclick="user_deregisterHandlers()">イベント削除</button> 
<script>

// 「テキスト入力」データ項目 ChangeEvent ハンドラ登録処理
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// 「テキスト入力」データ項目 ChangeEvent ハンドラ削除処理
function user_deregisterHandlers(){
  qbpms.form.off('change', 'q_Input_Text', user_countInputText);
}

// 文字数カウント処理
function user_countInputText(){

  // 「テキスト入力」データ項目の値の取得
  const strInputText = qbpms.form.get('q_Input_Text');

  // 文字数のカウントと、「文字数」データ項目へ文字数の値を設定
  qbpms.form.set('q_Characters_Count', strInputText.length);
}
</script>

このコードでは、次の処理を行っています。

ボタン［イベント登録］［イベント削除］の追加と、それぞれのボタンのクリック時処理の設定
追加したそれぞれのボタンクリック時に呼び出される、イベントハンドラの登録用／削除用関数の定義
1. 関数「user_registerHandlers()」は、入力フィールド［テキスト入力］へchangeイベントハンドラを登録する
2. 関数「user_deregisterHandlers()」は、入力フィールド［テキスト入力］からchangeイベントハンドラを削除する
関数「user_countInputText()」は、入力された文字数のカウント処理

コードを設定すると、［文字数カウント］ボタンが消え、代わりに［イベント登録］［イベント削除］の2つのボタンが表示されます。フォームプレビュー画面を再読込して確認してください。

ボタンが変更されたことまで確認したら再度、ワークフローアプリを［リリース］してください。

2.2.2. 動作確認

組み込んだコードの動作確認を行いましょう。ワークフローアプリのプロセスを「新規開始」し、「H1. Input」タスク処理画面を開いてください。

入力フィールド［テキスト入力］に適当な文字を入力してからフォーカスを移動させて、［テキスト入力］のchangeイベントを発生させてみましょう。入力フィールド［文字数］には、入力された文字数が表示されないと思います。実はこの段階では、入力フィールド［テキスト入力］のchangeイベント発生時の処理がまだ登録されていません。

ここで［イベント登録］ボタンをクリックしてください。これで changeイベント発生時処理が登録されたことで、文字数カウントが行われるようになりました。

改めて、入力フィールド［テキスト入力］に適当な文字を入力してみましょう。［テキスト入力］のchangeイベントが発生するたびに都度、入力フィールド［文字数］へ入力された文字数が表示されるようになりました。

では次に、［イベント削除］ボタンをクリックしてください。これで changeイベント発生時処理が削除され、文字数カウント処理が無効化されました。入力フィールド［テキスト入力］に適当な文字を入力しフォーカスを移動させて［テキスト入力］のchangeイベントを発生させても、今度は文字数カウント処理が行われなくなりました。

changeイベント発生時に都度入力した文字数が表示されるという処理の追加や削除を行うことができました。

さらに学習を進めましょう。

2.3. フォーム画面への ready イベントハンドラの登録／削除

この節では、入力された文字数をカウントする処理の登録を、フォーム画面の ready イベント発生時に行わせることにチャレンジします。
このチャレンジで、「フォーム画面への ready イベントハンドラの登録／削除」方法を学びます。

「Questetra Form JavaScript API」を用いた記述方法は、下記になります。

フォーム画面へ ready イベントハンドラを登録する
- qbpms.form.on(
  ‘ready‘,
  {イベント発生時に呼び出すFunction} );
フォーム画面から ready イベントハンドラを削除する
- qbpms.form.off(
  ‘ready‘,
  {イベント発生時に呼び出すFunction} );

※ change ではなく、ready イベントであること、データ項目が引数に含まれないことに注意してください。

2.3.1. コードの設定

データ項目［文字数］の［説明］欄に、下記のコードを上書きで貼り付け、［適用して保存］してください。

<script type="text/javascript">

// 文字数カウント処理
function user_countInputText(){

  // 「テキスト入力」データ項目の値の取得処理
  const strInputText = qbpms.form.get('q_Input_Text');

  // 文字数のカウントと、「文字数」データ項目へ文字数の値を設定
  qbpms.form.set('q_Characters_Count', strInputText.length);
}

// 「テキスト入力」データ項目 ChangeEvent ハンドラ登録処理
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// フォーム ReadyEvent ハンドラ登録処理
function user_onReady(){
  qbpms.form.on('ready', user_registerHandlers);
}

// フォーム ReadyEvent ハンドラ登録処理の実行
user_onReady();

</script>

このコードでは、次の処理を行っています。

フォーム画面へのreadyイベントハンドラの登録
1. フォームで ready イベント発生時に関数「user_registerHandlers()」を呼び出し、入力フィールド［テキスト入力］のchangeイベントハンドラを登録している
入力フィールド［テキスト入力］の changeイベント発生時に、文字数カウントの処理の関数「user_countInputText()」が実行される

コードを設定すると、2.2.1で表示された［イベント登録］［イベント削除］の2つのボタンが消え、2.0.3 の事前準備段階のワークフローアプリと同じ見た目に戻ります。フォーム画面（プレビュー）を再確認してください。

ボタンが削除されたことまで確認したら再度、ワークフローアプリを［リリース］してください。

2.3.2. 動作確認

組み込んだコードの動作確認を行いましょう。ワークフローアプリのプロセスを「新規開始」し、「H1. Input」タスク処理画面を開いてください。

入力フィールド［テキスト入力］に適当な文字を入力してからフォーカスを移動させて、［テキスト入力］のchangeイベントを発生させてみましょう。フォームの ready イベント(すなわち画面描画)時に、changeイベント発生時の文字数カウント処理が登録されているため、入力フィールド［文字数］の文字数のカウント処理が、何かしらのボタンをクリックするまでもなく、自動的に行われるようになりました。

何かのボタンをクリックしなくても自動的に入力文字数をカウントしてくれるようになりました。いままでの実装してきた内容より、さらにユーザビリティが向上したと思います。

2.4. 応用編) フォーム画面で独自の入力チェックを行う

今までのサンプルの実践を通して得た知識を元に、応用編にチャレンジしましょう。
フォーム画面に、クライアントサイドでの独自の数値チェックを組み込んでみます。

2.4.1. データ項目の追加

新たに、次のようにデータ項目を追加してください。

データ項目名	タイプ	選択肢種別/選択肢	データフィールド名	必須	「H1. Input」工程	備考
数値	数値	‐	q_num	‐	編集可	［小数点以下の桁数］は不問です。
数値の条件	選択(ラジオボタン)	［選択肢種別］は「固定の選択肢」、［選択肢］の内容CSVは下記のとおり。「>=0,0 以上 <=10,10 以下」	q_condition	‐	編集可	［依存する親データ項目］は設定不要です。

2.4.2. コードの設定

追加したデータ項目［数値］の［説明］欄に、下記のコードを貼り付け、［適用して保存］してください。

<div id="user_num_error">
 数値が条件を満たしていません
</div> 
<script>
qbpms.form.on('ready', () => {

    // ここは関数スコープなので、関数定義名称は"user_"始まりでなくても構いません。

    // エラーの表示・非表示
    const setErrorVisible = (visible) => {
        const span = document.getElementById('user_num_error');
        span.style.visibility = visible ? 'visible' : 'hidden';
    };

    // バリデーション処理
    const validateNum = () => {
        const num = qbpms.form.get('q_num');
        if (num === null) {
            return;
        }
        const condition = qbpms.form.get('q_condition')[0];
        switch (condition.value) {
            case '>=0':
                // num < 0 ならエラー表示
                setErrorVisible(num.lt(0));
                break;
            default:
                // num > 10 ならエラー表示
                setErrorVisible(num.gt(10));
        }
    };

    // ChangeEventハンドラ登録
    qbpms.form.on('change', 'q_num', () => {
        validateNum();
    });
    qbpms.form.on('change', 'q_condition', () => {
        validateNum();
    });

    // 画面初期表示時のバリデーション実施
    validateNum();
});
</script>

このコードでは、次の処理を行っています。

フォーム画面へ ready イベントハンドラの登録、フォームの ready イベント発生時処理（無名関数）の定義は下記のとおり。
1. バリデーション用関数「validateNum()」
2. バリデーション結果を受けての、エラーメッセージの表示/非表示の切替用関数「setErrorVisible()」
3. 入力フィールド［数値］へ change イベントハンドラを登録する処理
4. 入力フィールド［数値の条件］へ change イベントハンドラを登録する処理

ここまで準備ができたら再度、ワークフローアプリを［リリース］してください。

2.4.3. 動作確認

組み込んだコードの動作確認を行いましょう。ワークフローアプリのプロセスを「新規開始」し、「H1. Input」タスク処理画面を開いてください。

まず、入力フィールド［数値の条件］ラジオボタンで選択肢 ”0 以上” を選択し、入力フィールド［数値］に値 ”-1″ を入力してからフォーカスを移動させて changeイベントを発生させましょう。［数値］に入力されている値は、［数値の条件］を満たさないので、バリデーションエラー「数値が条件を満たしていません」が表示されます。

次に、入力フィールド［数値］の値を “11” に変更入力してchangeイベントを発生させましょう。　今度は［数値の条件］を満たすので、バリデーションエラー「数値が条件を満たしていません」が非表示になります。

この状態で、入力フィールド［数値の条件］ラジオボタンで選択肢 “10 以下” を選択してみましょう。　再度［数値の条件］を満たさなくなるので、バリデーションエラー「数値が条件を満たしていません」が再表示されます。

入力フィールド［数値］［数値の条件］のそれぞれの changeイベント発生時に、［数値］と［数値の条件］の入力内容でバリデーションを実施し、エラーであればエラーメッセージが表示されるようになりました。
数値と数値の条件を入力内容を変更したり、あるいは選択肢の内容／コード中のswitch ～ case文を追加・変更するなどし、メッセージ表示／非表示の切り替えなど挙動確認をしてください。

3. まとめ

いかがでしたか？ここまでサンプルコードを実際に動かしてみて、「Questetra Form JavaScript API」の使い方が理解できたかと思います。

こういった、クライアントサイドでの独自の入力チェックの追加といったフォーム画面のカスタマイズは、ユーザビリティの向上に役立ちます。
（タスク処理ボタン押下後の後工程での、入力不備チェック → タスク差し戻し、といったケースを減らせる　etc.）

「Questetra Form JavaScript API」は、アイデア／使い方次第で、フォーム画面をもっと便利にカスタマイズすることが可能です。ぜひ、フォーム画面のカスタマイズにチャレンジしてみてください。

フォーム画面で「Questetra Form JavaScript API」を利用する

PAGE UPDATED

1. フォーム画面をカスタマイズする

2. Questetra Form JavaScript API を利用する

2.0. 事前準備）ワークフローアプリを新規作成する

2.0.1.　ワークフロー図の設定

2.0.2. データ項目の設定

2.0.3. 設定後の確認

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

2.1.1. コードの設定

2.1.2. 動作確認

2.2. 入力フィールドへのイベントハンドラの登録／削除

2.2.1. コードの設定

2.2.2. 動作確認

2.3. フォーム画面への ready イベントハンドラの登録／削除

2.3.1. コードの設定

2.3.2. 動作確認

2.4. 応用編) フォーム画面で独自の入力チェックを行う

2.4.1. データ項目の追加

2.4.2. コードの設定

2.4.3. 動作確認

3. まとめ

いいね:

Related

Questetra BPM Suite

フォーム画面で「Questetra Form JavaScript API」を利用する

PAGE UPDATED

1. フォーム画面をカスタマイズする

2. Questetra Form JavaScript API を利用する

2.0. 事前準備）ワークフローアプリを新規作成する

2.0.1. ワークフロー図の設定

2.0.2. データ項目の設定

2.0.3. 設定後の確認

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

2.1.1. コードの設定

2.1.2. 動作確認

2.2. 入力フィールドへのイベントハンドラの登録／削除

2.2.1. コードの設定

2.2.2. 動作確認

2.3. フォーム画面への ready イベントハンドラの登録／削除

2.3.1. コードの設定

2.3.2. 動作確認

2.4. 応用編) フォーム画面で独自の入力チェックを行う

2.4.1. データ項目の追加

2.4.2. コードの設定

2.4.3. 動作確認

3. まとめ

共有:

いいね:

Related

Questetra BPM Suite

2.0.1.　ワークフロー図の設定