Topdata Topdata Docs

TopdataCategoryFilterSW6

Topdata Category Filter SW6 User Manual

Overview

The Topdata Category Filter SW6 plugin enhances Shopware’s product filtering capabilities by adding a powerful category filter. This filter allows customers to easily navigate through product categories, improving their shopping experience and increasing the likelihood of finding relevant products.

Key Features

  • Advanced category filtering with multi-level support
  • Customizable filter appearance and behavior
  • Performance optimization options
  • Integration with Elasticsearch for fast searches
  • Comprehensive configuration settings

Getting Started

To get started with the Topdata Category Filter SW6 plugin:

  1. Follow the Installation Guide to install and activate the plugin
  2. Configure the plugin settings according to your store’s needs using the Settings Guide
  3. Refer to the FAQ & Troubleshooting section for common issues and solutions

Support

For additional support, please contact our technical support team or visit our support portal.

Release Notes

Version 1.0.0 (June 2024)

  • Initial release with basic category filtering functionality
  • Integration with Shopware 6.4
  • Elasticsearch support for fast category searches

Version 1.1.0 (September 2024)

  • Added performance optimization settings
  • Improved UI/UX with collapsible subcategories
  • Enhanced configuration options

Version 1.2.0 (December 2024)

  • Support for dynamic product groups
  • Better handling of hidden categories
  • Various bug fixes and stability improvements

Roadmap

  • Improved integration with other Shopware plugins
  • Additional customization options for the filter UI
  • Enhanced analytics and reporting features

Topdata Category Filter SW6 Installation Guide

System Requirements

  • Shopware 6.4.x or higher
  • PHP 8.0 or higher
  • Composer installed on your server

Installation Steps

1. Install via Composer

Open your terminal and navigate to your Shopware project directory. Run the following command to install the plugin:

composer require topdata/topdata-category-filter-sw6

2. Activate the Plugin

After the installation is complete, you need to activate the plugin. You can do this via the Shopware admin panel or using the command line.

Option A: Using the Shopware Admin Panel

  1. Log in to your Shopware admin panel
  2. Go to Extensions > My extensions
  3. Find “Topdata Category Filter SW6” in the list
  4. Click Activate

Option B: Using the Command Line

Run the following command in your Shopware project directory:

bin/console plugin:install --activate TopdataCategoryFilterSW6

3. Clear Cache

After activating the plugin, it’s recommended to clear your cache to ensure all changes take effect:

bin/console cache:clear

Verification

To verify that the plugin has been installed and activated correctly:

  1. Go to the product listing page in your storefront
  2. You should see the category filter in the filter panel
  3. Test the filter functionality by selecting different categories

Troubleshooting

If you encounter any issues during installation:

  • Check the Shopware error logs for detailed error messages
  • Ensure that your server meets all the system requirements
  • Verify that Composer has the necessary permissions to install plugins

Topdata Category Filter SW6 Settings Guide

This guide provides detailed information about all the configuration options available in the Topdata Category Filter SW6 plugin.

General

SettingDefaultDescription
filterPositionbeginningPosition of the category filter in the panel: beginning, afterManufacturer, end, or hidden. afterManufacturer matches the previous “Display as first filter = off”. hidden removes the filter completely: no rendering, no filtering, no product aggregation.
initialFilterStatecollapsedSets whether the category filter accordion is initially collapsed or expanded when the page loads. Other listing filters are not affected.
sortnoneDetermines the sorting order of categories (name, count, or default).

Category tree

SettingDefaultDescription
collapseSubcategoriestrueShows a toggle arrow on categories with subcategories. When disabled, the tree is rendered flat without arrows; the number of visible levels is controlled by subcategoryInitialExpandDepth.
subcategoryMaxDepthallMaximum tree depth when expand/collapse is enabled: 1, 2, 3, or all. Deeper levels are neither shown nor expandable. Ignored when toggle arrows are disabled.
subcategoryInitialExpandDepthcollapsedWith toggle arrows: levels expanded on page load (collapsed, 1, 2, 3, all), limited by subcategoryMaxDepth. Without arrows: number of levels shown in the flat tree.
showNumbertrueDisplays the number of products in each category.
manyMainCategoriestrueHandles cases with only one main category by splitting it into subcategories.
joinParentsfalseCombines parent categories in the display. Category names are separated by ”/”.
showParentCategory0How many parent category levels to show (0 to 20, or “All”).
hideParentsfalseHides parent categories in the filter.

Visibility

SettingDefaultDescription
hideOtherBranchestrueHides categories from other category branches on category pages. Must be disabled when using the filter with dynamic product groups.
excludeHiddenfalseHides categories marked as “Hide in navigation”.
hideSingleCategorytrueHides the filter if there’s only one category available.
hideDynamicCategorytrueHides categories with dynamic product groups.
popularCount0Shows only the most popular end categories. Set to 0 to show all.
  • For stores with a deep category structure, limit subcategoryMaxDepth to 2 or 3 levels.
  • For a flat, fully expanded tree without arrows: disable collapseSubcategories and set subcategoryInitialExpandDepth to all.
  • If you have only one main category, enable manyMainCategories for better visualization.
  • For stores with dynamic product groups, disable hideOtherBranches and hideDynamicCategory.

Visual Examples

Default View

Default category filter

Collapsed Subcategories

Collapsed filter

Combined Parent Categories

Joined parents

Topdata Category Filter SW6 FAQ & Troubleshooting

Common Issues

SymptomLikely CauseSolution
Missing categoriesHidden category exclusionCheck the excludeHidden setting in the plugin configuration.
Slow filter loadingComplex tree processingLimit subcategoryMaxDepth or use popularCount to reduce the number of displayed categories.
Dynamic categories missingMapping issueVerify that the streamCategories property is correctly configured in your Elasticsearch index.
URL parameters not workingRequest parameter handlingCheck the _getCategoryIdsFromRequest method in the Subscriber class.
Subcategory tree always collapsed after updateOld subcategoryInitialState setting removedRe-select the desired depth in the subcategoryInitialExpandDepth setting.
Expand/collapse arrows missingPlugin version < 3.3.0 or theme paints icons whiteUpdate to version 3.3.0 or newer and recompile the theme.
“Expansion depth” setting not foundsubcategoryExpandDepth renamed to subcategoryInitialExpandDepth (3.3.0)The saved value is migrated automatically; look for the field in the “Category tree” card.
Category filter missing after updatefilterPosition was migrated to hidden (previous showCategoryFilter = off)Select a position other than “Do not show” in the plugin configuration.

Troubleshooting Guide

1. Missing Categories in Filter

If you notice that some categories are not appearing in the filter:

  1. Check if the excludeHidden setting is enabled, which hides categories marked as “Hide in navigation”.
  2. Verify that the categories have products assigned to them.
  3. Ensure that the Elasticsearch index is up-to-date with the latest category data.

2. Slow Filter Performance

If the category filter is loading slowly:

  1. Enable the hideUnpopular setting to remove categories with low product counts.
  2. Consider increasing the popularCount threshold to show only the most popular categories.
  3. Enable caching for the category tree data.

3. Dynamic Categories Not Displayed

If dynamic product groups are not appearing in the filter:

  1. Verify that the hideDynamicCategory setting is disabled.
  2. Check that the Elasticsearch mapping includes the streamCategories property.
  3. Ensure that products are properly assigned to dynamic categories.

4. URL Parameters Not Working

If category selections are not being preserved in the URL:

  1. Check the _getCategoryIdsFromRequest method in the Subscriber class.
  2. Ensure that the filter name (tdxcats) is correctly configured in the plugin settings.
  3. Verify that JavaScript errors are not preventing the filter from updating the URL.

Best Practices

Category Management

  • Regularly review and update your category structure to ensure it remains optimized.
  • Use descriptive category names to help customers understand the product groupings.
  • Consider the depth of your category tree and enable settings like hideUnpopular for better performance.

Performance Optimization

  • Enable caching for the category tree to reduce processing time.
  • Use the popularCount setting to limit the number of categories displayed.
  • Consider batching category ID lookups in your Elasticsearch queries.

Configuration Tips

  • For stores with a complex category structure, enable joinParents to simplify the display.
  • Use the showParentCategory setting to control how many parent levels are shown in category names.
  • Regularly review and update your configuration settings to match your store’s needs.

Why are the manufacturer / price / property filters greyed out when I select a category?

This happens only when the shop setting “Filter options without results deactivate” (core.listing.disableEmptyFilterOptions) is enabled. The storefront then asks Shopware to recompute every filter’s available options while excluding the other active filters (reduce-aggregations). Because the category filter selects from the whole category tree (product.categoriesRo.id), selecting an ancestor category that still contains all current products previously collapsed the other filters to zero options, so they were disabled.

The plugin now marks its category filter (tdxcats) as transparent to that recomputation: it is never excluded from the other filters’ aggregations. As a result, selecting any category keeps the manufacturer / price / property filters enabled and usable, and combination filtering (category ∩ manufacturer, …) works correctly. A filter is still greyed out only when a selected category genuinely yields no matching products.

Why are all subcategories collapsed again after the update?

The former subcategoryInitialState setting (collapsed/expanded) was replaced by the expansion depth (today subcategoryInitialExpandDepth: collapsed / 1 / 2 / 3 / all). The old value is not carried over: shops that previously chose “expanded” fall back to the default collapsed. Simply re-select the desired depth in the plugin configuration — the previous “fully expanded” behavior corresponds to the all option.

Why was the setting renamed to subcategoryInitialExpandDepth?

In version 3.3.0 the expansion depth was split into two settings: subcategoryInitialExpandDepth (expanded on page load) and subcategoryMaxDepth (maximum reachable depth with toggle arrows). The saved value of the old subcategoryExpandDepth setting is migrated automatically to subcategoryInitialExpandDepth during the update.

How do I get a flat, fully expanded category tree without arrows?

Disable “Subcategories expandable (toggle arrows)” and set the “Initial expansion depth of subcategories” to All. The maximum depth is ignored without arrows. Choosing another depth (e.g. 2) shows only that many levels, with no way for customers to expand deeper.