LoaderEvents 概要
Yellowfin 9.4では、「loaderEvents」APIを通して、JavaScript APIにカスタマイズされたローダーを追加するオプションを有効にしました。
これらのローダーは、コードモードやウィンドウオブジェクトによるカスタムヘッダー使用時にも利用可能です。
これにより、開発者はYellowfin要素内の要素にローダーが追加、または削除されているインスタンスをリッスンし、そのイベントに応答することができます。
以下のように、実行できる様々なアクションがあります。
- Yellowfin ローダーが追加されるのを防ぎ、同じ要素にカスタムローダーを追加します。
- 異なる関連する要素にローダーを添付します。
- ローダーの追加や削除をログに記録します（開発段階で役に立ちます）。
例えば、Yellowfinをホワイトラベル化して使用している企業は、Yellowfinのデフォルト設定である青い丸ではなく、独自のブランドに対応したローダーアイコンを使用したいと考えるかもしれません。
注意：LoaderEvents APIの性質により、固有のプロパティや関連するイベントはありません。
関数リファレンス
yellowfin.loaderEvents
Yellowfin API init()の呼び出しが完了したら、yellowfin.loaderEvents関数が利用できるようになります。これは、listenとstopListeningの2つの基礎的な関数を提供し、必要に応じてローダーイベントを設定、または削除することができます。また、一度に複数の子ローダーの置き換えを簡略化するために、interceptChildLoadersForElementとstopListeningToElementInterceptという2つの関数が用意されています。
注意: コードモードまたはカスタムヘッダーでこの関数を使用するには、「yellowfin.loaderEvents」を「window.loaderEvents」に切り替えてください。
listen(listenObject)
これは、渡されたlistenObject オブジェクトを使用して、ローダーイベントリスナーを作成します。
listenObject オブジェクトには、次のパラメーターが含まれます。
| パラメーター | 型 | 説明 | 追加情報 |
| selector | String | リスナーを作成するオブジェクトのCSS セレクターです。すべてのローダーをインターセプトする場合は、セレクター「html *」を使用します。 | イベントリスナーが作成されないエラーを回避するためには、selectorかelementのどちらかが定義されている必要があります。この2つのうち、selcorを定義するのが望ましいです。 |
| element | HTML Element | ローダーが追加されたことを確認するためのHTML elementです。これはloaderに追加されたelementが、ここで定義されたelementと同じである場合のみ、イベントをトリガーします。 | オプションで、selectorを定義する代わりになります。 |
| onAdd | 関数 | Yellowfinが、セレクターに一致する要素にローダーを追加する直前に呼び出される関数です。LoaderEventは、このコールバック関数に渡されます。 | onAdd、またはonRemoveのいずれかを定義する必要があります。必要に応じて、両方を定義することも可能です。どちらも定義されていない場合はエラーが発生し、イベントリスナーは作成されません。 |
| onRemove | 関数 | Yellowfin コードが、セレクターに一致する要素からローダーを削除する直前のコールバック関数です。LoaderEventは、このコールバック関数に渡されます。 | onAdd、またはonRemoveのいずれかを定義する必要があります。必要に応じて、両方を定義することも可能です。どちらも定義されていない場合はエラーが発生し、イベントリスナーは作成されません。 |
stopListening(listenObject)
ローダーイベントを削除します。渡されるlistenObjectは、listen関数に渡されたオブジェクトとまったく同じでなくてはならず、これが異なる場合、リスナーは削除されません。
interceptChildLoadersForElement(element, listenObject)
この関数が呼び出されると、Yellowfinは子ローダーをもつすべてのElementを遮り、それらのローダーを子ではなく渡されたElementに適用します。
interceptChildLoadersForElementのlistenObjectパラメータは、loaderEvents.listenのlistenObjectパラメータと同様に動作します。onAdd関数は、渡された要素に初めてローダーが追加されたときに呼び出され、onRemove関数は、渡された要素からローダーが削除されたときに呼び出されます。
以下のサンプルコードでは、ページ内の任意の場所に追加されたローダーを探し、代わりにbodyタグに追加しています。
yellowfin.loaderEvents.interceptChildLoadersForElement(document.querySelector('body'), {
onAdd: function(e) { console.log('loader added to body') },
onRemove: function(e) { console.log('loader removed from body') }
});
stoplisteningToElementIntercept (listenObject)
interceptChildLoadersForElement()リスナーは、stopLingentToElementIntercept()関数を使って削除することができます。リスナーを止めたいelementのみを渡します。
LoaderEvents.stopListeningToElementIntercept(document.querySelector('body'))
LoaderEvent
onAdd、またはonRemove関数が呼び出される度に、LoaderEvent オブジェクトが作成されます。これには、ローダーが追加される要素と、イベントの処理方法を操作できるいくつかの関数が含まれます。同じElementでinterceptChildLoadersForElementが複数回呼び出された場合、最初のアプリケーションのみが使われます。
LoaderEvent.element
これはローダーが追加、または削除される要素です。
LoaderEvent.preventDefault()
このイベントは、ローダーが要素に追加、または要素から削除されるのを防ぎます。
例えば、イベントリスナーを以下のように初期化できます。
yellowfin.loaderEvents.listen({
selector: ‘html *’,
onAdd: function(event) {
event.preventDefault();
}
});
これにより、Yellowfin 要素にローダーは追加されません。これ単独では特に役に立ちませんが、独自にカスタマイズしたローダーを追加するコードと、preventDefaultを組み合わせることができます。
デフォルトを回避するonRemove関数のみを含むイベントリスナーを作成すると、次のようになります。
yellowfin.loaderEvents.listen({
selector: ‘html *’,
onRemove: function(event) {
event.preventDefault();
}
});
これにより、要素からローダーが削除されるの防ぎます。そのため通常は、onRemove関数でローダーの削除を自分で処理する場合にのみ、削除時にpreventDefaultを使用してください。
LoaderEvent.setOverrideElement(element)
LoaderEvent オブジェクトに渡された要素ではなく、標準的なYellowfin ローダーを追加する要素を定義します。
これにより、標準的なYellowfin ローダーを親要素上に置くことができます。この関数を使用する場合は、onAdd、およびonRemove関数の両方でsetOverrideElementを定義しなくてはいけません。
yellowfin.loaderEvents.listen({
selector: ‘report-output > div’, //Listen for loaders on immediate children of all reports
onAdd: function(event) {
event.setOverrideElement(event.element.parentNode); //Adds a loader to the parent node of the passed element
},
onRemove: function(event) {
event.setOverrideElement(event.element.parentNode); //Removes the loader from the parent node
}
});