# Core Concepts

Query Name - The Connection Key

**All elements must share the same Query Name to work together.**

The Query Name is how elements communicate with each other. Think of it as a channel - all elements tuned to the same channel will work together.

```
Example:
- Main Query: query_name = "my-products"
- Facet 1: query_name = "my-products"
- Facet 2: query_name = "my-products"
- Pagination: query_name = "my-products"

✅ All elements share "my-products" = They work together
❌ Different query names = Elements won't connect
```

#### Apply On: Input vs Submit

Most filter elements have an "Apply on" setting:

* **Input (Immediate)**: Filter triggers instantly when user makes a selection
* **Submit (Button)**: Filter waits until user clicks the Submit/Apply button

Use "Submit" mode when you have multiple filters and want users to select all options before filtering.

### The Index System

Woohoo Filters uses a pre-computed index for fast filtering instead of querying WordPress directly each time.

#### Why an Index?

| Approach         | Speed | Scalability           |
| ---------------- | ----- | --------------------- |
| Direct WP\_Query | Slow  | Poor with many posts  |
| **Index-based**  | Fast  | Scales to 100k+ posts |

#### How the Index Works

```
1. REGISTRATION (When page is saved)
   ┌─────────────────────────────────────────────────────────┐
   │ Breakdance Page Save                                    │
   │    ↓                                                    │
   │ Scan for Ajax Filter Facet elements                     │
   │    ↓                                                    │
   │ Register facets in woohoo_facets table                  │
   │    • slug (element_id)                                  │
   │    • name                                               │
   │    • source (taxonomy/category, post_meta/_price, etc.) │
   │    • page_id                                            │
   │    • settings (JSON)                                    │
   └─────────────────────────────────────────────────────────┘

2. INDEXING (Admin action)
   ┌─────────────────────────────────────────────────────────┐
   │ For each registered facet:                              │
   │    ↓                                                    │
   │ Get all posts matching post type                        │
   │    ↓                                                    │
   │ Extract facet values from each post                     │
   │    ↓                                                    │
   │ Store in woohoo_index table                             │
   │    • facet_slug                                         │
   │    • object_id (post ID)                                │
   │    • value (raw value)                                  │
   │    • display_value (formatted for display)              │
   └─────────────────────────────────────────────────────────┘

3. QUERYING (When user filters)
   ┌─────────────────────────────────────────────────────────┐
   │ User selects filter options                             │
   │    ↓                                                    │
   │ AJAX request with selections                            │
   │    ↓                                                    │
   │ Query woohoo_index for matching object_ids              │
   │    ↓                                                    │
   │ Intersect IDs across all active facets                  │
   │    ↓                                                    │
   │ Return filtered results                                 │
   └─────────────────────────────────────────────────────────┘
```

#### Index Data Flow

```
Post: "Blue T-Shirt" (ID: 123)
├── Category: "Clothing" (term_id: 5)
├── Color: "Blue" (term_id: 12)
└── Price: 29.99 (_price meta)

           ↓ Indexing ↓

woohoo_index table:
┌─────────────────┬───────────┬─────────┬───────────────┐
│ facet_slug      │ object_id │ value   │ display_value │
├─────────────────┼───────────┼─────────┼───────────────┤
│ facet_category  │ 123       │ 5       │ Clothing      │
│ facet_color     │ 123       │ 12      │ Blue          │
│ facet_price     │ 123       │ 29.99   │ $29.99        │
└─────────────────┴───────────┴─────────┴───────────────┘
```