Operazioni con i dati esterni -- Flash CS3

ActionScript 3.0 include dei meccanismi per caricare dati da origini esterne. Queste origini possono essere costituite da contenuti statici come i file di testo o da contenuti dinamici come gli script Web che recuperano i dati da un database. I dati possono essere formattati in molti modi e ActionScript fornisce le funzionalità per decodificare e accedere ai dati. Inoltre, è possibile inviare dati al server esterno come parte del processo di recupero dei dati.

Sezioni

Utilizzo delle classi URLLoader e URLVariables

ActionScript 3.0 utilizza le classi URLLoader e URLVariables per caricare i dati esterni. La classe URLLoader scarica i dati da un URL sotto forma di testo, dati binari o variabili con codifica URL. La classe URLLoader è utile per scaricare file di testo, XML o altre informazioni da utilizzare nelle applicazioni ActionScript dinamiche basate su dati. La classe URLLoader sfrutta il modello di gestione degli eventi avanzato di ActionScript 3.0, che consente l'intercettazione di eventi come complete, httpStatus, ioError, open, progress e securityError. Il nuovo modello di gestione degli eventi costituisce un miglioramento significativo rispetto al supporto di ActionScript 2.0 per i gestori di eventi LoadVars.onData, LoadVars.onHTTPStatus e LoadVars.onLoad, perché consente di gestire gli errori e gli eventi in modo più efficiente. Per ulteriori informazioni sulla gestione degli eventi, vedere Gestione degli eventi..

In modo analogo alle classi XML e LoadVars presenti nelle versioni precedenti di ActionScript, i dati dell'URL di URLLoader non sono disponibili finché lo scaricamento non viene completato. È possibile verificare lo stato di avanzamento dello scaricamento (byte caricati e byte totali) intercettando gli eventi flash.events.ProgressEvent.PROGRESS da inviare, benché se un file viene caricato troppo velocemente, l'evento ProgressEvent.PROGRESS potrebbe non essere inviato. Dopo che un file è stato scaricato, viene inviato l'evento flash.events.Event.COMPLETE. I dati caricati vengono decodificati dalla codifica UTF-8 o UTF-16 in una stringa.

Il metodo URLLoader.load() (e facoltativamente la funzione di costruzione della classe URLLoader) accetta un solo parametro, request, ovvero un'istanza URLRequest. Un'istanza URLRequest contiene tutte le informazioni per una singola richiesta HTTP, ad esempio l'URL di destinazione, il metodo di richiesta (GET o POST), informazioni aggiuntive sull'intestazione e il tipo MIME (ad esempio, quando si carica il contenuto XML).

Ad esempio, per caricare un pacchetto XML in uno script sul lato server, è possibile utilizzare il codice ActionScript 3.0 riportato di seguito:

var secondsUTC:Number = new Date().time;
var dataXML:XML = 
    <login>
        <time>{secondsUTC}</time>
        <username>Ernie</username>
        <password>guru</password>
    </login>;
var request:URLRequest = new URLRequest("http://www.yourdomain.com/login.cfm");
request.contentType = "text/xml";
request.data = dataXML.toXMLString();
request.method = URLRequestMethod.POST;
var loader:URLLoader = new URLLoader();
try
{
    loader.load(request);
}
catch (error:ArgumentError)
{
    trace("An ArgumentError has occurred.");
}
catch (error:SecurityError)
{
    trace("A SecurityError has occurred.");
}

Lo snippet di codice precedente crea un'istanza di XML di nome dataXML che contiene un pacchetto XML da inviare al server. Vengono quindi impostate la proprietà contentType di URLRequest su "text/xml" e la proprietà data di URLRequest sul contenuto del pacchetto XML, che viene convertito in una stringa mediante il metodo XML.toXMLString(). Infine, viene creata una nuova istanza di URLLoader e viene inviata la richiesta allo script remoto utilizzando il metodo URLLoader.load().

Quando si definiscono le variabili all'interno della funzione di costruzione URLVariables o del metodo URLVariables.decode(), è necessario assicurarsi di eseguire la codifica URL del carattere e commerciale, in quanto ha un significato particolare e agisce come delimitatore. Ad esempio, quando si passa una e commerciale, è necessario eseguire la codifica URL di questo carattere modificandolo da & in %26, in quanto la e commerciale agisce come delimitatore per i parametri.

Caricamento di dati da documenti esterni

Quando si creano applicazioni dinamiche con ActionScript 3.0, è consigliabile caricare i dati da file esterni o da script sul lato server. In questo modo è possibile creare applicazioni dinamiche senza modificare o ricompilare i file ActionScript. Ad esempio, se si crea un'applicazione di tipo "suggerimento utile", è possibile scrivere uno script sul lato server che recuperi un suggerimento casuale da un database e lo salvi in un file di testo una volta al giorno. L'applicazione ActionScript può quindi caricare il contenuto di un file di testo statico, anziché interrogare il database ogni volta.

Lo snippet di codice seguente crea un oggetto URLRequest e URLLoader che carica il contenuto di un file di testo esterno, params.txt:

var request:URLRequest = new URLRequest("params.txt");
var loader:URLLoader = new URLLoader();
loader.load(request);

var loader:URLLoader = new URLLoader(new URLRequest("params.txt"));

Per impostazione predefinita, se non si definisce un metodo di richiesta Flash Player carica il contenuto utilizzando il metodo HTTP GET. Se si desidera inviare i dati utilizzando il metodo POST, impostare la proprietà request.method su POST utilizzando la costante statica URLRequestMethod.POST, come descritto nel codice seguente:

var request:URLRequest = new URLRequest("sendfeedback.cfm");
request.method = URLRequestMethod.POST;

Il documento esterno, params.txt, che viene caricato in fase di runtime contiene i seguenti dati:

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

Il file contiene due parametri, monthNames e dayNames. Ogni parametro contiene un elenco separato da virgole che viene analizzato come stringa. Questo elenco può essere suddiviso in un array utilizzando il metodo String.split().

Dopo che i dati sono stati caricati, viene inviato l'evento Event.COMPLETE e il contenuto del documento esterno diventa disponibile per l'utilizzo nella proprietà data di URLLoader, come illustrato nel codice riportato di seguito:

private function completeHandler(event:Event):void
{
    var loader2:URLLoader = URLLoader(event.target);
    trace(loader2.data);
}

Se il documento remoto contiene coppie nome-valore, è possibile analizzare i dati utilizzando la classe URLVariables passando il contenuto del file caricato, come riportato di seguito:

private function completeHandler(event:Event):void
{
    var loader2:URLLoader = URLLoader(event.target);
    var variables:URLVariables = new URLVariables(loader2.data);
    trace(variables.dayNames);
}

Ogni coppia nome-valore contenuta nel file esterno viene creata sotto forma di proprietà nell'oggetto URLVariables. Ogni proprietà all'interno dell'oggetto variables nell'esempio di codice precedente viene considerato come una stringa. Se il valore della coppia nome-valore è un elenco di elementi, è possibile convertire la stringa in un array chiamando il metodo String.split(), come riportato di seguito:

var dayNameArray:Array = variables.dayNames.split(",");

Anziché caricare il contenuto del file remoto come stringa e creare un nuovo oggetto URLVariables, è possibile impostare la proprietà URLLoader.dataFormat su una delle proprietà statiche presenti nella classe URLLoaderDataFormat. Di seguito sono riportati i tre valori possibili per la proprietà URLLoader.dataFormat:

Il codice seguente dimostra come l'impostazione della proprietà URLLoader.dataFormat su URLLoaderDataFormat.VARIABLES consenta di analizzare automaticamente i dati caricati in un oggetto URLVariables:

package
{
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.URLLoader;
    import flash.net.URLLoaderDataFormat;
    import flash.net.URLRequest;

    public class URLLoaderDataFormatExample extends Sprite
    {
        public function URLLoaderDataFormatExample()
        {
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt");
            var variables:URLLoader = new URLLoader();
            variables.dataFormat = URLLoaderDataFormat.VARIABLES;
            variables.addEventListener(Event.COMPLETE, completeHandler);
            try
            {
                variables.load(request);
            } 
            catch (error:Error)
            {
                trace("Unable to load URL: " + error);
            }
        }
        private function completeHandler(event:Event):void
        {
            var loader:URLLoader = URLLoader(event.target);
            trace(loader.data.dayNames);
        }
    }
}

Come illustrato nell'esempio seguente, caricare contenuto XML da un file esterno è come caricare URLVariables. È possibile creare un'istanza di URLRequest e un'istanza di URLLoader e utilizzarle per scaricare un documento XML remoto. Dopo che il file è stato completamente scaricato, viene inviato l'evento Event.COMPLETE e il contenuto del documento esterno viene convertito in un'istanza di XML che può essere analizzata utilizzando i metodi e le proprietà XML.

package
{
    import flash.display.Sprite;
    import flash.errors.*;
    import flash.events.*;
    import flash.net.URLLoader;
    import flash.net.URLRequest;

    public class ExternalDocs extends Sprite
    {
        public function ExternalDocs()
        {
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml");
            var loader:URLLoader = new URLLoader();
            loader.addEventListener(Event.COMPLETE, completeHandler);
            try
            {
                loader.load(request);
            }
            catch (error:ArgumentError)
            {
                trace("An ArgumentError has occurred.");
            }
            catch (error:SecurityError)
            {
                trace("A SecurityError has occurred.");
            }
        }
        private function completeHandler(event:Event):void
        {
            var dataXML:XML = XML(event.target.data);
            trace(dataXML.toXMLString());
        }
    }
}

Comunicazione con script esterni

Oltre a caricare file di dati esterni, è possibile utilizzare la classe URLVariables per inviare variabili a uno script sul lato server ed elaborare la risposta del server. Questa operazione è utile, ad esempio, quando si programma un gioco e si desidera inviare il punteggio dell'utente a un server per calcolare se dovrà essere aggiunto all'elenco dei punteggi più alti oppure per inviare le informazioni di login di un utente a un server per la convalida. Uno script sul lato server può elaborare il nome utente e la password, convalidarli rispetto a un database e confermare se le credenziali fornite dall'utente sono valide.

Lo snippet di codice seguente crea un oggetto URLVariables di nome variables, che a propria volta crea una nuova variabile denominata name. Viene quindi creato un oggetto URLRequest che specifica l'URL dello script sul lato server a cui inviare le variabili. Si imposta quindi la proprietà method dell'oggetto URLRequest in modo che le variabili siano inviate come una richiesta POST HTTP. Per aggiungere l'oggetto URLVariables alla richiesta URL, impostare la proprietà data dell'oggetto URLRequest sull'oggetto URLVariables creato precedentemente. Infine, viene creata l'istanza di URLLoader e viene richiamato il metodo URLLoader.load(), che avvia la richiesta.

var variables:URLVariables = new URLVariables("name=Franklin");
var request:URLRequest = new URLRequest();
request.url = "http://www.[yourdomain].com/greeting.cfm";
request.method = URLRequestMethod.POST;
request.data = variables;
var loader:URLLoader = new URLLoader();
loader.dataFormat = URLLoaderDataFormat.VARIABLES;
loader.addEventListener(Event.COMPLETE, completeHandler);
try
{
    loader.load(request);
}
catch (error:Error)
{
    trace("Unable to load URL");
}

function completeHandler(event:Event):void
{
    trace(event.target.data.welcomeMessage);
}

Il codice riportato di seguito include il contenuto del documento greeting.cfm di Adobe ColdFusion® utilizzato nell'esempio precedente:

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0>
    <cfset Form.Name = "Stranger" />
</cfif>
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)#
</cfoutput>