Elvis 5 JavaScript library - FacetRenderer

This class simplifies creating HTML from the JSON search facets received from the Elvis REST API. See the screenshots below for some simple possibilities.

It provides the following features:

• Render HTML for facets.
• Add search parameters to your query to filter based on the facet selection made by the user.

Functions

render( data )

Renders facets as HTML. The HTML will be put into html elements named: fieldName + 'Facet'. You must pass the data object returned from Elvis API as argument to the function.

addFacetSelectionParams( [{ params }][1] )

Adds facet.<field>.selection parameters to filter facets to a params object that can be passed to the elvisAPi.search( ... ) function.

How to use

var facetRenderer = new FacetRenderer();

facetRenderer.facets = ["assetDomain", "tags"];

facetRenderer.facetClick = function(field, value, selected, element) {
    // called after a facet is clicked by the user
    // facet selection change has already been tracked by FacetRenderer
    // so you can just refresh results and facets
    refreshResults();
};

function refreshResults() {
    var params = {
        q: 'ancestorPaths:"/Demo Zone"',
        facets: facetRenderer.facets.join(",")
    };
    
    // add facet selections
    facetRenderer.addFacetSelectionParams(params);
    
    // execute search and update results
    elvisApi.search(params, function(data) {
        hitRenderer.render(data);
        facetRenderer.render(data);
    });
}

<div id="assetDomainFacet">
    <h1>Image type:</h1>
    <!-- facet list will be inserted here -->
</div>
<div id="tagsFacet">
    <h1>Tags:</h1>
    <!-- facet list will be inserted here -->
</div>

Step by step:

Create a facet renderer instance.

var facetRenderer = new FacetRenderer(); 

Set the facets to be returned:

facetRenderer.facets = ["assetDomain", "tags"];

Register a facetClick handler function to refresh the results and filter the search with the facet that was clicked. In some cases you may want to add some custom behaviour, in which case the facet click handler receives the following arguments.

• field: The facet field for which a value was clicked.
• value: The value of the facet that was clicked.
• selected: True if the value is selected (after the click), false if it is no longer selected.
• element: The HTML element that was clicked.

facetRenderer.facetClick = function(field, value, selected, element) {
    // just refresh results and facets
    // facet selection change has already been tracked by FacetRenderer
    refreshResults();
};

Adding parameters to filter the search based on selected facets is be done with the FacetRenderer.addFacetSelectionParams( params ) function:

// add facet selections
facetRenderer.addFacetSelectionParams(params);

When you call the render function, the FacetRenderer will look in your HTML for elements with an id matching the name of the facet field appended with "Facet".

// execute search and update results
elvisApi.search(params, function(data) {
    hitRenderer.render(data);
    facetRenderer.render(data);
});

And the HTML:

<div id="assetDomainFacet">
    <h1>Image type:</h1>
    <!-- facet list will be inserted here -->
</div>
<div id="tagsFacet">
    <h1>Tags:</h1>
    <!-- facet list will be inserted here -->
</div>

The FacetRendere will render <ul> lists for each facet and insert them as the last element under those HTML elements. This means you can add headers for the facets yourself in the HTML.