[mrujs]
v0.5.0-beta.5
Close

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 theyre 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-with="Now I'm disabled...">
  I'm enabled!
</button>

<script>
  document.querySelector("#disable-example").addEventListener("click", (event) => {
    setTimeout(() => window.mrujs.enableElement(event.target), 3000)
  })
</script>

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

To trigger an ajax request on a link, add the data-remote="true" property to the <a> tag like so:

<a href="/" 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.

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 return 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>

Expect a JSON response

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

AJAX Lifecycle

Remote Elements