Adding a Search function to your Roku channel allows your viewers to quickly locate and jump to any video items located in your channel.
Search Screen
Setting up a Search function requires that your Instant TV Channel account is in "Advanced" Developer Mode.
If your Developer Mode is not already set to "Advanced",
select Account from the navigation links along the left side of the page,
change Developer Mode to "Advanced",
then click Save.
Activate the Search function using the SearchScope parameter in the Theme page.
The available options for the SearchScope parameter are:
Off - The Search function is disabled.
ShortDescriptionLine1 - Enable the Search function and search on the contents of each video's ShortDescriptionLine1 parameter.
ShortDescriptionLine2 - Enable the Search function and search on the contents of each video's ShortDescriptionLine2 parameter.
ShortDescriptionLine1+2 - Enable the Search function and search on the contents of each video's ShortDescriptionLine1 and ShortDescriptionLine2 parameters.
If a parameter being searched in, either ShortDescriptionLine1 or ShortDescriptionLine2, contains the %SKIP keyword,
then there will be no match, even if one or both parameters would otherwise match the query.
This allows selected items to be excluded from search results in order to avoid duplication, or for other purposes.
For example if a movie consists of 3 separate video files,
then the 2nd and 3rd files will be excluded from search results if SearchScope is set to "ShortDescriptionLine1+2"
and ShortDescriptionLine2 for the 2nd and 3rd files contains the text %SKIP.
Enclose the %SKIP keyword in curly braces like this {%SKIP} in order to prevent %SKIP from being displayed on-screen.
Additional Search-related parameters are:
SearchBreadcrumbLabel - A short line of text displayed at the right side of the Search screen overhang.
SearchHistoryLabel - The title displayed at the top of the box that contains results of previous searches.
SearchResultsLabel - The title displayed at the top of the box containing the current search results.
SearchWaitLabel - The message that is displayed while a search is in progress.
Searches are often quick enough that this message is not visible.
SearchExitButton - The label on the Search screen's exit button.
SearchMoreResultsButton - The label for the button that loads the next batch of search results if there are too many matches to display on the screen at one time.
SearchBackButton - The label for the button that loads the previous batch of search results.
SearchNoResults - The message that is displayed if the search returns no matches.
SearchNoSearches -The message that is displayed if there is no previous search history.
SearchResultsLimit - The maximum number of matches to return for a search.
SearchResultsDisplayTrim - Not yet implemented.
SearchResultsLimit - The maximum number of search results to display.
Results exceeding this amount will not be displayed.
All of the channel's overhang artwork is also used on the Search screen.
When Search is enabled, there are two ways that a viewer of your channel can display the Search screen:
For most screens, pressing the directional-pad DOWN button on the remote control will display the Search screen.
Screens that require the use of the directional-pad DOWN button to navigate on the screen,
for example Springboard screens or Grid screens,
must use an alternate method to initiate the Search function.
If Springboard screens (the screen with the Play button, the description of a video, and a poster of the video) are used,
an optional Search button can be provided.
To provide a Search button on a Springboard screen:
From the Content page, select the video item which will have a Search button.
Locate the list of Buttons in the middle of the Content item's parameter list.
(Button editing must be enabled on the Account page in order to see the Button parameters.)
Click the New button located on the last set of Button parameters (typically Button 3).
This will create a new Springboard button initially set to an Action of "New".
Change the Action of the new Springboard button to "Search".
This changes the button into a Search button.
Enter the Label for the Search button. The default is "search".
You can click the ⇧ or ⇩ arrows to change the position of the Search button on the Springboard screen.
If one or more Grid screens are used,
a Programmable Button with Function set to "Search" can be added as an item in a grid row to display a dedicated Search button/poster.
If present, the contents of the ShortDescriptionLine1, trimmed using the SearchResultsDisplayTrim token, is used to populate the search results.
If ShortDescriptionLine1 not present, then ShortDescriptionLine2 will be used.
Items inside password-protected and registration-protected areas of a channel are accessible by the search function,
even if the password is not known or the device is not registered.
It is necessary to use the "%SKIP" keyword described above to prevent protected items from being accidentally accessed using the search function.
A Programmable Button can be used to display a poster-sized search button anywhere in the channel.
Please see the
Programmable Buttons help page for additional information.
Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.
