# Wiki — Tema Tents Single Page (Child Twenty Seventeen)

**Repository:** `https://niphredil.duckdns.org/git/fabio/tonitalia-theme.git`  
**Cartella WordPress:** `wp-content/themes/tents-singlepage-child/`  
**Nome tema:** Tents Single Page (Twenty Seventeen Child)  
**Versione attuale:** 1.0.11  
**Parent obbligatorio:** Twenty Seventeen (`twentyseventeen`)

---

## 1. Scopo del tema

Il child theme trasforma il sito in un layout **single-page** sulla homepage: ogni voce di **primo livello** del menu principale che punta a una **pagina** diventa una **sezione** scrollabile con ancora (`#section-slug`).

Le **pagine interne** (sottomenu o link diretti) mantengono il comportamento classico di WordPress con permalink normali.

---

## 2. Requisiti

| Requisito | Dettaglio |
|-----------|-----------|
| WordPress | 6.0+ consigliato |
| PHP | 8.0+ (allineato all’hosting) |
| Tema parent | **Twenty Seventeen** installato e attivo |
| Menu | Posizione tema `top` (Menu principale) configurata |

---

## 3. Installazione e aggiornamento

1. Caricare la cartella `tents-singlepage-child` in `wp-content/themes/`.
2. **Aspetto → Temi** → attivare **Tents Single Page (Twenty Seventeen Child)**.
3. Verificare che Twenty Seventeen sia presente (non disattivarlo).
4. Per aggiornamenti da Git: sovrascrivere la cartella del child theme e svuotare eventuale cache (plugin cache, Aruba, ecc.).

---

## 4. Architettura file

| File / cartella | Ruolo |
|-----------------|--------|
| `style.css` | Intestazione tema (Template: twentyseventeen) |
| `functions.php` | Asset, Customizer, menu ancore, helper sezioni |
| `front-page.php` | Template homepage: renderizza tutte le sezioni |
| `page.php` | Pagine interne con titolo stile homepage |
| `template-parts/section-generic.php` | Markup di ogni sezione homepage |
| `template-parts/navigation/navigation-top.php` | Menu superiore (override child) |
| `template-parts/navigation/menu-toggle-button.php` | Bottone hamburger menu (componente riutilizzabile) |
| `template-parts/page/content-page.php` | Contenuto pagine interne |
| `assets/css/singlepage.css` | Stili layout single-page, header fisso, sezioni |
| `assets/js/singlepage.js` | Scroll ancore, menu mobile, header fisso |

---

## 5. Come funziona la homepage (single-page)

### 5.1 Origine delle sezioni

La funzione `tents_singlepage_get_sections()` legge il **menu nella posizione `top`**:

- Considera solo voci di **primo livello** (`menu_item_parent = 0`).
- Solo voci che puntano a una **pagina** (`object = page`).
- Per ogni pagina crea una sezione con:
  - **ID HTML:** `section-{slug-pagina}` (es. `section-chi-siamo`)
  - **Titolo:** titolo della pagina
  - **Contenuto:** contenuto editor della pagina (filtro `the_content`)

### 5.2 Template `front-page.php`

In homepage WordPress carica `front-page.php`, che in loop chiama `template-parts/section-generic.php` per ogni sezione.

Se **nessuna sezione** è disponibile (menu vuoto o mal configurato), mostra un fallback con il contenuto pagina front-page standard.

### 5.3 Sezione generica (`section-generic.php`)

Ogni sezione può avere:

- **Immagine di sfondo** da Customizer (per slug pagina) oppure immagine in evidenza della pagina.
- **Colori testo/sfondo** da Customizer (`section_{slug}_bg_color`, `section_{slug}_text_color`, ecc.).
- **Pulsanti stack** (fino a 3 CTA per sezione) configurabili nel Customizer.
- Tipografia titoli allineata al design Tents (classi CSS dedicate).

---

## 6. Menu e navigazione

### 6.1 Comportamento link

Filtro `tents_singlepage_filter_nav_menu_link_attributes`:

| Livello menu | Destinazione link |
|--------------|-------------------|
| **Primo livello** (pagina) | Sempre `https://sito.it/#section-{slug}` — anche da pagine interne |
| **Secondo livello e oltre** | Permalink normale della pagina (`get_permalink`) |

Esempio struttura menu:

```
Chi siamo          → /#section-chi-siamo     (primo livello)
Progetti           → /#section-progetti
  └ Sotto-progetto A → /progetti/sotto-a/     (secondo livello)
Contatti           → /#section-contatti
```

### 6.2 JavaScript (`singlepage.js`)

- **Click su primo livello:** scroll animato alla sezione se si è già in homepage; altrimenti navigazione a `/#section-*` e scroll al caricamento.
- **Menu hamburger:** toggle classe `is-open` su `.singlepage-nav`; con header fisso attivo il toggle è anche nella barra superiore (`menu-toggle-button.php`).
- **Pannello mobile:** con header fisso, il menu collassabile usa la classe `singlepage-menu-container--mobile-panel`.
- **Header fisso:** calcolo altezza `--tents-fixed-header-height` per offset scroll corretto.
- **Hash in URL:** supporto `#section-slug` all’apertura pagina (deep link).

### 6.3 Stili menu e cache

- `singlepage.css`: colori menu responsive con header fisso (mobile/desktop).
- Fallback CSS inline in `functions.php` se **WP Fastest Cache** o regole globali del parent forzano testo bianco illeggibile sul menu mobile.

### 6.4 Impostazione menu in WordPress

1. **Aspetto → Menu** (o **Personalizza → Menu**).
2. Assegnare il menu alla posizione **Menu principale** / `top` (dipende dall’etichetta in Personalizza).
3. Creare voci di primo livello come **Collegamenti a: Pagina**.
4. Eventuali sottomenu come pagine figlie per contenuti “interni”.

---

## 7. Personalizzazione (Customizer)

**Aspetto → Personalizza** espone impostazioni aggiuntive del child theme.

### 7.1 Header fisso

Sezione dedicata (es. “Header fisso” / impostazioni `tents_singlepage_fixed_header`):

- Abilitazione header fisso.
- Colori sfondo e testo barra.
- Logo (altezza massima).
- Due CTA opzionali (testo, URL, colori) — es. Dona / Contatti.
- Variabili CSS inline: `--tents-fixed-header-*`.

### 7.2 Immagini e colori per sezione

Per **ogni pagina** usata come sezione homepage, il Customizer registra dinamicamente:

- Immagine di sfondo sezione.
- Colore sfondo / testo.
- Opacità overlay.
- Pulsanti stack (etichetta, URL, stile).

Gli slug delle impostazioni seguono il nome slug della pagina WordPress.

### 7.3 Social

Sezione **Social** nel Customizer:

- URL Facebook, Instagram, YouTube (campi URL).
- Usati nel markup del tema dove previsto.

### 7.4 Header image Twenty Seventeen

Il child normalizza URL asset locali (`tents_singlepage_normalize_*`) per evitare problemi con `localhost` vs produzione dopo migrazione.

---

## 8. Pagine interne

`page.php` + `content-page.php`:

- Titoli con classe `tents-home-title-typography` (stessa tipografia titoli sezioni homepage, colori da tema).
- Non usano il layout a sezioni scroll; sono pagine classiche.

Utile per: privacy policy, iscrizione socio (shortcode plugin), articoli lunghi, sottopagine del menu.

---

## 9. Asset e stili

- Il child **ricarica** lo stylesheet del parent da `get_template_directory_uri()` (evita path errati del child).
- `singlepage.css` gestisce: sezioni full-width, contrasto testo, menu responsive, header fisso.
- Versioning asset tramite `filemtime` per cache busting in sviluppo.

---

## 10. Configurazione consigliata (checklist)

- [ ] Twenty Seventeen installato
- [ ] Child theme attivo
- [ ] Homepage impostata: **Impostazioni → Lettura → Una pagina statica** (la pagina front può essere qualsiasi; il template `front-page.php` ha priorità)
- [ ] Menu `top` con voci primo livello = pagine
- [ ] Slug pagine chiari (generano ancore leggibili)
- [ ] Customizer: colori/immagini per sezione principali
- [ ] Test da mobile: menu hamburger + scroll ancore
- [ ] Test da pagina interna: click menu primo livello → torna a homepage sulla sezione giusta

---

## 11. Risoluzione problemi

| Problema | Possibile causa | Soluzione |
|----------|-----------------|-----------|
| Homepage senza sezioni | Menu non assegnato a `top` o voci non sono “Pagina” | Riconfigurare menu |
| Click menu non scrolla | Link non è `#section-*` | Verificare che la voce sia primo livello + pagina |
| Colori titoli pagine interne diversi | Normale: parent usa stili diversi | Child applica `tents-home-title-typography` in `content-page.php` |
| Immagini rotte dopo migrazione | URL assoluti localhost | Search-replace DB o filtri normalize nel tema |
| Header copre contenuto | Header fisso attivo | JS imposta offset; verificare `has-tents-fixed-header` su body |
| Menu mobile testo bianco su sfondo chiaro | Cache CSS / parent Twenty Seventeen | Aggiornare a v1.0.11+; purge WP Fastest Cache |

---

## 12. Repository Git e release

```bash
cd wp-content/themes/tents-singlepage-child
git pull origin master
git add .
git commit -m "v1.0.x: descrizione"
git push origin master
```

Pacchetti zip in `releases/tents-singlepage-child-X.Y.Z.zip` (tag Git `vX.Y.Z`).

**Download ultima release (1.0.11):**  
`https://niphredil.duckdns.org/git/fabio/tonitalia-theme/raw/v1.0.11/releases/tents-singlepage-child-1.0.11.zip`

Generazione zip dal progetto sito: `./deploy/build-theme-zip.sh` (legge la versione da `style.css`).

**Importante:** lo zip deve contenere la cartella `tents-singlepage-child/` come radice.

### Changelog sintetico

| Versione | Novità principali |
|----------|-------------------|
| 1.0.11 | Menu toggle in header fisso, pannello mobile, fix colori menu con cache |
| 1.0.0 | Release iniziale single-page, header fisso, Customizer sezioni |

---

## 13. Sviluppo locale

**Non includere** nel repo del tema: l’intero sito WordPress, plugin, upload.

---

## 14. Relazione con altri componenti

- **Plugin TON Italia Registration:** non dipende dal tema; inserire shortcode `[ton_registration_form]` in una **pagina** (es. voce menu secondo livello o pagina dedicata).
- **Deploy hosting:** pacchetto completo sito separato; il tema si aggiorna via Git o copia FTP della sola cartella child.

---

## 15. Crediti

- Author: Fabio Arrigoni  
- Basato su Twenty Seventeen (WordPress.org)
