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:
- Follow the Installation Guide to install and activate the plugin
- Configure the plugin settings according to your store’s needs using the Settings Guide
- 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
- Log in to your Shopware admin panel
- Go to Extensions > My extensions
- Find “Topdata Category Filter SW6” in the list
- 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:
- Go to the product listing page in your storefront
- You should see the category filter in the filter panel
- 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
| Setting | Default | Description |
|---|---|---|
filterPosition | beginning | Position 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. |
initialFilterState | collapsed | Sets whether the category filter accordion is initially collapsed or expanded when the page loads. Other listing filters are not affected. |
sort | none | Determines the sorting order of categories (name, count, or default). |
Category tree
| Setting | Default | Description |
|---|---|---|
collapseSubcategories | true | Shows 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. |
subcategoryMaxDepth | all | Maximum 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. |
subcategoryInitialExpandDepth | collapsed | With 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. |
showNumber | true | Displays the number of products in each category. |
manyMainCategories | true | Handles cases with only one main category by splitting it into subcategories. |
joinParents | false | Combines parent categories in the display. Category names are separated by ”/”. |
showParentCategory | 0 | How many parent category levels to show (0 to 20, or “All”). |
hideParents | false | Hides parent categories in the filter. |
Visibility
| Setting | Default | Description |
|---|---|---|
hideOtherBranches | true | Hides categories from other category branches on category pages. Must be disabled when using the filter with dynamic product groups. |
excludeHidden | false | Hides categories marked as “Hide in navigation”. |
hideSingleCategory | true | Hides the filter if there’s only one category available. |
hideDynamicCategory | true | Hides categories with dynamic product groups. |
popularCount | 0 | Shows only the most popular end categories. Set to 0 to show all. |
Recommended Configurations
- For stores with a deep category structure, limit
subcategoryMaxDepthto 2 or 3 levels. - For a flat, fully expanded tree without arrows: disable
collapseSubcategoriesand setsubcategoryInitialExpandDepthtoall. - If you have only one main category, enable
manyMainCategoriesfor better visualization. - For stores with dynamic product groups, disable
hideOtherBranchesandhideDynamicCategory.
Visual Examples
Default View

Collapsed Subcategories

Combined Parent Categories

Topdata Category Filter SW6 FAQ & Troubleshooting
Common Issues
| Symptom | Likely Cause | Solution |
|---|---|---|
| Missing categories | Hidden category exclusion | Check the excludeHidden setting in the plugin configuration. |
| Slow filter loading | Complex tree processing | Limit subcategoryMaxDepth or use popularCount to reduce the number of displayed categories. |
| Dynamic categories missing | Mapping issue | Verify that the streamCategories property is correctly configured in your Elasticsearch index. |
| URL parameters not working | Request parameter handling | Check the _getCategoryIdsFromRequest method in the Subscriber class. |
| Subcategory tree always collapsed after update | Old subcategoryInitialState setting removed | Re-select the desired depth in the subcategoryInitialExpandDepth setting. |
| Expand/collapse arrows missing | Plugin version < 3.3.0 or theme paints icons white | Update to version 3.3.0 or newer and recompile the theme. |
| “Expansion depth” setting not found | subcategoryExpandDepth 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 update | filterPosition 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:
- Check if the
excludeHiddensetting is enabled, which hides categories marked as “Hide in navigation”. - Verify that the categories have products assigned to them.
- 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:
- Enable the
hideUnpopularsetting to remove categories with low product counts. - Consider increasing the
popularCountthreshold to show only the most popular categories. - Enable caching for the category tree data.
3. Dynamic Categories Not Displayed
If dynamic product groups are not appearing in the filter:
- Verify that the
hideDynamicCategorysetting is disabled. - Check that the Elasticsearch mapping includes the
streamCategoriesproperty. - Ensure that products are properly assigned to dynamic categories.
4. URL Parameters Not Working
If category selections are not being preserved in the URL:
- Check the
_getCategoryIdsFromRequestmethod in the Subscriber class. - Ensure that the filter name (
tdxcats) is correctly configured in the plugin settings. - 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
hideUnpopularfor better performance.
Performance Optimization
- Enable caching for the category tree to reduce processing time.
- Use the
popularCountsetting 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
joinParentsto simplify the display. - Use the
showParentCategorysetting 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.