Rails UJS documentation

There’s been times when building apps with Turbolinks that I’ve needed to tap into Rails UJS to be able to perform an action (e.g submit a form).

As an example, if you want to submit a rails form with JS you need to use Rails.fire(...) or Rails.handleRemote(...)and there’s no reference to that anywhere in the docs.

I’m not sure if those methods should be used or not. Maybe I’ve misused rails ujs but I wouldn’t know because most examples in stack overflow point to using these methods instead of handlers like ajax:beforeSend or ajax:success.

Are Rails.fire, Rails.handleRemote and others meant to be used? Are they part of a private API? If it’s something we can use, could we add a section to the docs explaining when to use them instead of the handlers?

16 Likes

I second this. I’ve recently tried to migrate from jquery-ujs to @rails/ujs, and I noticed that the handleRemote() function which we were using changed its signature (it doesn’t accept the element anymore).

I wanted to read on its documentation to figure out the correct way to call it, only to find out that methods from @rails/ujs are not actually documented.

1 Like

+1 for this too. Better documentation would be so much better than relying on SO posts that work but leave you unsure if you’re doing things the “Rails Way”.

I agree. I also think the @rails/ujs interaction with Webpacker just to get it running isn’t very well documented.

2 Likes

Second this! Webpacker + UJS setup was a pain for me, especially since I had been able to take so much from UJS for granted before.

What’s the status on this? Where would be an appropriate place to document these methods? I’d be more than happy to draft some documentation with the assistance of a more-experienced developer. There’s been multiple times I’ve only learned that these methods exist because of watching third-party educational content.

@jacobdaddario you might get some idea of status from JavaScript Documentation Coordination.

1 Like

Hey @Betsy_Haibel ! It looks like that Javascript thread is unfortunately inaccurately named, and the guide being drafted is exclusively for Webpacker. Here’s a comment in a PR I opened addressing the topic.

Additionally, in the comment, it was mentioned that there is another comment on a Rails PR that mentions that Rails UJS methods shouldn’t be called directly in code. This relates back to a question posed in the original post.

Given this comment in the original post, I think that this is particularly of note since there seems to be a lack of awareness of this recommendation across third-party sources. In fact, I’ve found the direct use of Rails-UJS methods to be pretty common. It may even be worth opening the discussion on whether methods should be encouraged to be used outside of the library, especially since methods like Rails.ajax() help prevent common errors that catch-up newbies, like not including the CSRF token in the header of the AJAX request (I’m no exception to this).

Hi, I commented in the GitHub issue, but I’m completely open to people starting other documents, eventually we’ll need to make this a PR to Rails itself, but one step at a time.

1 Like

One thing to keep in mind here is that Rails UJS is on its way out and will probably be supplanted by Turbolinks 6.

1 Like

It seems it is @Betsy_Haibel. However we might have apps in the community which will not upgrade anytime soon to TL6 or that may not even be able to (we’ll need to wait and see how different TL6 is to the current implementation of TL + UJS).

IMO there’s value to documenting this regardless of the newer changes. Probably not a full blown, perfect documentation but something that clarifies the role of the methods found in stackoverflow and youtube tutorials like Rails.fire, Rails.ajax, Rails.handleRemote, etc.

I don’t feel comfortable enough with rails ujs to document these but I’m willing to pour some time to it with the guidance of someone knowledgeable of the subject.

The guides cover extended UJS here: Working with JavaScript in Rails — Ruby on Rails Guides

The things I propose adding/modifying are:

  1. How to use custom handlers (e.g ajax:success)? Can we add a couple of real life examples for those?
  2. Are fire, handleRemote etc meant to be used? If yes: how? If not: why? If yes but at your own risk, ok, what’s the risk?

What do you think? :slightly_smiling_face:

2 Likes

I have to go in and out of at least 10 blogs while dealing with Ujs. yes, the document is insufficient.