FilterGate

Your gateway to filtered content - A WordPress Gutenberg block plugin that provides navigation-based archive filtering with restricted category access.

Description

FilterGate is a custom WordPress block that displays a search box and category dropdown filter. When users interact with the filter, they are redirected to the appropriate WordPress archive pages rather than filtering inline. This approach leverages WordPress's native archive templates for displaying results.

Key Features

• Gutenberg Block - Native WordPress block editor integration
• Category Restriction - Limit which categories appear in the filter dropdown
• Navigation-Based Filtering - Redirects to actual WordPress category archive pages
• Search Integration - Search functionality that redirects to WordPress search results
• Customizable Controls - Toggle search box and category dropdown visibility
• Security - Category restriction enforcement via URL parameters
• Responsive Design - Mobile-friendly filter controls
• Shortcode Support - Use [filtergate] shortcode for classic editor compatibility

Installation

1. Upload the filtergate folder to /wp-content/plugins/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Use the block editor to add the "FilterGate" block to any page or template

Usage

Adding the Block

1. Open the WordPress block editor (Gutenberg)
2. Click the "+" button to add a new block
3. Search for "FilterGate"
4. Add the block to your page or template

Block Settings

In the block sidebar, configure the following options:

Setting	Description	Default
Included Categories	Select which categories to show in the filter dropdown	None (required)
Post Type	The post type to filter	post
Posts Per Page	Number of posts to display per page	12
Display Style	Grid or list layout option	grid
Show Search	Toggle the search input field	Enabled
Show Category Filter	Toggle the category dropdown	Enabled

Shortcode Usage

You can also use the shortcode in classic editor or anywhere shortcodes are supported:

[filtergate included_categories="1,2,3" post_type="post" posts_per_page="12" display_style="grid" show_search="yes" show_category_filter="yes"]

How It Works

1. Category Selection: When a user selects a category from the dropdown, they are redirected to that category's archive page (e.g., /category/blog/)

2. Search Submission:

   • With category selected: Redirects to category archive with search parameter (e.g., /category/blog/?s=keyword)
   • Without category: Redirects to WordPress search page (e.g., /?s=keyword)

3. Category Restriction: The allowed_cats URL parameter ensures only permitted categories are accessible

File Structure

filtergate/
├── filtergate.php            # Main plugin file
├── block.json                # Block configuration
├── render.php                # Frontend block rendering
├── index.php                 # Directory protection
├── README.md                 # Documentation
├── assets/
│   ├── index.php             # Directory protection
│   ├── css/
│   │   ├── frontend.css      # Frontend styles
│   │   ├── editor.css        # Editor styles
│   │   └── index.php         # Directory protection
│   └── js/
│       ├── frontend-filter.js # Frontend JavaScript
│       ├── block-settings.js  # Block editor settings
│       └── index.php          # Directory protection
└── inc/
    ├── index.php              # Directory protection
    ├── functions.php          # Helper functions
    ├── class-filtergate.php   # Main plugin class
    ├── class-block-registration.php # Block registration
    ├── class-query-builder.php     # Query building utilities
    └── class-shortcode.php         # Shortcode support

Security Features

• Direct Access Prevention - All PHP files check for WordPress environment
• Directory Listing Protection - index.php files in all directories
• Input Sanitization - All user inputs sanitized with sanitize_text_field(), absint(), esc_html(), esc_attr(), esc_url()
• Category Validation - Categories validated against existing terms
• Output Escaping - All output properly escaped to prevent XSS
• Query Parameter Validation - URL parameters validated and sanitized
• Nonce Protection - Form submissions protected where applicable

Frontend Components

Search Box

• Search icon (left)
• Text input (center)
• Clear button (X) - appears when text is entered
• Submit button (right) - green rounded button

Category Dropdown

• Positioned below the search box on the right
• Displays only allowed categories
• "CATEGORY" placeholder text

CSS Classes

Class	Description
.filtergate-container	Main wrapper
.filtergate-controls	Filter controls wrapper
.filtergate-form	Form element
.filtergate-search-row	Search input row
.filtergate-search-wrapper	Search input wrapper
.filtergate-search-input	Search text input
.filtergate-search-icon	Search icon (SVG)
.filtergate-clear-search	Clear search button
.filtergate-search-button	Submit button
.filtergate-category-row	Category dropdown row
.filtergate-category-select	Category dropdown select

Hooks & Filters

Actions

// Fires when plugin is fully loaded
do_action( 'filtergate_loaded' );

Filters

// Filter query arguments before executing
apply_filters( 'filtergate_query_args', $query_args, $args );

// Filter shortcode output
apply_filters( 'filtergate_shortcode_output', $output, $atts, $query );

// Filter block output
apply_filters( 'filtergate_block_output', $output, $attributes, $query );

The plugin modifies the main query via pre_get_posts to enforce category restrictions when the allowed_cats parameter is present.

Theme Integration

For best results, ensure your theme's category archive template (category.html or category.php) includes:

1. A Query Loop block with "inherit": true to respect the current category
2. Optionally, a wp:query-no-results block for empty results messaging

Example Category Template Structure

<!-- wp:query {"inherit":true} -->
<div class="wp-block-query">
    <!-- wp:post-template -->
    <!-- Post content here -->
    <!-- /wp:post-template -->

    <!-- wp:query-no-results -->
    <p>No posts found.</p>
    <!-- /wp:query-no-results -->

    <!-- wp:query-pagination -->
    <!-- /wp:query-pagination -->
</div>
<!-- /wp:query -->

Requirements

• WordPress 6.0 or higher
• PHP 7.4 or higher
• Block editor (Gutenberg) enabled

Changelog

1.0.0

• Initial release
• Gutenberg block with category multi-select
• Navigation-based filtering (redirects to archive pages)
• Search integration with WordPress search page
• Category restriction enforcement
• Responsive frontend design
• Shortcode support with [filtergate]
• Full security implementation

Author

Osama Ali Website: https://osama-ali.com

License

GPL v2 or later - https://www.gnu.org/licenses/gpl-2.0.html