Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
162 lines (121 sloc) 11.4 KB

AJAX JavaScript

L'API JavaScript

L'API JavaScript est plus puissante que l'API des attributs de données. La fonction request peut être utilisée sur n'importe quel élément à l'intérieur d'un formulaire, ou sur un formulaire. Lorsque la fonction est utilisée sur un élément à l'intérieur d'un formulaire, elle est renvoyée au formulaire.

La fonction request n'as qu'un seul argument obligatoire : le nom du gestionnaire AJAX. Exemple :

<form onsubmit="$(this).request('onLogin'); return false;">

Le second argument de la fonction request est l'objet options. Vous pouvez utiliser toutes les options compatibles avec la fonction AJAX de jQuery. Les options suivantes sont spécifiques au framework d'October :

Option Description
update un objet, défini une liste de partiels et d'éléments de page (sous forme de sélecteur CSS) à mettre à jour: {'partiel': '#select'}. Si le sélecteur est précédé du signe @, le contenu retourné par le serveur sera insérer avant le contenu actuel de l'élément au lieu de le remplacer.
confirm une chaîne de caractères. Si défini, ce texte sera affiché avant l'envoi de la requête. Si l'utilisateur cliques sur le bouton Annuler, la requête ne sera pas envoyé.
data un objet, détermine des données additionnelles à envoyer avec ceux du formulaire : {variable : 'valeur'}. Lorsque l'option files est définie à true, vous pouvez aussi intégrer des fichiers a charger dans cet objet en utilisant des objets Blob. Pour spécifier le nom du fichier d'un objet Blob, définissez simplement la propriété filename de l'objet Blob lui-même. (Ex. var blob = new Blob(variable); blob.filename = 'test.txt'; var data = {'uploaded_file': blob};)
redirect une chaîne de caractères qui détermine l'URL vers laquelle rediriger le navigateur après le succès de la requête.
beforeUpdate une fonction callback à exécuter avant de mettre à jour la page. La fonction prends trois paramètres : l'objet data retourné par le serveur, une chaîne de caractère correspondant à l'état de la requête et l'objet jqXHR. La variable this à l'intérieur de la fonction retourne le contenu de la requête - un objet avec deux paramètres: handler et options qui sont les paramètres initiaux de la requête.
success une fonction callback à exécuter lorsque la requête as été exécutée avec succès. Si elle est définie, elle remplacera la fonctionnalité par défaut du framework : les partiels ne seront pas mis à jour et les évènements beforeUpdate, ajaxUpdate et ajaxUpdateComplete ne seront pas émis. Vous pouvez toutefois appelé ces fonctionnalités en faisant un appel de la méthode this.success(...) à l'intérieur de votre fonction. La fonction reçois trois paramètres : l'objet data retourné par le serveur, une chaîne de caractère correspondant à l'état de la requête et l'objet jqXHR.
error une fonction callback à exécuter lorsque la requête as échouée. Si cette option est définie, le message d'alerte par défaut ne sera pas affiché. La fonction reçois trois paramètres : l'objet jqXHR, une chaîne de caractère correspondant à l'état de la requête et l'objet erreur - voir la fonction jQuery AJAX.
complete une fonction callback à exécuter lorsque la requête as été exécutée, peu importe son état de retour.
form un élément form à utiliser en tant que source de données de la requête, défini en tant que sélecteur CSS ou d'élément DOM.
flash quand défini à true, indique au serveur de vider et la possibilité de renvoyer un message "toast". Par défaut à false.
files quand défini à true, la requête accepte les chargement de fichiers, cela requiert le support par le navigateur de l'interface FormData. Par défaut à false.
loading optionnel: une chaîne de caractère ou un objet à afficher lorsque la requête est en cours. La chaîne de caractère doit être le sélecteur CSS d'un élément, l'objet doit supporter les fonctions show() et hide() pour gérer sa visibilité. Vous pouvez passer l'objet global $.oc.stripeLoadIndicator lorsque vous utilisé les fonctionnalités supplémentaires.

Vous pouvez aussi certaines parties de la logique de la requête en passant les nouvelles méthodes comme options. Ces méthodes de la logique sont disponibles.

Méthodes Description
handleConfirmMessage(message) appelée lorsque vous demandez la confirmation de l'utilisateur.
handleErrorMessage(message) appelée lorsqu'un message d'erreur doit apparaître.
handleValidationMessage(message, fields) donnes le focus au premier champs invalide lorsque la validation est utilisée.
handleFlashMessage(message, type) appelée lorsqu'un message flash est fournis en utilisant l'option flash (voir ci-dessus).
handleRedirectResponse(url) appelée lorsque le navigateur doit redirigé vers une autre page.

Exemples d'utilisation

Demande la confirmation de l'utilisateur avant l'envoi de la requête onDelete :

$('form').request('onDelete', {
    confirm: 'Êtes-vous sûr?',
    redirect: '/dashboard'
})

Exécute le gestionnaire onCalculate et inject le partiel calcresult à l'intérieur de l'élément de la page avec la classe CSS result :

$('form').request('onCalculate', {
    update: {calcresult: '.result'}
})

Exécute le gestionnaire onCalculate avec des données additionnelles :

$('form').request('onCalculate', {data: {value: 55}})

Exécute le gestionnaire onCalculate et exécutes un code avant que les éléments de la page ne soit mise à jour :

$('form').request('onCalculate', {
    update: {calcresult: '.result'},
    beforeUpdate: function() { /* fait quelque-chose */ }
})

Exécute le gestionnaire onCalculate et s’il retourne un succès, exécutes du code puis la méthode success par défaut :

$('form').request('onCalculate', {success: function(data) {
    //... fait quelque-chose ...
    this.success(data);
}})

Exécute une requête sans élément form:

$.request('onCalculate', {
    success: function() {
        console.log('Fini!');
    }
})

Exécute le gestionnaire onCalculate et s’il retourne un succès, exécutes du code après que la méthode success par défaut ai terminée :

$('form').request('onCalculate', {success: function(data) {
    this.success(data).done(function() {
        //... fait quelque-chose après que la méthode success() ai été exécutée ...
    });
}})

Gestionnaire AJAX globaux

Le framework ajax émets certains évènements sur les éléments mis à jours, les éléments déclencheurs, le formulaire et l'objet window. Les évènements sont émis peu importe l'API utilisée - l'API des attributs de données ou l'API JavaScript.

Évènements Description
ajaxBeforeSend émis sur l'objet window avant que la requête ne soit envoyée
ajaxBeforeUpdate émis sur l'objet form juste après que la requête ai été terminée mais avant la mise à jour de la page. La méthode prends 5 paramètres: l'objet de l'évènement, l'objet contexte, l'objets des données reçu du serveur, le status de la requête au format texte, l'objet jqXHR.
ajaxUpdate émis sur un élément de la page après qu'il ai été mis à jour par le framework. La méthode prends 5 paramètres: l'objet de l'évènement, l'objet contexte, l'objets des données reçu du serveur, le status de la requête au format texte, l'objet jqXHR.
ajaxUpdateComplete émis sur l'objet window après que tous les éléments ai été mis à jours par le framwork. La méthode prends 5 paramètres: l'objet de l'évènement, l'objet contexte, l'objets des données reçu du serveur, le status de la requête au format texte, l'objet jqXHR.
ajaxSuccess émis sur l'objet form après que la requête ai été exécuté avec succès. La méthode prends 5 paramètres: l'objet de l'évènement, l'objet contexte, l'objets des données reçu du serveur, le status de la requête au format texte, l'objet jqXHR.
ajaxError émis sur l'objet form si la requête as échouée. La méthode prends 5 paramètres: l'objet de l'évènement, l'objet contexte, le message d'erreur, le status de la requête au format texte, l'objet jqXHR.
ajaxErrorMessage émis sur l'objet window si la requête as échouée. La méthode prends 2 paramètres: l'objet de l'évènement, le message d'erreur retourné par le serveur.
ajaxConfirmMessage émis sur l'objet window lorsque l'option confirm est demandée. La méthode prends 2 paramètres: l'objet de l'évènement, le message de confirmation comme indiqué dans l'option confirm. Cela est utile pour implémenter une interface customisée de confirmation au lieu de celle fournie nativement par JavaScript.

Ces évènements sont émis sur l'élément déclencheur :

Évènements Description
ajaxSetup émis avant que la requête ne soit formée, permets aux options d'être modifiés via l'objet context.options.
ajaxPromise émis juste avant que la requête AJAX ne soit émise.
ajaxFail émis seulement si la requête échoue.
ajaxDone émis seulement si la requête est réussie.
ajaxAlways émis peu importe si la requête échoue ou est réussie.

Exemples d'utilisation

Exécute du code JavaScript lorsque l'évènement ajaxUpdate est émis sur un élément.

$('.calcresult').on('ajaxUpdate', function() {
    console.log('Mis à jour!');
})

Exécute une seule requête qui affiche un message Flash utilisant une logique customisée.

$.request('onDoSomething', {
    flash: 1,
    handleFlashMessage: function(message, type) {
        $.oc.flashMsg({ text: message, class: type })
    }
})

Applique une configuration globale à toutes les requêtes AJAX.

$(document).on('ajaxSetup', function(event, context) {
    // Active la gestion de message Flash sur toutes les requêtes AJAX
    context.options.flash = true

    // Active l'indicateur de chargement StripeLoadIndicator sur toutes les requêtes AJAX
    context.options.loading = $.oc.stripeLoadIndicator

    // Gères les messages d'erreurs en émétant un message flash de type "erreur"
    context.options.handleErrorMessage = function(message) {
        $.oc.flashMsg({ text: message, class: 'error' })
    }

    // Gères les messages d'erreurs en émétant un message flash selon le type retourné
    context.options.handleFlashMessage = function(message, type) {
        $.oc.flashMsg({ text: message, class: type })
    }
})