Topdata Topdata Docs

TopdataColors v2.2.0

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

Topdata Colors SW6

Introduction

Topdata Colors SW6 is a powerful Shopware 6 plugin that enhances your online store by displaying visual color indicators for products. The plugin automatically generates color dots or custom shapes based on product properties, making it easier for customers to identify and select products by color.

Key Benefits

  • Enhanced User Experience: Customers can quickly identify product colors at a glance
  • Visual Product Differentiation: Stand out from competitors with clear color visualization
  • Flexible Configuration: Choose from multiple display styles or create your own
  • Seamless Integration: Works automatically with existing Shopware templates
  • Multi-Language Support: Supports both German and English color names

How It Works

The plugin reads color information from product properties and displays corresponding color dots in:

  • Product listing pages
  • Product detail pages
  • Search results
  • Cross-selling sections

Colors are automatically mapped using an extensive built-in database of over 200 color names, or you can define your own custom color mappings.

Getting Started

  1. Installation: Follow the installation guide in 10-installation.en.md
  2. Configuration: Set up the plugin settings as described in 30-settings.en.md
  3. Usage: Learn how to configure your products in 50-usage.en.md
  4. Troubleshooting: Check the FAQ in 40-faq.en.md for common questions

Support

For technical support and additional resources, visit TopData Software GmbH.

Installation Guide

System Requirements

Before installing Topdata Colors SW6, ensure your system meets the following requirements:

  • Shopware Version: 6.6.* or 6.7.*
  • PHP Version: 8.1 or higher
  • Server Requirements: Standard Shopware 6 server requirements

Installation Steps

1. Download and Extract

  1. Download the plugin package from your source
  2. Extract the plugin files to your Shopware installation directory:
    /custom/plugins/topdata-colors-sw6/

If you have the plugin available via Composer:

composer require topdata/topdata-colors

3. Manual Installation

If installing manually:

  1. Copy all plugin files to /custom/plugins/topdata-colors-sw6/
  2. Ensure proper file permissions are set

4. Plugin Installation Commands

Execute the following commands in your Shopware root directory:

# Refresh plugin list
bin/console plugin:refresh

# Install the plugin
bin/console plugin:install --activate TopdataColors

# Clear cache
bin/console cache:clear

5. Verify Installation

  1. Log into your Shopware Administration
  2. Navigate to Extensions > My Extensions
  3. Verify that “Topdata Colors” appears in the installed plugins list
  4. Check that the plugin status shows as “Active”

Post-Installation Setup

After successful installation:

  1. Configure Plugin Settings: Go to Extensions > My Extensions > Topdata Colors > Configure
  2. Set Up Property Groups: Configure which property groups should be used for color display
  3. Test Display: Create a test product with color properties to verify the plugin works correctly

Troubleshooting Installation

Plugin Not Visible

  • Ensure files are in the correct directory: /custom/plugins/topdata-colors-sw6/
  • Run bin/console plugin:refresh to update the plugin list
  • Check file permissions

Installation Fails

  • Verify Shopware version compatibility (6.6.* or 6.7.*)
  • Check PHP version requirements
  • Review server error logs for specific error messages
  • Ensure sufficient disk space and memory

Cache Issues

  • Clear all caches: bin/console cache:clear
  • If using Redis or other cache systems, clear those as well
  • Restart web server if necessary

Uninstallation

To remove the plugin:

# Deactivate the plugin
bin/console plugin:deactivate TopdataColors

# Uninstall the plugin
bin/console plugin:uninstall TopdataColors

# Clear cache
bin/console cache:clear

Note: Uninstalling the plugin will not remove your configuration data by default. If you want to completely remove all plugin data, use the --keep-user-data=false flag:

bin/console plugin:uninstall --keep-user-data=false TopdataColors

Configuration Settings

Access the plugin configuration through Extensions > My Extensions > Topdata Colors > Configure in your Shopware Administration.

Configuration Options

1. Color Style

Field Name: colorStyle
Type: Single Select
Default Value: drop

Choose the visual style for displaying color indicators:

  • Drop: Teardrop-shaped color indicators
  • Point: Circular color dots
  • Quad: Square-shaped color indicators
  • Italic Quad: Tilted square-shaped color indicators

Each style uses a predefined SVG shape that will be filled with the appropriate color. The selected style applies to all color displays throughout your store.

2. Custom SVG

Field Name: ownSvg
Type: Textarea
Default Value: Empty

Upload your own custom SVG code for color display. When this field contains SVG code, the “Color Style” selection above will be ignored.

Important Notes:

  • The color will be applied via the CSS fill property
  • Your SVG should be designed to work with dynamic fill colors
  • A CSS class own-svg will be automatically applied to custom SVG elements
  • Ensure your SVG is properly formatted and valid

Example SVG Structure:

<?xml version="1.0" encoding="utf-8"?>
<svg version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg" 
     viewBox="0 0 1280 1280" xml:space="preserve">
    <path d="M6094.9,12800L6094.9,12800L40,0h12760"/>
</svg>

3. Color Overrides

Field Name: colorOverwrite Type: Textarea Default Value: Empty

Define custom color mappings or override existing color definitions.

Important Note: This setting has the highest priority. A color defined here will override both the hex code set on a property and the plugin’s built-in color database.

This allows you to:

  • Add new color names not in the built-in database
  • Override existing color definitions with different hex codes
  • Create multi-color combinations

4. Color Property Groups

Field Name: colorPropertyGroups
Type: Multi-Select Entity Selector
Entity: Property Groups
Default Value: Empty

Select which property groups should be used for color display. Only properties from the selected groups will be processed for color visualization.

Setup Process:

  1. First, create property groups in Catalogues > Properties
  2. Add color-related properties to these groups (e.g., “Color”, “Farbe”, “Main Color”)
  3. Select the appropriate property groups in this configuration field
  4. Assign these properties to your products

Best Practices:

  • Create dedicated property groups specifically for colors
  • Use clear, descriptive names for color properties
  • Consider creating separate groups for different color types (main color, accent color, etc.)
  • Ensure property names match the built-in color database or your custom overrides

Built-in Color Database

The plugin includes an extensive database of over 200 color names with corresponding hex codes, supporting both English and German color names:

Examples of Supported Colors:

  • Basic colors: red, blue, green, yellow, black, white
  • German colors: rot, blau, grün, gelb, schwarz, weiß
  • Extended colors: aquamarine, cornflowerblue, darkslategray
  • Special combinations: multicolor, transparent, 3-farbig

Advanced Configuration Tips

Multi-Color Products

The plugin supports complex color combinations using special syntax:

  • Count Prefix: 3x red displays three red dots
  • Color Combinations: red+blue (primary) or red/blue (legacy) for multi-color items
  • Mixed Syntax: 2x red+blue for two red-blue combination dots

CSS Customization

You can further customize the appearance using CSS:

  • Target .topdata-color for the main container
  • Use .color for individual color elements
  • Apply styles to specific shape classes: .drop, .circle, .quad, .cursivequad, .own-svg

Performance Considerations

  • Limit the number of selected property groups to improve performance
  • Use the built-in color database when possible instead of extensive custom overrides
  • Consider caching implications when using complex CSS gradients or patterns

Frequently Asked Questions

General Questions

Q: What is the purpose of this plugin?

A: Topdata Colors SW6 displays visual color indicators (dots, shapes) on product listings and detail pages based on product properties. This helps customers quickly identify product colors without having to read text descriptions.

Q: Which Shopware versions are supported?

A: The plugin supports Shopware 6.6.* and 6.7.* versions.

Q: Does the plugin work with custom themes?

A: Yes, the plugin integrates with Shopware’s template system and should work with most custom themes. The color displays are added through template extensions that respect your theme’s styling.

Setup and Configuration

Q: Why don’t I see any color dots on my products?

A: Check the following:

  1. Ensure you’ve selected property groups in the plugin configuration
  2. Verify that your products have properties assigned from those groups
  3. Make sure the property names match colors in the built-in database or your custom overrides
  4. Clear the cache after configuration changes

Q: How do I add a new color that’s not in the built-in database?

A: Use the “Color Overrides” field in the plugin configuration:

mynewcolor|#ff5733

Each color definition should be on a separate line, with the color name and hex code separated by a pipe symbol (|).

Q: Can I use custom color names in different languages?

A: Yes, you can define custom color names in any language using the color overrides feature:

rouge|#ff0000
azul|#0000ff

Q: How do I create multi-colored indicators?

A: Use plus signs to separate multiple colors (primary separator):

rainbow|#ff0000+#00ff00+#0000ff

Forward slashes are still supported for backward compatibility:

rainbow|#ff0000/#00ff00/#0000ff

This will create multiple color dots for a single property.

Property Setup

Q: How do I set up property groups for colors?

A:

  1. Go to Catalogues > Properties in Shopware Administration
  2. Create a new property group (e.g., “Colors”)
  3. Add individual color properties to this group (e.g., “Red”, “Blue”, “Green”)
  4. In the plugin configuration, select this property group
  5. Assign these properties to your products

Q: Can I use multiple property groups for colors?

A: Yes, you can select multiple property groups in the plugin configuration. The plugin will process properties from all selected groups.

Q: What happens if a product has multiple color properties?

A: All color properties from the selected groups will be displayed. Each property creates its own color indicator.

Advanced Features

Q: How does the count syntax work (e.g., “3x red”)?

A: The plugin recognizes count prefixes:

  • 3x red displays three red dots
  • 2x blue+white displays two blue-white combination dots
  • The format is [number]x [color]

Q: Can I use CSS gradients or patterns?

A: Yes, you can use any valid CSS color value in the color overrides:

gradient|linear-gradient(45deg, #ff0000, #0000ff)
stripes|repeating-linear-gradient(45deg, #000, #000 2px, #fff 2px, #fff 4px)

Q: How do I use custom SVG shapes?

A: Paste your SVG code into the “Custom SVG” field in the plugin configuration. The SVG should be designed to work with the CSS fill property for coloring.

Troubleshooting

Q: Colors are not displaying correctly

A: This is usually due to the priority order in which colors are resolved. Check the following items in this order:

  1. Check Plugin Configuration: Look in the “Color Overrides” field. A definition here will override everything else.
  2. Check Property Hex Code: Verify if a “Color hex code” is set on the property itself (in Catalogues > Properties). This will override the built-in database.
  3. Check Property Name: Ensure the property’s name exactly matches an entry in the built-in color database (matching is case-insensitive).
  4. Clear Cache: After any changes, clear both the shop and browser cache.

Q: Plugin configuration is not saving

A:

  1. Check file permissions on the Shopware installation
  2. Verify database connectivity
  3. Look for error messages in the Shopware logs
  4. Ensure you have proper admin permissions

Q: Colors appear but with wrong colors

A: This is usually due to the priority order in which colors are resolved. Check the following items in this order:

  1. Check Plugin Configuration: Look in the “Color Overrides” field. A definition here will override everything else.
  2. Check Property Hex Code: Verify if a “Color hex code” is set on the property itself (in Catalogues > Properties). This will override the built-in database.
  3. Check Property Name: Ensure the property’s name exactly matches an entry in the built-in color database (matching is case-insensitive).
  4. Clear Cache: After any changes, clear both the shop and browser cache.

Q: Performance issues with many products

A:

  1. Limit the number of selected property groups
  2. Avoid complex CSS gradients for large product catalogs
  3. Consider using simple hex colors instead of gradients
  4. Ensure proper caching is enabled

Integration Questions

Q: Does this work with product variants?

A: Yes, the plugin works with product variants. Each variant can have its own color properties and will display accordingly.

Q: Can I customize the CSS styling?

A: Yes, you can add custom CSS to modify the appearance:

  • .topdata-color - Main container
  • .color - Individual color elements
  • .drop, .circle, .quad, .cursivequad, .own-svg - Shape-specific classes

Q: Does this affect search functionality?

A: No, the plugin only adds visual elements and doesn’t modify Shopware’s search functionality.

Q: Can I disable colors for specific products?

A: Simply don’t assign color properties to products where you don’t want color displays to appear.

Migration and Updates

Q: What happens to my configuration when updating the plugin?

A: Your configuration settings are preserved during plugin updates. However, always backup your configuration before updating.

Q: Can I export/import color configurations?

A: Currently, there’s no built-in export/import feature. You can manually copy the configuration values from the plugin settings.

Q: How do I migrate from an older version?

A: Follow the standard Shopware plugin update process. Check the changelog for any breaking changes or required migration steps.

Support

Q: Where can I get additional support?

A: Contact TopData Software GmbH through their website at https://www.topdata.de for technical support and additional resources.

Q: How do I report bugs or request features?

A: Contact the plugin developer through the official support channels provided by TopData Software GmbH.

Usage Guide

This guide explains how to set up and use the color display functionality in your Shopware store.

Setting Up Product Properties

Step 1: Create Property Groups

  1. Navigate to Catalogues > Properties in your Shopware Administration
  2. Click Add property group
  3. Enter a name for your color property group (e.g., “Product Colors”, “Main Color”, “Accent Color”)
  4. Configure the group settings:
    • Display type: Choose how properties should be displayed in filters
    • Sorting type: Set how color options should be sorted
    • Filterable: Enable if you want customers to filter by colors

Step 2: Add Color Properties

  1. Open your newly created property group
  2. Click Add property to add individual color options
  3. For each color property:
    • Name: Enter the color name (e.g., “Red”, “Blue”, “Forest Green”)
    • Color hex code: Optionally set a specific hex code (this overrides the plugin’s built-in colors)
    • Position: Set the display order
    • Media: Optionally add a color swatch image

Step 3: Configure Plugin Settings

  1. Go to Extensions > My Extensions > Topdata Colors > Configure
  2. In the Color Property Groups field, select the property groups you created
  3. Configure other settings as needed (see Configuration Settings guide)
  4. Save the configuration

Step 4: Assign Properties to Products

  1. Edit a product in Catalogues > Products
  2. Go to the Properties tab
  3. Select the appropriate color properties for this product
  4. Save the product

Understanding Color Display Logic

Color Mapping Priority

The plugin determines the color for a property based on a clear order of priority. As soon as a matching color is found, the subsequent steps are ignored:

  1. Custom Color Overrides (Highest Priority)

    • First, the plugin checks if the property name is defined in the “Color Overrides” field within the plugin configuration.
    • Example: If you define red|#FF00FF, the property “Red” will always be displayed as pink, regardless of any other settings.
  2. Property Hex Code

    • If no custom override is found, the plugin checks if a “Color hex code” has been set for the property itself in the Shopware Administration (under Catalogues > Properties).
    • Example: If the “Red” property has the hex code #FFC0CB, this value will be used.
  3. Built-in Color Database (Lowest Priority)

    • If neither of the above conditions are met, the plugin searches for the property name in its built-in database of over 200 predefined colors.
    • Example: If the property is named “Red” and has not been overridden, the default value #ff0000 will be used.

Color Name Matching

Color names are matched case-insensitively. These all work the same:

  • “Red” → matches built-in red color
  • “red” → matches built-in red color
  • “RED” → matches built-in red color

Multi-Color Syntax

The plugin supports advanced color combinations:

Count Prefixes

  • 3x red → Displays 3 red dots
  • 2x blue → Displays 2 blue dots

Color Combinations

  • red+blue → Displays red and blue dots together (primary separator)
  • red/blue → Legacy separator (still supported for backward compatibility)
  • red+blue+green → Displays three colors together

Complex Examples

  • 2x red+blue → Displays 2 combination dots (each with red and blue)
  • 3x multicolor → Displays 3 multicolor dots
  • red, blue, green → Displays separate color groups (comma-separated)

Product Setup Examples

Example 1: Simple Single Color Product

Product: Red T-Shirt Property Assignment: “Red” from “Product Colors” group Result: Single red dot displayed

Example 2: Multi-Color Product

Product: Striped Shirt Property Assignment: “Red+Blue” from “Product Colors” group Result: Red and blue dots displayed together

Example 3: Product with Multiple Color Options

Product: Available in multiple colors Property Assignment: “Red”, “Blue”, “Green” from “Product Colors” group Result: Three separate color dots displayed

Example 4: Product with Color Variations

Product: Jacket with accent colors Property Assignment:

  • “Black” from “Main Color” group
  • “Red” from “Accent Color” group Result: Black dot and red dot displayed

Best Practices

Property Naming

  1. Use standard color names when possible (red, blue, green, etc.)
  2. Be consistent across your product catalog
  3. Use descriptive names for custom colors (e.g., “Forest Green” instead of “Green1”)
  4. Consider translations if you operate in multiple languages

Property Group Organization

  1. Create specific groups for different color types:

    • “Main Color” for primary product colors
    • “Accent Color” for secondary colors
    • “Pattern Colors” for multi-colored patterns
  2. Keep groups focused - don’t mix color properties with other attributes

  3. Use clear naming that makes sense to your team

Color Override Strategy

  1. Start with built-in colors before adding custom overrides
  2. Document custom colors for your team
  3. Use hex codes consistently (#ff0000 format)
  4. Test color combinations before going live

Display Locations

Colors automatically appear in:

Product Listing Pages

  • Category pages
  • Search results
  • Brand pages
  • Tag pages

Product Detail Pages

  • Main product information area
  • Variant selection (if applicable)

Cross-Selling Areas

  • Related products
  • Recommended products
  • Recently viewed products

Comparison Features

  • Product comparison popups
  • Wishlist displays

Troubleshooting Common Issues

Colors Not Appearing

  1. Check property group selection in plugin configuration
  2. Verify property assignment to products
  3. Clear cache after configuration changes
  4. Check color name spelling against built-in database

Wrong Colors Displaying

  1. Verify property names match color database entries
  2. Check custom color overrides for conflicts
  3. Review property hex codes in property configuration
  4. Test with simple color names first

Performance Optimization

  1. Limit property groups to only those needed for colors
  2. Use simple color names instead of complex overrides when possible
  3. Avoid excessive custom SVG complexity
  4. Monitor page load times with many color properties

Advanced Usage

Custom Color Definitions

For colors not in the built-in database, add them to the color overrides:

corporate-blue|#1e3a8a
brand-red|#dc2626
custom-green|#059669

Pattern and Gradient Colors

Create special visual effects:

rainbow|linear-gradient(45deg, #ff0000, #00ff00, #0000ff)
stripes|repeating-linear-gradient(45deg, #000, #000 2px, #fff 2px, #fff 4px)

Multi-Language Support

Define color names in multiple languages:

rot|#ff0000
rouge|#ff0000
rojo|#ff0000

Integration with Themes

The plugin works with most Shopware themes. If you need to customize the appearance:

  1. Override templates in your theme if needed
  2. Add custom CSS to style color displays
  3. Use provided CSS classes for styling:
    • .topdata-color - Main container
    • .color - Individual color elements
    • .group - Color group container

Testing Your Setup

  1. Create test products with various color combinations
  2. Check different page types (listing, detail, search)
  3. Test with different devices and screen sizes
  4. Verify color accuracy matches your expectations
  5. Test performance with realistic product catalogs

By following this guide, you should be able to successfully implement and use the color display functionality throughout your Shopware store.