Dynamique.js - Documentation module Ajax

Module Ajax

Ce module est dédié au chargement de données par requête HTTP asynchrone. Il est basé sur l'API XMLHttpRequest, en facilite l'usage en exploitant les Promise et prépare la transition de l'API XMLHttpRequest vers l'API Fetch. Il peut être utilisé indépendamment de Dynamique mais est aussi prévu pour s'y intégrer en tant que module.

Le module Ajax permet:

La création, l'envoi de données par requête HTTP: Ajax (méthode), send, buildData;
La gestion de liste d'attente des requêtes: queue, createQueue, addResponseToQueue, removeResponseFromQueue, verifQueue, sortQueue;
La création de requête d'après un modèle: model, createModel, deleteModel;
La gestion particulière des méthodes HTTP: method, getMethod, addMethod.

Le module supporte un ensemble d'événements permettant de suivre l'évolution d'une requête, de traiter les erreurs éventuelles et d'analyser les résultats.

Principe de fonctionnement et terminologie

Le module permet l'envoi de requête HTTP à un serveur afin d'en obtenir un résultat.

On définit comme étant une réponse un objet créé lors de l'appel de la méthode send et symbolisant une requête envoyée et dont le résultat est en attente. Le statut d'une réponse précise alors quel est l'état de celle-ci dans son processus d'envoi.

On entend par une requête, un objet contenant toutes les propriétés indiquant de quelle manière une réponse doit être obtenue: son protocole, son URL... Une requête ne représente donc pas une "vraie requête HTTP" au sens réseau mais son objet contenant ses propriétés.

Une requête est soit issue d'un modèle, créé via la méthode createModel, soit être issu d'un objet créé spontanément. Le premier cas est utilisé afin de générer plusieurs réponses à partir d'une seule requête et le second afin de charger une ressource ponctuellement. L'utilisation de modèles permet d'éviter les redondances dans la création d'une requête dont seuls les arguments sont amenés à changer.

Ainsi, afin d'exploiter plusieurs fois une ressource avec des arguments différents, on pourra procéder tel que:


						// Création du modèle "example"
						Ajax.createModel("example", {
							method 	: "POST",				// Méthode à utiliser
							async 	: true, 				// La valeur pas défaut est déjà à true
							url		: "test.php"			// Ressource cible
						});
						
						// Envoi de la requête en utilisant le modèle et certains arguments
						Ajax("example", ["arguments"]);
						
						// Envoi de la requête en utilisant le même modèle mais d'autres arguments
						Ajax.send("example", ["autres arguments"]);

On remarque que l'utilisation de modèle évite toute redondance et améliore ainsi la maintenance du code. Pour le chargement ponctuel d'une ressource, on préférera alors:


						Ajax({
							method 	: "POST",		// Méthode à utiliser
							async 	: true, 		// La valeur pas défaut est déjà à true
							url		: "image.png"	// Ressource cible
						});

La création du modèle se fait par l'utilisation de la méthode createModel. Un modèle est défini à partir d'un objet et/ou d'autres modèles. Il est ainsi possible de combiner les modèles entre eux lors de leur création. Il n'y a pour autant pas de dépendance réelle entre les objets, la suppression d'un modèle utilisé précédemment pour la création d'un nouveau modèle n'entrainera pas la suppression des deux modèles. La création d'un modèle à partir d'un autre modèle implique aussi la copie des événements éventuels. Le code ci-dessous crée deux modèles dont certaines propriétés étant commune, peuvent être partagées:


						// Création du modèle "post"
						Ajax.createModel("post", {
							method 	: "POST",				// Méthode à utiliser
							async 	: true, 				// La valeur pas défaut est déjà à true
							url		: "test.php"			// Ressource cible
						});
						
						// Création du modèle "get"
						Ajax.createModel("get", "post", {
							method 	: "GET"
						});
						
						// le modèle "get" aura les propriétés "async" et "url" issues du modèle post

L'ordre des arguments a son importance lors de l'utilisation de createModel. Les propriétés des arguments premiers seront toujours réécrites par les propriétés des arguments suivants.

Etat d'une réponse

Une réponse est un objet possédant un ensemble de propriétés informant de l'état de chargement de la ressource demandée. Au cours de son processus d'envoi, une réponse passe par différents états en fonction du paramétrage appliqué à la requête qui l'a générée. La liste de ces états est:

create: la requête a été créée mais pas encore envoyée;
init: la requête a été initialisée pour envoi. À cet état, la promesse liée à la réponse a été créée et les propriétés resolve et reject sont disponible dans la réponse;
queue: la requête est en attente dans une liste. Uniquement si la propriété queue est une chaine de caractère.
prepare: la requête est en préparation d'envoi et les arguments doivent être préparés;
send: la requête a été envoyée;
receive: la requête a été envoyée;
load: la réception des données est terminée;
prepareData: les données reçues sont en cours de traitement avant exploitation;
history: la réponse est en cours d'ajout à l'historique du navigateur. Uniquement si history vaut true;
complete: la réponse est finie et les réponses prêtes à être exploitées.

A chaque état peut-être attaché un événement. Bien que ces événements soit attachés à la requête créatrice, ils sont pour autant appliqués sur les réponses générées. Consulté la section Evénements supportés pour plus de détails.

Evénements supportés

Le module propose un ensemble d'événements afin de suivre l'évolution d'une réponse, de traiter les erreurs éventuelles et d'analyser les résultats. Ces événements sont assignables à une requête en utilisant les mêmes procédés que ceux décris par la gestion d'événements sur des objets du module Event. Les événements supportés sont:

success:
error:
statechange:
create:
init:
queue:
prepare:
send:
receive:
load:
prepareData:
history:
complete:
maxResponse:
alreadySending:
opened:
headersReceived:
loading:
done:
progress:
prepareArg:
statusUnknow:
statusInformational:
statusSuccess:
statusRedirectionError:
statusNetworkError:
statusServerError:
modified:
checkData:
queueAdd:
queueRemove:
queueMove:

Code d'erreur supportés

AlreadySending: une réponse est déjà en traitement/envoie pour une requête.
QueueNotFound: la liste auquelle la requête doit être ajoutée n'a pas été trouvée.
NoURLSupply: aucune URL n'a été donnée.
XHRNotSupported: les requêtes XHR ne sont pas supportés.
XHRError: une erreur liée à la requête est survenue.
XHRTimeout: le temps maximal d'envoi d'une requête est atteint.
XHRUncomplete: la requête a été annulée ou a subie une erreur rendant sa réponse inexploitable.
QueueError: la requête n'a pas pu être supprimée de la queue auquelle elle appartient.
MethodNotSupported: la méthode HTTP fournie n'est pas supportée.
JSONParseError: une erreur dans le parsage de la réponse est survenue.
JSONEvalError: une erreur est survenue lors de l'éxécution de la réponse.
JSONScriptError: une erreur est survenue dans l'éxécution par balise de la réponse.
StyleLoadError: une erreur est survenue lors de l'interprétation de la réponse sous forme de style CSS.
QueueAbort: la réponse à été annulée alors qu'elle était dans une liste.

Propriétés d'une requête

.method Facultatif: méthode HTTP à utiliser. Valeur par défaut GET.
.async Facultatif: indique si la requête doit être envoyée de manière synchrone (false) ou asynchrone (true). Valeur par défaut true.
.url : URL de la cible de la requête.
.user Facultatif: nom d'utilisateur à utiliser lorsqu'une authentification sur le serveur est nécessaire pour accéder à la ressource. Valeur par défaut undefined.
.password Facultatif: mot de passe à utiliser lorsqu'une authentification sur le serveur est nécessaire pour accéder à la ressource. Valeur par défaut undefined.
.header Facultatif: objet contenant tous les en-têtes de la requête. Valeur par défaut undefined.
.encode ou Facultatif: détermine si les arguments doivent être encodés avant l'envoi de la requête (true). Si une fonction est fournie, elle sera utilisée afin d'encoder les arguments. Elle prend alors comme seul argument les arguments associés à la requête et doit retourner une chaine de caractère représentant les arguments encodés. Si un booléen true est fourni, la fonction d'encodage encodeURIComponent sera utilisée. Valeur par défaut true.
.noCache Facultatif: indique si la page doit être chargée sans tenir compte du cache. Dans le cas où cette option est activée, un argument supplémentaire est associé à la requête sous la forme dateEnMs=0. Valeur par défaut false.
.useParse ou Facultatif: défini si la réponse de la requête doit être parsé (true) ou non (false). Uniquement valable lorsque ContentType == "application/json". Si une fonction est fournie, elle sera appellée afin de parser le résultat de la requête. Valeur par défaut true.
.useEval ou Facultatif: défini si la réponse de la requête doit être évaluée (true) ou non (false). Uniquement valable lorsque ContentType == "application/javascript". Si une fonction est fournie, elle sera appellée afin d'évaluer le résultat de la requête. Valeur par défaut true.
.useScript Facultatif: défini si la réponse de la requête doit être stocké dans une balise script. Uniquement valable lorsque ContentType == "application/javascript" et .useEval = false. Valeur par défaut false.
.useStyle Facultatif: défini si la réponse de la requête doit être stocké dans une balise . Uniquement valable lorsque ContentType == "text/css". Valeur par défaut true.
.useFragment Facultatif: défini si la réponse de la requête doit être évaluée dans un fragment de document, uniquement lorsque ContentType == "text/html". Uniquement valable lorsque ContentType == "text/html". Valeur par défaut true.
.useDynamique Facultatif: défini si les éléments DOM créés doivent être stockés dans un tableau Dynamique. Uniquement valable lorsque .useFragment = true et que Dynamique est utilisé. Valeur par défaut true.
.multiple Facultatif: indique si il est possible d'envoyer une requête alors qu'une autre est déjà en cours de traitement Valeur par défaut true.
.withCredentials Facultatif: Indique si l'envoie des cookies est autorisés lorsque une requête est faite en crossdomain. Valeur par défaut true.
.multipart Facultatif:
.format Facultatif: indique le format de la réponse. Si il est spécifié, il remplacera la valeur de l'en-tête Content-Type renvoyé par le serveur. Le format doit être un MIME valide.
.history Facultatif: indique si la réponse de la requête doit être enregistrée dans l'historique du navigateur client. Valeur par défaut false.
.historyURL Facultatif: indique l'URL à associer avec l'ajout de la requête à l'historique client, lorsque .history = true. Valeur par défaut "".
.maxResponse Facultatif: indique le nombre maximale de réponse qui peuvent être stockées dans l'historique d'un modèle. Si la valeur vaut -1, aucune réponse ne sera stockée. Cette option est à privilégier si la sauvegarde du résultat d'une réponse est inutile pour la suite du programme. Valeur par défaut -1.
.queue ou Facultatif: nom d'une liste d'attente dans laquelle la réponse doit passer avant son envoi. Valeur par défaut false.
.priority Facultatif: défini la priorité d'une réponse dans une liste d'attente. Plus elle est proche de 0, plus la requête est prioritaire Valeur par défaut 0.
.timeout ou Facultatif: temps maximum en millisecondes que peut prendre une réponse avant d'être terminée. Une erreur XHRTimeout sera générée si le délai expire. Valeur par défaut false.

Propriétés d'une réponse

.id : identifiant unique de la réponse issu de l'incrémentation de Ajax.id.
.arg : arguments finaux envoyés avec la réponse.
.state [0-10]: état numérique de la réponse.
.stateText : état textuel de la réponse. Voir la propriété stateList pour voir la liste compléte des chaines possibles.

request : null, data : null, dataText : null, isDataValid : false, stateText : null, header : {}, stat : { load : 0, headerSize : 0, bodySize : 0, fileSize : 0, byteLoaded : 0, byteRemaining : 0, timeLoadRemaining : 0, time : 0, timeStart : 0, timeOpen : 0, timeHeaders : 0, timePayload : 0, timeEnd : 0

Propriétés d'une liste

Accessibilité

Lorsque le module Ajax est utilisé sans Dynamique, il s'initialise directement sur l'objet window. Il est alors accessible tel que:


						Ajax.send(...);
						// ===
						window.Ajax.send(...);

Lorsque Ajax est utilisé avec Dynamique, il s'initialise en tant que module de ce dernier. Il est alors accessible tel que:


						Dynamique.module.Ajax

Compatibilité

Le module Ajax a été réalisé sous le standard EcmaScript 6.

Dépendances

Le module Ajax utilise l'API XMLHttpRequest, l'API Promises et la gestion d'événements sur des objets du module Event.

Source

/Module/Ajax/Ajax.js