SearchDataSource

Current version: 9.0

You use the SearchDataSource component to retrieve Sitecore items from a specified root item. You can restrict the items that the component retrieves with a search query. You use another component, such as the ListControl, to display the items that the SearchDataSource component retrieves.

By default, the SearchDataSource component retrieves all items that match the search query. If you set the PageSize property to a value > 0, the SearchDataSource component retrieves the specified number of items at a time. You can tell the SearchDataSource component to retrieve the next “page” of items by raising the next event. For example, you can add a button to the page, and set the Click property of this button to invoke the next event.

You can specify an initial search by defining a search configuration item and specifying the initial search in the Search field of this configuration item. You then reference the configuration item from the SearchConfigItemId property. You use the SearchPanel Config template when you create this item.

You can use facets for searches as well. Facets are distinct characteristics of items that you can use for grouping. Items can have multiple facets, but they can only have one distinct value for each facet. Examples of facets are Dimensions (size of an image), File Type, or Language.

You use the FilterControl control to display facets. Users can select and deselect facets, and the search updates immediately.

You must create the facets you want to present to the users first. You use the Facet template to create an item for each facet.

Search query syntax

You can search for specific field values with the following syntax:

RequestResponse
<modifier><field name>:<search string>

Where:

  • <modifier> defines how Sitecore interprets the search criteria for this field when you enter multiple field names. You can use these modifiers:

    • no modifier translates to SHOULD and corresponds to a logical OR

    • + translates to MUST and corresponds to a logical AND

    • – translates to MUST NOT and corresponds to a logical AND NOT

  • <field name> specifies the template field name. You must enclose it in quotes if the field name has embedded spaces.

  • <search string> is a simple text criteria. You can use * (asterix) as a wildcard. You must enclose the search string in quotes if it has embedded spaces.

You can include search strings for multiple fields, separated by spaces.

Sorting

The Search field supports sorting using the following syntax:

RequestResponse
<field name><sort direction>

Where:

  • <field name> specifies the template field name. Enclose in quotes if the field name includes embedded spaces.

  • <sort direction> optionally specifies ascending or descending sorting.

    Acceptable values include:

    • |ASC indicates ascending values.

    • |DESC indicates descending values.

You can include multiple sort fields.

Properties

Name

Description

Default

Appearance

Formatting

Specify a formatting token:

  • $convert_date_to_friendly_format: convert internal date format to localized format

  • $send_localized_dates: send localized versions of all dates

  • $convert_id_to_display_name: convert item IDs to the display names of the items

You can enter multiple formats as a pipe-separated (“|”) list.

Sorting

Specify how the component sorts items. You can bind to another control to make sorting interactive.

For example, you often use the ListControl to display the items that the SearchDataSource component retrieves. You can bind the Sorting property of your SearchDataSource component to the Sorting property of the ListControl , and when users click the sorting “arrow” buttons of the ListControl , SPEAK notifies the SearchDataSource component.

Data

Database

Specify the database that Sitecore searches:

  • The exact name of a database, for example core, or master.

  • $context_database: context database.

  • $context_contentdatabase: content database.

The context database

Facets

Specify the facets that the SearchDataSource component uses.

FacetsRootItemId

Points to a configuration item that contains search facets as child items. You create a facet configuration item based on the Facet template for each facet.

Fields

You can provide a pipe-separated (“|”) list of fields that Sitecore should search in. If you enter an asterix, “*”, Sitecore searches in all fields. Search in as few fields as possible to improve performance.

If you do not enter anything, all fields are searched.

Items

Contains the retrieved items. You normally bind to this property from a control that can show items, for example the ListControl control.

Language

Specify the language version of the items you want to search in:

  • Empty: search in all languages.

  • $context_language: search in current language from the CMS

  • Exact language: for example: "ja-jp" or "en-us"

All languages

RootItemId

Point to the item in the content tree that you want the search to start from.

The root of the Sitecore content tree.

SearchConfigItemId

Points to a configuration item that contains a search configuration. You create a configuration item based on the SearchPanel Config template as a child of the PageSettings item, and use the fields in this item to configure the search.

SelectedFacets

Specifies which of the available facets the component uses. You normally bind this property to the SelectedFacets property of a FilterControl control. When you do this, users can select facets in the FilterControl control, and the SearchDataSource component updates the search results.

Text

The text to search for. You normally data bind this value to a text property of another component, for example, a text box where a user can enter search terms. You can use the drop-down list to select properties of the other components that are on the page.

Paging

PageIndex

The SearchDataSource component updates this property with the index (number) of the current page when the PageSize property is smaller than the total number of pages.

PageSize

Sets the number of items that the component retrieves from Sitecore.

HasItems

True if the search finds items (read-only).

HasMoreItems

True if the search result contains items that the data source has not yet sent to the client (read-only).

HasNoItems

True when the data source has sent all items in the search result to the client (read-only).

IsBusy

True if the component is in the process of retrieving data from the server (read-only).

Configuration

You can create a configuration item for a SearchDataSource component by creating an item based on the SearchDataSource Parameters template.

The configuration item has these specific fields:

  • Formatting

  • Sorting

  • Text

  • FacetsRootItemId

  • Facets

  • SearchConfigItemId

  • Items

  • RootItemId

  • SelectedFacets

  • IsBusy

  • HasItems

  • HasNoItems

  • HasMoreItems

It inherits these fields:

  • Database

  • Fields

  • PageSize

  • PageIndex

  • Language

  • Behaviors

  • Id

Do you have some feedback for us?

If you have suggestions for improving this article,