Topdata Topdata Docs

TopdataTopFinderProSW6 v8.1.4 - v8.1.6

This is an older version of the manual. Show the latest version

Welcome to the user manual for the Topdata TopFinder Pro plugin for Shopware 6.

This plugin provides your customers with a powerful and intuitive way to find products that are compatible with their specific devices. It is ideal for stores that sell accessories, spare parts, or consumables, such as printer ink and toner, where compatibility is key.

With a highly configurable finder bar, dedicated device pages, and advanced search capabilities, TopFinder Pro makes it easy for customers to find exactly what they need, improving user experience and boosting sales.

1. System Requirements

  • Shopware 6.7.x or higher
  • PHP 8.2 or higher
  • All other system requirements for your Shopware version

2. Plugin Dependencies

Before installing Topdata TopFinder Pro, you must install and activate the following two plugins, as they are required for TopFinder to function correctly:

  1. Topdata Foundation (TopdataFoundationSw6)
  2. Topdata Connector (TopdataConnectorSw6)

Ensure these plugins are installed and activated before proceeding.

3. Installation Steps

  1. Download the Plugin: Obtain the plugin ZIP file.

  2. Upload to Shopware: Log in to your Shopware Admin panel, navigate to Extensions > My extensions, and click the Upload extension button. Select the ZIP file.

  3. Install & Activate: Once uploaded, the plugin will appear in your list of extensions.

    • Click the ... button next to “Topdata TopFinder Pro” and select Install.
    • After installation is complete, toggle the switch in the “Status” column to activate the plugin.
  4. Clear Cache: After activation, it is crucial to clear your shop’s cache to ensure all changes are applied correctly. You can do this in the Admin under Settings > Caches & Indexes by clicking Clear caches, or by running the following command in your Shopware root directory via the command line:

    bin/console cache:clear

The plugin is now installed and ready for configuration.

All settings for the Topdata TopFinder Pro plugin can be found in your Shopware Admin under Extensions > My extensions > ... > Configure. The configuration is divided into several sections for clarity.

Select Boxes

This section controls the main finder bar displayed in your storefront.

  • Choose the select boxes that should be displayed: Defines the structure of the finder.
    • Options:
      • Brands - Series - Devices: A three-step selection process.
      • Brands - Types - Devices: An alternative three-step process.
      • Brands - Types/Series - Devices: (Default) A three-step process with a toggle to switch between Series and Types.
      • Brands - Devices: A simplified two-step process.
  • Show selectboxes: Determines where the finder bar appears.
    • Options: on all pages (Default), only on Topfinder pages, don't show.
  • Display “brand / series / type” page after selection: If enabled, selecting an option (e.g., a brand) will navigate the user to that brand’s page instead of just loading the next dropdown. Default: Disabled.
  • Show device history: If enabled, a dropdown with recently viewed devices is shown in the finder bar. Default: Enabled.
  • Allow user to hide select boxes: If enabled, users can collapse the finder bar. Default: Enabled.
  • Dropdowns Column Class: Enter the Bootstrap column classes to control the layout of the dropdowns (e.g., col-sm-4 col-md for horizontal layout, col-sm-12 for vertical). Default: col-sm-4 col-md.
  • Loading spinner display mode: How the loading indicator is shown during AJAX requests.
    • Options: None, Overlay (Default).
  • Position of the finder bar: Controls where the finder bar is rendered on the page.
    • Options: Top of page (above header) (Default), Above main navigation (below search bar), Below main navigation.

Devices Brand Letters

This controls the A-Z navigation bar.

  • Show letters: Toggles the visibility of the A-Z navigation bar. Default: Enabled.
  • Show devices instead of brands by search via letters: If enabled, clicking a letter shows a list of devices. If disabled, it shows a list of brands. Default: Disabled.
  • Disable empty letters: If enabled, letters with no associated brands/devices are grayed out and unclickable. Default: Enabled.

Devices History and Slider

This controls the device history functionality.

  • Number of devices on device history: How many recently viewed devices are stored. Default: 10.
  • Show device history on all pages: If enabled, a slider of recently viewed devices appears in the storefront. Default: Enabled.
  • Hide slider with device history: If enabled, users can hide the device history slider. Default: Enabled.

Device Finder Popup

This controls the modal-based finder.

  • Show an additional popup with device finder: Toggles the button in the header that opens the popup. Default: Enabled.
  • Choose the select boxes of the device finder…: Sets the dropdown structure inside the popup (same options as the main finder bar). Default: Brands - Types/Series - Devices.
  • Show device history: Toggles the history feature inside the popup. Default: Enabled.
  • Color Settings: A series of color pickers (Background dark, Background light, etc.) to customize the visual appearance of the popup finder to match your theme.

Product Details Page

This controls features on the product detail page.

  • Display a tab with “compatible devices”: Toggles the “Compatible Devices” tab. Default: Enabled.
  • Mode of grouping the devices: How devices are grouped within the tab.
    • Options: Group by series (Default), Group by brand, No grouping.
  • Mode of compatible device names: How device names are formatted in lists.
    • Options: device, brand + device (Default), brand + new line + device.
  • Show sub navigation (fixProductBreadcrumbs): Adjusts the breadcrumb trail on product pages for better context. Default: Enabled.

This controls the device search integration.

  • Printer Search Input:
    • Options:
      • Combined with productsearch (Default): Device search results are shown alongside regular product search results.
      • Separate searchfield: A separate search bar for devices is displayed.
      • Disabled: Device search is disabled.
  • If no device found. Don’t display Result: Hides the device results section in the combined search if no devices are found. Default: Enabled.

User “Device List”

This controls the feature for logged-in customers.

  • Activate personal device list: Enables the “My Device List” feature, allowing logged-in customers to save their devices. Default: Enabled.

Display devices in compact mode

These settings define the threshold at which a full-detail view switches to a more compact list view to save space.

  • Number on search results: Default 10.
  • Number on device list: Default 10.
  • Number on product detail page: Default 3.

Device details page

This controls the product listings on the automatically generated device pages.

  • Property to group products by tabs: Allows you to select a product property group (e.g., “Condition”). Products on the device page will be separated into tabs based on the values of this property (e.g., a tab for “Original” and a tab for “Compatible”).
  • Default product sorting: Sets the default sort order for products on device pages. Default: Topseller.
  • Products per page: Sets the number of products to show per page. Default: 10.
  • Css Class For Product Box In Product List: Enter the Bootstrap column classes to control the product grid layout on device pages. Default: col-sm-6 col-lg-4 col-xl-3.

Cart Settings

  • Show last used compatible device in cart: If enabled, when a customer adds a product to the cart, the system will show which of their recently viewed devices this product is compatible with. This provides extra confirmation for the customer. Default: Disabled.

This section provides a more detailed overview of the main features of the TopFinder Pro plugin.

The Finder Bar

The finder bar is the primary tool for your customers. It consists of several components:

  • Dropdown Selects: Customers make selections sequentially (e.g., Brand > Series > Device). The options in each dropdown are loaded dynamically via AJAX based on the previous selection. The structure of these dropdowns is controlled by the selectboxesMode setting.
  • A-Z Navigation: An alphabetical list that allows customers to quickly filter brands or devices by their first letter. The behavior is controlled by the letterDisplayDevices setting.
  • Device History Dropdown: If enabled (showDeviceHistorySelect), this dropdown shows a list of the customer’s most recently viewed devices for quick selection.

The Popup Finder

As an alternative to the static finder bar, a “Device Finder” button can be displayed in the header. Clicking this opens a large, user-friendly modal window with a more advanced interface. It includes:

  • The same dropdown functionality as the main finder bar.
  • A-Z navigation within the popup.
  • Access to the user’s “My Device List” and device history.
  • A dedicated search function within the popup.
  • A customizable color scheme to match your store’s branding.

Device Pages & Product Listings

The plugin automatically generates SEO-friendly pages for every brand, series, type, and device. When a customer navigates to a device page, they are presented with a complete list of all products compatible with that device.

The product listing on these pages is highly customizable:

  • Pagination: The number of products per page can be set via productsPerPage.
  • Sorting: You can define the default sort order using defaultSortKey.
  • Tabbed Grouping: Using the groupingTabPropery setting, you can separate products into tabs based on a property like “Condition” or “Manufacturer”, making it easy for customers to switch between original and compatible products.

“My Device List” for Customers

When enabled (showDevicelist), logged-in customers gain access to a “My Device List” area in their account. Here, they can save their devices for future visits. This allows them to quickly find compatible products without having to use the finder every time. They can also add personalized information to their saved devices, such as a location or serial number.

Search Integration

Device search can be integrated in two ways, controlled by the search setting:

  1. Combined: When a customer uses the main shop search bar, the results will include both regular products and matching devices in a separate, clearly marked section.
  2. Separate: A dedicated search bar for finding devices is added to the storefront.

“Compatible Devices” Tab on Product Pages

To help with cross-selling and provide useful information, the plugin can add a “Compatible Devices” tab to your product detail pages. This tab lists all devices that the viewed product is compatible with. The grouping of devices in this list is controlled by the deviceTabMode setting.

Note: If you are also using the TopdataTopFeedSW6 plugin, this “Compatible Devices” tab will automatically take priority, and the tab from the TopFeed plugin will be hidden to avoid duplicates.

CMS Block

The plugin registers a “TopFinder Selectboxes” block in Shopware’s Shopping Experiences (CMS). This allows you to place the finder bar on any CMS page, such as a custom landing page or the shop’s homepage, giving you full control over its placement.

Cart Integration

When the showDeviceInCart setting is enabled, the plugin enhances the shopping cart experience. If a customer views a device page and then adds a compatible product to their cart, a small icon and tooltip will appear next to the product in the cart, confirming which of their recently viewed devices it is for. This provides reassurance and can help reduce purchase errors.

faq

Q: Why are some letters in the A-Z navigation bar grayed out and unclickable?
A: This is controlled by the “Disable empty letters” setting in the “Devices Brand Letters” section of the plugin configuration. If this option is enabled, any letter that does not have at least one active brand or device starting with it will be disabled to prevent users from clicking to an empty page.

Q: The main finder bar is not showing up on my store. How do I fix this?
A: There are a few settings to check:

  1. Navigate to the “Select Boxes” section in the plugin configuration.
  2. Ensure that the “Show selectboxes” option is set to either on all pages or only on Topfinder pages. If it is set to don't show, the finder will be hidden.
  3. Check the “Position of the finder bar” setting. It’s possible it is being rendered in a location your theme does not support or that is hidden by custom CSS.
  4. If you have a custom theme, ensure it has not removed the theme blocks where the finder is rendered.

Q: A device page is showing “No products found”, but I know there are compatible products. Why?
A: Product compatibility is managed by the Topdata Connector plugin. Please ensure that the product-to-device relationships are correctly configured within the Connector. After making changes, always clear the Shopware cache.

Q: How do I change the colors of the popup finder?
A: In the plugin configuration, there is a section called “Device Finder Popup”. This section contains a series of color picker fields (e.g., Background dark, Text, Button text mouse over). You can use these fields to customize every aspect of the popup’s appearance to match your store’s theme.

Q: Where can I change the SEO texts like the page title for the device pages?
A: The SEO templates for all pages generated by this plugin (Brand, Series, Type, Device pages) are managed as Text Snippets in Shopware. In the Admin, navigate to Settings > Shop > Text Snippets and search for the key topdata-topfinder.SEO. You will find all relevant snippets (e.g., topdata-topfinder.SEO.devicePageTitle) which you can then edit for each of your sales channels.