JavaScript API for custom widgets

The search method performs a search on a specific data source and gets the search result. There are two usages with regard to how you get the search result, "pub/sub search" and "callback search".

Pub/sub search uses a mechanism like publish/subscribe design pattern for sharing the search result among multiple UI widgets, as illustrated below.

The search API performs a search on a specific data source and the search result is stored in a global data source state called DsState. Any widgets that have an interest in the search result can listen to the data source and get the search result through the onSearch lifecycle method.

Callback search takes a callback method as a parameter and gets the search result through it. In this case, the caller of the search API gets the result directly through the callback and DsState is not involved. Therefore, the search result is not shared with the other widgets. The search result is consumed only by the caller widget.

In the Custom widget's code editor (Custom > Edit > Edit code > Settings), if you check Perform search on data source and choose a data source to search, the search API makes a search request to the specified data source.

The search method has two overloaded signatures. The first one does not have the sendTo parameter. It performs a search on data sources specified by the Perform search on data source setting in the Custom widget code editor UI. The second one has the sendTo parameter. It performs a search on data sources specified by the sendTo parameter. The sendTo parameter is an array of data source ids, which you specified when you created the data sources. Data source ids are strings, and can be found by opening a data source from Manage Data Sources. The value of the key property in the data source definition JSON shows a data source id.

If the sendTo parameter is given, a search is always performed regardless of the Perform search on data source setting. However, data sources specified by sendTo must be project data sources, i.e., the ones selected in the Manage Data Sources view. If a data source in sendTo is not one of the project data sources, it will be ignored.

If multiple data sources are specified either by the Perform search on data sourcesetting in the UI, or by the sendTo parameter, a search is performed on all of them when in the "pub/sub search" mode. When in the "callback search" mode, however, only the first data source (the top of the selected checkboxes in the UI, or the first element of the sendTo array) is used.

Method

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

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

Parameters

Table 1. Summary

Name	Type	Description
query	string	Query string
send To?	string[ ]	An array of data sources to perform search
params?	object	A JavaScript object that contains key-value pairs of search parameters.
callback?	function	A function that is called when the search is successful.
errback?	function	A function that is called when the search fails.

query (string)

In addition to simple keyword search, Apache Solr query syntax can be used.

sendTo (string[ ])

An array of data sources to perform search.

params (object)

A JavaScript object that contains key-value pairs of search parameters.

page: number

Page number to request. Default is 1.

pageSize: number

The maximum number of search results that the API will return for your query. If unspecified, the default value defined in the data source definition will be used.

sort: object[]

Array of sort definitions, where each definition contains the column and dir properties. dir indicates sort direction and takes either asc for ascending sort or desc for descending sort.

verb: string

A string that is used to construct the REST service endpoint URL. For oneWEX data sources, query can be specified. Having this property value tells the search API to make a low-level REST API call using queryParams.

queryParams: object

Low-level query parameters for the REST endpoint. When a verb is specified, the query string for the REST endpoint URL is constructed by using only the queryParams.

Two examples are shown here.

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

callback (function)

A callback function whose signature is function(payload: object). The payload object contains the following data.

page: number

The page number you requested.

pageSize: number

The maximum number of search results you requested.

query: string

The query string you requested.

searchResults: object

The normalized search results.

items: object[]

An array of normalized search result items.

itemsRaw: object[]

An array of the original search result items.

totalCount: number

The total hit count for the query.

searchResultsRaw: object

The entire original search result returned from the backend.

Returns

None.

Some examples are shown here.

Example of pub/sub search

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

Example of callback search

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]);
    }
  });
},

Example of getting the second page

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

Example of pub/sub search on multiple data sources.

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

Example of callback search on a specified data source.

For callback search, only the first data source in the sendTo parameter is used. In this example, only voc is used and nhtsa is ignored.

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]);
    }
  });
},

The selectItem method selects a specified document. It updates a global data source state called DsState. Any widgets that are listening to the data source may react to it. For example, document detail view widgets would show the newly selected document.

Method

selectItem(uniqueId: any): void

Parameters

uniqueId (any)

Unique document ID, which can be obtained from the uniqueId property of a document.

Returns

None.

Example

props.selectItem(uniqueId);

The addDefaultParams method adds the default search parameters to the existing ones. The given parameters will be stored in the data source state called DsState and used by subsequent search API calls. If sendTo is omitted, "Data sources to search" in the UI is used.

Method

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

Parameters

params (any)

A JavaScript object that contains default search parameters to add.

sendTo? (string)

An array of target data sources.

Returns

None.

Example

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

The setDefaultParams method sets the default search parameters. Existing parameters will be discarded. The given parameters will be stored in the data source state called DsState and used by subsequent search API calls. If sendTo is omitted, "Data sources to search" in the UI is used.

Method

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

Parameters

params (any)

A JavaScript object that contains default search parameters to set.

sendTo? (string)

An array of target data sources.

Returns

None.

Example

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

The getDefaultParams method gets the default search parameters. If dsId is omitted, the first one from "Data sources to search" in the UI is used.

Method

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

Parameters

dsId? (string or number)

Data source ID.

Returns

The default search parameters.

Example

var params =props.getDefaultParams()

The like method votes a specified document and marks as like. To use the API, the Listen to search results check box must be checked and a data source to listen to must be selected. The API makes a request only for the chosen data source.

Method

like(uniqueId: any): void

Parameters

uniqueId (any)

Unique document ID, which can be obtained from the uniqueId property of a document.

Returns

None.

Example

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

The dislike method votes a specified document and mark as dislike. To use the API, the Listen to search results check box must be checked and a data source to listen to must be selected. The API makes a request only for the chosen data source.

Method

dislike(uniqueId: any): void

Parameters

uniqueId (any)

Unique document ID, which can be obtained from the uniqueId property of a document.

Returns

None.

Example

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

The rate method votes a five-star rating value for a specified document. To use the API, the Listen to search results check box must be checked and a data source to listen to must be selected. The API makes a request only for the chosen data source.

Method

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

Parameters

value (number)

The number of stars.

uniqueId (any)

Unique document ID, which can be obtained from the uniqueId property of a document.

Returns

None.

Example

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

The sendClick method makes a request to increment click counts of the specified document. To use the API, the Listen to search results check box must be checked and a data source to listen to must be selected. The API makes a request only for the chosen data source.

Method

sendClick(uniqueId: any): void

Parameters

uniqueId (any)

Unique document ID, which can be obtained from the uniqueId property of a document.

Returns

None.

Example

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

The startRender method starts rendering HTML template in the HTML tab. To use this method, The Render HTML automatically setting should be unchecked.

Method

startRender(data: object): void

Parameters

data (object)

A JavaScript object to apply to a template.

Returns

None.

Example

This example passes data to the template after 2 second delay

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

The passed data can be accessed from HTML template as a JavaScript variable.

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

The openTab method opens a tab page specified by a page ID.

Method

openTab(tab: string): void

Parameters

tab: (string)

The page ID to open

Returns

None.

Example

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

The loadScript method asynchronously loads an external JavaScript code specified by a URL. When the load completes, an optional callback function is called.

Method

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

Parameters

url (string)

The URL for an external JavaScript file

callback (function)

A function that is called when the JavaScript file has been loaded.

Returns

None.

Example

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

The loadStyle method loads an external style sheet file (CSS) specified by a URL.

Method

loadStyle(url: string): void

Parameters

string url

The URL for an external style sheet file

Returns

None.

Example

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

The publish API provides a simple PubSub mechanism that can be used for inter-widget communication. Subscriber's callback function is registered with an ID of the current widget instance by default. Therefore, if you want to register multiple callbacks to the same topic from one widget instance, you need to give a uniqueId to the third parameter of the subscribe method.

Note also that a publisher widget and a subscriber widget must be in the same page, because widget instances in hidden tabs do not exist until they become visible.

The publish method publishes a topic along with any user data.

Method

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

Parameters

topic (string)

A topic name.

args? (any)

Any data to publish.

Returns

None.

Example

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

The subscribe method registers a callback function to the list of subscribers to a particular topic.

Method

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

Parameters

topic (string)

A topic name.

callback (any)

A callback function that is called when the topic is published.

uniqueId? (string)

Unique key to register the callback. By default, widget instance id is used.

Returns

None.

Example

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

The unsubscribe method unregisters a callback function to a particular topic.

Method

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

Parameters

topic (string)

A topic name.

uniqueId? (string)

Unique key to unregister the callback. By default, widget instance id is used.

Returns

None.

Example

props.unsubscribe('topic#1');

The escapeHtml method converts HTML special characters to their entity equivalents

Method

props.escapeHtml(ml: string): string

Parameters

topic (string)

A topic name.

uinqueID? (string)

Unique key to unregister the callback. By default, widget instance id is used.

Returns

None.

Example

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

The loadClusters method is a low-level oneWEX API that retrieves document clusters from the results of the current search. The operation is performed asynchronously and the result is returned to the specified callback. If callback is omitted, the result is stored in the data source state called DsState and the change will be notified to its listeners. If dsId is omitted, "A data source to listen" in the UI is used

Method

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

Parameters

dsID (string or number)

ID of target data source.

callback? (function)

A function that is called when the method is successful.

errback? (function)

A function that is called when the method fails.

Returns

None.

Example

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

The loadRecommendedDocuments method is a low-level oneWEX API that retrieves recommended documents based on the current search. The operation is performed asynchronously, and the result is returned to the specified callback. If callback is omitted, the result is stored in the data source state called DsState and the change will be notified to its listeners. If sendTo is omitted, "Data sources to search" in the UI is used.

Method

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

Parameters

type (string)

Recommendation type. Either sss (Documents with similar content) or cf (Documents people also viewed)

doc (any)

A document to compare. Only applicable when type is sss.

sendTo? (string[])

An array of target data sources.

callback? (function)

A function that is called when the method is successful.

errback? (function)

A function that is called when the method fails.

Returns

None.

Example

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

The loadRecommendedQueries method is a low-level oneWEX API that retrieves recommended query strings based on the current search. The operation is performed asynchronously and the result is returned to the specified callback. If callback is omitted, the result is stored in the data source state called DsState and the change will be notified to its listeners. If dsId is omitted, "A data source to listen" in the UI is used.

Method

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

Parameters

type (string)

Recommendation type:

• term - Words or phrases in the index
• correlated - Words or phrases correlated to the input
• ontolection - Words or phrases used in similar context
• spell - Spell correction

dsID? (string or number)

ID of target data source.

callback? (function)

A function that is called when the method is successful.

errback? (function)

A function that is called when the method fails.

Returns

None.

Example

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