Walkthrough: Configuring widgets at runtime

In Sitecore Search, widgets are typically configured in the Sitecore Search user interface. This configuration includes widget type, rules, and features.

Search only applies a widget rule when its context conditions are met. Sometimes you might want to apply a rule when context conditions can only be defined at runtime. In those cases, you can configure widget behavior in the request.

For example, conversions can be evaluated only at runtime. To alter widget behavior based on them, you can add a rule in the request.

Rules configured in Sitecore Search and those created at runtime are similar. The only difference is that you do not need to define the context conditions in the rules created at runtime. It can be assumed that the conditions have already been met.

This walkthrough describes how to:

  • Create a search results widget at runtime.

  • Create a rule to boost items.

  • Create a rule to bury items.

  • Override personalization settings.

  • Override attribute rankings.

Create a search results widget at runtime

Since rules are specific to a widget, you must instantiate a WidgetRequest object before creating a rule.

To create a search results widget at runtime:

  • In a TypeScript file called search_widget.ts, copy and paste the following code block then adjust the imports:

    RequestResponse
    import {
  WidgetRequest,
} from "@sitecore-search/data";

const widgetRequest = new WidgetRequest("rfkid_7");
widgetRequest.setEntity("content");

Create a rule to boost items

A boost rule displays in specified slots, items that pass the SearchFilter.

To create and add a rule to boost items authored by William Shakespeare or William Wordsworth using a SearchFilter object:

  • To search_widget.ts, add the following code block then adjust the imports:

    RequestResponse
    import {
  SearchFilter, 
  Boost
} from "@sitecore-search/data";

const boostFilter: SearchFilter = {  
  type: "anyOf",
  name: "author",
  values: ["William Shakespeare", "William Wordsworth"]
}

const boostRule: Boost = {  
  filter: boostFilter,
  slots: [0,3,8]
}

widgetRequest.addRfkFlag( "+rules" );
widgetRequest.addSearchRuleBoost( boostRule )

Create a rule to bury items

A bury rule does not display items that pass the SearchFilter.

To create and add a rule to bury items published after January 1, 1900 using a SearchFilter object:

  • To search_widget.ts, add the following code block then adjust the imports:

    RequestResponse
    import {
  SearchFilter,
  Bury
} from "@sitecore-search/data";

const buryFilter: SearchFilter {
  type: "gte",
  name: "publication_date",
  values: [ new Date( 1900 ) ]
}

const buryRule: Bury {  
  filter: buryFilter
}

widgetRequest.addRfkFlag( "+rules" );
widgetRequest.addSearchRuleBoost( buryRule )

Override personalization settings

To override personalization settings to use the affinity algorithm using a Personalization object:

  • To search_widget.ts, add the following code block then adjust the imports:

    RequestResponse
    import {
  Personalization
} from "@sitecore-search/data";

const personalization: Personalization {
  algorithm: "affinity",
}
widgetRequest.addRfkFlag( "+personalization" );
widgetRequest.addSearchRuleBoost( personalization )

Override attribute rankings

To override personalization settings to use the affinity algorithm using a Ranking object:

  • To search_widget.ts, add the following code block then adjust the imports:

    RequestResponse
    import {
  Personalization
} from "@sitecore-search/data";

const likesRanking: Ranking {
  name: "likes",
  weight: 5
}
const ratingRanking: Ranking {
  name: "rating",
  weight: 10
}
widgetRequest.addRfkFlag( "+ranking" );
widgetRequest.addSearchRanking( likesRanking )
widgetRequest.addSearchRanking( ratingRanking )

Do you have some feedback for us?

If you have suggestions for improving this article,