How to Extend the Admin Search in Shopware 6.7

Shopware 6.7 introduces significant improvements to the administration interface, particularly in how developers can extend and customize the admin search functionality. The new search system provides a more flexible and powerful way to enhance product discovery, customer management, and overall administrative efficiency.

Understanding Shopware 6.7 Admin Search Architecture#

In previous versions of Shopware, extending the admin search required complex modifications to core components. However, Shopware 6.7 has introduced a more modular approach through its new search extension system. The administration now leverages a sophisticated search engine that can be extended at multiple levels.

The core architecture consists of several key components:

• Search service layer
• Search criteria builder
• Result transformers
• Admin search components
• Customizable search fields

Prerequisites and Setup#

Before diving into the implementation, ensure you have:

1. Shopware 6.7+ installed
2. A custom plugin structure ready
3. Basic understanding of Shopware's administration system
4. Knowledge of JavaScript/TypeScript and Vue.js

Creating a Custom Search Extension#

Step 1: Plugin Structure Setup#

First, create your plugin structure with the necessary files:

<?php declare(strict_types=1);

use Shopware\Core\Framework\Plugin;

class YourCustomPlugin extends Plugin
{
    // Plugin implementation
}

The plugin should include the following directory structure:

custom/plugins/YourCustomPlugin/
├── src/
│   ├── Resources/
│   │   ├── administration/
│   │   │   └── module/
│   │   │       └── your-module/
│   │   │           ├── search/
│   │   │           │   └── custom-search-extension.js
│   │   │           └── index.js
│   │   └── config/
│   │       └── config.xml
├── composer.json
└── src/YourCustomPlugin.php

Step 2: Registering Search Extensions#

Create the main search extension file in src/Resources/administration/module/your-module/search/custom-search-extension.js:

import { SearchExtension } from 'src/core/service/admin-search.service';

export default class CustomSearchExtension extends SearchExtension {
    constructor() {
        super();
        this.extensionName = 'custom-search-extension';
    }

    /**
     * Extends the search criteria with custom filters
     */
    extendSearchCriteria(criteria) {
        // Add custom fields to search criteria
        if (criteria.getAssociation('customFields')) {
            criteria.getAssociation('customFields').addSorting(
                new Criteria.Sorting('customFields.customField1', 'ASC')
            );
        }
        
        return criteria;
    }

    /**
     * Transforms search results for custom data handling
     */
    transformSearchResult(result) {
        // Custom transformation logic
        if (result.data && Array.isArray(result.data)) {
            result.data = result.data.map(item => {
                // Add custom properties or modify existing ones
                item.customProperty = this.generateCustomProperty(item);
                return item;
            });
        }
        
        return result;
    }

    generateCustomProperty(item) {
        // Your custom logic here
        return `Processed-${item.id}`;
    }
}

Step 3: Registering the Extension#

In your module's main index file (src/Resources/administration/module/your-module/index.js):

import './search/custom-search-extension.js';

Shopware.Module.register('your-custom-module', {
    // Module configuration
    name: 'Your Custom Module',
    title: 'Custom Search Extension',
    
    routes: {
        // Your routes
    },
    
    searchExtensions: [
        {
            name: 'custom-search-extension',
            component: 'custom-search-extension',
            priority: 100,
            entity: 'product'
        }
    ]
});

Advanced Search Extensions#

Custom Search Fields#

To add completely new searchable fields, you need to extend the search service:

import { AdminSearchService } from 'src/core/service/admin-search.service';

class AdvancedSearchExtension extends AdminSearchService {
    constructor() {
        super();
        this.customFields = [];
    }

    /**
     * Register custom searchable fields
     */
    registerCustomField(fieldConfig) {
        this.customFields.push({
            name: fieldConfig.name,
            type: fieldConfig.type,
            searchable: fieldConfig.searchable || true,
            entity: fieldConfig.entity,
            mapping: fieldConfig.mapping
        });
    }

    /**
     * Build custom search query
     */
    buildCustomSearchQuery(searchTerm, context) {
        const query = {
            term: searchTerm,
            fields: this.customFields.filter(field => field.searchable),
            filters: [],
            sorts: []
        };

        // Add custom filters based on context
        if (context.categoryId) {
            query.filters.push({
                field: 'categoryId',
                operator: '=',
                value: context.categoryId
            });
        }

        return query;
    }
}

Search Result Transformers#

For more complex transformations, create a transformer service:

export default class SearchResultTransformer {
    /**
     * Transform search results for specific entity types
     */
    transform(entityType, results) {
        switch (entityType) {
            case 'product':
                return this.transformProductResults(results);
            case 'customer':
                return this.transformCustomerResults(results);
            default:
                return results;
        }
    }

    /**
     * Custom product result transformation
     */
    transformProductResults(results) {
        return results.map(product => {
            // Add computed properties
            product.displayPrice = this.calculateDisplayPrice(product);
            product.stockStatus = this.getStockStatus(product);
            
            // Add search-specific metadata
            product.searchRelevance = this.calculateSearchRelevance(product);
            
            return product;
        });
    }

    calculateDisplayPrice(product) {
        // Custom pricing logic
        return `${product.price} ${product.currency}`;
    }

    getStockStatus(product) {
        if (product.stock > 10) return 'in_stock';
        if (product.stock > 0) return 'low_stock';
        return 'out_of_stock';
    }

    calculateSearchRelevance(product) {
        // Relevance calculation based on various factors
        let relevance = 0;
        
        if (product.name.includes(this.searchTerm)) relevance += 10;
        if (product.description.includes(this.searchTerm)) relevance += 5;
        if (product.tags && product.tags.includes(this.searchTerm)) relevance += 3;
        
        return relevance;
    }
}

Performance Optimization#

When extending admin search, performance becomes crucial. Here are optimization techniques:

Caching Strategies#

export default class OptimizedSearchExtension {
    constructor() {
        this.cache = new Map();
        this.cacheTimeout = 5 * 60 * 1000; // 5 minutes
    }

    /**
     * Cached search results
     */
    async cachedSearch(term, context) {
        const cacheKey = `${term}-${JSON.stringify(context)}`;
        
        if (this.cache.has(cacheKey)) {
            const cached = this.cache.get(cacheKey);
            if (Date.now() - cached.timestamp < this.cacheTimeout) {
                return cached.data;
            }
        }

        const results = await this.performSearch(term, context);
        this.cache.set(cacheKey, {
            data: results,
            timestamp: Date.now()
        });

        return results;
    }
}

Lazy Loading Implementation#

export default class LazySearchExtension {
    /**
     * Lazy load search extensions only when needed
     */
    async loadExtensionIfNeeded(entityType) {
        if (!this.isExtensionLoaded(entityType)) {
            await this.loadExtension(entityType);
        }
    }

    isExtensionLoaded(entityType) {
        return this.loadedExtensions.includes(entityType);
    }

    async loadExtension(entityType) {
        const extensionModule = await import(`./extensions/${entityType}-extension.js`);
        this.registerExtension(extensionModule.default);
        this.loadedExtensions.push(entityType);
    }
}

Integration with Existing Search Components#

Extending Product Search#

To extend the product search specifically, you need to modify the product module:

// In product module configuration
Shopware.Module.register('product', {
    // ... existing configuration
    
    search: {
        extensions: [
            {
                name: 'custom-product-search',
                component: 'custom-product-search',
                priority: 200,
                fields: ['customField1', 'customField2'],
                filters: {
                    customStatusFilter: {
                        type: 'select',
                        options: ['active', 'inactive', 'pending']
                    }
                }
            }
        ]
    }
});

Custom Search Components#

Create a custom search component:

<template>
    <div class="custom-search-component">
        <sw-search-field 
            v-model="searchTerm"
            @input="handleSearch"
            :placeholder="$tc('your-plugin.search.placeholder')"
        />
        
        <div class="custom-search-results" v-if="results.length > 0">
            <template v-for="result in results" :key="result.id">
                <div class="search-result-item">
                    <span>{{ result.name }}</span>
                    <span class="status-badge">{{ result.status }}</span>
                </div>
            </template>
        </div>
    </div>
</template>

<script>
export default {
    name: 'CustomSearchComponent',
    
    data() {
        return {
            searchTerm: '',
            results: [],
            debouncedSearch: null
        };
    },
    
    methods: {
        handleSearch() {
            if (this.debouncedSearch) {
                clearTimeout(this.debouncedSearch);
            }
            
            this.debouncedSearch = setTimeout(() => {
                this.performCustomSearch();
            }, 300);
        },
        
        async performCustomSearch() {
            try {
                const response = await this.$http.get('/api/_action/search/custom-products', {
                    params: {
                        term: this.searchTerm,
                        limit: 20
                    }
                });
                
                this.results = response.data;
            } catch (error) {
                console.error('Search error:', error);
            }
        }
    }
};
</script>

Testing Your Search Extensions#

Unit Tests#

describe('Custom Search Extension', () => {
    let searchExtension;

    beforeEach(() => {
        searchExtension = new CustomSearchExtension();
    });

    test('should extend search criteria correctly', () => {
        const criteria = new Criteria();
        const extendedCriteria = searchExtension.extendSearchCriteria(criteria);
        
        expect(extendedCriteria).toBeDefined();
        // Add more specific assertions
    });

    test('should transform search results properly', () => {
        const mockResults = [{ id: 1, name: 'Test Product' }];
        const transformedResults = searchExtension.transformSearchResult({
            data: mockResults
        });
        
        expect(transformedResults.data[0].customProperty).toBe('Processed-1');
    });
});

Integration Tests#

describe('Admin Search Integration', () => {
    test('should handle custom search fields', async () => {
        const response = await adminClient.get('/api/_action/search/products', {
            params: {
                'customField1': 'test-value'
            }
        });
        
        expect(response.status).toBe(200);
        expect(response.data).toHaveProperty('data');
    });
});

Best Practices and Considerations#

1. Performance: Always implement caching and lazy loading for search extensions
2. Security: Validate all search parameters to prevent injection attacks
3. Maintainability: Keep search extension logic modular and well-documented
4. Compatibility: Ensure extensions work across different Shopware 6.7 versions
5. User Experience: Provide clear feedback during search operations

Conclusion#

Shopware 6.7's enhanced admin search system provides developers with powerful tools to extend and customize the administrative experience. By understanding the architecture, implementing proper extensions, and following optimization best practices, you can create highly efficient and user-friendly search solutions that significantly improve admin productivity.

The ability to extend search functionality at multiple levels—from simple field additions to complex result transformations—makes Shopware 6.7 a robust platform for building sophisticated e-commerce administration interfaces. As you implement these extensions, remember to consider performance implications and maintain backward compatibility with existing functionality.

With proper implementation and testing, your custom search extensions will provide administrators with enhanced discovery capabilities while maintaining the performance and stability that Shopware 6.7 is known for.