# FilterWell – Query Loop Filters

Native filters for the WordPress **Query Loop** block: search, sorting, taxonomy, author and date filters, applied with a button or instantly, without page reloads (Interactivity API).

User documentation lives in [`readme.txt`](readme.txt), which is what WordPress.org displays. This file is for development.

## Requirements

- WordPress 6.8 or later
- PHP 7.4 or later
- Node.js 20 or later (only to build)

## Development

```bash
npm install
npm run start   # watch mode
npm run build   # production build
```

Sources are in `src/` and the compiled blocks in `build/`. Both are shipped: WordPress.org requires human-readable sources.

## Structure

| Path | Purpose |
|---|---|
| `filterwell.php` | Plugin header and bootstrap. |
| `includes/class-filterwell.php` | Server logic: URL parameters, query changes, archive handling, counts. |
| `src/filters` | Container block, frontend store (`view.js`) and the Query Loop sidebar panel. |
| `src/taxonomy` | Taxonomy filter; the Author Filter is a variation of it (`taxonomy: "_author"`). |
| `src/date`, `src/sort`, `src/search` | Date range, sorting and search blocks. |
| `src/actions`, `src/active` | Filter / clear buttons and active filter chips. |
| `src/shared` | Code shared by several blocks (loop list, colors, pills row scrolling). |
| `languages` | POT template. |
| `.wordpress-org/translations` | Spanish (`es_ES`, `es_CL`) translations, kept out of the plugin package to import into translate.wordpress.org. |

Each `render.php` wraps its code in a closure so its variables stay local.

## URL parameters

Filters are stored in the URL, per loop. The prefix is `qlf{queryId}` for loops with their own query and `qlf` for loops that inherit the template query.

| Parameter | Meaning |
|---|---|
| `{prefix}_s=text` | Search text. |
| `{prefix}_t_{taxonomy}=a,b` | Terms (slugs), match any (OR). |
| `{prefix}_ta_{taxonomy}=a,b` | Terms (slugs), match all (AND). |
| `{prefix}_au=a,b` | Authors (nicenames). |
| `{prefix}_from=YYYY-MM-DD`, `{prefix}_to=YYYY-MM-DD` | Publish date range, inclusive. |
| `{prefix}_o=date-asc` | Sort order (a key of `FilterWell::SORTS`). |

On category, tag, taxonomy and author archives, the archive term counts as the selected value of its filter and choosing another one navigates to its archive URL. On date archives, the archive period counts as the date range (`date_archive` in `get_request()`).

The Taxonomy Filter's `termsScope` (`all`, `top`, `children`) builds two-level category rows: both rows read the same URL parameter and derive what to show from the selected term and its ancestors.

## Translations

Source strings are in English and translations are delivered by translate.wordpress.org, so the plugin package only includes the POT template. To update it:

```bash
wp i18n make-pot . languages/filterwell.pot --exclude=node_modules,languages,.wordpress-org
```

The Spanish translations (`es_ES`, `es_CL`) live in `.wordpress-org/translations`. Update them with the new template (for example with Poedit) and import them into translate.wordpress.org once the plugin is published.

## Release

```bash
npm run build
npm run plugin-zip   # files listed in package.json "files"
```

Check the package with [Plugin Check](https://wordpress.org/plugins/plugin-check/) before uploading.