Practical Guide to mrujs
If you’re new to the concept of UJS, or want a practical example of what mrujs does, this document will provide a guided tour of the core features of mrujs.
There are 2 ways to approach this guide.
1.) Create your own project with the HTML provided and play with it.
2.) Follow along with the examples provided below.
Prerequisites
If you are going to be following along on your own project, make sure to read the Getting Started Guide for instructions on how to install mrujs.
Showing a basic confirm dialog
If I want to prompt a user before performing an action, I can throw a
data-confirm on clickable elements (<button>, <a>) and ask the
user to answer “yes” or “no” before continuing on with what the action
or link intends to do.
To see an example, heres a basic button:
<button data-confirm="Hey! You clicked me!">
Click me and I'll show a confirm dialog.
</button>
Disabling Elements
mrujs believes in providing strong defaults. As a result, when forms are submitted or links are clicked, they get automatically disabled. Heres an example:
<button id="disable-example"
data-disable-with="Now I'm disabled...">
I'm enabled!
</button>
<!--
This re-enables the element after 3 seconds
since regular buttons have no concept of when
to re-enable themselves if they're not part of a
form.
-->
<script>
document.querySelector("#disable-example").addEventListener("click", (event) => {
setTimeout(() => window.mrujs.enableElement(event.target), 3000)
})
</script>
Maybe you don’t want to display any other text, maybe you just want to disable the element without showing new text. Not a problem.
<button id="disable-example"
data-disable="true">
I'm enabled!
</button>
<script>
document.querySelector("#disable-example").addEventListener("click", (event) => {
setTimeout(() => window.mrujs.enableElement(event.target), 3000)
})
</script>
Sending forms and links via “AJAX”
If you’re not familiar with the term AJAX, it just means sending a request to the server asynchronously (in the background)
mrujs sends this requests via a web native API called fetch.
https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
Trigger ajax on a link
To trigger an ajax request on a link, add the
data-remote="true" property to the <a> tag like so:
<a href="/" data-ujs-navigate="false" data-remote="true">
I send a GET request to this server in the background. <br>
Check your network tab!
</a>
I send a GET request to this server in the background.
Check your network tab!
Trigger ajax on a form
<form action="/blah" method="post" data-remote="true" data-ujs-navigate="false">
<input class="btn btn--primary" type="submit" value="Submit via AJAX">
</form>
Check your network tab! You will see the request gets sent as an “XHR” request.
Make a link send a request other than a GET
By default, links send GET requests to the server. But perhaps you
want to instead send a DELETE request. Heres how you would do that.
<!--
If you specify data-method,
you do not need data-remote,
it is implied
-->
<a href="/" data-method="delete" data-ujs-navigate="false">
Click me and I send a delete request
</a>
Click me and I send a delete request
Making a request expect a certain response.
If you’re familiar with Accept headers, mrujs provides a way to
expect a certain response. For example, if I want JSON to be returned I
could do this:
<a href="/" data-remote="true" data-type="application/json">
Expect a JSON response
</a>
However, this can get annoying to type. So instead we can hook into a shortcut provided by mrujs like so:
<a href="/" data-remote="true" data-type="json">
Expect a JSON response
</a>
A list of all shortcuts is provided here:
https://github.com/ParamagicDev/mrujs/tree/main/src/utils/headers.ts#L3-L10
If the predefined shortcuts feel limiting, it is possible to create your own. To do so, check out the documentation on MimeTypes
Next Steps
Now that the core of mrujs has been explained. Perhaps a good next step would be to look at the AJAX lifecycle to get an understanding on how to hook into the ajax events. Or if you’re feeling a little shaky how ajax works, you can check out the docs on Remote forms and links