# Resource Filter Documentation

## Overview

The Resource Filter is a custom shortcode for the Kadence child theme that provides dynamic filtering functionality for WordPress posts. It allows users to filter content by category, custom taxonomies, and search terms while maintaining URL state and providing a smooth user experience.

## Features

- **Dynamic Filtering**: Filter posts by Topic (categories), Service, and Resource Type taxonomies
- **Search Functionality**: Full-text search across filtered content
- **URL Parameters**: Filter states are reflected in the URL for bookmarking and sharing
- **Manual Content Control**: Hide specific Gutenberg blocks when filtering is active
- **AJAX Loading**: Smooth, no-refresh filtering experience
- **Responsive Design**: Mobile-friendly layout with proper stacking

## Installation

The filter is automatically available when using the Kadence child theme. All necessary files are included:

- `functions.php` - Contains shortcode registration and AJAX handlers
- `assets/js/resource-filter.js` - JavaScript functionality
- `assets/css/resource-filter.css` - Styling

## Usage

### Basic Shortcode

Add the shortcode to any page or post:

```
[bw_resource_filter]
```

### Shortcode Parameters

- `hide_selector` (string, default: `.bw_manual_block`) - CSS selector for elements to hide during filtering
- `posts_per_page` (integer, default: 10) - Number of posts to display in filtered results

Example with custom parameters:
```
[bw_resource_filter hide_selector=".my-custom-class" posts_per_page="20"]
```

### Manual Block Control

To hide specific Gutenberg blocks when filtering is active:

1. Edit the block in the Gutenberg editor
2. In the block settings sidebar, expand "Advanced"
3. Add `bw_manual_block` to the "Additional CSS class(es)" field
4. Save the page

Any block with the `bw_manual_block` class will be hidden when filters are applied and shown again when filters are cleared.

## URL Parameters

The filter automatically updates the URL with the current filter state:

- `topic` - Category slug (e.g., `?topic=ai`)
- `service` - Service taxonomy slug (e.g., `?service=consulting`)
- `resource_type` - Resource Type taxonomy slug (e.g., `?resource_type=guide`)
- `s` - Search term (e.g., `?s=machine+learning`)

### Examples

- Single filter: `https://yoursite.com/resources/?topic=ai`
- Multiple filters: `https://yoursite.com/resources/?topic=ai&service=consulting`
- With search: `https://yoursite.com/resources/?topic=ai&s=neural+networks`

## Styling Classes

### Container Classes

- `.bw-resource-filter-container` - Main container
- `.bw-filter-row` - Filter controls row
- `.bw-filter-item` - Individual filter item wrapper
- `.bw-filtered-results` - Results container

### State Classes

- `.bw-filtering-active` - Added to body when filtering is active
- `.bw-loading` - Loading state
- `.bw-error` - Error state
- `.bw-no-results` - No results message

### Result Item Classes

- `.bw-resource-list` - Results list container
- `.bw-resource-item` - Individual result item
- `.bw-resource-image` - Featured image wrapper
- `.bw-resource-content` - Content area (title, meta, excerpt)
- `.bw-resource-title` - Post title
- `.bw-resource-meta` - Meta information (date, author)
- `.bw-resource-excerpt` - Post excerpt
- `.bw-read-more` - Read more link

## Customization

### Custom Styling

Override default styles in your theme's CSS:

```css
/* Example: Change filter button color */
.bw-reset-button {
    color: #ff0000 !important;
}

/* Example: Adjust result item spacing */
.bw-resource-item {
    padding-bottom: 40px;
    margin-bottom: 40px;
}
```

### JavaScript Hooks

The filter triggers several jQuery events you can hook into:

```javascript
// Example: Do something when filtering starts
jQuery(document).on('bw-filter-start', function() {
    console.log('Filtering started');
});

// Example: Do something when results are loaded
jQuery(document).on('bw-filter-complete', function(event, data) {
    console.log('Results loaded:', data);
});
```

## Taxonomies

### Required Taxonomies

The filter expects these taxonomies to exist:

1. **Categories** (Default WordPress) - Used for Topic filter
2. **service** - Custom taxonomy for Service filter
3. **resource_type** - Custom taxonomy for Resource Type filter

### Creating Custom Taxonomies

If the custom taxonomies don't exist, register them in your theme:

```php
// Example: Register service taxonomy
function register_service_taxonomy() {
    register_taxonomy('service', 'post', array(
        'label' => 'Services',
        'public' => true,
        'hierarchical' => true,
        'show_in_rest' => true, // For Gutenberg support
    ));
}
add_action('init', 'register_service_taxonomy');
```

## Troubleshooting

### Common Issues

1. **Filter not showing results**
   - Check if posts are published (not draft)
   - Verify taxonomy terms are assigned to posts
   - Check browser console for JavaScript errors
   - Ensure taxonomies exist and have the correct slugs

2. **Blocks not hiding**
   - Verify the `bw_manual_block` class is added correctly
   - Check if there are CSS conflicts with theme styles
   - Inspect element to ensure class is present in HTML

3. **URL parameters not working**
   - Clear browser cache
   - Check for JavaScript errors
   - Ensure no other plugins are interfering with URL handling

### Debug Mode

Enable debug logging by adding to `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

Check debug log at `/wp-content/debug.log` for PHP errors.

## Browser Compatibility

- Chrome/Edge: Full support
- Firefox: Full support
- Safari: Full support
- IE11: Not supported (uses modern JavaScript features)

## Performance Considerations

- Results are loaded via AJAX to prevent full page reloads
- Debounced search input (500ms delay) to reduce server requests
- Efficient jQuery selectors for better performance
- Minimal DOM manipulation

## Future Enhancements

Potential improvements for future versions:

- Pagination for filtered results
- Sort options (date, title, etc.)
- Multiple selection for taxonomies
- Saved filter presets
- Export filtered results
- Visual indicators for active filters

## Support

For issues or feature requests, please contact the theme developer or submit an issue through the appropriate channels.

---

*Last updated: December 2024*
*Version: 1.0.8*