Načítání obsahu webových stránek bez nutnosti obnovení stránky prostřednictvím AJAXového volání je dnes běžnou praxí.
Toto chování urychluje zobrazení webové stránky a snižuje množství přenášených dat mezi serverem a prohlížečem.
Zavést toto chování na webu postaveném na frameworku Nette je, díky připraveným skriptům snadné a rychlé.
Soubor nette.ajax.js je skript, který do webu postaveného na frameworku Nette přináší snadnou implementaci AJAXového chování.
Podporuje výstřižky šablon (snippets), přesměrování apod.
Stažení a závislosti
- skript je k dispozici ke stažení na Githubu: vojtech-dobes/nette.ajax.js
- skript ke svému fungování vyžaduje knihovnu jQuery verze 1.7 a výše
Inicializace
Pro zapnutí funkcí je potřeba zavolat funkci init():
$(function () { $.nette.init(); });
Základní použití
Všechny odkazy s třídou ajax budou po kliknutí (event click) volány AJAXově:
<a class="ajax" href="...">Odkaz</a>
Všechny formuláře s třídou ajax budou odesílány (event submit) AJAXově:
<form class="ajax">
nebo
<input class="ajax" type="submit">
Změna výchozího chování
Skript reaguje na prvky s třídou .ajax. Toto výchozí chování lze změnit v rozšíření init. Objekt vrácený při zavolání:
var init = $.nette.ext('init');
obsahuje vlastnosti:
| Vlastnost | Výchozí hodnota | Popis |
|---|---|---|
| linkSelector | a.ajax | Výběr prvku pro odkazy |
| formSelector | form.ajax | Výběr prvku pro formuláře |
| buttonSelector | input.ajax[type=“submit“], input.ajax[type=“image“] |
Výběr prvku pro odeslání formuláře |
Vypnutí AJAXu
AJAXové chování můžeme pro konkrétní prvek vypnout:
$('a.no-ajax').off('click.nette');
nebo
$('a.no-ajax').netteAjaxOff();
Rozšíření
Funkce skriptu obaluje standardní jQuery funkci $.ajax() a rozšiřuje ji o několik dalších užitečných událostí.
Registrace rozšíření
$.nette.ext('nazev', {
event1: function () {
},
event2: ...
}, {
// ... shared context (this) of all callbacks
});
Parametry funkce
- (volitelný) název
- sada callbacků, nazvaných podle odpovídajících událostí:
| Název události (callbacku) | Parametry | Popis |
|---|---|---|
| init | Callback je volán pouze 1x během volání $.nette.init() | |
| load | requestHandler | Should contain ajaxification. requestHandler can be bound to UI events to initiate AJAX request. |
| before | jqXHR, settings |
Callback je volán těsně před provedením AJAXového požadavku. Pokud vrací FALSE, požadavek nebude zavolán. |
| start | jqXHR, settings |
Callback je volán těsně po započetí AJAXového požadavku. |
| success | payload, status, jqXHR, settings |
Callback je volán po úspěšném dokončení AJAXového požadavku. Ekvivalent pro $.ajax(…).done(…) |
| complete | jqXHR, status, settings |
Callback je volán po každém dokončení AJAXového požadavku. Ekvivalent pro $.ajax(…).always(…) |
| error | jqXHR, status, error, settings |
Callback je volán v případě selhání AJAXového požadavku. Ekvivalent k $.ajax(…).fail(…) |
Vypnutí rozšíření
$.nette.ext('name', null);
Kontext rozšíření
Rozšíření lze přenastavit. Jeho kontext získáme následovně:
var context = $.nette.ext('name');
Základní rozšíření
Základní rozšíření dostupná ve skriptu nette.ajax.js.
init
Základní rozšíření zapínající fungování AJAXu.
validation
Omezuje fungování AJAXu na
- kliknutí na odkaz či odeslání formuláře bez současného stisknutí kláves Ctrl, Alt či Shift
- lokální odkazy v rámci webu
- a odeslání pouze validních formulářů
forms
Přidává podporu pro odeslání formulářů se všemi daty, názvu tlačítka na které bylo kliknuto a koordinuje kliknutí na inputy [type=image].
snippets
Aktualizuje DOM vrácením pole se snipety v odpovědi (výchozí chování výstřižků šablon v Nette).
redirect
Provádí přesměrování na danou URL (pokud je v presenteru volána funkce pro přesměrování $this->redirect()).
Lze nahradit rozšířením history.
unique
Povoluje či zakazuje provádění více volání ve stejnou chvíli.
abort
Umožňuje uživateli stisknutím klávesy Escape přerušit aktuálně probíhající požadavek.
Užitečné triky
Následující funkce jsou dostupné pouze při zapnutí všech základních rozšíření.
Atribut data-ajax-off
Atribut data-ajax-off obsahuje názvy rozšíření, která mají být pro AJAXový požadavek spuštěný na daném prvku vypnuta.
<a n:href="do!" class="ajax" data-ajax-off="snippets">
Totéž chování lze nastavit při volání funkce $.nette.ajax():
$.nette.ajax({ url: ..., off: ['snippets'] });
Atribut data-ajax-pass
<a n:href="do!" class="ajax" data-ajax-pass>
Vypíná volání funkce e.preventDefault().
Užitečné v případě, pokud potřebujeme spustit více callbacků po sobě.
(Součást rozšíření validation.)
Atribut data-ajax-append
<a n:href="do!" class="ajax" data-ajax-append>
Nový obsah výstřižku šablony nenahradí původní obsah, ale bude připojen za něj.
(Součást rozšíření snippets.)
Atribut data-ajax-prepend
<a n:href="do!" class="ajax" data-ajax-prepend>
Nový obsah výstřižku šablony nenahradí původní obsah, ale bude připojen před něj.
(Součást rozšíření snippets.)
Atribut data-ajax-validate
Kliknutí na odkaz nebo odeslání formuláře je validováno různými podmínkami. Lze přepnout libovolnou z nich.
Např. pro otevření odkazu do nového okna a současného provedení AJAXového volání při stisknuté klávese Ctrl v okamžiku kliknutí na odkaz:
<a n:href="do!" class="ajax" data-ajax-validate='{"keys":false}'>
případně:
$.nette.ajax({ url: ..., validate: { keys: false } });
(Součást rozšíření snippets.)
Závislost na rozšíření
Uvnitř callbacku lze získat kontext dalšího rozšíření zavoláním funkce this.ext(). Pokud jako druhý parametr předáme hodnotu true, skript vrátí chybu, pokud nebude rozšíření dostupné:
$.nette.ext({ success: function (payload) { var snippets = this.ext('snippets', true); ... } });