phoenix_ujs
Unobtrusive vanilla JS toolset for Phoenix framework
Purpose
A compact port of jquery-ujs for Phoenix framework (the library is agnostic, so you can use it with other backends as well). The library does not requires jQuery and covers only essential needs:
- non-'GET' links (POST, PUT, PATCH, DELETE, etc)
- confirmation and/or remote request on clicking link or submitting form
- refreshing CSRF inputs in forms (fix browser form caching)
Installation
npm i --save phoenix_ujs
If your js build system supports commonjs require
and/or import
methods (Brunch, Webpack, Browserify) add the
next code at the top of your main js file:
var UJS = ;// or;
For other cases you can use one of the package files:
~ : ls node_modules/phoenix_ujsujs.js # browser versionujs.min.js # minified browser versionujs.cjs.js # commonjs version (used in `require` by default)ujs.es.js # ES6 version
To setup your backend - open layout file and add next at the top of the :
<!-- example for Phoenix.HTML 2.7.1+ --> <%= csrf_meta_tag() %> <!-- example for Phoenix.HTML 2.7.0 and below--> <!-- also meta tag can contain the next setting-attributes: csrf-param="_csrf_token" csrf-header="x-csrf-token" method-param="_method" -->
Usage
Markup
<!-- to specify non-get method add `ujs-method` -->Make a POST requestMake a DELETE requestMake a PATCH request
<!-- add confirmation with `ujs-confirm` -->Ask confirmation to open linkAsk confirmation to make a POST request <!-- ask confirmation when form is submitting -->
<!-- make an ajax request on click if `ujs-remote` is present --><!-- the next event will be triggered: ajax:beforeSend - event before AJAX call. AJAX request can be canceled if handler will return `false` ajax:success - a success response (2xx status code) ajax:error - an error response (4xx, 5xx status code) ajax:complete - an response received with any status-->Patch remotely <!-- AJAX form submitting -->
JS API
The library exports module (window.UJS in browser version) with the next properties:
confirm
- the confirmation function which accepts a message as the first argument. You can override it for your needscsrf
- a CSRF configuration object:token
- a current CSRF token. You can skip the meta tag in the header and put the token in runtimeheader
- a header used for CSRF requestsparam
- a query/form param used for CSRF requests
xhr
- the AJAX contructor
var UJS = ; UJS; // a simple get request// all ajax events (ajax:beforeSend, ajax:success, ...) will be triggered on documentUJS; UJS;
options
accepts the next params:
headers
- additional headerstarget
- js event target (by default - document)beforeSend
- the callback before xhr executed. It passes the config with xhr & options properties.return false
will stop the ajax requestsuccess
- the success callback (200 <= status_code < 300)error
- the error callback (status_code >= 400)complete
- the complete callback (any status_code)type
- indicated additional processings;- "json" - converts data into json string, sets Content-Type & Accept headers to
application/json
- "text" - sets Content-Type & Accept headers to
text/plain
- Array(2..3) - sets Content-Type - the first array's element, sets Accept - the second array's element and process data with the third element (if it's exist)
- "json" - converts data into json string, sets Content-Type & Accept headers to
AJAX events
Each ajax request triggers the following events:
ajax:beforeSend
is triggered before making an ajax call. In this event you can cancel the ajax request:
document;
ajax:success
is triggered after getting an response and response is 2xx.
document;
ajax:error
is triggered after getting an response and response is 4xx or 5xx.
document;
ajax:complete
is triggered after any response:
document;
Things which are not included
- executing a response js code. It's highly recommended to not do it, but if you need - there's an example:
document;
Eval the server code
Old browser support
If you're working on a project with old browsers support (IE 9-, Android 2.x, etc) - the library will not work unless you add a polyfill for FormData. For example this one https://www.npmjs.com/package/js-polyfills
License
TODO
- tests
- examples