venne/nette-ajax

Flexible utility script for AJAX. Supports snippets, redirects etc.

dev-master / 2.0.x-dev 2014-09-06 12:54 UTC

Suggests

• janmarek/webloader: *

MIT

• Vojtěch Dobeš

• ajax
• extension
• nette

README

Flexible utility script for AJAX. Supports snippets, redirects etc.

License

MIT

Dependencies

jQuery 1.7

Installation

1. Get the source code from Github.
2. Copy nette.ajax.js to your directory with Javascript files.
3. Link the file in your templates (usually in app/@layout.latte, after jQuery!).
4. Put somewhere the initialization routine:

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

Usage

By defaults all links and forms with CSS class ajax will be instantly ajaxified. Behavior can be altered in configuration of init extension. Object returned by call var init = $.nette.ext('init'); has these props:

name	default value	description
linkSelector	a.ajax	CSS selector for links
formSelector	form.ajax	CSS selector for forms
buttonSelector	input.ajax[type="submit"], input.ajax[type="image"]	CSS selector for form elements responsible for submit

Ajaxification is bound to click (submit) event in nette namespace. Ajaxification of specific link can be canceled with code like this (while other callbacks will remain):

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

Or even simpler:

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

Extensions

Ajaxification envelopes standard $.ajax() call and extends it with several events, that can be hooked with custom callbacks. Set of associated callbacks is called extension. Snippets processing, ability to cancel running request by Escape... all this functionality is implemented in form of extensions. Registration of extension looks like this:

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

First argument is name. It's optional.

Second argument should be hash of callbacks with keys corresponding to names of events. These events are available:

name	arguments	description
init		Called just once during $.nette.init(); call.
load	requestHandler	Should contain ajaxification. requestHandler can be bound to UI events to initiate AJAX request.
before	jqXHR, settings	Called immediatelly before AJAX request execution. If FALSE is returned, request won't start.
start	jqXHR, settings	Called immediatelly after start of AJAX request.
success	payload, status, jqXHR, settings	Called after successful completion of AJAX request. Equivalent to $.ajax( ... ).done( ....
complete	jqXHR, status, settings	Called after every AJAX request completion. Equivalent to $.ajax( ... ).always( ....
error	jqXHR, status, error, settings	Called in case of failure of AJAX request. Equivalent to $.ajax( ... ).fail( ....

Extension can be disabled:

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

Extension can be configured. Its context can be acquired by:

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

Default extensions

name	description
validation	Limits the ajaxification to clicks/submits without Ctrl, Alt or Shift key, local links and valid form submits.
forms	Adds support for submitting forms with all data, name of clicked button and coordinates of click in [type=image] inputs.
snippets	Updates DOM by snippets array in response (default Nette handling of Latte snippets).
redirect	Executes redirect to different URL (when $this->redirect() is called in presener). Can be replaced by history extension.
unique	Keeps only request running at the same moment.
abort	Allows user to abort running request by pressing Escape.
init	Default ajaxification.

Useful tricks

All these special features expect all default extensions to be on.

data-ajax-off

Link or any other ajaxified element can have custom data attribute data-ajax-off. It contains names of extensions, that should be deactivated for Ajax request fired on element.

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

You can also use it in $.nette.ajax(). Like this:

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

data-ajax-pass (in validation extension)

Ajaxification of element ensures, that e.preventDefault() will be called. This attribute can prevent it, if you need more callbacks to be fired.

data-ajax-append (in snippets extension)

New content of snippet with this attribute won't replace the old content, but it will rather be appended to it.

data-ajax-validate (in validation extension)

Click on link or submittion of form is validated on various conditions. You can switch any of them:

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

And as in case of data-ajax-off, you can pass it right into $.nette.ajax().

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

This means that clicking link with Ctrl will not open new tab, but will ajaxify request.

Dependency on other extension

In event callbacks, you can call this.ext() to get context of other extension. If you add true as second argument, script will fail if that extension won't be available.

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