Utilisation de données externes -- Flash CS3

ActionScript 3.0 comprend des mécanismes permettant de charger des données depuis des sources externes. Ces sources peuvent être du contenu statique tel que des fichiers de texte ou du contenu dynamique tel qu'un script Web qui récupère des données d'une base de données. Les données peuvent être formatées de plusieurs façons, et ActionScript fournit une fonctionnalité pour décoder les données et y accéder. Vous pouvez également envoyer des données au serveur externe lors de leur récupération.

Sous-rubriques

Utilisation des classes URLLoader et URLVariables

ActionScript 3.0 utilise les classes URLLoader et URLVariables pour charger des données externes. La classe URLLoader télécharge des données à partir d'une URL, sous forme de texte, de données binaires ou de variables de code URL. La classe URLLoader est utile pour le téléchargement des fichiers texte et XML, ou d'autres informations destinées à des applications ActionScript dynamiques et orientées données. La classe URLLoader tire avantage du modèle de gestion des événements d'ActionScript 3.0 qui permet d'écouter des événements tels quecomplete, httpStatus, ioError, open, progress et securityError. Le nouveau modèle de gestion des événements constitue une avancée considérable par rapport à ActionScript 2.0 pour les gestionnaires d'événements LoadVars.onData, LoadVars.onHTTPStatus et LoadVars.onLoad parce qu'il permet une gestion plus efficace des erreurs et des événements. Pour plus d'informations sur la gestion des événements, voir Gestion d'événements.

Comme dans le cas des classes XML et LoadVars dans les versions antérieures d'ActionScript, les données obtenues par URLLoader ne sont disponibles qu'une fois le téléchargement terminé. Vous pouvez suivre la progression du téléchargement (nombre d'octets chargés et nombre total) en écoutant l'événement flash.events.ProgressEvent.PROGRESS qui doit être distribué. Toutefois, si le chargement du fichier s'effectue trop rapidement, il est possible que l'événement ProgressEvent.PROGRESS ne soit pas distribué. Une fois que le téléchargement d'un fichier est terminé, l'événement flash.events.Event.COMPLETE est distribué. Les données chargées sont décodées du format UTF-8 ou UTF-16 en chaînes.

La méthode URLLoader.load() (et éventuellement le constructeur de la classe URLLoader) prend un seul paramètre, request, qui correspond à une instance URLRequest. Une instance URLRequest contient toutes les informations d'une requête HTTP unique, telles que l'URL cible, la méthode de requête (GET ou POST), les informations d'en-tête supplémentaires et le type MIME (si vous chargez du contenu XML par exemple).

Pour charger un paquet XML dans un script côté serveur, par exemple, vous pouvez utiliser le code ActionScript 3.0 ci-après :

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.");
}

L'extrait ci-dessus crée une instance XML nommée dataXML, qui contient un paquet XML à envoyer au serveur. Ensuite, attribuez à la propriété contentType d'URLRequest la valeur "text/xml" et à la propriété data le contenu du paquet XML. Ces valeurs sont alors converties en chaînes à l'aide de la méthode XML.toXMLString(). Enfin, créez une nouvelle instance URLLoader et envoyez la requête au script distant à l'aide de la méthode URLLoader.load().

Vous pouvez spécifier les paramètres à transmettre dans la requête URL de trois manières :

Lorsque vous définissez des variables au sein du constructeur URLVariables ou de la méthode URLVariables.decode(), vous devez veiller à encoder l'esperluette au format URL parce que ce caractère revêt un sens particulier et joue le rôle de délimiteur. Par exemple, lorsque vous transmettez une esperluette, vous devez l'encoder en remplaçant & par %26.

Chargement de données à partir de documents externes

Lorsque vous élaborez une application dynamique avec ActionScript 3.0, il est judicieux de charger les données à partir de fichiers externes ou de scripts côté serveur. Cela vous permet de construire vos applications dynamiques sans avoir à modifier ou recompiler vos fichiers ActionScript. Par exemple, si vous créez une application « conseil du jour », vous pouvez écrire un script côté serveur qui récupère un conseil au hasard dans une base de données et l'enregistre dans un fichier texte une fois par jour. Votre application ActionScript peut ensuite charger le contenu du fichier texte statique au lieu d'envoyer une requête à la base de données à chaque fois.

L'extrait de code suivant crée un objet URLRequest et URLLoader, qui charge le contenu d'un fichier texte externe nommé 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"));

Par défaut, si vous ne définissez aucune méthode de requête, Flash Player charge le contenu à l'aide de la méthode HTTP GET. Si vous souhaitez envoyer des données avec la méthode POST, vous devez lui attribuer la propriété request.method à l'aide de la constante statique URLRequestMethod.POST, comme le montre le code suivant :

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

Le document externe params.txt, qui est chargé au moment de l'exécution, contient les données suivantes :

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

Le fichier contient deux paramètres, monthNames et dayNames. Chacun des paramètres contient une liste séparée par des virgules qui est analysée sous forme de chaîne. Vous pouvez transformer cette liste en tableau à l'aide de la méthode String.split().

Une fois les données chargées, l'événement Event.COMPLETE est distribué et le contenu du document externe peut alors être utilisé dans la propriété data de URLLoader, comme l'illustre le code suivant :

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

Si le document distant contient des paires nom-valeur, vous pouvez analyser les données à l'aide de la classe URLVariables en transmettant le contenu du fichier chargé, comme suit :

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

Chaque paire nom-valeur issue du fichier externe devient une nouvelle propriété de l'objet URLVariables. Chaque propriété de cet objet dans l'exemple de code précédent est traité comme une chaîne. Si la valeur de la paire nom-valeur est une liste d'éléments, vous pouvez convertir la chaîne en tableau en appelant la méthode String.split(), comme suit :

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

Au lieu de charger le contenu du fichier distant sous forme de chaîne et de créer un nouvel objet URLVariables, vous pouvez attribuer à la propriété URLLoader.dataFormat la valeur de l'une des propriétés statiques de la classe URLLoaderDataFormat. Les trois valeurs possibles de URLLoader.dataFormat sont les suivantes :

Le code suivant montre comment vous pouvez automatiquement analyser les données chargées dans un objet URLVariables en attribuant à la propriété URLLoader.dataFormat la valeur URLLoaderDataFormat.VARIABLES.

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);
        }
    }
}

Comme le montre l'exemple suivant, le chargement de données XML à partir d'un fichier externe s'effectue comme le chargement de données URLVariables. Vous pouvez créer une instance URLRequest et une instance URLLoader et vous en servir pour télécharger un document XML distant. Lorsque le fichier est complètement téléchargé, l'événement Event.COMPLETE est distribué et le contenu du fichier externe est converti en instance XML, que vous pouvez analyser avec les méthodes et propriétés 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());
        }
    }
}

Communication avec des scripts externes

Outre le chargement de fichiers de données externes, la classe URLVariables permet d'envoyer des variables à un script côté serveur et de traiter la réponse du serveur. Cela s'avère utile, par exemple, si vous programmez un jeu et souhaitez envoyer le score de l'utilisateur à un serveur afin de vérifier s'il faut l'ajouter à la liste des scores les plus élevés ; ou encore envoyer les informations de connexion de l'utilisateur au serveur pour validation. Un script côté serveur peut traiter le nom d'utilisateur et le mot de passe, les compare à une base de données et confirmer en retour la validité des informations fournies par l'utilisateur.

L'extrait de code ci-après crée un objet URLVariables nommé variables, qui génère une nouvelle variable appelée name. Ensuite, un objet URLRequest est créé pour spécifier l'URL du script côté serveur à laquelle doivent être envoyées les variables. Vous pouvez alors définir la propriété method de l'objet URLRequest pour envoyer les variables sous forme de requête HTTP POST . Pour ajouter l'objet URLVariables à la requête URL, définissez la propriété data de l'objet URLRequest sur l'objet URLVariables créé plus tôt. Enfin, l'instance URLLoader est créée et la méthode URLLoader.load() appelée ; cette dernière lance la requête.

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);
}

Le code suivant reprend le contenu du document Adobe ColdFusion® greeting.cfm utilisé dans l'exemple précédent :

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