2022-09-05 / Questetra Developers Blog /
tutorial questetra form javascript api

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

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

1. フォーム画面でイベントを検知する

Questetra Form JavaScript API では、「フォーム画面でデータ項目の値が変更された」（change イベント）ことや「フォーム画面の表示が完了した」（ready イベント）ことを検知できます。

これらのイベントを検知した際に処理が行われるようなコードを記述することによって、「ボタンクリックで文字数をカウント」していた動作を「入力値が変更されたときに文字数をカウント」するように変更できます。

イベントを検知したときに処理が行われるようにするには、検知対象と処理を定義するイベントハンドラを登録する必要があります。この記事では、データ項目（入力フィールド）の change イベント、およびフォーム画面の ready イベントについて、イベントハンドラの利用方法を学びます。

  • フォーム画面上のデータ項目の change イベントハンドラの登録／削除
  • フォーム画面の ready イベントハンドラの登録／削除

利用可能なイベントハンドラの詳細は、リファレンス「R2132: Questetra Form JavaScript API」を参照ください。

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

入力された文字数をカウントする処理を、データ項目（入力フィールド）の change イベント発生時に動作させるように実装します。この実装を通じて、「Questetra Form Javascript API」を利用してフォーム画面上のデータ項目にイベントハンドラを登録／削除する方法を学びます。

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

ボタンクリック時に次の処理を行うサンプルコードを記述します。

  • ［イベント登録］ボタンクリックで、データ項目「テキスト入力」の change イベントハンドラを登録する
    • change イベント発火時に、入力された文字列の文字数をカウントし、カウント結果をデータ項目「文字数」にセットする
  • ［イベント削除］ボタンクリックで、データ項目「テキスト入力」から change イベントハンドラを削除する
    • change イベント発火時の処理を無効化する

「Questetra Form JavaScript API」では、次の形式でデータ項目へのイベントハンドラの登録／削除を行います。

  • データ項目へ change イベントハンドラを登録する
    • qbpms.form.on(
      ‘change’,
      ‘{データ項目のフィールド名}’,
      {イベントハンドラ} );
  • データ項目から changeイベントハンドラを削除する
    • qbpms.form.off(
      ‘change’,
      ‘{データ項目のフィールド名}’,
      {イベントハンドラ} );

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

本章で扱う “change” イベントは、HTMLにおけるchangeイベントとは厳密には異なります。
たとえば、qbpms.form.set( ‘{データ項目のフィールド名}’, {設定したい値} ); 実行時（ロストフォーカスしない時）でも、change イベントハンドラは発火します。

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>

コード設定後、「H1. Input」工程のプレビュー画面を表示します。データ項目「文字数」の下に［イベント登録］［イベント削除］の2つのボタンが追加されていれば、設定完了です。

2.2.1 Form Preview

2.2. 動作確認

記述したスクリプトの動作確認を行いましょう。「H1. Input」工程のプレビュー画面を開いてください。

データ項目「テキスト入力」に適当な文字を入力し、change イベントを発火させてみましょう（入力フィールドからフォーカスを外す）。まだ「文字数」には入力された文字数が表示されません。なぜならば、この時点では「テキスト入力」の change イベントハンドラが未登録で有効となっていないため、文字数カウントの処理は動作しません。

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

改めて、「テキスト入力」に適当な文字を入力し、change イベントを発火させましょう。今度は、「テキスト入力」の change イベントが発火するたびに、「文字数」へ入力された文字数が表示されるようになりました。

では次に、［イベント削除］ボタンをクリックしてください。 これで change イベントハンドラが削除され、文字数カウント処理が呼び出されなくなりました。
「テキスト入力」の change イベントを発火させても、文字数カウント処理が行われなくなっています。

データ項目に change イベントハンドラを登録／削除することで、イベント発火時に動作させる処理の実行制御を行うことができました。

3. フォーム画面の ready イベント

［イベント登録］ボタンクリック時に行なっていた change イベントハンドラの登録を、フォーム画面表示時に自動的に行われるように変更します。この実装を通じて、「Questetra Form Javascript API」を利用してフォーム画面に ready イベントハンドラを登録する方法を学びます。

フォーム画面表示時に次の処理を行うサンプルコードを記述します。

  • フォーム画面の ready イベントハンドラを登録する
    • ready イベント発火時に、データ項目「テキスト入力」の change イベントハンドラが登録される
      • change イベント発火時に、入力された文字列の文字数をカウントし、カウント結果をデータ項目「文字数」に設定するようにする

「Questetra Form JavaScript API」では、次の形式でフォーム画面へのイベントハンドラの登録／削除を行います。

  • フォーム画面へ ready イベントハンドラを登録する
    • qbpms.form.on(
      ‘ready‘,
      {イベントハンドラ});
  • フォーム画面から ready イベントハンドラを削除する
    • qbpms.form.off(
      ‘ready‘,
      {イベントハンドラ} );

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

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();

// フォーム ReadyEvent ハンドラ削除処理の実行
// qbpms.form.off('ready', user_registerHandlers); // コメントアウト、処理無効
</script>

コード設定後、「H1. Input」工程のプレビュー画面を表示します。データ項目「文字数」の下から［イベント登録］［イベント削除］の2つのボタンが消えていれば、設定完了です。

2.3.1 Form Preview

3.2. 動作確認

記述したスクリプトの動作確認を行いましょう。「H1. Input」工程のプレビュー画面を開いてください。

「テキスト入力」に適当な文字を入力して change イベントを発火させてみましょう。 フォーム画面の表示が完了した際（ready イベント発火時）に「テキスト入力」へ change イベントハンドラ登録が行われているので、文字数のカウント処理が自動的に行われるようになっています。

ボタンクリック等を行わなくても、フォーム画面表示とともに入力文字数のカウント処理が動作するようになりました。画面表示時に処理が利用できるようなっていることで、処理担当者のユーザビリティが向上していますね。

サンプルでは触れていませんが、コード qbpms.form.off(‘ready’, user_registerHandlers); を実行させれば、入力文字数をカウントする処理の登録を無効化できます。サンプルコードを改変して、フォーム画面のイベントハンドラの削除にもチャレンジしてみてください。

本記事では、「Questetra Form Javascript API」を利用してフォーム画面上のデータ項目やフォーム画面自体にイベントハンドラを登録／削除する方法を学びました。
次は、これまで学んだことを活用して、フォーム画面上で独自の入力チェックを実装します。

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