Ace Search

A WordPress plugin that enhances the core Search block with AJAX-powered search suggestions and responsive expansion functionality.

Features

✅ Hashtag Tag Search: Click tags to add them as #hashtag format, supports multiple tags with additional text filtering

✅ Featured Images: Displays small thumbnail images alongside search results for visual recognition

✅ Twenty Twenty-Five Styling: Designed to seamlessly integrate with WordPress Twenty Twenty-Five theme

✅ Recently Used Tags: On focus, displays a dropdown with the most popular tags as clickable search suggestions

✅ Live AJAX Search: As users type, fetches and displays matching posts/pages in real-time with excerpts

✅ Post Type Control: Admin settings page to control which post types appear in search results

✅ Keyboard Navigation: Full keyboard support with arrow keys, Enter, and Escape

✅ Accessibility: ARIA labels, screen reader support, and high contrast mode compatibility

✅ Dark Mode: Automatic dark mode support based on user preferences

✅ Mobile Responsive: Optimized for all screen sizes with touch-friendly interactions

Installation

1. Upload the plugin folder to /wp-content/plugins/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. The plugin automatically enhances all core/search blocks on your site

How It Works

The plugin automatically detects WordPress core Search blocks and wraps them with additional functionality:

• Hashtag Tag Search: Click on tags to add them as #hashtag format. Supports multiple hashtags plus additional text
• Tag Suggestions: Popular tags are shown when the field is empty and focused, prefixed with # symbol
• Live Search: As users type (after 1+ characters), live search results appear with thumbnails and excerpts
• Combined Search: Search with hashtags filters by those tags, plus any additional text searches within those results
• Post Type Filtering: Only searches within the post types configured in settings
• Smart Debouncing: Search requests are debounced by 150ms to avoid excessive API calls

Search Examples

• #wordpress - Shows all posts tagged with "wordpress"
• #wordpress #tutorial - Shows posts tagged with both "wordpress" AND "tutorial"
• #wordpress advanced - Shows posts tagged with "wordpress" that also contain "advanced" in title/content
• gutenberg - Regular text search for "gutenberg"

Settings

Navigate to Settings > ACE Search in your WordPress admin to configure:

• Post Types: Select which post types should appear in search results (posts, pages, custom post types, etc.)
• Search Sources: Toggle tabs for posts, categories, tags, and authors
• Initial Suggestions: Enable/disable recent tags and popular searches when the field is empty
• Caching: Enable caching and set TTLs for tags, search suggestions, and popular searches

REST API Endpoints

The plugin creates two REST API endpoints:

GET /wp-json/ace/v1/tags

Returns recently used tags (sorted by popularity)

Parameters:

• number (int, default: 10) - Number of tags to return

GET /wp-json/ace/v1/search

Returns search suggestions

Parameters:

• q (string) - Search query
• post_type (string, default: 'any') - Post type to search
• per_page (int, default: 8) - Number of results to return

GET /wp-json/ace/v1/popular-searches

Returns popular search terms tracked by the plugin

Parameters:

• number (int, default: 8) - Number of terms to return

Configuration

The plugin includes several configurable options via the ACE_AjaxExplorer JavaScript object:

{
    rest: {
        root: '/wp-json/ace/v1/',
        nonce: 'wp_rest_nonce'
    },
    ui: {
        minChars: 1,        // Minimum characters before searching
        debounceMs: 150,    // Debounce delay in milliseconds
        maxItems: 8,        // Maximum items in dropdown
        labels: {
            recentTags: 'Recent tags',
            results: 'Results',
            viewAll: 'View all results',
            noResults: 'No results'
        }
    }
}

Development

File Structure

ace-ajax-content-explorer/
├── ace-ajax-content-explorer.php  # Main plugin file
├── assets/
│   ├── js/
│   │   └── ace-ajax-content-explorer.js  # Frontend JavaScript
│   └── css/
│       └── ace-ajax-content-explorer.css # Styling
├── .github/
│   └── copilot-instructions.md    # Development guide
└── README.md

Key Components

1. PHP Class (ACE_Ajax_Content_Explorer):

   • Handles asset enqueuing
   • Registers REST API endpoints
   • Modifies Search block HTML output
   • Provides AJAX handlers for tags and search

2. JavaScript (ace-ajax-content-explorer.js):

   • Manages focus/blur events
   • Handles AJAX requests
   • Implements keyboard navigation
   • Controls dropdown visibility

3. CSS (ace-ajax-content-explorer.css):

   • Responsive expansion styles
   • Dropdown appearance and animations
   • Dark mode and accessibility support

Hooks and Filters

• render_block - Modifies core/search block HTML
• wp_enqueue_scripts - Enqueues frontend assets
• enqueue_block_editor_assets - Enqueues editor assets
• rest_api_init - Registers REST endpoints

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Performance

• Debounced search requests (150ms default)
• Maximum 8 results per request (configurable)
• Aborts previous requests when new ones are made
• Minimal DOM manipulation for smooth performance

Security

• Nonce verification for REST API requests
• Sanitized input/output
• XSS prevention with proper escaping
• WordPress capability checks

Accessibility

• ARIA live regions for screen readers
• Keyboard navigation support
• High contrast mode compatibility
• Focus management
• Semantic HTML structure

License

GPL-2.0-or-later

Author

AceMedia

Version

0.1.0