ItemCharacteristics_Filter Widget

The ItemCharacteristics_Filter widget displays selectable characteristic values for the current item-search scope. Selecting a value refreshes Items_TileListing so that only matching items are shown.

Add the widget to a page

Use this widget on the same page as Items_TileListing. The characteristicPaths option is required; the available characteristic paths are not established by this widget source and must match the site’s item-characteristic data.

<Control src="LoadWidgetControl.ascx"
    FileLocation="ItemCharacteristics_Filter.html"
    Options="characteristicPaths: '<required characteristic paths>',
        minimumToShow: 2,
        pageSize: 10,
        enableAccordion: true,
        showCollapsed: false" />

How characteristic filters affect the item listing

The widget retrieves available values for each configured characteristic path within the current Items_TileListing search scope. A shopper can select one value in each characteristic filter.

When a selection changes, the widget:

  1. Collects the selected characteristic filters through its GetActiveFilters function.
  2. Serializes those filters into the item-search request supplied by Items_TileListing.
  3. Calls SetupItemsToDisplay to refresh the main item listing.
  4. Displays selected values in the active-filter area that Items_TileListing provides.

The widget also exposes ReloadAllFilters, which refreshes the available values for every configured characteristic path using the current selections.

Items_TileListing must be present on the same page. It supplies the search parameters, item refresh function, and active-filter area used by this widget.

Widget options

Option Default Valid values or format Effect
characteristicPaths
String		 Not specified Comma-separated characteristic paths Identifies the characteristic filters to load. This option is required.
minimumToShow
Number		 2 Number Hides a filter when it has fewer values than this threshold and no selected value.
pageSize
Number		 10 Number Sets the initial number of values shown per characteristic filter before a Show More link is provided.
enableAccordion
Boolean		 true true, false Enables collapsible characteristic-filter groups.
showCollapsed
Boolean		 false true, false Collapses filter groups when accordion behavior is enabled.
preferredFilter
String		 Not specified One configured characteristic path Keeps the matching characteristic filter expanded when the groups are collapsed.
activeFiltersLabelText
String		 'Active Filters:' Text Sets the label that precedes selected filters in the active-filter area.

Characteristic value behavior

For color characteristics, the widget uses the configured color dictionary and matching swatch image. Other characteristic values are displayed with their value and suffix.

The widget shows a Show More link when a characteristic has more values than pageSize. The shopper can expand the list to see all values and then show fewer values again.

Interaction with the price filter

ItemPriceRange_Filter calls GetActiveFilters when this widget is present. This means a price-range change retains the selected characteristic filters.

Validate the widget

  1. Place ItemCharacteristics_Filter and Items_TileListing on the same page.
  2. Configure one or more valid characteristicPaths values and confirm the corresponding filters load.
  3. Select a characteristic value and confirm the main item listing refreshes with matching items.
  4. Confirm the active-filter area shows the selection and removes it when the shopper clears it.
  5. If ItemPriceRange_Filter is present, apply both filters and confirm the listing reflects both selections.