jiripudil / Naja 2.1.1

Modern AJAX library for Nette Framework


Build Status Code Coverage latest version license minified size minzipped size monthly downloads downloads total

Naja. a genus of venomous elapid snakes comprising the true cobras. (Also, German for "Well" at the beginning of a sentence.)

Naja is a full-featured JS client-side AJAX library for Nette Framework.

It is written using modern-day JavaScript, but compiled into a bundle that works in all modern browsers. Every build of Naja is thoroughly tested and therefore guaranteed to work in the latest versions of Chromium (Chrome and Edge), Firefox, and WebKit (Safari).

Very quick start

$ npm install --save naja
import naja from 'naja';
document.addEventListener('DOMContentLoaded', () => naja.initialize());


You can find the documentation here.

  • 2.1.1 2.1.1

    • ๐Ÿž FormsHandler: add missing undefined check to condition in processForm (#184)
  • 2.1.0 2.1.0

    • UIHandler: manual dispatch methods clickElement() and submitForm() now return the promise from the underlying request call (#177).
    • naja.makeRequest() now serializes simple POJO data into query string for GET and HEAD requests (#178).
  • 2.0.1 2.0.1

    • ๐Ÿž Fixed reading historyUiCache setting from defaultOptions (#85)
    • ๐Ÿž Fixed type definitions file path in package.json (#91, #92, thanks @dakur)
  • 2.0.0 2.0.0

    New features

    • SnippetHandler: allow changing snippet update operation in "before" event. You can change the planned snippet update operation (i.e. replace, prepend, or append) in the beforeUpdate event. You can also provide your own implementation of the snippet update mechanism, e.g. using a Virtual DOM library.
    • UniqueExtension: add support for multiple groups of uniqueness. You can now provide a custom string key via the unique option or data-naja-unique attribute to create a new unique group. Only requests from the same group are aborted when a new one is started.

    Breaking changes

    • Naja now uses Fetch API instead of XMLHttpRequest.
    • All EventTargets in Naja codebase now dispatch proper CustomEvents.
    • The interaction event has moved to UIHandler.
    • The load event has been removed.
    • Extensions API has been greatly refactored.
    • Options are no longer read from response payload.
    • Dropped support for Internet Explorer.

    Please refer to the migration guide for further details.

  • 2.0.0-alpha.3 2.0.0-alpha.3


  • 2.0.0.-alpha.2 2.0.0-alpha.2

  • 1.8.3 1.8.3

    • Made support for submitting forms via GET even more reliable.
  • 1.8.2 1.8.2

    • Fixed submitting forms via GET (#63).
  • 1.8.1 1.8.1

    • Reverted a commit that got into 1.8.0 as a result of a brain fart.
  • 1.8.0 1.8.0

    • SnippetHandler events now have the fromCache flag. The beforeUpdate and afterUpdate events now carry the information about whether the snippet is being updated from cache after user navigation (i.e. going back in history), or as a result of an AJAX request to the server.
    • RedirectHandler detects local redirects via UIHandler.allowedOrigins. Until now, redirects leading to the same origin were done via another AJAX request (unless forced otherwise). This detection now takes into account the configured allowed origins, which means that redirects to any of the allowed origins is processed asynchronously by default.
    • RedirectHandler dispatches the redirect event prior to redirection. This event allows you to override the soft vs. hard redirection settings, or even entirely prevent the redirection from happening.
  • 2.0.0-alpha.1 2.0.0-alpha1

  • 1.7.0 1.7.0

    • Deprecate reading options from response payload (#44). After some thought, I consider passing options such as replaceHistory or forceRedirect to Naja via the response payload to be a cul-de-sac; server should not be able to affect the client-side processing of the request in such direct way. Therefore, Naja now emits a deprecation warning if it encounters such options in the payload, and will stop supporting them in 2.0.

    • RedirectHandler: pass original options to the new "redirection" request (#45). If the target redirection URL is local (i.e. relative, or absolute pointing to the same origin), RedirectHandler sends another AJAX request instead of redirecting. Since redirect sequences are usually perceived as a single request, Naja now mimics such flow by passing the options of the original request to the redirected request, so that the intended behaviour of the request is preserved.

  • 1.6.0 1.6.0

    • Refactor UIHandler and FormsHandler to only rebind updated snippets (#19). This is a simple internal refactoring which could lead to a better performance. As a side effect, the UIHandler now exposes the bindUI() method which you can use to manually bind the AJAX handler to DOM nodes that are created dynamically via a different mechanism than Nette snippets.

    • Accept defaultOptions in naja.initialize() (#24). The naja.initialize() method now accepts defaultOptions, adding a second way to configure them in addition to modyfing naja.defaultOptions directly. The default options passed to the initialize method are also provided to the init event listeners.

    • HistoryHandler: implement disabling UI cache (#17). This is an advanced feature that entirely disables the UI state cache; this helps prevent errors caused by big snippets that exceed the maximum storage quota. During navigation through the browser history, requests are actually sent again rather than artificially replayed from the history entry state. Be sure that you know what you're doing before using this feature.

    • Optimized SnippetHandler prepend/append (#20). Thanks @vitkutny!

  • 1.5.1 1.5.1

    • Fixed: HistoryHandler now respects naja.defaultOptions.history and does not override it to true when data-naja-history attribute is not set on the element. (Thanks @brosland for investigation!)
  • 1.5.0 1.5.0

    • FormsHandler now optionally accepts a reference to nette-forms (#15). This is handy if you import the nette-forms script manually. If you provide the reference, FormsHandler will use it instead of relying on global window.Nette.
  • 1.4.0 1.4.0

    • Added UIHandler.clickElement() and UIHandler.submitForm() helper methods (#12) that allow you to dispatch UI-bound events manually. This is especially useful if you need to submit a form programmatically (e.g. on change of select box), because form.submit() does not trigger the form's submit event.
      • โš ๏ธ The helper methods trigger the interaction event with originalEvent set to undefined. This potentially breaks BC if you choose to use the newly introduced methods!
    • Simplified initial pop detection (#10). It doesn't appear to be a problem anymore, but in browsers where it still is a problem (some ancient Chromes and Safaris), this solution should work too while being elegantly simple. As a side effect, this should also prevent popstate behaviour in HistoryHandler being triggered on hashchange.
      • โš ๏ธ This also removes a few attributes from HistoryHandler that are no longer necessary: initialUrl, initialState, and popped. They were part of the internal API and were never documented, thus I don't consider their removal to be a BC break.
  • 1.3.2 1.3.2

    • Fixed incorrect data-naja-snippet-prepend and data-naja-snippet-append attributes detection in SnippetHandler
  • 1.3.1 1.3.1

    • Fixed incorrect data-naja-history-nocache attribute detection in HistoryHandler (#8, thanks @dakur)
  • 1.3.0 1.3.0

    • You can provide default options for your extensions or even Naja's core components via naja.defaultOptions.
    • The options object is now passed to the success, error, and complete event handlers. Components and extensions can now use the options object to pass metadata along with the request instead of having to keep track of them internally, which should prevent potential concurrency issues.
    • RedirectHandler reads the forceRedirect flag not only from response payload but also from options.
  • 1.2.0 1.2.0

    • SnippetHandler now exposes events that are dispatched prior to and after every snippet update.
    • I got rid of an unnecessary layer of inheritance in a small internal refactoring.
  • 1.1.0 1.1.0

    • Initialization of core services was refactored to allow for further changes.
    • The Promise returned by naja.makeRequest() is resolved with the parsed response body, or rejected with the thrown error. This allows you to chain custom behavior after the response is processed by Naja when calling makeRequest() manually.
    • Aborted requests are handled in a specific abort event. They no longer trigger error handling, as the reasons for aborting the request usually do not indicate an erroneous state.
    • The bound selector (.ajax) is now customizable via naja.uiHandler.selector.
    • To prevent people from shooting themselves in the foot, UIHandler now checks that the link target matches a set of allowed origins, and does not dispatch the asynchronous request if it does not match. You can configure the allowed origins by pushing them to naja.uiHandler.allowedOrigins.
    • Browser history manipulation can be disabled for specific requests by adding history: false to the request options, or data-naja-history="off" to the .ajax element.
    • Also, you can now decide on the front-end side whether you want to push a new state, or replace the current one, by adding history: 'replace' to the options or data-naja-history="replace" to the element.
    • Tests now run in real browsers via SauceLabs, so that there's a better guarantee that IE 10+ is actually supported. ๐ŸŽ‰




Componette Componette