Published — v. 5
/
フィルター API

フィルター API

Owned by YUKA SAITO
Last updated: Apr 16, 2021Version comment


フィルターAPIは、大きく2つの項目に分けられます。

  • フィルター API：これは、フィルターコンテナーオブジェクトと、その中のすべてのフィルター（ひとつ、または複数のフィルター）に関する機能を指します。
  • フィルターオブジェクト API：これは、個別のフィルターに関する機能を指します。



フィルター概要

フィルターはYellowfin内で使用され、レポートに返されるデータを、ユーザーが興味のあるものに制限します（例えば、期間を制限することで返されるデータを前四半期のみにしたり、国の一覧を制限することでユーザーの担当する地域のみを表示します）。一般的なフィルターやその作成方法について、より詳細な情報は、こちらを参照してください。

ダッシュボードおよびレポートオブジェクトは、両方ともオブジェクトフィルターを含みます。このオブジェクトには、ユーザープロンプトフィルターとして設定された任意のフィルターが含まれます。これは実行時に、ユーザーが値を変更できるフィルターです。レポート上のハードコードされたフィルターには、APIを通してアクセスすることはできません。


フィルターオブジェクトには、次の方法でアクセスできます。

レポートの場合：

report.filters


ダッシュボードの場合：

dashboard.filters


このフィルター APIには、開発者がフィルターを操作できるようにする様々な方法だけでなく、コンテンツの一部に対して使用可能なすべてのユーザープロンプトフィルターが含まれています。また、フィルター内の変更にアプリケーションが対応できるようにするための、数多くのイベントを起動することができます。


フィルター値の仕組み

フィルターは一般的に、特定の日付フィールドや、ディメンション（次元）フィールド（国、製品）、メトリック（数値）（売上、費用、利益率）など、制限されるデータベースカラム（列）に関連しています。値はフィルターに対して設定され、これらの値は返されるデータを制限するために、データベースクエリーに渡されます。

フィルター値には、2つの状態があります。ステージング（または正常）と適用済みです。

適用済みの値は、クエリー結果をフィルタリングするために、レポートやダッシュボードで現在使用されている値です。APIがgetAppliedValueを使用するときはいつでも、これらの値を参照しています。

ステージングフィルター値は、フィルターに設定されてはいるが、レポート出力に適用されていない値です。例えば、「ツアータイプ」フィルターで、ユーザーが値に「アドベンチャー」を選択すると、フィルターのステージング値が「アドベンチャー」に設定されます。APIがsetValueや、getValueを使用するときはいつでも、フィルターのステージング値を参照しています。これは、フィルターが適用されるまで、レポートやダッシュボードには反映されません。

フィルターの中には、defaultValues（デフォルト値）を持つ場合はありますが、これは常に読み取り専用です。


値の理解

このリファレンスドキュメントと、フィルターオブジェクトリファレンスオブジェクトを通して、異なる値オブジェクトへのリファンレスが表示されます。

例：valueOne、valueTwo、appliedValueOne

Yellowfinは、レポート実行時に、これらの値を使用して正確にフィルター値を適用します。

ValueOneは、単一の入力オプションを持つフィルターの値を参照します（等しい、異なる、など）。これは、間演算子（〜の間、〜の間ではない）の低い方の値にも使用されるため、間演算子を使用する場合、ValueOneは、常にValueTwoよりも低くなります。

ValueListは、一覧演算子（一覧に含む、一覧に含まない）に使用される値であり、文字列、または数値の配列です。


レポートフィルターとダッシュボードフィルターの違い

機能的な観点から、レポートフィルターとダッシュボードフィルターオブジェクトには、わずかな違いがあります。ダッシュボードフィルターオブジェクトは、複数のレポートをひとつのフィルターにリンクできるリンクオブジェクトがあるため、多くのレポートに使用できます。

Yellowfinでダッシュボードを構築する場合、まずはダッシュボードにレポートを追加し、それらのレポートからダッシュボードへフィルターを追加します。詳細は、こちらを参照してください。

ダッシュボードに追加されたフィルターは、最初のインスタンスでレポートフィルターから派生している場合でも、固有のフィルターIDを割り当てられます。このダッシュボードフィルターは、元のレポートフィルターへのリファレンスを維持し続けます。レポートフィルターに追加された変更は、ダッシュボードフィルターに反映されます。

UUIDを使用してレポートフィルターを参照するコードがあれば、そのUUIDを使用して、レポートフィルターオブジェクトにアクセスすることができます。

report.filters.getFilter('47fe96c2-5101-4b0d-9018-7d12a84d3519');

そのレポートやフィルターがダッシュボードに追加された場合、同様のコードを使用してダッシュボードフィルターにアクセスすることはできなくなります。これは、レポートとフィルターの複数のインスタンスが、ダッシュボード上で同時にアクティブになる可能性があるため、これらはすべてダッシュボードフィルターUUIDに参照されるためです。

dashboard.filters.getFilter('47fe96c2-5101-4b0d-9018-7d12a84d3519'); //Will return null 



プロパティのリファレンス

API機能を活用するために、フィルターオブジェクトに関連付けられたプロパティにアクセスする必要はありません。



関数のリファレンス

getFilter (filterId)（フィルターの取得）

リターン

フィルターオブジェクト

説明

渡されたフィルターIDのフィルターオブジェクトを取得します。一致するfilterIdが無い場合は、nullが返されます。

パラメーター

filterId - (String, Number)

アクセスするフィルターの名前、またはUUIDです。

例

「Demographic」という名前のフィルターを取得します。

let filter = filters.get('Demographic');
console.log(filter.name, filter.uuid); //Output the name of the filter as well as its UUID


UUIDを使用してフィルターを取得します。

let filter = filters.get('47fe96c2-5101-4b0d-9018-7d12a84d3519');
console.log(filter.name, filter.uuid); //Output the name of the filter as well as its UUID


getAllFilters()（すべてのフィルターを取得）

リターン

Object - {String, FilterObject}

説明

フィルターAPI が適用されているコンテンツのすべてのユーザープロンプトフィルターを含むオブジェクトを返します。このオブジェクトは、フィルターUUIDによりキー設定されています。

注意・制限

この関数は、フィルター APIで利用可能なフィルターを確認するのに有効です。特定のフィルターを探している場合は、getAllFilters()[uuid]ではなく、filters.getFilter(filterId)の使用を推奨します。これは、getFiltersがUUID、または名前を受け付けるからです。すべてのフィルターを反復処理する場合は、代わりにfilters.forEach(fn)の使用を推奨します。


forEach(fn)

リターン

なし

説明

フィルター API内のすべてのフィルターオブジェクトを反復処理し、各反復で個別のフィルターオブジェクトを渡しながら、渡されたfnを呼び出します。

パラメーター

fn - ループの各反復を呼び出す関数です。

例

適用されたすべての値の一覧を作成できます。

let appliedFilterValues = [];
filters.forEach(filter => {
          appliedFilterValues.push(Object.assign({
                    name: filter.name,
                    uuid: filter.uuid,
           }, filter.appliedValues));

これにより、適用されたフィルター値の一覧が作成され、フィルターの名前とUUIDもオブジェクトに含まれます。


hasFilters()

リターン

Boolean

説明

コンテンツにユーザープロンプトフィルターがある場合、trueを返します。それ以外は、falseを返します。

例

フィルター APIにフィルターがあるかどうかに基づき、カスタムフィルターパネルジェネレーターを呼び出します。

if(filters.hasFilters()) {
          generateMyCustomFilterPanel(filters);
}


clearFilter(filterId)（フィルターのクリア）
リターン

なし

説明

値をクリアし、渡されたfilterIdに関連するフィルターオブジェクトから、すぐに空の値を適用します。フィルターIDに一致するフィルターが見つからない場合は、何も起きません。

パラメーター

filterId - (String)

クリアするフィルターのUUID、または名前です。


clear()（クリア）

リターン

なし

説明

フィルター APIに含まれるすべてのフィルターオブジェクトの値をクリアし、空のフィルター値を適用します。



applyFilters()（フィルターの適用）

リターン

なし

説明

すべてのステージング値を適用されたフィルターオブジェクトにコピーし、これに影響受けるすべてのレポートを実行します。適用されたイベントのトリガーになります。

例

Average Age at CampとDemographicを設定し、それらを適用します。

let demographic = filters.getFilter('Demographic');
let ageAtCamp = filters.getFilter('Average Age at Camp');

demographic.setValue(['Adventure']);
ageAtCamp.setValue([15, 35]);

filters.applyFilters();


または、ページ上のボタンがクリックされたときに、フィルターを適用します。

document.querySelector('div#applyButton').addEventListener('click', function(e) {
          filters.applyFilters();
});


LoadFilters()（フィルターのロード）

リターン

Promise

説明

サーバからフィルターデータをリロードします。フィルターがロードされると、Promiseが解決されます。


resetFiltersToDefault()（フィルターをデフォルト値にリセット）

リターン

なし

説明

すべてのフィルターをデフォルト値にリセットします。

例

filters.resetFiltersToDefault();


addEventListener(eventName, callbackFunction)（イベントリスナーの追加）

リターン

Number

説明

特定のイベントが発生するたびにcallbackFunctionを呼び出すイベントにリスナーを作成します。

イベントが設定されると、固有のIDが割り当てられ、この関数の結果として返されます。このIDは、removeEventListener関数により使用され、コールバックが終了したときにこれを削除します。レポートのロードおよびアンロードを必要とするアプリケーションを作成する場合は、これらのリスナーIDをトラッキングし、不要になったときに削除できるようにすることを推奨します。

API自体がトリガーするイベントの詳細については、フィルター API#イベントのリファレンス項目を参照してください。

また、開発者が独自のイベントをトリガーすることも可能であり（.trigger()参照）、この関数を使用してリッスンすることができます。

例

変更されたオブジェクトにリスナーを作成し、イベントが発生したらこれを削除します。

let eventListenerId = filters.addEventListener('changed', function(event) {
          console.log('One of my filters changed');
          filters.removeEventListener(eventListenerId);
});


removeEventListener(listenerId)（イベントリスナーを削除）

リターン

なし

説明

渡されたリスナーIDに関連するコールバック関数を削除します。これは、このコールバック関数に関連するイベントが発生したときに、そのコールバックは起動されなくなることを意味します。

例
let eventListenerId = filters.addEventListener('changed', function(event) {
          console.log('One of my filters changed');
          filters.removeEventListener(eventListenerId);
});


trigger(eventName, eventData)（トリガー）

リターン

なし

説明

フィルター API上のイベントをトリガーし、そのイベント用に作成された任意のリスナー関数を呼び出します。これを使用して、アプリケーション用に設定したカスタムイベントのトリガーに使用できます。

例

カスタムフィルター入力を使用する場合、フィルタークリックイベントをトリガーして、アプリケーションの別の部分が反応できるようにすることができます。

//Add a 'userClick' listener to the filter object, which we will set up a trigger for later on.
filters.addEventListener('userClick', function(event) {
         console.log('A user clicked on the element ' + event.element + ' which is tied to this filter');
});
//Get the custom filter list from the DOM and create a click listener on that which will trigger userClicked events on the filter
let myCustomFilterList = document.querySelector(‘div#customFilterList’)
myCustomFilterList .addEventListener('click', function(e) {
         filters.trigger('userClicked', { element: e.currentTarget } );
});



イベントのリファレンス

フィルター API内で自動的にトリガーされる、ユーザーが実行するアクション、または呼び出される関数に関連するイベントが多数あります。これらのイベントにはすべて、次の構造が含まれます。

  • eventName - String - トリガーされたイベントの名前です。
  • filterEvents - Array{Object} - このフィルター一覧変更イベントを構成するイベントの配列です。オブジェクトには少なくとも、次が含まれます。
    • uuid - 変更されたフィルターのUUIDです。
    • filter - このイベントを発生させたフィルターオブジェクトです。
    • 他の一部のフィルターイベントには、さらに多くの情報を含めることができます。各イベントのイベントオブジェクトについて、より詳細な情報は、フィルターオブジェクトを参照してください。


changed（変更）

説明

フィルター API内のいずれかのフィルターオブジェクトがステージング値を変更したときに発生します。

パラメーター

Event - Object

次を含みます。

  • eventName - "changed"
  • filterEvents - Array{Object} - 変更されたイベントをトリガーするフィルター APIに貢献する変更イベントオブジェクトの配列です。

例

let filters = report.filters;

filters.addEventListener('changed', function(event) {
             console.log(event.eventName); //'changed'
             console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject, changed: Object, previous Object }, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);


applied（適用）

説明

フィルター API内のいずれかのフィルターに異なる値が適用されたときに発生します。これは、ユーザーが適用ボタンをクリックしたとき、またはapplyFilters関数が呼び出された時に発生します。

パラメーター

Event - Object

次を含みます。

  • eventName - "applied"
  • filterEvents - Array{Object} - 適用されたイベントをトリガーするフィルター APIに貢献する適用イベントオブジェクトの配列です。

例

let filters = report.filters;

filters.addEventListener('applied', function(event) {
             console.log(event.eventName); //'applied'
             console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject, changed: Object, previous Object }, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);

filters.applyFilters();


reset（リセット）

説明

フィルター API内のいずれかのフィルターオブジェクトがリセットされたときに発生します。

パラメーター

Event - Object

次を含みます。

  • eventName - "reset"
  • filterEvents - Array{Object} - リセットされたイベントをトリガーするフィルター APIに貢献するリセットイベントオブジェクトの配列です。

例

let filters = report.filters;

filters.addEventListener('reset', function(event) {
             console.log(event.eventName); //'changed'
             console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject}, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);
filters.resetFiltersToDefault();

filters.getFilter('Demographic').reset(); //Trigger reset on an individual filter


cleared（クリア）

説明

フィルター API内のいずれかのフィルターオブジェクトがクリアされた時に発生します。

パラメーター

Event - Object

次を含みます。

  • eventName - "cleared"
  • filterEvents - Array{Object} - クリアされたイベントをトリガーするフィルター APIに貢献するクリアイベントオブジェクトの配列です。

例

let filters = report.filters;

filters.addEventListener('reset', function(event) {
             console.log(event.eventName); //'changed'
             console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject}, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);

filters.applyFilters();