« Senate votes to repeal DADT! | Main | Awaits the sun's return »

jQuery basics

| 4 Comments

I'm finally starting to teach myself how to use the jQuery JavaScript library.

So I'm looking at some of the tutorials on the Tutorials page.

And they all dive right into a mysterious notation using dollar signs and parentheses that doesn't match anything I've seen in JavaScript before.

So in case anyone else is in the same boat:

The fundamental piece that the tutorials don't bother to mention at the start, and without which you may have a hard time understanding the examples, is explained on the jQuery() reference page.

As I understand it, the gist of it (bearing in mind that I'm new to this too, and that I'm somewhat oversimplifying) is this:

  • The mysterious-looking $() is just a shorthand/synonym for jQuery().
  • jQuery() is a constructor for a jQuery object.
  • jQuery(selector) (where selector is a CSS selector) “searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements.”
  • jQuery(html_fragment) creates a new DOM element containing the specified HTML, then creates a jQuery object that refers to the new element.

It's really not that complicated. But by saying that they're starting from scratch and then throwing $(foo) constructions at the reader immediately, without explanation, the tutorials are doing readers a disservice.

I know, I know, instead of posting publicly about it, I should go contact the owners of the tutorials and ask them to add a note about this. I'll probably do that too. I'm just in a bad mood and am being easily annoyed. (I keep running into things in various contexts and on various sites today that are unclear or confusing or otherwise need fixing, so my patience is wearing thin.)

P.S. added a bit later: The Tutorials main page has edit links on it, so I thought maybe I could just go and fix things myself. No such luck. It turns out you need to log in first. How do I log in? Turns out you need to create an account first. Makes sense; how do I create an account? Oh, okay, there's a link that says “Log in / create account.” So I clicked that. Nope, it just gives you a login prompt. After about five minutes of increasing frustration, I finally went and asked on the IRC channel. Someone on the IRC channel answers that you can't create an account. And then quits the channel seconds later, before I can ask for clarification.

SO WHY DOES THE LINK SAY CREATE ACCOUNT?????

Gah.

If any jQuery people happen across this entry, I would love to talk with someone about improving the new-user experience on your site; drop me a note in email if you're interested in some suggestions.

P.P.S. added a bit later: I went to file a bug about the account creation thing.

And Akismet rejected my bug as spam.

It offered me a CAPTCHA.

Which I answered correctly.

And it not only re-rejected it as spam, but it stopped even offering me CAPTCHAs for subsequent attempts at filing bugs.

I finally managed to file a bug asking for help filing bugs, but only by giving my email address as “anonymous.”

This has been the single most frustrating new-user experience I have ever had. I'm sitting here yelling at my computer.

Not so sure I want to learn jQuery any more.

4 Comments

Wow, that is frustrating.

But please don't give up on jQuery! jQuery is awesome; I love jQuery.

Regarding the tutorials: I agree that the "How jQuery Works" one doesn't explain enough, but the "Getting Started With jQuery" does a pretty good job, I think. Yes, it throws in the weird syntax right away -- but then it says "Let's take a look at what we're doing" and explains. I feel like it's not uncommon for programming language tutorials to have you do something that you don't understand (so you can see it work) and then explain later. (My favorite is the java

public static void main(String[] args) {
//"Hello World" code here
}

which is invariably introduced as "just do this, we'll explain it much, much later".)


Thanks for the note!

I did end up continuing with the jQuery tutorial (the Getting Started one) last night, and I agree that it does a decent job. It could be much better—I really want to go in and edit it—but once I got past the confusing beginning, it's not bad. (It's certainly better than most of the other jQuery beginner tutorials I've found; most of them are full of ungrammatical and confusing sentences. It appears to be a library that attracts documentation written by people who aren't very good at writing English.)

I agree that a lot of tutorials start by saying "Don't worry about such-and-such, we'll explain this later." But I would say that the jQuery Getting Started tutorial doesn't do that; it tosses in the weird syntax without comment, and then it doesn't explain it later. It does link to a reference page on which the explanation can be found, which is good and which is how I found out the information in my entry here. But as I demonstrated in this entry, it would have taken very little space to just provide a brief explanation of the weird syntax upfront. (It could be a lot briefer than my version.)

And the GS tutorial is about the fourth tutorial that a reader runs into on the site. the first one, "How jQuery Works," is much worse about jumping into the deep end without explanation; and then on the tutorials page, the first two listed are tutorials on how to write plugins, with no explanation of what a plugin is or why you would want to write one.

Anyway, none of these issues are insurmountable; give me editing privileges for half an hour, and I'll fix the worst of them. Give me editing privileges for another two hours, and I'll do an editing/cleanup pass on the Getting Started one to fix the other (more minor) issues with it.

And I agree that jQuery does appear to be pretty cool, and will make various things easier/better for me (and for the magazine). So I'll keep poking at it.


Wow, what a lousy user experience! Hope it gets better for you. I too struggled with the $. And then learned $ can even conflict with other javascript libraries.

You can rename it like:
jed = jQuery;
TheKitchConstructor = jQuery;
$$$$$ = $;

How are you planning on using jQuery for your site?


Thanks, Elyon!

What I was hoping to do with jQuery was some nice animated showing and hiding of stuff. Ask a question, then depending on their answer, show or hide various responses to their answer, including the next question in the series. I can do all that in JS reasonably straightforwardly, but I was hoping jQuery would make it look really nice, 'cause I saw it done really nicely using jQuery on someone else's page.

But it turned out that the project I wanted to use it for got vetoed, so I put jQuery on the back burner until I have time to dig into it again.

Some day I hope to go back to the site and try again on proposing improvements to their documentation.


Post a comment