# Documentazione Plugin Entourance WordPress

## Panoramica Generale

Il plugin **Entourance** è un plugin WordPress sviluppato da Alessandro Caponi e Eleonora Pirri di Poistory S.r.l. che permette di integrare prodotti del sistema DMS Entourance in un sito WordPress. Il plugin è attualmente alla versione 1.9.9 e supporta la visualizzazione di diversi tipi di contenuti turistici.

## Tipi di Contenuti Supportati

Il plugin gestisce i seguenti tipi di prodotti:

1. **Experience** - Esperienze turistiche
2. **Event** - Eventi
3. **Host** - Strutture ricettive (hotel, B&B, agriturismi, ecc.)
4. **Eatery** - Ristoranti e locali
5. **POI** - Punti di interesse
6. **Itinerary** - Itinerari
7. **Article** - Articoli
8. **Experience-Supplier** - Fornitori di servizi

## Architettura del Plugin

### Classi Principali

#### 1. EntourancePlugin
- **File**: `class-entouranceplugin.php`
- **Funzione**: Classe principale del plugin che gestisce:
  - Registrazione degli script e stili
  - Pagine di amministrazione
  - Impostazioni del plugin
  - Gestione dei template personalizzati
  - Sistema di cache per gli stili personalizzati

#### 2. Entourance_Product
- **File**: `class-entourance-product.php`
- **Funzione**: Classe per la gestione dei prodotti Entourance con:
  - Mapping dei dati dall'API
  - Gestione delle traduzioni
  - Cache dei prodotti (6 ore)
  - Supporto per tutti i tipi di contenuto

#### 3. Entourance_Admin
- **File**: `class-entourance-admin.php`
- **Funzione**: Gestione dell'interfaccia di amministrazione

#### 4. EntouranceAPI
- **File**: `class-entouranceapi.php`
- **Funzione**: Gestione delle chiamate API al sistema Entourance

#### 5. Entourance_Rewrite
- **File**: `class-entourance-rewrite.php`
- **Funzione**: Gestione delle regole di rewrite per URL personalizzati

## Shortcode Disponibili

### 1. entourance-slider
**Funzione**: Visualizza uno slider di prodotti

**Parametri**:
- `ids` (default: null) - ID specifici dei prodotti
- `type` (default: 'experience') - Tipo di prodotto
- `city` (default: null) - Filtro per città
- `category` (default: 'all') - Filtro per categoria
- `tag` (default: null) - Filtro per tag
- `experience_type` (default: 'all') - Tipo di esperienza
- `show_event` (default: 'on') - Mostra eventi
- `order_field` (default: 'title') - Campo per ordinamento
- `order_direction` (default: 'ASC') - Direzione ordinamento
- `limit` (default: 1000) - Limite prodotti
- `title` (default: null) - Titolo dello slider
- `loop` (default: false) - Loop continuo
- `autoplay` (default: false) - Autoplay
- `season` (default: null) - Filtro per stagione

**Esempio**:
```
[entourance-slider type="experience" category="sport_e_avventura" limit="6" autoplay="true"]
```

### 2. entourance-list-map
**Funzione**: Visualizza una lista di prodotti con mappa e calendario

**Parametri**:
- `type` (default: 'experience') - Tipo di prodotto
- `city` (default: null) - Filtro per città
- `category` (default: null) - Filtro per categoria
- `map` (default: 'true') - Mostra mappa
- `list` (default: 'true') - Mostra lista
- `calendar` (default: 'true') - Mostra calendario
- `experience_type` (default: 'all') - Tipo di esperienza
- `category_filter` (default: 'true') - Filtro categorie
- `subcategory_filter` (default: 'true') - Filtro sottocategorie
- `location_filter` (default: 'false') - Filtro località
- `location_type` (default: 'city') - Tipo di località
- `date_filter` (default: 'true') - Filtro date
- `order_field` (default: null) - Campo ordinamento
- `order_direction` (default: null) - Direzione ordinamento
- `tag` (default: null) - Tag da includere (virgola-separati: prodotti con almeno uno dei tag)
- `tag_not` (default: null) - Tag da escludere (virgola-separati: esclude prodotti con questi tag)
- `tag_filter` (default: 'false') - Mostra dropdown filtro tag
- `type_page` (default: null) - Tipo di pagina
- `items_to_show` (default: null) - Elementi per pagina
- `show_search_box` (default: true) - Mostra box di ricerca
- `tab_order` (default: 'list,map,calendar') - Ordine dei tab
- `list_label` (default: 'Lista') - Etichetta del tab lista (se 'Lista' viene tradotto automaticamente)

**Esempio**:
```
[entourance-list-map type="host" category="hotel" map="true" calendar="true" show_search_box="true"]
```

**Esempio con ordine tab personalizzato**:
```
[entourance-list-map type="experience" tab_order="map,list,calendar" list_label="Archivio"]
```

**Note sulle traduzioni**:
- Se `list_label="Lista"`, l'etichetta viene tradotta automaticamente in base alla lingua del sistema
- Se `list_label="Archivio"` (o altro testo), viene mostrato il testo personalizzato senza traduzione
- Le altre etichette (Mappa, Calendario) sono sempre tradotte automaticamente

### 3. entourance-single-product
**Funzione**: Visualizza un singolo prodotto

**Parametri**:
- `id` (default: null) - ID del prodotto (obbligatorio)
- `type` (default: 'experience') - Tipo di prodotto
- `language` (default: null) - Lingua
- `title` (default: null) - Titolo personalizzato

**Esempio**:
```
[entourance-single-product id="123" type="experience" title="Esperienza Speciale"]
```


## Funzionalità delle Liste

### Template: product-list.php
Il template delle liste offre:

1. **Sistema a Tab**:
   - Tab Lista: visualizzazione a griglia dei prodotti
   - Tab Calendario: visualizzazione temporale degli eventi

2. **Filtri Disponibili**:
   - Ricerca testuale
   - Filtro per categoria
   - Filtro per sottocategoria
   - Filtro per località
   - Filtro per tag
   - Filtro per stelle (per strutture ricettive)
   - Filtro temporale (per calendario)

3. **Funzionalità Avanzate**:
   - Infinite scroll
   - Paginazione personalizzabile
   - Ordinamento dinamico
   - Cache delle traduzioni
   - Responsive design

### Template: product-slider.php
Il template dello slider offre:

1. **Caratteristiche**:
   - Slider responsive (1-3 elementi per slide)
   - Controlli di navigazione (frecce e indicatori)
   - **Supporto touch/swipe** per dispositivi mobili
   - **Supporto drag** per desktop
   - Indicatori di posizione
   - Autoplay opzionale
   - Loop continuo
   - Transizioni fluide e animate

2. **Interazione Mobile/Desktop**:
   - **Swipe touch** su dispositivi mobili (distanza minima 30px)
   - **Drag con mouse** su desktop
   - Rilevamento intelligente dello swipe orizzontale vs scroll verticale
   - Cursore grab/grabbing durante l'interazione
   - Prevenzione selezione testo durante swipe/drag

3. **Filtri**:
   - Filtro per categoria
   - Filtro per stagione
   - Ordinamento personalizzato
   - Limite elementi

## Funzionalità Single Product

### Template: single-product-template.php
Il template per i singoli prodotti include:

1. **Sezioni Principali**:
   - Header con titolo e categoria
   - Galleria immagini
   - Contenuto principale
   - Sidebar con informazioni aggiuntive
   - Prodotti correlati

2. **Sidebar Dinamica**:
   - Prezzi e biglietti
   - Disponibilità
   - Durata
   - Pubblico di riferimento
   - Numero partecipanti
   - **Difficoltà** (con visualizzazione icone attive/disabilitate)
   - Informazioni specifiche per itinerari (distanza, tempo, mezzi di trasporto, tipo strada, ecc.)
   - File GPX scaricabili
   - Contatti
   - Servizi
   - Organizzatore/Fornitore
   - Tag
   - Accessibilità

3. **Funzionalità Speciali**:
   - Sticky sidebar
   - Carousel immagini
   - Gestione traduzioni

## Sistema di Traduzioni

Il plugin supporta un sistema di traduzioni avanzato:

1. **Lingue Supportate**:
   - Italiano (it_IT)
   - Inglese (en_EN, en_US, en_GB)

2. **Campi Traducibili**:
   - Titoli
   - Descrizioni
   - Informazioni utili
   - Descrizioni accessibilità
   - Descrizioni località

3. **Gestione Traduzioni**:
   - Cache delle traduzioni
   - Fallback automatico
   - Traduzioni specifiche per tipo di contenuto

## Impostazioni di Amministrazione

### Pagine di Amministrazione

1. **Settings**: Configurazione generale
2. **Shortcode Generator**: Generatore di shortcode
3. **Content Settings**: Impostazioni contenuti e visualizzazione
4. **Icons and Labels Settings**: Impostazioni icone, marcatori mappa e difficoltà

### Impostazioni Principali

1. **Connessione API**:
   - Server Entourance
   - Email e password
   - Client ID
   - Realm ID

2. **Personalizzazione**:
   - Colori primari e secondari
   - CSS personalizzato
   - Icone personalizzate per ogni tipo di contenuto
   - **Icona difficoltà personalizzabile** (default: fas fa-mountain)
   - **Difficoltà massima** (4 o 5 livelli)
   - Marcatori mappa colorati per tipo
   - Font Awesome Pro

3. **Visualizzazione Difficoltà**:
   - Configurazione difficoltà massima (4 o 5 livelli)
   - Visualizzazione con icone attive (colorate) e disabilitate (grigie)
   - Testo esplicativo "X su Y" (es. "2 su 5" o "2 of 5")
   - Icona personalizzabile tramite Font Awesome

4. **Contenuti**:
   - Filtri per categoria
   - Gestione tag
   - Impostazioni calendario
   - Mostra/nascondi elementi

## Sistema di Cache

Il plugin implementa un sistema di cache per:

1. **Prodotti**: Cache di 6 ore per i prodotti
2. **Traduzioni**: Cache delle traduzioni in file JSON
3. **Stili**: Cache degli stili personalizzati
4. **Immagini**: Gestione cache delle immagini di copertina

## Funzionalità AJAX

Il plugin utilizza AJAX per:

1. **Caricamento dinamico** dei prodotti
2. **Filtri in tempo reale**
3. **Paginazione** senza ricaricamento pagina

## Responsive Design

Tutti i template sono completamente responsive con:

1. **Breakpoint Bootstrap**:
   - Mobile: < 576px
   - Tablet: 576px - 992px
   - Desktop: > 992px

2. **Adattamenti**:
   - Slider: 1 elemento mobile, 2 tablet, 3 desktop
   - Griglie: responsive automatico
   - Sidebar: sticky su desktop, normale su mobile

## Sicurezza

Il plugin implementa:

1. **Sanitizzazione** di tutti gli input
2. **Escape** di tutti gli output
3. **Verifica** delle capacità utente
4. **Validazione** dei parametri shortcode

## Performance

Ottimizzazioni implementate:

1. **Lazy loading** delle immagini
2. **Minificazione** degli asset
3. **Cache** intelligente
4. **Caricamento condizionale** degli script

## Compatibilità

- **WordPress**: 5.0+
- **PHP**: 7.4+
- **Browser**: Moderni (Chrome, Firefox, Safari, Edge)
- **Dispositivi**: Desktop, Tablet, Mobile (iOS e Android)
- **Touch Events**: Supporto completo per dispositivi touch

## Novità Versione 1.9.9

### Difficoltà Prodotti
- Aggiunto setting per configurare la **difficoltà massima** (4 o 5 livelli)
- Migliorata visualizzazione difficoltà nella sidebar dei prodotti:
  - Icone attive mostrate a colori (primary color)
  - Icone rimanenti mostrate disabilitate (grigie con opacità 30%)
  - Testo esplicativo "X su Y" (es. "2 su 4" o "3 su 5")
- Icona difficoltà personalizzabile nelle impostazioni (default: `fas fa-mountain`)

### Product Slider Touch/Swipe
- Implementato **supporto completo per touch/swipe** su dispositivi mobili
- Implementato **supporto drag** con mouse su desktop
- Rilevamento intelligente swipe orizzontale vs scroll verticale
- Transizioni fluide e animate
- Migliorata gestione delle card per evitare tagli durante la navigazione
- Distanza minima swipe ottimizzata (30px) per maggiore sensibilità
- Cursore interattivo grab/grabbing durante il drag

### Miglioramenti Tecnici
- Corretta formula di traslazione dello slider per allineamento perfetto delle card
- Rimosso `gap` CSS in favore di `padding` per calcoli più precisi
- Ottimizzato layout responsive per mobile, tablet e desktop
- Prevenzione selezione testo durante interazioni touch/drag
- Gestione corretta eventi `touchstart`, `touchmove`, `touchend`
- Gestione eventi mouse `mousedown`, `mousemove`, `mouseup`, `mouseleave`