カスタム・ウィジェットの JavaScript API

search メソッドは、特定のデータ・ソースに対して検索を実行し、検索結果を取得します。検索結果を取得するための使用方法としては、「パブリッシュ/サブスクライブ検索」と「コールバック検索」の 2 つがあります。

パブリッシュ/サブスクライブ検索では、以下に示すように、複数の UI ウィジェット間で検索結果を共有するためにパブリッシュ/サブスクライブ設計パターンと同様のメカニズムが使用されます。

検索 API は、特定のデータ・ソースに対して検索を実行し、検索結果は DsState と呼ばれるグローバル・データ・ソース状態に格納されます。検索結果に関心のあるすべてのウィジェットで、データ・ソースを listen し、onSearch ライフサイクル・メソッドを介して検索結果を取得できます。

コールバック検索では、コールバック・メソッドをパラメーターとして取り、コールバック・メソッドを使用して検索結果を取得します。この場合、検索 API の呼び出し元はコールバックから直接結果を取得し、DsState は関与しません。したがって、検索結果は他のウィジェットとは共有されません。検索結果は、呼び出し元ウィジェットによってのみ消費されます。

カスタム・ウィジェットのコード・エディター (「カスタム」 > 「編集」 > 「コードの編集」 > 「設定」) で「データ・ソースの検索」にチェック・マークを付け、検索するデータ・ソースを選択すると、検索 API は、指定のデータ・ソースに対して検索要求を実行します。

search メソッドには 2 つの多重定義シグニチャーがあります。最初のシグニチャーには sendTo パラメーターがありません。カスタム・ウィジェットのコード・エディター UI の「データ・ソースの検索」設定で指定したデータ・ソースで検索が実行されます。2 番目のシグニチャーには sendTo パラメーターがあります。sendTo パラメーターで指定したデータ・ソースで検索が実行されます。sendTo パラメーターは、データ・ソースの作成時に指定したデータ・ソース ID の配列です。データ・ソース ID は文字列です。「データ・ソースの管理」からデータ・ソースを開いて確認できます。データ・ソース定義 JSON の key プロパティーの値としてデータ・ソース ID が表示されます。

sendTo パラメーターを指定すると、「データ・ソースの検索」設定に関係なく常に検索が実行されます。ただし、sendTo で指定するデータ・ソースは、プロジェクト・データ・ソース (つまり、「データ・ソースの管理」ビューで選択したデータ・ソース) でなければなりません。sendTo 内のデータ・ソースがプロジェクト・データ・ソースでなければ、無視されます。

UI の「データ・ソースの検索」設定または sendTo パラメーターで複数のデータ・ソースを指定した場合、「パブリッシュ/サブスクライブ検索」モードでは、そのすべてのデータ・ソースで検索が実行されます。「コールバック検索」モードでは、最初のデータ・ソース (UI で選択した一番上のチェック・ボックスまたは sendTo 配列の最初のエレメント) だけが使用されます。

メソッド

search(query: string, params?: object, callback?: function, errback?: function): void

search(query: string, sendTo?: string[], params?: object, callback?: function, errback?: function): void

パラメーター

表 1. サマリー

名前	タイプ	説明
query	string	照会ストリング
send To?	string[ ]	検索を実行するデータ・ソースの配列
params?	object	検索パラメーターのキーと値のペアが含まれている JavaScript オブジェクト。
callback?	function	検索が成功したときに呼び出される関数。
errback?	function	検索が失敗したときに呼び出される関数。

query (string)

単純なキーワード検索に加え、Apache Solr 照会構文を使用できます。

sendTo (string[ ])

検索を実行するデータ・ソースの配列。

params (object)

検索パラメーターのキーと値のペアが含まれている JavaScript オブジェクト。

page: number

要求するページ番号。デフォルトは 1 です。

pageSize: number

API が照会に対して返す検索結果の最大数。指定されない場合、データ・ソース定義で定義されているデフォルト値が使用されます。

sort: object[]

ソート定義の配列。各定義に column および dir プロパティーが含まれます。dir はソート方向を示し、昇順ソートの場合は asc、降順ソートの場合は desc を指定します。

verb: string

REST サービス・エンドポイント URL を構成するために使用されるストリング。oneWEX データ・ソースでは、query を指定できます。このプロパティー値があると、検索 API は、queryParams を使用して低レベルの REST API 呼び出しを実行します。

queryParams: object

REST エンドポイントの低レベル照会パラメーター。verb が指定された場合、REST エンドポイント URL の照会ストリングは queryParams のみを使用して構成されます。

以下に 2 つの例を示します。

• {page: 1, pageSize: 10, sort:[{ "column": "title", "dir": "asc" }]}
• {verb: "query", queryParams: {q: "ice", start: 0, rows: 10}}

callback (function)

function(payload: object) というシグニチャーのコールバック関数。ペイロード・オブジェクトには、以下のデータが含まれます。

page: number

要求したページ番号。

pageSize: number

要求した検索結果の最大数。

query: string

要求した照会ストリング。

searchResults: object

正規化された検索結果。

items: object[]

正規化された検索結果項目の配列。

itemsRaw: object[]

元の検索結果項目の配列。

totalCount: number

照会の合計ヒット数。

searchResultsRaw: object

バックエンドから返される元の検索結果全体。

戻り値

ありません。

いくつかの例を示します。

Pub-Sub 検索の例

mySearchHandler(ev, props) {
  props.search('ice');
},

コールバック検索の例

mySearchHandler(ev, props) {
  props.search('ice', null, function(payload) {
    var items = payload.searchResults.items;
    for (var i = 0; i < items.length; i++) {
      console.log(items[i]);
    }
  });
},

2 番目のページを取得する例

mySearchHandler(ev, props) {
  props.search('ice', {page: 2});
},

複数のデータ・ソースに対するパブリッシュ/サブスクライブ検索の例。

mySearchHandler(ev, props) {
  props.search('ice', ['voc', 'nhtsa']);
},

指定したデータ・ソースに対するコールバック検索の例。

コールバック検索の場合は、sendTo パラメーター内の最初のデータ・ソースだけが使用されます。この例では、voc だけが使用され、nhtsa は無視されます。

mySearchHandler(ev, props) {
  props.search('ice', ['voc', 'nhtsa'], null, function(payload) {
    var items = payload.searchResults.items;
    for (var i = 0; i < items.length; i++) {
      console.log(items[i]);
    }
  });
},

selectItem メソッドは、指定された文書を選択します。DsState と呼ばれるグローバル・データ・ソース状態を更新します。データ・ソースを listen しているすべてのウィジェットが、この更新に反応する可能性があります。例えば、文書明細ビューのウィジェットでは、新たに選択された文書が表示されます。

メソッド

selectItem(uniqueId: any): void

パラメーター

uniqueId (any)

固有の文書 ID。文書の uniqueId プロパティーから取得できます。

戻り値

ありません。

例

props.selectItem(uniqueId);

addDefaultParams メソッドは、既存の検索パラメーターにデフォルトの検索パラメーターを追加します。 指定したパラメーターは、DsState というデータ・ソース状態に保管され、それ以降の検索 API 呼び出しで使用されます。sendTo を省略すると、UI の「検索するデータ・ソース」が使用されます。

メソッド

props.addDefaultParams(params: any, sendTo?: any[]): void

パラメーター

params (any)

追加するデフォルトの検索パラメーターが含まれている JavaScript オブジェクト。

sendTo? (string)

ターゲット・データ・ソースの配列。

戻り値

ありません。

例

props.addDefaultParams({sort:[{ 'column':'date', 'dir':'asc' }]});

setDefaultParams メソッドは、デフォルトの検索パラメーターを設定します。既存のパラメーターは破棄されます。指定したパラメーターは、DsState というデータ・ソース状態に保管され、それ以降の検索 API 呼び出しで使用されます。sendTo を省略すると、UI の「検索するデータ・ソース」が使用されます。

メソッド

props.setDefaultParams(params: any, sendTo?: any[]):void

パラメーター

params (any)

設定するデフォルトの検索パラメーターが含まれている JavaScript オブジェクト。

sendTo? (string)

ターゲット・データ・ソースの配列。

戻り値

ありません。

例

props.setDefaultParams({sort:[{ 'column':'date', 'dir':'asc' }]});

getDefaultParams メソッドは、デフォルトの検索パラメーターを取得します。dsId を省略すると、UI の「検索するデータ・ソース」の最初の項目が使用されます。

メソッド

props.getDefaultParams(dsId?: string | number): any

パラメーター

dsId? (string または number)

データ・ソース ID。

戻り値

デフォルトの検索パラメーター。

例

var params =props.getDefaultParams()

like メソッドは、指定された文書に投票し、like としてマークします。この API を使用するには、「検索結果の listen」チェック・ボックスが選択され、かつ、listen するデータ・ソースが選択されている必要があります。選択されたデータ・ソースに対してのみ、API から要求が行われます。

メソッド

like(uniqueId: any): void

パラメーター

uniqueId (any)

固有の文書 ID。文書の uniqueId プロパティーから取得できます。

戻り値

ありません。

例

onSelect: function(props) {
  props.like(props.selectedItem.uniqueId);
}

dislike メソッドは、指定された文書に投票し、dislike としてマークします。この API を使用するには、「検索結果の listen」チェック・ボックスが選択され、かつ、listen するデータ・ソースが選択されている必要があります。選択されたデータ・ソースに対してのみ、API から要求が行われます。

メソッド

dislike(uniqueId: any): void

パラメーター

uniqueId (any)

固有の文書 ID。文書の uniqueId プロパティーから取得できます。

戻り値

ありません。

例

onSelect: function(props) {
  props.dislike(props.selectedItem.uniqueId);
}

rate メソッドは、指定した文書に対する 5 つ星評価の値の票を投じます。この API を使用するには、「検索結果の listen」チェック・ボックスが選択され、かつ、listen するデータ・ソースが選択されている必要があります。選択されたデータ・ソースに対してのみ、API から要求が行われます。

メソッド

rate(value: number, uniqueId: any): void

パラメーター

value (number)

星の数。

uniqueId (any)

固有の文書 ID。文書の uniqueId プロパティーから取得できます。

戻り値

ありません。

例

onSelect: function(props) {
  props.rate(3, props.selectedItem.uniqueId); // three stars
}

sendClick メソッドは、指定された文書のクリック数を増分する要求を行います。この API を使用するには、「検索結果の listen」チェック・ボックスが選択され、かつ、listen するデータ・ソースが選択されている必要があります。選択されたデータ・ソースに対してのみ、API から要求が行われます。

メソッド

sendClick(uniqueId: any): void

パラメーター

uniqueId (any)

固有の文書 ID。文書の uniqueId プロパティーから取得できます。

戻り値

ありません。

例

onSelect: function(props) {
  props.sendClick(props.selectedItem.uniqueId);
}

startRender メソッドは、HTML タブで HTML テンプレートのレンダリングを開始します。このメソッドを使用するには、「HTML の自動レンダリング」設定がチェック解除されている必要があります。

メソッド

startRender(data: object): void

パラメーター

data (object)

テンプレートに適用される JavaScript オブジェクト。

戻り値

ありません。

例

この例では、2 秒の遅延の後にテンプレートにデータが渡されます。

setTimeout(function(){
  props.startRender({text: 'JavaScript'});
}, 2000);

渡されたデータには、HTML テンプレートから JavaScript 変数としてアクセスできます。

<h1>Hi <%= text %>!</h1>

openTab メソッドは、ページ ID で指定されたタブ・ページを開きます。

メソッド

openTab(tab: string): void

パラメーター

tab: (string)

開くページ ID

戻り値

ありません。

例

myClickHandler: function(ev, props) {
  props.openTab('home');
}

loadScript メソッドは、URL で指定された外部 JavaScript コードを非同期にロードします。ロードが完了すると、オプションのコールバック関数が呼び出されます。

メソッド

loadScript(url: string, callback?: function): void

パラメーター

url (string)

外部 JavaScript ファイルの URL

callback (function)

JavaScript ファイルがロードされたときに呼び出される関数。

戻り値

ありません。

例

init: function(props) {
  var url = 'https://www.external.server.com/some/script.js';
  props.loadScript(url, function(){
    ...
  });
}

loadStyle メソッドは、URL で指定された外部スタイル・シート・ファイル (CSS) をロードします。

メソッド

loadStyle(url: string): void

パラメーター

string url

外部スタイル・シート・ファイルの URL

戻り値

ありません。

例

init: function(props) {
  var url = 'https://www.external.server.com/some/style.css';
  props.loadStyle(url);
}

publish API には、ウィジェット間の通信に使用できるシンプルなパブリッシュ/サブスクライブ・メカニズムが用意されています。デフォルトでは、サブスクライバーのコールバック関数は、現在のウィジェット・インスタンスの ID で登録されます。したがって、1 つのウィジェット・インスタンスから同じトピックへの複数のコールバックを登録する場合は、サブスクライブ・メソッドの 3 番目のパラメーターで uniqueId を指定する必要があります。

パブリッシャー・ウィジェットとサブスクライバー・ウィジェットは同じページに存在していなければなりません。非表示タブ内のウィジェット・インスタンスは、表示されるまで存在しないからです。

publish メソッドは、トピックとユーザー・データをパブリッシュします。

メソッド

props.publish(topic: string, args?: any):void

パラメーター

topic (string)

トピック名。

args? (any)

パブリッシュするデータ。

戻り値

ありません。

例

props.publish('topic#1', {myData:input.value});

subscribe メソッドは、特定のトピックへのサブスクライバーのリストにコールバック関数を登録します。

メソッド

props.subscribe(topic: string, callback:function, uniqueId?: string): void

パラメーター

topic (string)

トピック名。

callback (any)

トピックのパブリッシュ時に呼び出されるコールバック関数。

uniqueId? (string)

コールバックを登録するための固有キー。デフォルトではウィジェット・インスタンスの ID が使用されます。

戻り値

ありません。

例

props.subscribe('topic#1', function(args) { console.log(args.myData); });

unsubscribe メソッドは、特定のトピックからコールバック関数の登録を解除します。

メソッド

props.unsubscribe(topic: string, uniqueId?: string):void

パラメーター

topic (string)

トピック名。

uniqueId? (string)

コールバックの登録を解除するための固有キー。デフォルトではウィジェット・インスタンスの ID が使用されます。

戻り値

ありません。

例

props.unsubscribe('topic#1');

escapeHtml メソッドは、HTML 特殊文字を同等のエンティティーに変換します。

メソッド

props.escapeHtml(ml: string): string

パラメーター

topic (string)

トピック名。

uinqueID? (string)

コールバックの登録を解除するための固有キー。デフォルトではウィジェット・インスタンスの ID が使用されます。

戻り値

ありません。

例

var s =props.escapeHtml('<h1>'); ->"&lt;h1&gt;"

loadClusters メソッドは、現在の検索の結果から文書クラスターを取得する低レベルの oneWEX API です。操作は非同期で実行され、指定したコールバックに結果が返されます。コールバックを省略すると、結果は DsState というデータ・ソース状態に保管され、その変更がリスナーに通知されます。dsId を省略すると、UI の「listen するデータ・ソース」が使用されます。

メソッド

props.loadClusters(dsId?: string | number, callback?:function, errback?: function): void

パラメーター

dsID (string または number)

ターゲット・データ・ソースの ID。

callback? (function)

メソッドが成功したときに呼び出される関数。

errback? (function)

メソッドが失敗したときに呼び出される関数。

戻り値

ありません。

例

props.loadClusters(function(payload) { console.log(payload); });

loadRecommendedDocuments メソッドは、現在の検索に基づいて推奨文書を取得する低レベルの oneWEX API です。操作は非同期で実行され、指定したコールバックに結果が返されます。コールバックを省略すると、結果は DsState というデータ・ソース状態に保管され、その変更がリスナーに通知されます。sendTo を省略すると、UI の「検索するデータ・ソース」が使用されます。

メソッド

props.loadRecommendedDocuments(type: string, doc: any, sendTo?: any, callback?: any, errback?: any):void

パラメーター

type (string)

推奨のタイプ。sss (内容が類似した文書) または cf (同時に閲覧された文書) のどちらかです。

doc (any)

比較する文書。タイプが sss の場合にのみ有効です。

sendTo? (string[])

ターゲット・データ・ソースの配列。

callback? (function)

メソッドが成功したときに呼び出される関数。

errback? (function)

メソッドが失敗したときに呼び出される関数。

戻り値

ありません。

例

props.loadRecommendedDocuments('sss', {fields: fields});

loadRecommendedQueries メソッドは、現在の検索に基づいて推奨照会の文字列を取得する低レベルの oneWEX API です。操作は非同期で実行され、指定したコールバックに結果が返されます。コールバックを省略すると、結果は DsState というデータ・ソース状態に保管され、その変更がリスナーに通知されます。dsId を省略すると、 UI の「listen するデータ・ソース」が使用されます。

メソッド

props.loadRecommendedQueries(type: string, dsId?: string | number, callback?: any, errback?: any):void

パラメーター

type (string)

推奨のタイプ:

• term - 索引のワードまたは句
• correlated - 入力と相関するワードまたは句
• ontolection - 類似のコンテキストで使用されているワードまたは句
• spell - スペル修正

dsID? (string または number)

ターゲット・データ・ソースの ID。

callback? (function)

メソッドが成功したときに呼び出される関数。

errback? (function)

メソッドが失敗したときに呼び出される関数。

戻り値

ありません。

例

props.loadRecommendedQueries('correlated', function(payload) { console.log(payload); });