This topic describes how to use the SearchDataSource component in SPEAK.

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.

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

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


  • <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.

The Search field supports sorting using the following syntax:

<field name><sort direction>


  • <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.






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.


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.



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


Specify the facets that the SearchDataSource component uses.


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.


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.


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


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


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

The root of the Sitecore content tree.


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.


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.


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.



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.


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


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


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


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


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

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