Recipes for using CSS Selectors with dart:html

scoped_selectors.asciidoc

Index: scoped_selectors.asciidoc
diff --git a/scoped_selectors.asciidoc b/scoped_selectors.asciidoc
new file mode 100644
index 0000000000000000000000000000000000000000..28790f3569918323fa5c18897ee34f2de64a7fc3
--- /dev/null
+++ b/scoped_selectors.asciidoc
@@ -0,0 +1,47 @@
+=== Using CSS selectors within a limited scope
+
+==== Problem
+
+You have a handle on a selected DOM element and want to search for other

[Kathy Walrath, 2013/04/29 21:17:02]

handle on -> handle to

(Now I'm getting confused about what "selected" means here. I was thinking CSS,
but then I started wondering if you meant radio button or checkbox.)

Is it necessary to use "selected" here? How about just:

You want to find elements that are contained by a particular element.

[Andrei Mouravski, 2013/04/29 21:21:44]

A handle?

[Andrei Mouravski, 2013/04/29 21:21:44]

You want to find an element that is a child of a selected DOM element. Or
something.

[shailentuli, 2013/04/30 02:59:31]

Done.

[shailentuli, 2013/04/30 02:59:31]

Using Kathy's suggestion, above.

+elements within it.
+
+==== Solution
+
+Use the `query()` and `queryAll()` functions as methods of the currently

[Kathy Walrath, 2013/04/29 21:17:02]

I found this a bit confusing and wasn't sure it was correct. How about just:

Instead of using the top-level `query()` or `queryAll()` function, use the
Element method with the same name.

[Andrei Mouravski, 2013/04/29 21:21:44]

"As methods of the..." is weird.

Call the `query` or `queryAll` methods on the selected element.

[shailentuli, 2013/04/30 02:59:31]

Done.

[shailentuli, 2013/04/30 02:59:31]

Done.

+selected element. This restricts the scope of the query to the currently

[Kathy Walrath, 2013/04/29 21:17:02]

"This" -> Using one of these methods restricts the scope of the query to the
element's descendants.

[shailentuli, 2013/04/30 02:59:31]

Done.

+selected element's descendants:
+
+--------------------------------------------------------------------------------
+currentlySelectedElement.query(cssSelector);

[Kathy Walrath, 2013/04/29 21:17:02]

currentlySelectedElement -> containerElement

(global)

[shailentuli, 2013/04/30 02:59:31]

Done.

+currentlySelectedElement.queryAll(cssSelector);
+--------------------------------------------------------------------------------
+
+==== Examples
+
+Consider the following table of user records:
+
+--------------------------------------------------------------------------------
+<table>
+  <tr><td>Jose</td><td class='status'>Accepted</td></tr>
+  <tr><td>Marie</td><td class='status'>Accepted</td></tr>
+  <tr><td>Kwame</td><td class='status'>Accepted</td></tr>
+  <tr><td>Rohan</td><td class='status'>Accepted</td></tr>
+</table>

[Andrei Mouravski, 2013/04/29 21:21:44]

Have two tables, or maybe they can be ULs and give them unique IDs or something,
and then have the second one have a group of people, one of whom is Donny.

Then, use "queryAll" on the first table/UL and do the same as you do before, but
Donny is not affected, because he's out of his element.

[shailentuli, 2013/04/30 02:59:31]

WITTIEST CL COMMENT EVER. But, no, alas, Donny will have to stay out of his
element without any help from me.  Leaving this as is.

[shailentuli, 2013/04/30 02:59:31]

Done.

+--------------------------------------------------------------------------------
+
+The following code attaches an event handler to each <tr>. When a <tr> is
+clicked, the text within the matching descendant <td> toggles:
+
+--------------------------------------------------------------------------------
+queryAll('tr').forEach((element) {

[Kathy Walrath, 2013/04/29 21:17:02]

I was initially a bit confused when I saw this because the queryAll wasn't
invoked on an element.

[shailentuli, 2013/04/30 02:59:31]

Yup, it is a bit confusing. Adding a note at the end of the recipe about the
scope of a top-level queryAll().

+  element.onClick.listen((event) {
+    var record = event.currentTarget.query('.status');
+    record.innerHtml = record.innerHtml == 'Accepted' ? 'Declined' : 'Accepted';
+  });
+});
+--------------------------------------------------------------------------------
+
+Because of the scoped query, non-descendant <td>s with the '.status' class are

[Kathy Walrath, 2013/04/29 21:17:02]

Could be clearer. How about:

Because the query() method is invoked on the just-clicked row, status cells in
other rows are ignored.

(I can't think of a good way to get rid of the passive voice. It might be
appropriate here.)

[Andrei Mouravski, 2013/04/29 21:21:44]

"Because the query is scoped to whatever, ..."

[shailentuli, 2013/04/30 02:59:31]

Done.

[shailentuli, 2013/04/30 02:59:31]

Done.

+not affected.
+
+