Items_SortByDropdown Widget

The Items_SortByDropdown widget provides item sorting and, when used with Items_TileListing, Grid and List display controls. It sends a new item-search request when a shopper changes the sort selection or display template.

Add the widget to a page

Use this widget on the same page as Items_TileListing. The widgets share the item-listing functions and data that are required to refresh the results and select the active display template.

<Control src="LoadWidgetControl.ascx"
    FileLocation="Items_SortByDropdown.html"
    Options="defaultItemDisplayView: 'grid',
        itemDisplayLayoutOptions: 'both',
        showSortByOptions: false" />

Sorting behavior

The sorting drop-down is hidden by default. When showSortByOptions is True, shoppers can select the following sort values:

  • Default, which clears the selected sort.
  • Low to High or High to Low, which sorts by price using the configured price source.
  • Most Popular or Least Popular, which sorts by popularity.

Changing a selection refreshes the item listing from the first page. The visible sort type is set to the configured price or popularity label for the corresponding selection.

Grid and List display behavior

The widget supplies the GetTileListingTemplate function used by Items_TileListing. This function selects either the grid or list template and updates the active display button.

By default, Grid is the initial display and both Grid and List buttons are available. When itemDisplayLayoutOptions is grid or list, the display buttons are hidden and the permitted layout takes precedence if it conflicts with defaultItemDisplayView.

Items_SortByDropdown requires Items_TileListing on the same page. Items_TileListing defaults to its grid template when this widget is not present.

Widget options

Display and sorting options

Option Default Valid values or format Effect
defaultItemDisplayView
String		 'grid' 'grid', 'list' Sets the initial Items_TileListing template.
itemDisplayLayoutOptions
String		 'both' 'grid', 'list', 'both' Limits the permitted display layout. Grid and List buttons are visible only when the value is 'both'.
showSortByOptions
Boolean		 false true, false Shows or hides the sorting drop-down.
sortByLabelText
String		 'Sort By:' Text Sets the sorting drop-down label.
priceSource
String		 'List' Text appended to the price sort key Sets the price source suffix used for Low to High and High to Low sorting.
priceSortLabel
String		 'Price' Text Sets the visible sort type for price sorting.
popularitySortLabel
String		 'Popularity' Text Sets the visible sort type for popularity sorting.

Item-search options

These options are passed to the item-search request that refreshes Items_TileListing.

Option Default Valid values or format Effect
overrideCategoryList
String		 Not specified Value accepted by the search operation Uses the specified value instead of the current category when requesting items.
includeModels
Boolean		 true true, false Includes models in the search request.
includeStockCodes
Boolean		 true true, false Includes stock codes in the search request.
includeSKUs
Boolean		 false true, false Includes SKUs in the search request.
includeItemsFromAllChildCategories
Boolean		 false true, false Includes items from child categories in the search request.
pageSize
Number		 -1 Number Sets the requested number of items per page.
getPricingInResults
Boolean		 true true, false Uses the pricing-enabled search operation when True. When False, uses the characteristics search operation.

Validate the widget

  1. Place Items_SortByDropdown and Items_TileListing on the same page.
  2. Confirm the configured initial Grid or List display appears.
  3. When itemDisplayLayoutOptions is both, confirm Grid and List buttons switch the listing template.
  4. Enable showSortByOptions and confirm each selection refreshes the listing and applies the expected sort type.