5.2.7.4. 属性の DOM 表現の変更

kc 接頭辞付きのアノテーションを設定することで、追加のクライアント側の動作を有効にできます。この種類のアノテーションは、属性の対応する要素内の data- という接頭辞が付いた HTML 属性に変換されます。同じ名前のスクリプトが動的ページに読み込まれるため、カスタムの data- 属性に基づいて DOM から要素を選択し、それに応じて DOM 表現を変更して要素を装飾することができます。

たとえば、属性に kcMyCustomValidation アノテーションを追加すると、HTML 属性 data-kcMyCustomValidation が属性の対応する HTML 要素に追加され、<THEME TYPE>/resources/js/kcMyCustomValidation.js にあるカスタムテーマから JavaScript モジュールがロードされます。カスタム JavaScript モジュールをテーマにデプロイする方法の詳細は、サーバー開発者ガイド を参照してください。

JavaScript モジュールは任意のコードを実行して、DOM と各属性に対してレンダリングされる要素をカスタマイズできます。そのためには、次のように userProfile.js モジュールを使用して、カスタムアノテーションのアノテーション記述子を登録します。

import { registerElementAnnotatedBy } from "./userProfile.js";

registerElementAnnotatedBy({
  name: 'kcMyCustomValidation',
  onAdd(element) {
    var listener = function (event) {
        // do something on keyup
    };

    element.addEventListener("keyup", listener);

    // returns a cleanup function to remove the event listener
    return () => element.removeEventListener("keyup", listener);
  }
});

registerElementAnnotatedBy は、アノテーション記述子を登録するメソッドです。記述子は、アノテーション名を参照する name と onAdd 関数を持つオブジェクトです。ページがレンダリングされるか、アノテーション付きの属性が DOM に追加されるたびに、onAdd 関数が呼び出され、要素の動作をカスタマイズできるようになります。

onAdd 関数は、クリーンアップを実行する関数を返すこともできます。たとえば、要素にイベントリスナーを追加する場合、要素が DOM から削除されたときにイベントリスナーを削除することもできます。

userProfile.js がニーズに合わない場合は、任意の JavaScript コードを使用することもできます。

document.querySelectorAll(`[data-kcMyCustomValidation]`).forEach((element) => {
    var listener = function (evt) {
        // do something on keyup
    };

    element.addEventListener("keyup", listener);
  });