# 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/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)
