Working with the Search Box Web Part

Article
11/17/2011

The Search Box Web Part lets shoppers search the catalog and static content of the site. Shoppers can select the applicable categories or all categories, enter a free-form text phrase, and initiate the search by pressing ENTER or the Go button.

You must also add a Search Results Web Part to the page to implement the search feature.

You can also put the Search Results Web Part on a different page, but this requires that you set the SearchResultPageUrl parameter to point to the new page.

This is a user control-based Web Part.

Architecture

The Web Part updates the URL query string parameters and submits the page.

Properties

The following table lists and describes the properties for the Search Box Web Part.

Name	Maps to	Type	Description	Default value
Category drop-down root category	RootCategory	String	Sets the name of the catalog category where searching will start when populating the options of the "category" drop-down.	Blank
Display "Category" drop-down	ShowCategoryList	Boolean	If checked, displays a drop-down allowing the user to pick a category filter to apply to the search.	True
"Search phrase" maximum length	FreeTextMaxLength	Int	Sets the maximum character length allowed in the "search phrase" text box.	40
"Search Results" page URL	SearchResultsPageUrl	String	Sets the URL of the page that will perform the search and show results. If not specified, the URL of the current page is used.	Blank
"Search" button image URL	SearchSubmitButtonImageUrl	String	Sets the file URL of the image to display on the search button.	Blank
"Category" label text	CategoryLabelText	String	Sets the text displayed beside the "category" drop-down.	Search
"All categories" drop-down option text	AllCategoriesText	String	Sets the text displayed as an option in the "category" drop-down control that will cause searching to be performed within all categories.	All Categories
"Search phrase" label text	FreeTextLabelText	String	Sets the text displayed beside the "search phrase" text box.	For
"Search" button text	SearchSubmitButtonText	String	Sets the text displayed on the "search" button.	Go!
Initial search box text	DefaultSearchText	String	Sets the text that is displayed in the search phrase text box. This string disappears when the user starts typing in the box.	Enter keyword
Entire site search text	EntireSiteText	String	Sets the text displayed as an option in the drop-down menu that indicates all catalogs will be searched.	Entire Site
Prefix to describe a search for all items in a category	AllPrefixText	String	Sets the prefix text that precedes the category name to indicate all items in this category.	All
"Category Id" URL parameter	CategoryIdUrlKey	String	Sets the category parameter name in the URL query string.	Category
"Catalog" URL parameter	CatalogUrlKey	String	Sets the catalog parameter name in the URL query string.	Cat
User Control name	UserControlName	String	The user control that displays the search box	SearchBox.ascx

Customization

You can customize the Search Box Web Part by modifying the SearchBox.ascx file by using HTML and CSS in the actual control.

Important Note:
If you make modifications to the ASCX file to customize a Web Part, rename the modified ASCX file to avoid the risk of overwriting your Web Part customizations during an upgrade.

Error Handling

The Search Box Web Part returns friendly error messages when required fields have not been supplied.

API Dependencies

Not applicable.

Architecture

Properties

Customization

Error Handling

API Dependencies

See Also

Other Resources

Additional resources