1. Using SPEAK

Walkthrough: Create a search page

Version:

The Select Media dialog is an example of a search page that has basic search functionality as well as a number of more advanced features.

282DE75D54C44FE5A80836DA8B5251D7.png

Users interact with the dialog in different ways:

  • They enter text in the search text box (for example, "Android") and the SearchDataSource retrieves items where this search word appears. You create this functionality by binding a text box to the SearchDatasource and using a ListControl to show the items that the data source retrieves. This is the basic functionality of a SPEAK search page.
  • They use the links in the Media menu to select to see “All image files”, “All video files”, “My images”, “Recently uploaded images”, “Recently updated video”, or "Recently updated by me". You create this functionality with configuration items and a HyperlinkButtonsGroup control.
  • They filter items to only see "Huge" files or only "Image" media types, and so on. This is often called "faceted classification." You create this functionality with a FilterControl.

This walkthrough outlines how to:

Create the basic search functionality

You need two SPEAK components on all search pages: a component that can retrieve items and a control that can show items. You can do this in different ways. This example uses a SearchDataSource component and a ListControl:

  1. Add a SearchDataSource component to the page layout, and configure it in the following way:

    • Set the RootItemId property to the Sitecore ID of the root folder of the items that you want to retrieve.

      In the Select Media dialog, this root folder is the Media Library folder in the master database. In the current version of Sitecore Rocks, you cannot browse to this folder from the RootItemId property sheet field (the dialog itself is in the root database). You must find and copy the Sitecore ID of the folder in the Sitecore Explorer (part of Sitecore Rocks).

    • Set the Database property to $context_contentdatabase.

  2. Add a ListControl to the page, and configure it in the following way:
    • Set the ViewMode property to IconList.
    • Bind the Items property to the Items property of the SearchDataSource: {Binding DataSource.Items}.

This is the minimal configuration of a search page in SPEAK. When the items have a Thumbnail field, it displays them as thumbnails, and, when they do not, it displays them as icons.

Things to consider

For items that need translation, it is best practice to move textual properties into separate configuration items.

The ListControl can only show items as an icon list. However, you can customize the ListControl to specify other view modes.

Add a Search Text Box

Users can enter search terms in a text box in the Select Media dialog, and either press Enter or click the search icon to search:

DFE2535DB9E64B348C288B816EA19E31.png

You implement this functionality in this way:

  1. Add a SearchPanel component to your page layout. This component adds placeholders that layout and style your page correctly.

  2. In the SearchPanel component, add a ButtonTextBox control to the Searches placeholder.

  3. Specify a text for the Watermark property, for example: “Enter your search criteria.” The ButtonTextBox control shows this text when the Text property is empty.

    • If you do not need to translate this text, enter it as the value of the Watermark property in the property sheet.
    • If you need to translate this text, create a configuration item based on the ButtonTextBox Parameters template. Point to this item in the DataSource property of the ButtonTextBox control, and enter the text in the Watermark field in the configuration item.

  4. Enter /sitecore/shell/client/Speak/Assets/img/Speak/Common/16x16/dark_gray/search.png as the value of the ButtonImageUrl property. This image is the search icon to the right of the text box itself.

  5. Enter the following JavaScript as the value of the Click property of the ButtonTextBox control: javascript:app.DataSource.refresh().

    This tells the SearchDataSource to refresh when the users click the button.

  6. Bind the Text property of the SearchDataSource to the Text property of the ButtonTextBox with this: {Binding ButtonTextBoxId.Text}.

Note

You do not need to do anything special to make Enter trigger a refresh of the data source. SPEAK provides the necessary wiring of events for this to happen. You have to trigger the refresh manually for the Click event because SPEAK does not make assumptions about the wiring in this case.

Show Only Media Files

The SearchDataSource retrieves all items by default. However, you can specify that the SearchDataSource only retrieves items based on specific templates:

  1. Create a configuration item based on the SearchPanel Config template.

  2. In the configuration item, edit the Base Templates field. The present version of Sitecore Rocks does not let you do this. Use the Content Editor to find the configuration item, and open it:

    9E1C8F8421F24ED5923245C4673016C9.png

  3. Click Edit, and select the templates that you need. When you specify the File template, the SearchDataSource retrieves file items. This filters the folder and the subfolder items.

    Note

    In the previous example, there are two templates called File. One is versioned, and the other one is non-versioned. This is necessary because there are items using both of these templates.

  4. In Sitecore Rocks, open the Edit Rendering Properties dialog for the SearchDataSource. Point the SearchConfigItemId property to the configuration item that you created in step 1.

Use the FilterControl

The FilterControl lets users filter items by facets. The Select Media dialog shows the FilterControl in the collapsed state initially:

72D3ADA0728D40408465FE8A3BA2505E.png

The FilterControl expands when you click the FiltersToggleButton:

048C62F68B374D55BABE3173F6BD8D4B.png

“Dimensions,” “Media Type,” and “Date Uploaded” are facets. For example, the Dimensions facet groups the items into two sets, “Medium” and “Small".

When users select "Medium," the SearchDataSource only retrieves items in this set. If users also select "Today," the SearchDataSource retrieves the files that are both in the "Medium" and in the "Today" sets.

When users have not selected any group in any facet, the SearchDataSource retrieves all items.

When you have a SearchDataSource component in your layout, you can create the facet functionality in this way:

  1. Under your Page Settings item for facets, add a folder. Create an item based on the Facet template for each facet that you need in this folder.

  2. In the FieldName field, specify the name of a field in the template that the items are based on. Sitecore uses the values in this field for grouping the items.

    Note

    Be careful – if the field that you specify has many different values across items, the facet will not be very useful. It is best to use fields where the values belong to a relatively small set. For example, in the Select Media dialog, the Media Type facet uses the TemplateName field to group items.

  3. Point the FacetsRootItemId property of your SearchDataSource component to the folder where you have created the Facet items.

  4. Add a FilterControl control to your layout and bind the Facets property of this control to the Facets property of the SearchDataSource component.

  5. Bind the SelectedFacets property of the SearchDataSource component to the SelectedFacets property of the FilterControl control.

Add a ToggleButton to Open and Close the FilterControl

You can leave the Facets open at all times. However, the Select Media dialog has a ToggleButton control that lets users open and collapse the Facets. To add the Toggle button:

  1. Add a ToggleButton control to your layout.

    Use the Filters placeholder of the SearchPanel control for this button.

  2. Configure the ToggleButton control:

    • Set the ButtonType property to Default.

    • Bind the IsEnabled property to the hasItems member of the SearchDataSource control.

      This means that SPEAK only shows the ToggleButton when the SearchDataSource has > 0 items.

    • Set the ShowArrow property to 1.

      The ToggleButton shows an arrow that indicates what the toggle state of the button is.

    • Add the following JavaScript to the Click property of the ToggleButton control:

      javascript:app.FilterControl.toggle()

      When users click the TogleButton control, the JavaScript makes the FilterControl toggle between the collapsed and the expanded state.

Create the HyperlinkButtonsGroup

The Select Media dialog has a menu called "Media." This menu has links to a series of views: "All Image Files," "All Video Files," and so on. You create the links as HyperlinkButton items in a HyperlinkButtonGroup control and the views as search config items:

  1. Create a search config item for each view.
  2. Create a folder under PageSettings, and create a HyperlinkButton item for each view in this folder.
  3. Configure the HyperlinkButton items like this:
    • Specify a text for the link in the Text field, for example "All video files."
    • Specify the JavaScript in the Click field that changes the SearchConfigItemId property of the SearchDataSource component. For example: set:DataSource({"searchConfig": "{378D67C9-279A-4FBB-AB43-52EC07034FE8}"})
  4. Add a HyperlinksButtonGroup component to your page layout, and point the DataSource property of this component to the folder where you created the HyperlinkButton items.
If you have suggestions for improving this article, let us know!