tutorial questetra form javascript api

フォーム画面のデコレーションで利用できる「Questetra Form JavaScript API」の基本的な使い方を次の3つの記事で学びます。

一連の記事は「フォーム画面で「Questetra Form JavaScript API」を利用する」を分割・再編集した内容になります。


1. フォーム画面に独自の処理を追加する

下記の2つの記事では、「Questetra Form JavaScript API」を利用して、フォーム画面でデータ項目の値を取得/更新したり、イベントハンドラを登録/削除したりする方法を学びました。

これらの機能(API)を活用することで、フォーム画面上で動作する独自の入力チェックや表示切り替えといった処理を実装することが可能となります。この記事では、一例として、ふたつのデータ項目が連動した入力チェックの方法について紹介します。

2. 選択内容に応じて数値チェックを行う

選択型データ項目(ラジオボタン)で選択された値に応じて、数値型データ項目の入力値が条件を満たしているかどうかをチェックする、独自の入力チェック機構を実装します。

ワークフローアプリは、「フォーム画面でデータ項目の値を取得/更新する」記事の「ワークフローアプリを準備する」セクションで作成したものを引き続き利用します。未作成の方は、先の記事を参考にサンプル用ワークフローアプリを新規作成してください。

2.1. データ項目の追加

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

項目名データタイプフィールド名選択肢種別/選択肢編集可否(「H1. Input」工程)
数値数値q_num編集可
数値の条件選択(ラジオボタン)q_condition・選択肢種別: 固定の選択肢
・選択肢(CSV 編集):
「>=0,0 以上
<=10,10 以下」
編集可

2.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>

コード設定後、「H1. Input」工程のプレビュー画面を表示します。データ項目「数値」の下に、「数値が条件を満たしていません」というメッセージが表示されていれば、設定完了です。

2.3. 動作確認

組み込んだコードの動作確認を行いましょう。「H1. Input」工程のプレビュー画面を開いてください。

選択型データ項目「数値の条件」には、「0 以上」「10 以下」のふたつの選択肢が表示されています。選択された選択肢に応じて、「数値」に入力された値がその条件を満たしているかどうかがチェックされます。

最初は「0 以上」を選択し、「数値」に値「-1」を入力してみてください(change イベントが発火するよう、入力フィールドからフォーカスを外します)。「数値」に入力されている値は「数値の条件」を満たしていないので、入力チェックエラーメッセージ「数値が条件を満たしていません」が表示されます。

次にデータ項目「数値」の値を「11」に変更してみます。今度は「数値の条件」を満たすようになったので、エラーメッセージ「数値が条件を満たしていません」が表示されなくなりました。

この状態で、「数値の条件」で選択肢「10 以下」を選択してみましょう。ふたたび「数値の条件」を満たさなくなったので、エラーメッセージ「数値が条件を満たしていません」が再表示されました。

データ項目「数値」「数値の条件」のそれぞれの change イベント発火時に、「数値」と「数値の条件」の入力内容で数値の妥当性チェックを実行しています。

「数値」と「数値の条件」の入力内容を変更したり、選択肢の内容/コード中のswitch ~ case文を追加・変更したりして、独自の入力チェックやメッセージ表示/非表示の切り替えなどの挙動を試してみてください。

「Questetra Form JavaScript API」は動作保証されていますが、それ以外の JavaScript コードの動作は保証されておりません。独自のチェックロジックなどを導入する際は、将来バージョンにおいて動作や振る舞いが変わる可能性がある点、ご留意ください。また、利用される際には、将来のメンテナンス(保守)の必要性も考慮のうえ、ご利用ください。

本記事では、「Questetra Form Javascript API」を利用してフォーム画面上で動作する独自の入力チェックの仕組みを実装しました。フォーム画面に独自の処理を追加することで、処理担当者の入力を支援したり、入力操作を軽減させたりすることが可能となります。

%d人のブロガーが「いいね」をつけました。