# 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        │
└─────────────────┴───────────┴─────────┴───────────────┘
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.woohoo.dance/ajax-filters/core-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.