Utilities¶

The JavaScript library includes utilities for creating filter and facet strings that can be used with queries to panels and zones.

Filter builder¶

The filter builder enables the creation of filters with single or multiple attributes, value ranges, and operators. It is recommended to always instantiate a FilterBuilder object.

var api = window.esalesAPI({ market: '{market}', url: 'https://{cluster-id}.api.esales.apptus.cloud' });

var fb = new api.utils.FilterBuilder();

When a filter is complete, the method toString() is used to extract the created filter string. The following example will convert a filter named myFilter to a string.

var myFilter = fb.attribute('filter attribute', 'value');
myFilter.toString();

The most basic filter possible includes one filter attribute and one value. The following example argument will create a filter with the value green for the filter attribute color. It will return the filter string color:'green' with the method toString().

var color = fb.attribute('color', 'green');

Multiple attributes can be used when creating filters. The following example argument will create a filter with the value green for the filter attributes color and title. It will return the filter string color,title:'green' with the method toString().

var color = fb.attribute(['color,title'], 'green');

Value ranges for attributes can also be expressed for single or multiple attributes. The following example argument will create a filter with a single attribute. The range has the start value 30 (from and including the start value) and the stop value 100 (to and including the stop value) for the filter attribute price. It will return the filter string price:['30','100'] with the method toString().

var price = fb.range('price', 30, 100);

The following example argument will create a filter multiple attributes. The range has the start value 30 (from and including the start value) and stop value 100 (to and including the stop value) for filter attribute price and cost. It will return the filter string price,cost:['30','100'] with the method toString().

var price = fb.range(['price,cost'], 30, 100);

Parameters for true and false can be added to a range argument to include or exclude the start and stop values from the range. The range argument defaults to true for both start (from and including) and stop (to and including) values if parameters are omitted.

var price = fb.range('price', 30, 100, true, false);
//returns price:['30','100') with the method toString().

var price = fb.range('price', 30, 100, false, false);
//returns price:('30','100') with the method toString().

var price = fb.range('price', 30, 100, false, true);
//returns price:('30','100'] with the method toString().

The filter builder can also use logical filter expressions to combine or exclude filters using AND, OR, and NOT.

var and = fb.and([color, price]);
var or = fb.or([color, price]);
var not = fb.not(color);

Facets builder¶

The facets builder enables the creation of filters with single or multiple attributes, value ranges, and arrays. It is recommended to always instantiate a Facet object.

var facet = new api.utils.Facet();

When a facet is complete, the method toString() is used to extract the created facet string. The following example will convert a facet named myFacet to a string.

var myFacet = facet.add('facet attribute', 'value');
myFacet.toString();

The most basic facet possible includes one facet attribute and one value. The following example argument will create a facet with the value green for the facet attribute color. It will return the facet string color:green with the method toString().

var myFacet = facet.add('color', 'green');

Value ranges for facets can also be expressed for single or multiple attributes. Value ranges for facets have a start value that is from and including the start value, and a stop value that is to and including the stop value.

The following example argument will create a facet with a single attribute. The range has the start value 30 and the stop value 100 for the filter attribute price. It will return the facet price:['30','100'] with the method toString().

var myFacet = facet.addRange('price', 30, 100);

Arrays and strings can also be used as a second parameter for facets. The following example will create a facet with the values red and orange for the facet attribute color. It will return the facet string color:red|orange with the method toString().

var myFacet = facet.add('color', ['red', 'orange']);

var myFacet = facet.add('color', 'red').add('brand','nike');

Chaining facets with the same facet attributes will create a facet just as an array would. The following example will chain a single value facet with the value red for the facet attribute color with a facet with the value orange for the facet attribute orange. It will return the facet color:red|orange with the method toString().

var myFacet = facet.add('color', 'red').add('color','orange');

Chaining is value type independent and can combine arrays and strings into facets. The following example will chain a facet with the array values red and orange for the facet attribute color. with a facet with the value nike for the facet attribute brand. It will return the facet color:red|orange,brand:nike with the method toString().

var myFacet = facet.add('color', ['red','orange']).add('brand','nike').toString();

Example usage¶

var api = window.esalesAPI({ market: '{market}', url: 'https://{cluster-id}.api.esales.apptus.cloud' });

var fb = new api.utils.FilterBuilder();
var facet = new api.utils.Facet();

var filter = fb.attribute('color', 'green');
facet.addRange('price', 30, 100);

api.panel(name, {
    window_first: 1,
    window_last: 10,
    filter: filter.toString(),
    facets: facet.toString()
}).then(function(data) {
    console.log('success', data);
}).catch(function(err) {
    console.log('error', err);
});