Skip to main content

Bug Tracker

Side navigation

#4944 closed bug (worksforme)

Opened July 22, 2009 07:37PM UTC

Closed November 22, 2010 06:29AM UTC

Last modified March 13, 2012 05:40PM UTC

Misleading docs about special characters in selectors

Reported by: breilly Owned by:
Priority: trivial Milestone:
Component: docs Version: 1.3.2
Keywords: Cc:
Blocked by: Blocking:
Description

I think that the documentation about "Special characters in selectors" (at the bottom of http://docs.jquery.com/Selectors) is misleading. In reality, the special characters only need a single preceeding backslash; the need for a double backslash is to represent a single backslash in a javascript string literal.

Knowing that I needed to escape backslashes in javascript string literals, I was putting '\\\\\\\\' in my javascript code so that I would be sending a double backslash to jQuery and was confused when it wasn't working. A little experimenting showed that I only needed '\\\\' in my code.

Attachments (0)
Change History (5)

Changed July 23, 2009 01:14AM UTC by dmethvin comment:1

resolution: → fixed
status: newclosed

I've edited the docs to clarify, thanks!

Changed February 12, 2010 03:37AM UTC by Chealer comment:2

resolution: fixed
status: closedreopened

This problem has come back. It can now be seen at the top of http://api.jquery.com/category/selectors/

I crafted the following which could be used as a replacement:

If you wish to use any of the meta-characters #;&,.+*~':"!^$[]()=>|/ inside of an attribute selector, you must escape the character with a backslash. A literal backslash needs to be escaped with another backslash. In JavaScript string literals, \\ is a special character, and as such, to include a literal backslash in a string, it must be escaped as "\\\\". Therefore, for example, matching an element with the name "Tricky!" could be done with $('input[name=Tricky\\\\!]'). Matching an element with the name "ProgramFiles\\OpenOffice" could be done with $('input[name=ProgramFiles\\\\\\\\OpenOffice]').

Note that current documentation doesn't explain how to escape a backslash. #jquery's ajpiano explained that, and I verified that is the actual behavior.

This is clearly fairly complicated and could use a full-fledged example.

Changed February 12, 2010 03:43AM UTC by paul.irish comment:3

I respectfully disagree.

The documentation explains how to do everything, with the exception of escaping a backslash, which is such an edge case it does not deserve to push down the contents of the page another four lines of text.

In my opinion, the docs should be explaining HOW to use jQUERY and not middling in the javascript internals that affect the API.

Tonight I added an example to the page and consider it completely sufficient.

Changed February 12, 2010 07:29AM UTC by Chealer comment:4

I disagree.

The problem that brought me here isn't the lack of documentation about backslashes, it's the claim that meta-characters need to be escaped with *2* backslashes. As the original reporter explained, jQuery only needs *1* backslash. Another backslash is typically used to escape the jQuery backslash when entering the selector as a JavaScript string literal, but this is just a JavaScript language requirement. Even though it is friendly to mention that for beginners, this shouldn't be done at the price of exactitude.

As for pushing down the page, this could be explained in a separate page. It might in fact be ideal to remove this paragraph and move it or refer to it from the pages about the selector forms using values that could need escaping (such as #id).

If not, the page is already 5 pages long, adding a few lines won't make much difference.

BTW, I've been wondering how "&" and "/" are meta-characters for selectors.

Changed November 22, 2010 06:29AM UTC by snover comment:5

resolution: → worksforme
status: reopenedclosed

The documentation in its current state seems abundantly clear on how this works, with the provided example resolving any ambiguity about what to do.

As far as & and / go, the issue is actually much more complicated than it is described and has to do with the CSS selectors grammar. CSS does not specify which characters are metacharacters, but rather specifies the grammar of an IDENT, which is what most things are (IDs, classes, attribute names, attribute values, etc.); this grammar is significantly more complicated, and most users do not need to understand exactly how it works, so we gloss over it and just provide the short list of characters that are not allowed to exist unescaped.