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
- Installation: Follow the installation guide in
10-installation.en.md - Configuration: Set up the plugin settings as described in
30-settings.en.md - Usage: Learn how to configure your products in
50-usage.en.md - Troubleshooting: Check the FAQ in
40-faq.en.mdfor 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
- Download the plugin package from your source
- Extract the plugin files to your Shopware installation directory:
/custom/plugins/topdata-colors-sw6/
2. Install via Composer (Recommended)
If you have the plugin available via Composer:
composer require topdata/topdata-colors
3. Manual Installation
If installing manually:
- Copy all plugin files to
/custom/plugins/topdata-colors-sw6/ - 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
- Log into your Shopware Administration
- Navigate to Extensions > My Extensions
- Verify that “Topdata Colors” appears in the installed plugins list
- Check that the plugin status shows as “Active”
Post-Installation Setup
After successful installation:
- Configure Plugin Settings: Go to Extensions > My Extensions > Topdata Colors > Configure
- Set Up Property Groups: Configure which property groups should be used for color display
- 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:refreshto 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
fillproperty - Your SVG should be designed to work with dynamic fill colors
- A CSS class
own-svgwill 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.
Property ID overrides:
- You can assign a specific color to an individual property by using the property ID as the key, e.g.
01992d6707037fd4bdb44e0d743ce6e0|#ff00ff. This forces the color for that exact property regardless of property name or other matching rules. - This ID-based mapping takes precedence over name-matching, but is still superseded by entries in
colorOverwriteif a matching override exists there.
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:
- First, create property groups in Catalogues > Properties
- Add color-related properties to these groups (e.g., “Color”, “Farbe”, “Main Color”)
- Select the appropriate property groups in this configuration field
- 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 reddisplays three red dots - Color Combinations:
red+blue(primary) orred/blue(legacy) for multi-color items - Mixed Syntax:
2x red+bluefor two red-blue combination dots
CSS Customization
You can further customize the appearance using CSS:
- Target
.topdata-colorfor the main container - Use
.colorfor 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:
- Ensure you’ve selected property groups in the plugin configuration
- Verify that your products have properties assigned from those groups
- Make sure the property names match colors in the built-in database or your custom overrides
- 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:
- Go to Catalogues > Properties in Shopware Administration
- Create a new property group (e.g., “Colors”)
- Add individual color properties to this group (e.g., “Red”, “Blue”, “Green”)
- In the plugin configuration, select this property group
- 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 reddisplays three red dots2x blue+whitedisplays 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:
- Check Plugin Configuration: Look in the “Color Overrides” field. A definition here will override everything else.
- 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.
- Check Property Name: Ensure the property’s name exactly matches an entry in the built-in color database (matching is case-insensitive).
- Clear Cache: After any changes, clear both the shop and browser cache.
Q: Plugin configuration is not saving
A:
- Check file permissions on the Shopware installation
- Verify database connectivity
- Look for error messages in the Shopware logs
- 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:
- Check Plugin Configuration: Look in the “Color Overrides” field. A definition here will override everything else.
- 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.
- Check Property Name: Ensure the property’s name exactly matches an entry in the built-in color database (matching is case-insensitive).
- Clear Cache: After any changes, clear both the shop and browser cache.
Q: Performance issues with many products
A:
- Limit the number of selected property groups
- Avoid complex CSS gradients for large product catalogs
- Consider using simple hex colors instead of gradients
- 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.
Q: Can I assign colors to specific property IDs (override by ID)?
A: Yes. You can target a specific property by its ID using an ID-based mapping. Use the syntax <id>|<color>, for example:
01992d6707037fd4bdb44e0d743ce6e0|#ff00ff
This forces the property with ID 01992d6707037fd4bdb44e0d743ce6e0 to display the specified color regardless of its name or other mappings. ID-based mappings take precedence over name-based mappings but are still superseded by explicit entries in the “Color Overrides” configuration if those are present.
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
- Navigate to Catalogues > Properties in your Shopware Administration
- Click Add property group
- Enter a name for your color property group (e.g., “Product Colors”, “Main Color”, “Accent Color”)
- 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
- Open your newly created property group
- Click Add property to add individual color options
- 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
- Go to Extensions > My Extensions > Topdata Colors > Configure
- In the Color Property Groups field, select the property groups you created
- Configure other settings as needed (see Configuration Settings guide)
- Save the configuration
Step 4: Assign Properties to Products
- Edit a product in Catalogues > Products
- Go to the Properties tab
- Select the appropriate color properties for this product
- 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:
-
Property ID Overrides (Highest Priority)
- First, the plugin checks for mappings that target a specific property ID (e.g.
01992d6707037fd4bdb44e0d743ce6e0|#ff00ff). If a matching property ID mapping exists it will be used. - Example:
01992d6707037fd4bdb44e0d743ce6e0|#FF00FFforces the property with ID01992d6707037fd4bdb44e0d743ce6e0to display as pink regardless of its name or other settings.
- First, the plugin checks for mappings that target a specific property ID (e.g.
-
Custom Color Overrides
- Next, 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 be displayed as pink, unless an ID override exists.
-
Property Hex Code
- If no custom override or ID mapping 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.
-
Built-in Color Database (Lowest Priority)
- If none 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
#ff0000will 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 dots2x 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 dotsred, 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
- Use standard color names when possible (red, blue, green, etc.)
- Be consistent across your product catalog
- Use descriptive names for custom colors (e.g., “Forest Green” instead of “Green1”)
- Consider translations if you operate in multiple languages
Property Group Organization
-
Create specific groups for different color types:
- “Main Color” for primary product colors
- “Accent Color” for secondary colors
- “Pattern Colors” for multi-colored patterns
-
Keep groups focused - don’t mix color properties with other attributes
-
Use clear naming that makes sense to your team
Color Override Strategy
- Start with built-in colors before adding custom overrides
- Document custom colors for your team
- Use hex codes consistently (#ff0000 format)
- 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
- Check property group selection in plugin configuration
- Verify property assignment to products
- Clear cache after configuration changes
- Check color name spelling against built-in database
Wrong Colors Displaying
- Verify property names match color database entries
- Check custom color overrides for conflicts
- Review property hex codes in property configuration
- Test with simple color names first
Performance Optimization
- Limit property groups to only those needed for colors
- Use simple color names instead of complex overrides when possible
- Avoid excessive custom SVG complexity
- 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:
- Override templates in your theme if needed
- Add custom CSS to style color displays
- Use provided CSS classes for styling:
.topdata-color- Main container.color- Individual color elements.group- Color group container
Testing Your Setup
- Create test products with various color combinations
- Check different page types (listing, detail, search)
- Test with different devices and screen sizes
- Verify color accuracy matches your expectations
- 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.