A fianco ai comportamenti predefiniti relativi alla navigazione tra le pagine e all'interazione con gli elementi di una pagina, jQuery Mobile mette a disposizione un insieme di API per l'interazione con il framework tramite JavaScript.
Le API sono composte da una collezione di metodi, eventi e opzioni di configurazione che consentono un maggiore controllo sugli elementi di jQuery Mobile e sul relativa comportamento. In questa sezione esploreremo i componenti di queste API e vedremo come sfruttarli nelle nostre applicazioni.
I metodi esposti dalle API di jQuery Mobile fanno riferimento all'oggetto globale $.mobile e consentono di gestire la navigazione tra le pagine e lo scrolling. Nello specifico, esamieremo i metodi changePage(), loadPage(), showPageLoadingMsg(), hidePageLoadingMsg() e silentScroll().
changePage
Il metodo changePage() consente di navigare mediante codice tra le pagine di un'applicazione. Esso è utile in quelle situazioni in cui la navigazione ad una pagina, interna o esterna che sia, non è semplicemente legata ad un link. Oltre a consentire la transizione verso una pagina, changePage() è in grado di gestire la history della navigazione e prevede altre opzioni che forniscono un meccanismo molto flessibile per il controllo del passaggio da una pagina all'altra.
La sintassi della chiamata a questo metodo prevede due parametri di cui soltanto il primo è obbligatorio:
changePage(to, options)| Parametro | Descrizione |
|---|---|
to |
indica la pagina verso cui navigare |
options |
parametro opzionale per specificare le modalità di transizione verso la nuova pagina |
Vediamo subito qualche esempio pratico. Per navigare verso una pagina interna possiamo indicare l'ID della pagina stessa:
$.mobile.changePage("#home");Se si tratta di una pagina esterna, possiamo indicare il nome del relativo file:
$.mobile.changePage("myPage.html")È anche possibile specificare l'oggetto jQuery che rappresenta la pagina interna come nel seguente esempio:
$.mobile.changePage($("#home"));Per personalizzare le modalità di navigazione alla pagina successiva, possiamo passare come secondo parametro del metodo changePage() un oggetto le cui proprietà rappresentano le opzioni da applicare.
Ad esempio, possiamo specificare l'effetto di transizione da utilizzare quando si passa alla nuova pagina:
$.mobile.changePage("#home", {transition: "slideup"});Se in particolari condizioni vogliamo fare in modo che la navigazione alla nuova pagina non modifichi la history corrente possiamo impostare a false l'opzione changeHash. Può essere il caso, ad esempio, della visualizzazione di una pagina come finestra di dialogo.:
$.mobile.changePage("#home", {transition: "popup", changeHash: false});Nel caso in cui abbiamo necessità di inviare dei dati ad una pagina tramite il metodo HTTP POST possiamo farlo utilizzando le opzioni type e data:
$.mobile.changePage("elaboraDati.aspx", {type: "post", data: $("#dati").serialize()});Da notare in quest'ultimo caso che i dati contenuti nell'elemento $("#dati") vengono serializzati invocando l'apposito metodo serialize().
loadPage
Il metodo loadPage() consente di caricare una pagina esterna ed inserire il suo contenuto nel DOM della pagina corrente. L'esecuzione di questo metodo non influenza la pagina attiva, può quindi essere utilizzato per caricare in maniera asincrona una pagina esterna.
Il metodo prevede due parametri: l'URL della pagina da caricare e un oggetto che rappresenta le opzioni per il caricamento, così come avviene per il metodo changePage(). Il metodo restituisce l'oggetto che rappresenta la pagina caricata.
showPageLoadingMsg e hidePageLoadingMsg
Il metodo showPageLoadingMsg() permette di visualizzare la finestra di dialogo standard di jQuery Mobile che indica il caricamento della pagina in corso. Il messaggio da visualizzare è configurabile tramite l'opzione $.mobile.loadingMessage, come vedremo in seguito.
Per nascondere la finestra di dialogo occorre utilizzare il metodo hidePageLoadingMsg(). Un esempio tipico di utilizzo di questi metodi è quello illustrato dal seguente codice:
$.mobile.showPageLoadingMsg();
$get("myPage.aspx?IDArticolo=123", function(resultHtml) {
$("#articolo").html(resultHtml);
$.mobile.hidePageLoadingMsg();
});La prima istruzione visualizza la finestra di dialogo mentre la seconda istruzione effettua una chiamata Ajax verso la pagina myPage.aspx passando un parametro e definisce la funzione di callback. In questa funzione, dopo aver inserito nel DOM della pagina corrente il risultato della richiesta, viene nascosta la finestra di dialogo.
silentScroll
Il metodo silentScroll() consente di effettuare lo scrolling della pagina fino al punto desiderato. Esso prevede un parametro che indica la posizione verticale a cui posizionarsi.
Ad esempio, la seguente chiamata:
$.mobile.silentScroll(600);scorre la pagina fino a visualizzare la posizione verticale 600 dello schermo.
È importante sottolineare che l'invocazione di questo metodo non attiva l'esecuzione di eventuali gestori dell'evento scroll, da qui l'attributo di silent.
