Skip to content

README.md

Latest commit

 

History

History
192 lines (141 loc) · 6.71 KB

README.md

File metadata and controls

192 lines (141 loc) · 6.71 KB
Raw

Mobile Lookup Module for Xataface

License: GPL v2 Xataface PHP Select2

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

Mobile Lookup Demo

📱 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