Mobile Lookup Module for Xataface

Widget mobile-friendly per lookup record con ricerca AJAX e interfaccia touch-optimized per Xataface.

📱 Caratteristiche

• ✅ Touch-optimized: Target touch 44px (iOS standard)
• ✅ Ricerca AJAX: Caricamento dinamico risultati con ricerca multi-parola (AND)
• ✅ Focus automatico: Casella ricerca attiva all'apertura elenco
• ✅ Mobile-first: Font-size 16px per evitare zoom iOS
• ✅ Responsive: Adattamento automatico mobile/tablet/desktop
• ✅ Select2: Libreria moderna e performante
• ✅ Sicurezza: Prepared statements e validazione input
• ✅ Dark mode: Supporto tema scuro (opzionale)

🚀 Installazione

1. Attiva modulo in conf.ini

[_modules]
    modules_mobile_lookup=modules/mobile_lookup/mobile_lookup.php

2. Riavvia applicazione

Riavvia PHP o pulisci cache Xataface per caricare il modulo.

📖 Utilizzo

Basic Usage

In tables/TuaTabella/fields.ini:

[fkCliente]
    widget:type=mobile_lookup
    widget:table=BBGFATTClienti
    widget:keycol=cod
    widget:labelcol=rag
    widget:placeholder="Seleziona cliente..."

Advanced Usage

[fkAgente]
    widget:type=mobile_lookup
    widget:table=BBGFATTAgenti
    widget:keycol=cod
    widget:labelcol=nome
    widget:searchFields=nome,cognome,codice
    widget:placeholder="Cerca agente per nome o codice..."
    widget:minimumInputLength=2

Con Filtri Dinamici

[fkRicambio]
    widget:type=mobile_lookup
    widget:table=BBGRicambi
    widget:keycol=id
    widget:labelcol=descrizione
    widget:searchFields=descrizione,codice
    widget:filters[categoria]=$fkCategoria
    widget:placeholder="Seleziona ricambio..."

I filtri con $nomeCampo vengono risolti dinamicamente dal valore di altri campi nel form.

⚙️ Parametri Widget

Parametro	Obbligatorio	Default	Descrizione
widget:table	✅ Sì	-	Nome tabella per lookup
widget:keycol	No	id	Colonna chiave primaria
widget:labelcol	No	nome	Colonna etichetta visualizzata
widget:searchFields	No	labelcol	Campi ricerca (comma-separated)
widget:placeholder	No	"Seleziona..."	Placeholder input
widget:minimumInputLength	No	0	Min caratteri per ricerca
widget:preloadOptions	No	selected	Preload iniziale: selected | first100 | none
widget:allscreen	No	0	Modalità fullscreen su mobile (1 = overlay a schermo intero)
widget:filters[campo]	No	-	Filtri fissi o dinamici ($)

🔍 Comportamento ricerca

La ricerca AJAX replica la logica della lookup standard Xataface (RecordBrowser / QueryBuilder):

• La stringa digitata viene spezzata in parole (separatori: spazi)
• Ogni parola deve comparire in almeno un campo tra widget:searchFields (OR tra campi)
• Tutte le parole devono essere soddisfatte (AND tra parole)

Esempio con widget:searchFields=cod,desc_breve,descrizione,codFornitore:

Query utente	Record tubolare 120 x 40
tubol 120	✅ Trovato (tubol in descrizione, 120 in descrizione)
tubol 120 (v1.0.0)	❌ Cercava %tubol 120% come stringa unica

Consiglio: elencare tutti i campi utili in widget:searchFields, non solo labelcol.

🎨 Personalizzazione CSS

Puoi sovrascrivere gli stili in css/custom.css:

/* Touch target più grande */
.select2-container--default .select2-selection--single {
    height: 52px !important;
}

/* Dropdown con bordo colorato */
.xf-mobile-lookup-dropdown {
    border: 2px solid #0056b3;
}

🔧 Troubleshooting

Widget non appare

• Verifica che il modulo sia attivato in conf.ini
• Controlla console browser per errori JS
• Verifica permessi view sulla tabella lookup

Ricerca non funziona o trova meno risultati della lookup standard

• Verifica widget:searchFields includa i campi giusti (codice, descrizione, ecc.)
• Testa URL AJAX: ?-action=mobile_lookup_search&-table=NomeTabella&-search=tubol%20120&-searchFields=descrizione,cod
• Controlla log PHP e permessi view sulla tabella target
• Dalla v1.1.0 la ricerca multi-parola usa AND tra token (come lookup nativa)

Su mobile non è touch-friendly

• Pulisci cache browser
• Verifica che mobile-lookup.css sia caricato (Dev Tools > Network)
• Font-size input deve essere >= 16px per evitare zoom iOS

🆚 Mobile Lookup vs Lookup Standard

Caratteristica	Lookup Standard	Mobile Lookup
Mobile-friendly	❌ No	✅ Sì
Touch targets	Piccoli	44px iOS standard
Ricerca	Client-side (multi-parola)	AJAX server-side (multi-parola)
Focus ricerca all'apertura	Manuale	Automatico
Paginazione	No	Sì (30 record/pagina)
Zoom iOS	Sì (font <16px)	No (font 16px)
Responsive	Limitato	Full responsive
Performance	OK	Ottimizzata

📝 Note Sviluppo

• Select2 versione: 4.1.0-rc.0 (da CDN)
• Compatibilità: Xataface 2.x, PHP 7.0+
• Database: Usa connessione nativa Xataface df_db()
• Sicurezza: Validazione parametri, sanitizzazione SQL, check permessi
• Performance grid/edit: usare widget:preloadOptions=selected (default) o none per evitare preload massivo di opzioni in form con molte righe

🔜 Roadmap

• Supporto multi-select
• Template custom per risultati
• Cache risultati ricerca
• Infinite scroll invece di paginazione
• Supporto immagini nei risultati

📄 Licenza

Questo progetto è distribuito con licenza GNU GPL v2, compatibile con Xataface.

🤝 Contributing

I contributi sono benvenuti! Leggi CONTRIBUTING.md per le linee guida.

🐛 Bug Reports

Per segnalare bug o richiedere nuove funzionalità, apri una issue su GitHub.

⭐ Supporto

Se questo modulo ti è stato utile, considera di mettere una stella ⭐ al repository!

---

Realizzato con ❤️ da Paolo Bonzini