State

The Coveo JavaScript Search Framework stores its state in a centralized location using a key-value set (see the QueryStateModel class). This state object is updated each time a component state changes, such as when the query in the Querybox is modified, or when a Facet value is selected. All state changes trigger events which you can monitor with external code. Certain Coveo components also monitor those state events in order to be able to update themselves when appropriate. Optionally, the state can be persisted in the query string of the URL to enable browser history management (see the HistoryController class).

Reading and Modifying the State

You can read and modify the state object using the Coveo.state top-level function:

  • Getting the state object:

    Coveo.state(Coveo.$$(document).find("#search"));
    
  • Getting the value of a specific state attribute:

    Coveo.state(Coveo.$$(document).find("#search"), "q");
    
  • Setting the value of a specific state attribute:

    Coveo.state(Coveo.$$(document).find("#search"), "q", "new value");
    

The q attribute in the previous two examples corresponds to the current query in the Querybox. When setting a new value (as in the third example), the Querybox component automatically updates its content to the new value.

It is also possible to set multiple state attribute values using a single Coveo.state function call:

Setting multiple state attribute values:

Coveo.state(Coveo.$$(document).find("#search"), {
  "q" : "new query",
  "sort" : "relevancy"
});

State Events

Whenever a value in the state is modified, events are triggered to inform potential listeners of the change. For example, when changing the q attribute as in the examples above, the following events are triggered on the root HTML element of the search interface:

  • state:change:q to signal that the q attribute has changed.
  • state:change to signal that at least one attribute in the model has changed.

Here is an example of code that monitors the value of the q attribute:

Registering a state change event handler:

var root = Coveo.$$(document).find("#search");
 
Coveo.$$(root).on("state:change:q", function(e, data) {
  alert("q has changed, the new value is: " + data.value);
});

You can find the full list of available event types in the reference documentation of the Model class (see eventTypes).

Silent Mode

When setting one or several state attribute values, you can pass an additional argument containing the silent option to prevent those changes from triggering state change events.

Modifying the state without triggering events:

Coveo.state(Coveo.$$(document).find("#search"), "q", "new value", {
  silent : true
});

Common State Attributes

This following table describes the common state attributes used in a typical search interface.

Attribute Description Sample value Related component/components
q The current query in the query box. "coveo state" Querybox
first The index of the first result to display. 0 Pager
t The data-id of the active tab. "All" Tab
tg

Coveo JavaScript Search Framework 1.0.59 (September 2015) 

The data-id of the active tab group. "General" TabGroup
sort The currently active sort order. "relevancy" Sort
layout The currently active result layout (see Result Layouts). "card" ResultList, ResultLayout
f:@id

The list of selected values in facet @data-id.

If you do not explicitly set a data-id for a facet, this attribute defaults to the facet data-field value.

  • The data-id of the following facet defaults to @sysauthor.

    <div class="CoveoFacet" data-field="@sysauthor"></div>
    
  • The data-id of the following facet is AuthorFacet.

    <div class="CoveoFacet" data-id="AuthorFacet" data-field="@sysauthor"></div>
    
["Alice Smith, Bob Jones"] Facet
f:@id:not The list of excluded values in facet @data-id. ["John Doe", "Jane Doe"] Facet 
f:@id:operator The operator used for facet @data-id. "and" Facet
hq The "hidden query", which is a query filter that can have a custom description. "@year==2017 AND @objecttype==Message" HiddenQuery
hd The description to display in the breadcrumbs for the "hidden query" filter. "My Hidden Filter" HiddenQuery, Breadcrumb

Registering a Custom State Attribute

You may want to persist the state of a custom component in the hash portion of the URL. In order to do so, you need to register your custom attribute (or attributes) in the state object after the Coveo components have been initialized (see Events - Initialization Events).

You create a custom component which allows users to choose a predefined theme when displaying your search page.

You want to persist the currently selected theme in the hash portion of the URL, so you register a theme state attribute and set its default value to standard:

// Suppose that this is the root of your search interface...
var root = Coveo.$$(document).find("#search");
 
Coveo.$$(root).on("afterComponentsInitialization", function(e) {
  Coveo.state(root).registerNewAttribute("theme", "standard");
});

When a user interacts with your component to select a theme, your component updates the theme state attribute value accordingly:

// When a user selects the "zen" theme from the custom component...
Coveo.state(root, "theme", "zen")

You also bind an event handler on the state:change:theme event to update your component when a user changes the colorTheme state attribute value directly in the hash portion of the URL:

Coveo.$$(root).on("state:change:theme", function(e, data)
  // Update your custom component...
})