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..90fdcdf9c1632776c182d2c28e1a107e744d1631
--- /dev/null
+++ b/scoped_selectors.asciidoc
@@ -0,0 +1,47 @@
+=== Using CSS selectors within a limited scope
+
+==== Problem
+
+You want to find elements that are contained by a particular element.
+
+==== Solution
+
+Call the `query()` or `queryAll()` methods on a DOM element. Invoking one of
+these methods on an element restricts the scope of the query to that
+element's descendants:
+
+--------------------------------------------------------------------------------
+containerElement.query(cssSelector);
+containerElement.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>
+--------------------------------------------------------------------------------
+
+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) {
+  element.onClick.listen((event) {
+    var record = event.currentTarget.query('.status');
+    record.innerHtml = record.innerHtml == 'Accepted' ? 'Declined' : 'Accepted';
+  });
+});
+--------------------------------------------------------------------------------
+
+Because the query is scoped to the just-clicked row, cells with the 'status'
+class in other rows are not affected.
+
+Note the use of `queryAll()` as a top-level function in the code above. Used
+in this manner, `queryAll()` is scoped to the entire document.