Re-writing the AJAX Guide #7493
Conversation
|
Oh, and I should probably link to the Russian Doll caching guide once it's up too, right? And PJAX. |
|
One thing that I was talking with @dhh few days ago is to add a Unobtrusive Javascript section talking about how we can do the same thing that the deprecated |
|
Seems great to add PJAX in this guide too. |
|
First, let me say thanks for doing this. You are doing the FSM's work here. I don't know if JSONP and CORS are out of scope, but having run into problems with cross-origin ajax requests over the last two days, it is something I could've used a hint about. (Still can't figure out why respond_with doesn't seem to work with rack/cors) Also, a clear list of what the callback events are and how to use them - I couldn't seem to get a handler bound to :failure, and wound up binding to ;error instead. I'm on a plane to PDX tomorrow AM, so I'll give this some thought when I'm in the air, and I'm sure to think of other stuff I had to google for. Thanks again! |
|
Leave in the intro to AJAX, please. Everyone is a beginner sometime, and Rails is perceived as getting more n00b hostile. Let's try to reverse that trend. And, yay, thanks for doing this. |
|
Steve, Regarding your first question: I don't think you should assume that "everybody knows what's up". There's probably more than a few people (myself included) who will jump into this topic without any knowledge beforehand and chances are some basic introduction will help them get the concept behind AJAX. Thanks for rewriting this! |
I think it'd make more sense to write "Working with Javascript" guide rather than "AJAX on Rails" guide. |
I like this, too. It used to be called "AJAX on Rails," which was the only reason I kept the name. "Working with Javascript" might be better! |
|
Thanks for volunteering to do the work on this, Steve. I see a lot of newbies who are confused with how JavaScript and Rails work together and this should help them. One thing I have not seen covered in this discussion so far is the organization of JavaScript files within the app. Perhaps that could also be mentioned? On 31/08/2012, at 4:25, Steve Klabnik notifications@github.com wrote:
|
|
Awesome, thanks for taking the baton! This guide was halted, a couple of people started working on it but Real Life didn't let them finish a draft. Problem was the HTML was generated anyway and albeit it was never in the guides index Google indexed it and it showed up in searches. I agree with the feedback given by @lifo. |
|
One thing that we didn't cover much in The Rails View book and that we get questions about all the time is the why, how, and what for of UJS. I'd love to see you all be opinionated about where JS belongs and show examples (good and bad) and possibly a refactor from bad to good. |
|
I think https://github.com/rails/jquery-ujs/wiki/ajax and https://github.com/rails/jquery-ujs/wiki/Unobtrusive-scripting-support-for-jQuery are worth being documented in guides. Thanks! |
|
Great initiative @steveklabnik |
|
Awesome! I also agree that external libraries barely need mentioning. It'd be great if they could see what they can do immediately without introducing anything else, and I feel like there's been so much flux with this topic that it's hard for a new person to figure out what the default Rails way is. |
|
Well, one of the things is that Rails does not currently have a default way to test Javascript. |
|
Thank you so much for working on this :) |
|
One thing I was thinking about that could be made clearer is the difference between rendering JS to be executed, or JSON to be used by a handler, or HTML to be stuffed into a DOM element. Also how this might play together with respond_to / respond_with (even though I can't seem to make it work for myself) |
|
+1 |
|
@steveklabnik @mattvanhorn What I think is grossly needed is a simple example that shows how AJAX works out of the box with Rails (without the need for outside frameworks, the building of JSON APIs, etc). The current functionality is similar to that of RJS from a few years ago, and yet I think it's been forgotten/lost in the shuffle with all of the talk about the modern JS client frameworks. DHH recently gave a remote talk at our office meetup discussing the New Basecamp and they (37signals) are still utilizing this old school, out of the box approach to AJAX ( http://www.youtube.com/watch?v=FkLVl3gpJP4#t=1h12m25s ). I have added this example and put in a pull request. |
|
@aantix heh, that's what I get for reading threads in the wrong order ;) I agree, this example is super useful. |
| and +jquery_ujs.js+ provided by the +jquery-rails+ gem. | ||
|
|
||
| If the application is not using the asset pipeline, this can be accessed as: | ||
| Image you have a series of users that you would like to display and provide a form on that same page |
There was a problem hiding this comment.
Typo alert /Image/Imagine :)
btw, this is amazing. great work. thanks for doing this
|
I rebased all this off of master, and converted to markdown. I'm gonna try to work on this a bunch today. Incorporate all the feedback here, as well as adding a TurboLinks suggestion of course... |
|
Hello everyone! I think that as a first rough draft, this is good to go. I tried to incorporate all your feedback; please review and leave me some comments! I think this is in pretty decent, though not perfect shape. |
|
Is there a reason for using respond_to instead of respond_with in the server side example? Apart from that, great initiative and nice and compelling writing. ;) |
|
That was just the code @aantix pulled together. Jim? (and thanks!) |
|
It would be nice to see UJS events called out in the guide a little bit more. I see a link at the very bottom of the guide an important piece to the puzzle when using ajax helper methods. Small example of client and server side interactions would be mega awesome too. |
|
Lookin' good man. Great start. |
|
Nice job. Since coffeescript is the default it feels like that should be introduced and maybe the examples should be in coffeescript too. |
|
@jeremywrowe Sure. What does 'a little more' mean? I figured that discussing them in the @barelyknown that's quite possibly a great idea. I'll have to convert them to CoffeeScript. |
|
Yeah, I'm not 100% sure that that's really in the scope of this guide. |
|
@steveklabnik Awesome work here! Just one suggestion: |
|
HAML is not included in base rails, and is therefore out of the scope of this guide. But thank you! |
|
I believe all of the current concerns have been addressed. |
| $(document).ready -> | ||
| $("a[data-fib]").click (e) -> | ||
| count = $(this).data("fib") | ||
| alert "fib of " + count + " is: " + fib(count) + "." |
There was a problem hiding this comment.
Use the string interpolation.
There was a problem hiding this comment.
dammit. I thought this was fixed?
|
Anything else blocking this from shipping? I would like a short debugging JS for newbs section, stuff as simple like check the console for errors, make sure your jquery selectors work using toggle in the console, and perhaps a little section on using console.log(). Mentioning those 3 things to a true newb makes a world of difference. That stuff could be added later though. I see nothing stopping this PR. Ship It? |
|
Yeah, I'm pretty happy overall. @fxn what do you think? |
|
Awesome, I'll do a pass this week. |
| that has that attribute: | ||
|
|
||
| ``` | ||
| <script> |
There was a problem hiding this comment.
remember to remove the script tag when we are using CoffeeScript code
|
Seems good. But the @lucasmazza any advice? |
|
I've learned a ton already and think this will be a great addition. That being said, I don't believe the fib example should delay this being shipped. In the context of the example the js is not as important as the amount of js. The subsequent discussion on built in helpers does a good job of providing a real world example while the replacement for fib is being worked. |
ghost
assigned
|
@steveklabnik remember to squash the commits. There is a lot of commits that doesn't make sense alone. |
|
@rafaelfranca absolutely. I figured I'd just wait till the end rather than keep doing it as I went along :) |
|
@hollanddd cool. :) |
|
Rebased! |
Originally, this guide was called "AJAX on Rails," but really, it's not just about AJAX. This was never finished, but it got accidentally generated and Google found out about it. In the meantime, all the guides were converted to markdown, as well. So here's a new guide. It covers all of the built-in helpers that use ajax requests, it covers CoffeeScript, and it covers UJS.
|
Thanks @steveklabnik for the work you did on this guide ! |
|
Hi guys, the guide is awesome. I believe it would be nice to change the fib example, and maybe I do minor copy-editing a little here and there (eg, #results is an element that may or may not be a div). The guide is already very polished, and we have time for those final details before Rails 4, so let's merge. I'll also write a guides changelog entry. Thanks a lot Steve! |
|
|
|
Hooray! |
|
|
|
|
I did a poll on Twitter to see what parts of Rails needed documentation the most, and one glaring thing that was pointed out was how out of date the AJAX guide was.
Currently, this request is not ready to be merged, but I wanted to get some feedback on what I plan to do before I bother to write the entire thing.
Basically, I built a new outline, and threw a quick paragraph or two together for a bunch of the parts.
Current guide (NOT the one I'm working on) is here, for reference.
Questions
Some specific feedback I'd like addressed before I flesh this out more:
Intro to AJAX
When this guide was written, AJAX was a bit newer of a technique. The original guide had an explanation of what AJAX is. Now that everybody knows what's up, do we still need this?
library coverage
I plan on (and have in the outline) linking to a bunch of different projects that are used for testing JS, for example. Is the 'give a bunch of them a paragraph and a link' something we want here?
SPAs?
I wrote up a little section mentioning Ember, Backbone, and Throne of JS. Obviously, "How to write a heavy JS app" is out of the scope of this guide, but I felt that mentioning tools that people can transition to once they get a lot of JS going would make sense. Is this useful?
/cc @fxn @radar @wycats @dhh