From Learn About the Ext JavaScript Library

Questo è un tutorial per la versione 2.0 di Ext. La e versione 1.x di questo tutorial è ancora disponibile.

Chi non conosce ancora la libreria Ext, o chi cerca di imparare di più a riguardo è arrivato nel posto giusto. Questo tutorial vi accompagnerà attaverso i concetti che sono alla base della libreria e vi permetterà di scrivere una applicazione funzionante molto rapidamente. Assumiamo che il lettore abbia una conoscenza basilare di javascript ed un'infarinatura del DOM (Document Object Model) di HTML.

Scaricare Ext

Se non l'avete già fatto , la prima cosa da fare è scaricare l'ultima versione di Ext che si trova all'indirizzo: http://extjs.com/download.

Avrete a disposizione diverse configurazioni da scaricare, probabilmente vorrete cominciare con la versione stabile più recente. Una volta scaricato e decompresso il file, un buon punto di partenza per le nostre esplorazioni è la directory examples.

Cominciamo

Scarica il file di esempio IntroToExt2.zip

Da qui in avanti illustreremo alcuni dei compiti più comuni che vi capiterà di dover svolgere in javascript e vedremo come utilizzare Ext per risolverli. Se nel frattempo vi piace sperimentare, dovreste scaricare il file che useremo per costruire una pagina con Ext: IntroToExt2.zip.

Questo archivio contiene quattro file: ExtStart.html, ExtStart.js, ExtStart.css and ajax-example.php.

• Estraete tutti e quattro i file in una cartella posta immediatamente sotto quella in cui si trova Ext, se, per esempio, è installato in "C:\code\ext-2.0\," create una nuova cartella chiamata "tutorial" in "ext-2.0\" o, in altre parole "C:\code\ext-2.0\tutorial\").
• Fate doppio click su ExtStart.html in modo che parta il vostro browser predefinito ed otterrete un messaggio che vi comunica che tutto è configurato correttamente. Se ottenete un errore Javascript, seguite, per favore, le istruzioni che appaiono sulla pagina per far funzionare il tutto.

Ora siete pronti dare un'occhiata all'interno di ExtStart.js con il vostro IDE o editor preferito:

Ext.onReady(function() {
	alert("Congratulations!  You have Ext configured correctly!");
});

Ext.onReady è probabilmente il primo metodo che utilizzerete sin ogni pagina. Questo metodo viene chiamato automaticamente non appena il dom finisce di essere caricato, garantendo che tutti gli elementi della pagina che andrete a referenziare saranno disponibili al momento dell'esecuzione dello script. Potete andare avanti e cancellare l'istruzione alert() in modo da poter aggiungere del codice che faccia qualcosa di utile!

Element: il cuore di Ext

Praticamente tutto quello che farete in Javascript avrà bisogno, prima o poi, di referenziare uno specifico elemento sulla vostra pagina per farci qualcosa di interessante. Usando solo Javascript, un nodo si seleziona così:

var myDiv = document.getElementById('myDiv');

Funziona, certo, ma l'oggetto restituito (un nodo DOM) non offre molto dal punto di vista della potenza o della comodità. Per poterci fare qualcosa di utile dovrete comunque scrivere molto codice. Inoltre ricade sotto di voi la resposabilità di gestire i modi differenti in cui bisogna manipolare il nodo da parte dei diversi browser, e questo potrebbe rivelarsi scoraggiante.

Introduciamo l'oggetto Ext.Element. Element è il cuore di Ext visto che la maggior parte di quello che dovrete fare consisterà nell'accedere oggetti di tipo Element e manipolarli. L'Api Element è fondamentale per l'intera libreria Ext, e se aveste il tempo di approfondire l'uso di una sola classe in Ext, questa dovrebbe essere Element!

Il codice per selezionare un oggetto Element per ID è simile a questo (La pagina iniziale ExtStart.js contiene un div con id "myDiv,", quindi andate avanti ed aggiungete questo codice ad ExtStart.js):

Ext.onReady(function() {
	var myDiv = Ext.get('myDiv');
});

In questo modo otterremo un oggetto Element, cosa c'è di interessante in questo?

• Element incapsula la maggior parte dei metodi e delle proprietà DOM, fornendo un'unica e comoda interfaccia cross-browser (ed è sempre possibile accedere al nodo DOM che racchiude attraverso Element.dom)
• Il metodo Element.get() ha anche una cache interna. in questo modo chiamate multiple allo stesso oggetto sono incredibilmente veloci.
• Le azioni più comunemente applicate ai nodi DOM sono garantite da metodi diretti e cross-browser (aggiungi/rimuovi classi CSS, aggiungi rimuovi gestori di eventi, posizionamento, dimensionamento, animazione, trascinamento ecc.)

Questo significa che potrete fare tante cose utili scrivendo pochissimo codice. Qui di seguito alcuni semplici esempi (vedi la documentazione dell'API di Element (in inglese) per una lista completa di tutto quello che è possibile fare. Intanto proseguite e provate ad aggiuingere alcune di queste istruzioni dopo la riga di codice che avevamo aiilustrato prima e che abbiamo usato per ottenere l'elemento 'myDiv':

myDiv.highlight();      // Lo sfondo dell'elemento diventa giallo e poi degrada verso il nero
myDiv.addClass('red');  // Aggiunge una classe CSS (definita in ExtStart.css)
myDiv.center();         // Centra l'elemento 
myDiv.setOpacity(.25);  // Rende l'elemento semitrasparente

Selezionare i nodi DOM

Spesso non è pratico, se non impossibile, selezionare dei nodi DOM in base al loro ID. Forse non hanno un ID, o forse non lo conosciamo, oppure ci sono così tanti elementi che è impossibile referenziarli direttamente per ID. A volte potremmo voler selezionare nodi in base a caratteristiche diverse dall'ID, ad esempio un attributo o il nome di una classe CSS a cui appartengono. Per queste ragioni. Ext dispone di DomQuery, una potentissima libreria di selezione.

DomQuery può essere utilizzata come una libreria autonoma, ma più comunemente durante l'utilizzo di Ext, viene utilizzata per selezionare elementi in modo da poterli poi manipolare attraverso l'intefaccia Element. Fortunatamente, l'oggetto Element supporta le ricerche tramite il metodo Element.select che usa internamente DomQuery. Come semplice esempio di utilizzo possiamo prendere questo: il file ExtStart.html contiene alcuni paragrafi (<p>), nessuno di questi ha un id. Se voleste semplicemente selezionare tutti i paragrafi ed agire su tutti contemporaneamente, potreste fare qualcosa simile a questo:

// Evidenzia tutti i paragrafi
Ext.select('p').highlight();

Questo esempio illustra un aspetto molto comodo di Element.selec - il metodo restituisce un elemento composito (CompositeElement), che permette l'accesso a tutti i sottoelementi che lo compongono attraverso l'interfaccia Element. Questo permette di aggire facilmente su tutte le istanze restituite da Element.select senza dover scrivere dei cicli ed agire singolarmente su ognuno di esse.

DomQuery supporta un'ampia scelta di opzioni di selezione, inclusi la maggiorn parte dei selettori dom CSS3 del W3C, Xpath, attributi HTML e molto altro ancora. Per favore fate riferimento alla Documentazione dell'Api di DomQuery per una descrizione esaustiva di questa potente libreria.

Rispondere agli eventi

Tutto il codice che abbiamo scritto finora nei nostri esempi andava direttamenre nella funzione onReady, il che significa che veniva eseguito subito dopo il caricamento della pagina. Questo non ci da molto controllo - vorrete probabilmente che il vostro codice venga eseguito in risposta a specifiche azioni dell'utente o eventi. Per fare questo dovrete creare gestori che possano rispondere ad eventi usando funzioni che voi gli assegnerete.

Cominciamo con un esempio semplice. Aprite ExtStart.js e modificatelo in modo che assomigli a questo codice:

Ext.onReady(function() {
    Ext.get('myButton').on('click', function(){
        alert("Hai fatto click sul pulsante");
    });
});

Anche questo codice viene eseguito al caricamento della pagina, ma con una importante differenza. La funzione che contiene alert() viene definita ma non eseguita - viene assegnata al "gestore" dell'evento click del pulsante. In italiano corrente il codice significa: "Prendi un riferimento all'elemento con id 'myButton' ed assegnali una funzione che sarà chiamata ogni volta che qualcuno fa click sull'elemento."

Non sorprendentemente, Element.select ci permette di fare la stessa cosa ma su interi gruppi di Elementi contemporaneamente. Per esempio per mostrare un messaggio quando si fa click su qualunque paragrafo nella nostra pagina di test, potremmo scrivere:

Ext.onReady(function() {
	Ext.select('p').on('click', function() {
		alert("Hai fatto click su un paragrafo");
	});
});

In questi due esempi, le funzioni che devono gestire l'evento vengono semplicemente dichiarare inline, senza dargli un nome. Il termine tecnico per questo tipo di funzioni è "funzione anonima" visto che viene dicharata senza assegnarle un nome. Ovviamente potete assegnare la gestione di evento una funzione non anonima, cosa molto utile se si vuole riutilizzare una funzione per gestire eventi multipli. Per esempio, questo codice equivale funzionalmente al precedente esempio:

Ext.onReady(function() {
    var paragraphClicked = function() {
      alert("Hai fatto click su un paragrafo");
    }
    Ext.select('p').on('click', paragraphClicked);
});

Finora abbiamo cercato di eseguire un'azione generica quando il nostro evento veniva scatenato, ma come fare a capire quale specifico Elemento ha generato l'evento in modo da poterlo manipolare? La cosa è particolarmente semplice - il metodo Element.on passa tre parametri molto utili alla funzione che gestisce l'evento (noi ci occuperemo solamente del primo, ma voi potete esplorare la documentazione per approfondire la conoscenza della gestione degli eventi). Negli esempi precedenti il gestore (la funzione) ignorava questi parametri, ma con una semplice modifica possiamo raggiungere un ulteriore livello di funzionalità. Il primo, e più importante, parametro è l'evento che si è verificato. Questo è un Ext.EventObject, che, oltre a fornire informazione aggiuntive rispetto agli eventi standard, è consistente tra i diversi browser. Per esempio, il nodo DOM oggetto dell'evento può essere recuperato con una semplice modifica:

Ext.onReady(function() {
	var paragraphClicked = function(e) {
		Ext.get(e.target).highlight();
	}
	Ext.select('p').on('click', paragraphClicked);
});

Notate che il'oggetto è un nodo DOM, quindi per prima cosa abbiamo preso l'Element che lo rappresenta e, quindi, abbiamo agito su quest'ultimo. In questo caso abbiamo evidenziato visualmente il paragrafo.

Usare i Widget

In aggiunta alla libreria di base di cui stavano discutendo, Ext include una delle selezioni più complete oggi disponibili, di widget javascript per l'interfaccia utente. Sono troppi per questa introduzione, ma diamo un'occhiata ad un paio dei widget che sono più usati in modo da constatare quanto è facile lavorarci.

MessageBox

Piuttosto che una noiosa "Hello World" message box, facciamo qualcosa di un po' più interessante. Abbiamo già il codice scritto nella precedente sezione che evidenziava ogni paragrafo al click. Modifichiamo il codice facendogli mostrare il testo del paragrafo su cui l'utente ha fatto click in una message box. Nella funzione paragraphClicked, modifichiamo la riga:

Ext.get(e.target).highlight();

...con questo codice:

var paragraph = Ext.get(e.target);
paragraph.highlight();
 
Ext.MessageBox.show({
	title: 'Paragraph Selezionato',
	msg: paragraph.dom.innerHTML,
	width:400,
	buttons: Ext.MessageBox.OK,
	animEl: paragraph
});

Ci sono un paio di nuovi concetti che abbiamo introdotti e che vale la pena esaminare. Nella prima riga abbiamo creato una variabile locale chiamata paragraph che conterrà un riferimanto all'oggetto Element che rappresenta il nodo DOM selezionato dall'utente (in questo caso sappiamo che sarà un paragrafo visto che l'evento clis e associato solo ai tag <p>). Perché stiamo facendo questo? Beh, pensare al futuro per un momento, abbiamo bisogno di un riferimento all'oggetto Element da evidenziare, riferimento che utilizzeremo anche per alcuni dei parametri della MessageBox. In generale, non è una buona pratica fare la stessa chiamata di funzione più volte per recuperare uno stesso valore o un riferimento ad un stesso oggetto, e quindi assegnare il risultato ad una variabile locale da riutilizzare ci fa sedere dalla parte degli sviluppatori ad oggetti diligenti.

Adesso concentriamoci sulla chiamata a MessageBox, che illustra l'altro concetto da discutere. Ad una prima occhiata, può sembrare una semplice lista di parametri passata ad un metodo ma, ad un più attento esame, si scopre che la sua sintassi è singolare. In definitiva viene passato a MessageBox.Show() un solo parametro: un letterale oggetto che contiene un insieme di proprietà e valori. In Javascript, un letterale oggetto è un oggetto generico che viene creato dinamicamente ogni volta che usiamo { e } per racchiudere una lista di coppie nome/valore che rappresentano le proprietà, ed il formato di queste è [nome proprietà]: [valore della proprietà]. Vedrete molto spesso questo pattern in Ext, quindi sarà bene il caso di impararlo bene!

Perché usare letterali oggetto? Il motivo principale è la flessibilità. Nuove proprietà possono essere aggiunte o rimosse da questi oggetti in qualunque momento, o definite in qualunque ordine, mentre la segnatura del metodo (il numero ed il tipo dei parametri da passare ad un metodo) non cambia. Anche per gli sviluppatori è conveniente questo sistema quando si ha a che fare con metodi con molti parametri opzionali (come nel caso di MessageBox.show). Per esempio, prendiamo una ipotetico metodo foo.action che ha quattro parametri opzionali, ma a cui vogliamo passare solo il quarto. In questo caso il vostro codice dovrebbe essere simile a questo: foo.action(null, null, null, 'ciao'). Se questo metodo avesse avuto come parametro un letterale oggetto li codice sarebbe stato qualcosa come foo.action({ param4: 'hello' }). Una modalità più semplice da usare e molto più leggibile.

Griglie

La griglia è uno dei widget più popolari in Ext, e di solito il primo che una persona vuole vedere, diamo uno sguardo a come è facile avere una griglia standard funzionante. Sostituite tutto il codice che avere in ExtStart.js con uno simile a quello qui sotto:

Ext.onReady(function() {
	var myData = [
		['Apple',29.89,0.24,0.81,'9/1 12:00am'],
		['Ext',83.81,0.28,0.34,'9/12 12:00am'],
		['Google',71.72,0.02,0.03,'10/1 12:00am'],
		['Microsoft',52.55,0.01,0.02,'7/4 12:00am'],
		['Yahoo!',29.01,0.42,1.47,'5/22 12:00am']
	];
 
	var myReader = new Ext.data.ArrayReader({}, [
		{name: 'company'},
		{name: 'price', type: 'float'},
		{name: 'change', type: 'float'},
		{name: 'pctChange', type: 'float'},
		{name: 'lastChange', type: 'date', dateFormat: 'n/j h:ia'}
	]);
 
	var grid = new Ext.grid.GridPanel({
		store: new Ext.data.Store({
			data: myData,
			reader: myReader
		}),
		columns: [
			{header: 'Company', width: 120, sortable: true, dataIndex: 'company'},
			{header: 'Price', width: 90, sortable: true, dataIndex: 'price'},
			{header: 'Change', width: 90, sortable: true, dataIndex: 'change'},
			{header: '% Change', width: 90, sortable: true, dataIndex: 'pctChange'},
			{header: 'Last Updated', width: 120, sortable: true, 
				renderer: Ext.util.Format.dateRenderer('m/d/Y'), 
	                        dataIndex: 'lastChange'}
		],
		viewConfig: {
			forceFit: true
		},
		renderTo: 'content',
		title: 'My First Grid',
		width: 500,
		frame: true
	});
 
	grid.getSelectionModel().selectFirstRow();
});

Anche se sembra parecchio, in realtà si tratta di sole 4 linee di codice (3 non contando i dati)!

• La prima riga di codice crea un array di dati che verranno visualizzati nella griglia. In un progetto reale questi dati verrebbero caricati da una sorgente dinamica come un database o un webservice.
• Creiamo un lettore di dati che sa come interpretare i dati e convertirli in record utilizzabili dal grid. Ci sono diversi tipi di classi Reades quanti i differenti tipi di dati.
• Ancora, creiamo un widget grid, passndogli tutti i parametri di configurazione inclusi:
  • Un nuovo data store, configurato al voli con i nostri dati di test ed il reader adeguato
  • la definizione delle colonne usando la proprietà columns
  • parametri aggiuntivi per personalizzare la griglia
• In ultimo,. diciamo alla griglia di selezionare la prima riga tramite SelectionModel.

Non è stato facile? Se tutto è andato per il meglio dovreste avere qualcosa di simile a questo:

Ovviamente, ci saranno alcuni dettagli in questo codice che potreste non comprendere a pieno. L'intento di quesro esempio è quello di mostrare come sia possibile creare una componente dell'interfacciam utente estremamente ricco, e visualmente comlesso con poche linee di codice - investigare questi dettagli rimasti indietro è un compito lasciato come esercizio a voi lettori. Ci sono molte risorse per aiutarvi a sviscerare il componente gridm inclusi il demo interattivo sulle griglie e la documentazione dell'API di GridPanel.

E molto altro ancora...

In questo tutorial abbiamo appena visto la punta dell'iceberg. Ci sono letteralmente dozzine di widget per l'interfaccia utente disponibili in Ext rta cui scegliere, inclusi layout automatici di pagina, tabs, menù, toolbar, finestre di dialogo, viste ad albero solo per fare degli esempi. Potete esplorare gli esempi interattivi per cominciare a farvi un'idea di tutto quello che è disponibile.

Usare Ajax

Dopo aver creato la vostra pagina ed aver capito come interagire con essa tramite Javascript, probabilmente vorrete sapere come gare a scambiare dati con un server remoto, di solito per caricare e salvare dati da un database su un server. Fare tutto questo in maniera asincrona con Javascript senza ricaricare la pagina è conosciuto comunemente come Ajax, Ext fornisce un eccellente supporto ad Ajax. Per esempio, un obiettivo comune e quello di gestire l'interazione con un utente inviando dati ad un server in maniera asincrona ed aggiornando lo stato degli elemento dell'interfaccia utente (UI) corrispondentemente. Qui di seguito c'è un esempio di una form HTML minimale contenente un campo di testo, un pulsante ed un div utilizzato per mostrare un messaggio ( Nota: potete aggiungere questo codice ad ExtStart.html, se volete continuare a seguire il tutorial, ma avrete bisogno dell'accesso ad un server web per eseguire il codice dei server che incontreremo più avanti):

<div>
    Name: <input type="text" id="name" />
    <input type="button" id="okButton" value="OK" />
</div>
<div id="msg"></div>

ora aggiungiamo il codice Javascript necessario per raccogliere i dati immessi e inviarli ad un processo su un server (rimpiazzate il codice che si trova in ExtStart.js con questo):

Ext.onReady(function(){
	Ext.get('okButton').on('click', function(){
		var msg = Ext.get('msg');
		msg.load({
			url: 'ajax-example.php', // <-- change if necessary
			params: 'name=' + Ext.get('name').dom.value,
			text: 'Updating...'
		});
		msg.show();
	});
});

Nota: Questo esempio funzionerà solo se eseguito su un server web. L'URL nel vostro browser dovrebbe iniziare con http:// e non con file:// o la transazione Ajax non funzionerà! Localhost andrà bene, ma raggiunto via http.

A questo punto spero che lo schema cominci a diventarvi familiare! Il codice incapsula l'input okButton con un oggetto Element e gli associa una funzione anonima che verrà invocata per gestire l'evento del click su quel pulsante. All'interno del gestore del click usiamo una classe speciale integrata in Ext, chiamata Updater - questa classe rende estremamante facile inviare una richiesta Ajax, attendere la risposta ed aggiornare un altro elemento. L'Updater può essere usato direttamente oppure, come nell'esempio, invocato attraverso l'elemento che vogliamo aggiornare (in questo caso il div 'msg') usando il metodo Element.load. Quando questo metodo (Element.load) viene invocato la risposta del server sostituisce automaticamente l'innerHTML dell'elemento. basta semplicemente passargli l'URL del processo che gestirà la richiesta sul server, una querystring con un parametri da elaborare (in questo caso il valore del campo 'name') ed il testo da mostrare nell'innerHTML dell'elemento mentre aspettiamo che la richiesta venga soddisfatta. Rendiamo visibile il div msg (visto che è invisibile di default) ed il gioco è fatto! Naturalmente, come la maggior parte delle cose in Ext, Updater supporta molte più opzioni, così come modi di elaborare le richieste Ajax in diverse situazioni (vedi la classe Ext.Ajax per unaccesso più diretto alle funzionalità Ajax), ma questo esempio mostra quanto sia facile allestire e far funzionare un esempio basilare.

L'ultimo pezzo del rompicapo Ajax è il processo sul web server che elabora effettivamente le richieste e spedisce la risposta alla pagina. Questo processo può essere una pagina web, una servlet, un web service o anche uno script Perl o CGI- in pratica qualunque cosa possa risiedere su un web server e gestire richieste HTTP. Sfortunatamente, proprio per questa varietà di soluzioni non esiste un esempio standard che copra tutte le possibilità. Qui di seguito elenco qualche esempio nei più comuni linguaggi di programmazione sperando di darvi una mano a partire (questo codice si limita a rimandare indietro quanto gli è stato passato dal campo 'name' con in testa la scritta 'From Server: ', in modo che possa essere scritta nel div 'msg'). L'esempio PHP è stato incluso nel file da scaricare come 'ajax-example.php' ma sentitevi liberi di rimpiazzarlo con un programma nel linguaggio che preferite:

PHP

<?php if(isset($_POST['name'])) {
		echo 'From Server: '.$_POST['name'];
	}
?>

CakePHP

<?php if(isset($this->data['name'])) {
		$this->flash('From Server: '.$this->data['name']);
	}
?>

Django

from django.http import HttpResponse
 
def ajax_request(request):
    return HttpResponse('From Server: %s' % request.POST.get('name', 'nada'))

Perl

#!/usr/bin/perl
use strict;
use warnings;
use CGI;
 
my $Query = new CGI;
 
print $Query->header();
print "Hello from : ".$Query->param('name');
 
exit;

ASP.Net

protected void Page_Load(object sender, EventArgs e)
{
	if (Request.Form["name"] != null)
	{
		Response.Write("From Server: " + Request.Form["name"]);
		Response.End();
	}
}

ColdFusion

<cfif StructKeyExists(form, "name")>
    <cfoutput>From Server: #form.name#</cfoutput>
</cfif>

    oppure, usando ColdFusion Scripting (cfscript)

if (StructKeyExists(form, "name")) {
        writeoutput("From Server : " & form.name);
        }

JSTL (JSP)

From Server: ${param.name}

Ruby on Rails

render :text => "From Server: #{params[name]}"

Il problema principale, quando si utilizza Ajax, consiste nello scrivere tutto il codice necessario all'elaborazione ed alla formattazione dei dati sul server. Ci sono diversi formati tra cui scegliere che sono di utilizzo comune (la maggior parte delle volte JSON o XML). Ci sono, inoltre, molte librerie per i più vari linguaggi dedicate ad Ajax che possono lavorare bene con Ext, visto che Ext è neutrale rispetto al linguaggio utilizzato sul server. Fin quando il risultato viene inviato alla pagina in un formato adeguato, Ext non si preoccupa di quello che avviene sul server! Potete far riferimento alle risorse nelle diverse piattaforme per avere informazioni aggiuntive sui framework ed i tool utilizzabili sul server.

E Adesso?

Adesso che avere cominciato a comprendere cosa sia Ext e quello che ha da offrire, avete molte risorse a disposizione utilia a raggiungere un livello più alto di familiarità con la libreria:

• Additional Tutorials
• Interactive Examples
• Ext Programmer's API Documentation
• Ext User Forums