# Shortcode di ricerca DM Parri

Documentazione degli shortcode che espongono interfacce di ricerca e dei parametri condivisi.

## Due URL diversi: `endpoint` e `results_page`

| Attributo | Ruolo |
|-----------|--------|
| **`endpoint`** | URL della **REST API** WordPress usata da JavaScript per le richieste `fetch()` (AJAX). Puoi sovrascriverlo solo se serve puntare a un’installazione o a un percorso API diverso. |
| **`results_page`** | URL **pubblico di una pagina WordPress** (barra degli indirizzi del browser) verso cui reindirizzare l’utente **con la stessa query string** che l’API si aspetta, così la “pagina risultati” può mostrare elenco e filtri senza duplicare la logica lato server. |

**Pattern consigliato**

1. **Pagina “home ricerca”** (form compatto): shortcode **con** `results_page="https://…/ricerca-documenti/"` (URL della pagina dove mostri i risultati).
2. **Pagina risultati**: stesso tipo di shortcode **senza** `results_page`, così i risultati restano sulla pagina corrente; con `[parri_unified_advanced_search]` i parametri `?q=&fondo=&…` vengono letti all’avvio e viene eseguita la prima ricerca.

`endpoint` e `results_page` sono **indipendenti**: il primo parla con WordPress REST, il secondo è solo navigazione del browser.

---

## Elenco shortcode

### `[parri_faceted_search]`

Ricerca facetata classica (barra, ordinamento, sidebar facet, elenco).

- **`results_page`**: se valorizzato, l’area elenco risultati è nascosta in pagina; i facet restano utilizzabili; **Invio** nel campo di ricerca invia a `results_page` con `q`, facet ripetuti, `page`, `sort`. Cambio facet, ordinamento, chip e “Pulisci tutto” reindirizzano con gli stessi parametri.
- Attributi principali: `facets`, `endpoint`, `page_size`, `sort`, `search_placeholder`, ecc. (vedi `frontend_functions.php`).

### `[parri_advanced_search]`

Form con più campi (fondo, titolo, date, …) e invio.

- **`results_page`**: al submit del form il browser va a quell’URL con tutti i campi compilati più `page` e `per_page` (nessuna chiamata AJAX sulla pagina di partenza).

### `[parri_text_search]`

Ricerca per testo libero.

- **`results_page`**: al submit si reindirizza con `text`, `page`, `per_page`. Sulla pagina destinazione, shortcode **senza** `results_page`: il campo viene letto da `?text=` (e `?page=`) all’avvio e parte la prima ricerca se `text` non è vuoto.

### `[parri_unified_search]`

Ricerca unificata stile ACS (raggruppamento per tipologia, pannello avanzato).

- **`results_page`**: sulla pagina di partenza non si caricano risultati in pagina; **Cerca** reindirizza alla URL indicata con i parametri di `buildParams()` (stessi nomi dell’API `unified_search`). Se l’URL di arrivo **contiene già** una ricerca (`q`, facet, ecc.) — ad esempio da un link preimpostato — lo script **reindirizza subito** verso `results_page` con quei parametri, così non resta una “pagina di mezzo” con solo la barra compilata. La **pagina destinazione** deve avere lo shortcode **senza** `results_page` così partono i risultati. Modifica facet/chip in modalità redirect aggiorna stato e chip fino al click su Cerca.
- **`visibili_subito`**: alias user-friendly di `per_tipologia` (quanti risultati mostrare subito per ogni categoria nella vista raggruppata). Default: **4**.
- **Allegati documento**: se un documento ha record in `wp_digit_allegato` (`id_documento`), nelle card risultato compare la sezione **Allegati** con link pubblico (URL assoluto già salvato, file locale `wp-content`, oppure URL Cloudflare R2 costruito da `provider_config.public_url` + `path_prefix` della voce `allegati` in `config.php`).
- Se un documento ha record in `wp_digit_allegato`, nella card/lista viene mostrata la sezione **Allegati** con link pubblico (Cloudflare R2 o URL file disponibile).

### `[parri_unified_advanced_search]`

Form ricerca avanzata + risultati con sidebar filtri.

- **`results_page`**: sulla pagina di partenza l’intero blocco risultati è nascosto; **Cerca** (barra o submit form avanzato) reindirizza con `buildParams()`.
- **Pagina destinazione senza** `results_page**: all’avvio, se l’URL contiene parametri di ricerca (`q`, campi avanzati, facet, ecc.), lo stato viene ricostruito e parte la prima `loadData()`.
- **`visibili_subito`**: alias di `per_tipologia` per il numero di risultati visibili subito in ciascun blocco tipologia. Default: **4**.

### `[parri_preset_search]` (alias `[parri_search_button_preset]`)

**Link** (non un modulo) verso la pagina risultati con **`results_page`** obbligatorio. Attributi in **italiano** per chi pubblica contenuti; i valori vengono convertiti in query string come `[parri_unified_search_button]` / API `unified_search`.

| Attributo | Effetto |
|-----------|---------|
| **`cerca`** | Testo libero (`q` nell’URL). |
| **`fondo`** | Uno o più ID numerici, oppure **nome** (o parte) del fondo in `digit_fondi.nome_fondo` → risoluzione in `fondo=ID`. |
| **`luogo`** | Come fondo, su `digit_luoghi.nome`. |
| **`tags`** | ID o testo tag (`digit_tags.tag`). |
| **`anno_da`** / **`anno_a`** | Intervallo anni inclusivo. |
| **`modalita_anno`** | `range` (default): URL corto con `anno_da`/`anno_a` e filtro SQL tipo BETWEEN. `lista`: espande in facet `data` (anni singoli). |
| **`ordinamento`** | Ordine blocchi tipologia: elenco separato da **virgole** (nomi o ID come `tipologia_order`), oppure `nome1|nome2|nome3` per evitare ambiguità. |
| **`results_page`** | URL della pagina con `[parri_unified_search]` (obbligatorio). |
| **`label`**, **`class`**, **`target`**, **`rel`**, **`extra_query`**, **`per_tipologia`** / **`visibili_subito`**, **`page_size`**, **`tipologia`**, **`page`** | Come per `parri_unified_search_button`. |

Se `label` è vuoto e `cerca` è valorizzato, l’etichetta diventa «Cerca: …».

### `[parri_unified_search_button]`

**Link** (stile pulsante) verso una pagina che contiene `[parri_unified_search]` **senza** `results_page`, con parametri GET opzionali già impostati (stessa logica di query di `unified_search.js` in modalità raggruppata / lista). Per **nomi** di fondo/luogo in chiaro usare `[parri_preset_search]`.

- **Obbligatorio per un link visibile**: `results_page` = URL completo della pagina di ricerca (es. `https://tuosito.it/archivio/ricerca/`).
- **Allineati a** `[parri_unified_search]`: `facets`, `tipologia_order`, `per_tipologia` (alias `visibili_subito`), `page_size`, `search_placeholder`, `endpoint`, `show_clear_all`, `debug` (in un link puro `endpoint` e `debug` non cambiano il comportamento; servono per coerenza e futuri usi).
- **`results_page`**: come sopra (pagina destinazione).
- **Pulsante / link**: `label` (testo), `class` (CSS, default `parri-us-button`), `target` (es. `_blank`), `rel`.
- **Preimpostazioni ricerca**: `q`, `tipologia` (ID per vista “lista” tipologia), `page`, `anno_da` / `anno_a`, `fondo` / `luogo` / `data` / `tags` (CSV), `extra_query` (stringa query aggiuntiva, uso avanzato).

Implementazione: `classes/class-dm-parri-unified-search-button.php` + test in `tests/`. Preset italiano: `classes/class-dm-parri-preset-search-link.php` + `tests/PresetSearchLinkTest.php`.

---

## Esempi

Home con redirect verso pagina risultati dedicata:

```
[parri_unified_search results_page="https://www.esempio.it/archivio/ricerca/" visibili_subito="8"]
```

Pagina `/archivio/ricerca/` (solo risultati, stessi parametri in query string):

```
[parri_unified_search]
```

Ricerca facetata da landing:

```
[parri_faceted_search results_page="https://www.esempio.it/archivio/elenco/"]
```

Link (non modulo) con parametri in italiano verso la pagina che contiene `[parri_unified_search]` (sostituisci l’URL con quello reale della tua pagina risultati):

```
[parri_preset_search results_page="https://www.esempio.it/archivio/ricerca/" cerca="partigiani" fondo="1" luogo="2" anno_da="1946" anno_a="1948" modalita_anno="range" visibili_subito="10" ordinamento="Fotografia|Volantino" label="Apri ricerca preimpostata"]
```

(`fondo` / `luogo` qui sono esempi numerici; puoi usare anche nomi risolvibili sul database.)

---

## File coinvolti

- Configurazione shortcode e `resultsPage` in JS: `frontend_functions.php`
- Pulsante link ricerca unificata: `classes/class-dm-parri-unified-search-button.php`, test `tests/UnifiedSearchButtonTest.php`
- Link preimpostato (attributi in italiano): `classes/class-dm-parri-preset-search-link.php`, test `tests/PresetSearchLinkTest.php`
- Logica redirect: `assets/filters.js`, `advanced_search.js`, `text_search.js`, `unified_search.js`, `unified_advanced_search.js`
- Stili modalità redirect: `assets/filters.css`, `assets/unified_search.css`, `assets/unified_advanced_search.css` (classi `*-redirect-mode`)

Per il dettaglio di ogni attributo PHP, cercare `shortcode_atts` e il nome dello shortcode in `frontend_functions.php`.