State

This is for:

Developer

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 search box 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’s also possible to set many state attribute values using a single Coveo.state function call:

Setting many 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 section describes the common state attributes used in a typical search interface.

q (string [query expression])

The current basic query expression (q) (see the Searchbox component).

  • Setting q in the URL fragment identifier.

    sort=modifying%20state

  • Setting q in the state object.

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

first (unsigned integer)

The 0-based position of the first item currently being displayed in the paginated query result set (see the Pager component).

Default value: 0.

  • Setting first in the URL fragment identifier.

    first=10

  • Setting first in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "first", 10);

t (string)

The id option of the currently selected tab (see the Tab component).

  • Setting t in the URL fragment identifier.

    t=All

  • Setting t in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "t", "All");

tg (string)

Coveo JavaScript Search Framework 1.0.59 (September 2015)

The id option value of the currently selected tab group.

  • Setting tg in the URL fragment identifier..

    t=General

  • Setting tg in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "t", "General");

sort (string)

The currently selected sort criteria (see the Sort component).

Default value: relevancy.

  • Setting sort in the URL fragment identifier..

    sort=date%20descending

  • Setting sort in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "sort", "date descending");

layout (string [enum])

The currently active result layout (see the ResultLayoutSelector component).

Allowed values: card, list, table (see ValidLayout).

Default value: list.

  • Setting layout in the URL fragment identifier..

    layout=card

  • Setting sort in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "layout", "card");

f:[id] (array of string)

The list of currently selected values in the facet whose id option value is [id] (see the Facet component).

The id option value of a facet defaults to its field option value.

  • The following facet has @author as its id (by default).
<div class="CoveoFacet" data-field="@author"></div>
  • The following facet has Author as an id (capital A and no preceding @).
<div class="CoveoFacet" data-id="Author" data-field="@author"></div>

  • Setting f:@author in the URL fragment identifier.

    f:@author=[Alice%20Smith,Bob%20Jones]

  • Setting f:@author in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "f:@author", ["Alice Smith", "Bob Jones"]);

Sample query string value: f:@author=[Alice%20Smith,Bob%20Jones]

f:[id]:not (array of string)

The list of currently excluded values in the facet whose id option value is [id] (see the Facet component).

  • Setting f:@author:not in the URL fragment identifier.

    f:@author:not=[Chloe%20Brown,David%20Moore]

  • Setting f:@author:not in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "f:@author:not", ["Chloe Brown", "David Moore"]);

f:[id]:operator (string [enum])

The currently selected operator of the facet whose id option value is [id] (see the useAnd and enableTogglingOperator options of the Facet component).

Allowed values: and, or.

Default value: or.

  • Setting f:@category:operator in the URL fragment identifier.

    f:@category:operator=and

  • Setting f:@category:operator in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "f:@category:operator", "and");

hq (string [query expression])

The current hidden query expression (see the HiddenQuery component).

  • Setting hq in the URL fragment identifier.

    hq=coveo

  • Setting hq in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "hq", "coveo");

hd (string)

The current hidden query description (see the HiddenQuery component).

  • Setting hd in the URL fragment identifier.

    hq=Add%20'Coveo'%20to%20the%20advanced%20query%20expression

  • Setting hd in the state object.

    Coveo.state(Coveo.$$(document).find("#search"), "hd", "Add 'Coveo' to the advanced query expression");

Registering a custom state attribute

You may want to persist the state of a custom component in the hash part of the URL. 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 part 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 part of the URL:

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