nette.ajax.js

Pour le cadre Nette

Script utilitaire flexible pour AJAX. Prend en charge les extraits de code, les redirections, etc.

Licence

MIT

Dépendances

jQuery 1.7

Installation

1. Copiez nette.ajax.js dans votre répertoire avec les fichiers Javascript (vous pouvez utiliser Bower pour cela).
2. Liez le fichier dans vos modèles (généralement dans app/@layout.latte , après jQuery !).
3. Mettez quelque part la routine d'initialisation :

 $ ( function ( ) {
	$ . nette . init ( ) ;
} ) ; 

Usage

Par défaut, tous les liens et formulaires avec la classe CSS ajax seront instantanément ajaxifiés. Le comportement peut être modifié dans la configuration de l'extension init . Objet renvoyé par l'appel var init = $.nette.ext('init'); a ces accessoires :

nom	valeur par défaut	description
linkSelector	a.ajax	Sélecteur CSS pour les liens
formSelector	form.ajax	Sélecteur CSS pour les formulaires
buttonSelector	input.ajax[type="submit"], input.ajax[type="image"]	Sélecteur CSS pour les éléments de formulaire responsables de la soumission

L'ajaxification est liée à l'événement click ( submit ) dans l'espace de noms nette . L'ajaxification d'un lien spécifique peut être annulée avec un code comme celui-ci (tandis que d'autres rappels resteront) :

 $ ( 'a.no-ajax' ) . off ( 'click.nette' ) ;

Ou encore plus simple :

 $ ( 'a.no-ajax' ) . netteAjaxOff ( ) ; 

Rallonges

L'ajaxification enveloppe l'appel standard $.ajax() et l'étend avec plusieurs événements, qui peuvent être associés à des rappels personnalisés. L'ensemble des rappels associés est appelé extension . Traitement des snippets, possibilité d'annuler une requête en cours par Escape ... toutes ces fonctionnalités sont implémentées sous forme d'extensions. L'enregistrement de l'extension ressemble à ceci :

 $ . nette . ext ( 'name' , {
    event1 : function ( ) {
    } ,
    event2 : ...
} , {
    // ... shared context (this) of all callbacks
} ) ;

Le premier argument est le nom. C'est facultatif.

Le deuxième argument doit être un hachage de rappels avec des clés correspondant aux noms d'événements. Ces événements sont disponibles :

nom	arguments	description
init		Appelé une seule fois pendant $.nette.init(); appel.
load	requestHandler	Doit contenir une ajaxification. requestHandler peut être lié aux événements de l'interface utilisateur pour lancer une requête AJAX.
before	jqXHR , settings	Appelé immédiatement avant l'exécution de la requête AJAX. Si FALSE est renvoyé, la requête ne démarrera pas.
start	jqXHR , settings	Appelé immédiatement après le démarrage de la requête AJAX.
success	payload , status , jqXHR , settings	Appelé après la réussite de la requête AJAX. Équivalent à $.ajax( ... ).done( ... .
complete	jqXHR , status , settings	Appelé après chaque achèvement de requête AJAX. Équivalent à $.ajax( ... ).always( ... .
error	jqXHR , status , error , settings	Appelé en cas d'échec de la requête AJAX. Équivalent à $.ajax( ... ).fail( ... .

L'extension peut être désactivée :

 $ . nette . ext ( 'name' , null ) ;

L'extension peut être configurée. Son contexte peut être acquis par :

 var context = $ . nette . ext ( 'name' ) ; 

Extensions par défaut

nom	description
validation	Limite l'ajaxification aux clics/soumissions sans touche Ctrl , Alt ou Shift , aux liens locaux et aux soumissions de formulaires valides.
forms	Ajoute la prise en charge de la soumission de formulaires avec toutes les données, le nom du bouton cliqué et les coordonnées du clic dans les entrées [type=image] .
snippets	Met à jour le DOM par tableau snippets en réponse (gestion par défaut des extraits de Latte par Nette).
redirect	Exécute la redirection vers une URL différente (lorsque $this->redirect() est appelé dans le présentateur). Peut être remplacé par une extension history .
unique	Ne conserve que les requêtes en cours d'exécution au même moment.
abort	Permet à l'utilisateur d'abandonner la requête en cours d'exécution en appuyant sur Escape .
init	Ajaxification par défaut.

Astuces utiles

Toutes ces fonctionnalités spéciales nécessitent que toutes les extensions par défaut soient activées.

data-ajax-off

Le lien ou tout autre élément ajaxifié peut avoir un attribut de données personnalisé data-ajax-off . Il contient les noms des extensions qui doivent être désactivées pour les requêtes Ajax lancées sur l'élément.

 < a n:href =" do! " class =" ajax " data-ajax-off =" snippets " >

Vous pouvez également l'utiliser dans $.nette.ajax() . Comme ça:

 $ . nette . ajax ( {
	url : ... ,
	off : [ 'snippets' ]
} ) ;

data-ajax-pass (dans l'extension validation )

L'ajaxification de l'élément garantit que e.preventDefault() sera appelé. Cet attribut peut l'empêcher si vous avez besoin de déclencher davantage de rappels.

data-ajax-append (dans l'extension snippets )

Le nouveau contenu de l'extrait avec cet attribut ne remplacera pas l'ancien contenu, mais il y sera plutôt ajouté.

data-ajax-prepend (dans l'extension snippets )

Le nouveau contenu de l'extrait avec cet attribut ne remplacera pas l'ancien contenu, mais il y sera plutôt ajouté.

data-ajax-validate (dans l'extension validation )

Le clic sur le lien ou la soumission du formulaire est validé sous diverses conditions. Vous pouvez changer n'importe lequel d'entre eux :

 < a n:href =" do! " class =" ajax " data-ajax-validate =' {"keys":false} ' >

Et comme dans le cas de data-ajax-off , vous pouvez le transmettre directement dans $.nette.ajax() .

 $ . nette . ajax ( {
	url : ... ,
	validate : {
		keys : false
	}
} ) ;

Cela signifie que cliquer sur le lien avec Ctrl n'ouvrira pas un nouvel onglet, mais ajaxifiera la demande.

Dépendance à une autre extension

Dans les rappels d'événements, vous pouvez appeler this.ext() pour obtenir le contexte d'une autre extension. Si vous ajoutez true comme deuxième argument, le script échouera si cette extension n'est pas disponible.

 $ . nette . ext ( {
	success : function ( payload ) {
		var snippets = this . ext ( 'snippets' , true ) ;
		...
	}
} ) ;