Checkpoint select documentation.

d3 · Sep 30, 2010 · c09dad7 · c09dad7
1 parent 8095516
commit c09dad7
Show file tree

Hide file tree

Showing 4 changed files with 102 additions and 3 deletions.
diff --git a/button-overlay.png b/button-overlay.png
diff --git a/docs/select.markdown b/docs/select.markdown
@@ -7,11 +7,89 @@ title: 'select'
 
 ![select](select.png)
 
-Selects a descendent of each node in the current selection that matches the
-selector <i>s</i>.
+Selects the first descendant of each node in the current selection that matches
+the [selector](http://www.w3.org/TR/css3-selectors/) *s*. The first descendant
+is determined using *document order*: depth-first pre-order traversal of the DOM
+tree or subtree in question. The descendant does not need to be an immediate
+child of the context node.
+
+For example, given the following HTML:
+
+{% highlight html linenos %}
+<table>
+  <tr><td>1.</td><td>One</td></tr>
+  <tr><td>2.</td><td>Two</td></tr>
+  <tr><td>3.</td><td>Three</td></tr>
+</table>
+{% endhighlight %}
+
+<div class="highlight ex">
+  <table>
+    <tr><td>1.</td><td>One</td></tr>
+    <tr><td>2.</td><td>Two</td></tr>
+    <tr><td>3.</td><td>Three</td></tr>
+  </table>
+</div>
+
+To select all `tr` elements, then sub-select the first `td` elements, say:
+
+{% highlight js linenos %}
+d3.selectAll("tr")
+  .select("td")
+    .style("background-color", "yellow")
+    .apply();
+{% endhighlight %}
+
+<div class="highlight ex">
+  <button onclick="d3.selectAll('tr').select('td').style('background-color', 'yellow').apply()">
+    Apply
+  </button>
+  <button onclick="d3.selectAll('tr').select('td').style('background-color', null).apply()">
+    Reset
+  </button>
+</div>
+
+Note that this example could alternatively be written using the
+[:first-child](http://www.w3.org/TR/CSS2/selector.html#first-child)
+psuedo-class.
 
 ## <tt>d3.select(<i>s</i>)</tt>
 
 ![select](select-init.png)
 
-Selects a descendent of the current document that matches the selector <i>s</i>.
+Selects the first descendent of the current document that matches the
+[selector](http://www.w3.org/TR/css3-selectors/) *s*. The first descendant is
+determined using *document order*: depth-first pre-order traversal of the DOM
+tree or subtree in question. The descendant does not need to be an immediate
+child of the root element.
+
+For example, given the following HTML:
+
+{% highlight html linenos %}
+<html>
+  <body>
+    <span id="hello">...</span>
+  </body>
+</html>
+{% endhighlight %}
+
+<div class="highlight ex">
+  <span id="hello">...</span>
+</div>
+
+To select the span, say:
+
+{% highlight js linenos %}
+d3.select("#hello")
+    .text("Hello, world!")
+    .apply();
+{% endhighlight %}
+
+<div class="highlight ex">
+  <button onclick="d3.select('#hello').text('Hello, world!').apply()">
+    Apply
+  </button>
+  <button onclick="d3.select('#hello').text('...').apply()">
+    Reset
+  </button>
+</div>
diff --git a/style.css b/style.css
@@ -52,3 +52,23 @@ h2 {
   width: 790px;
   margin-right: 0px;
 }
+
+button {
+  background: #222 url(button-overlay.png) repeat-x;
+  font: 12px Helvetica Neue;
+  text-rendering: optimizeLegibility;
+  color: #fff;
+  text-shadow: 0 -1px 1px #222;
+  padding: 6px 10px 6px 10px;
+  border: 0;
+  border-bottom: 1px solid #222;
+  min-width: 80px;
+  -moz-border-radius: 5px;
+  -moz-box-shadow: 0 1px 3px #999;
+  -webkit-border-radius: 5px;
+  -webkit-box-shadow: 0 1px 3px #999;
+}
+
+button:hover {
+  background-color: #555;
+}
diff --git a/syntax.css b/syntax.css
@@ -1,4 +1,5 @@
 .highlight  { background: #eee; position: relative; margin-left: 3em; border-left: solid 1px #aaa; }
+.highlight.ex { padding: .5em; }
 .highlight .lineno { position: absolute; text-align: right; width: 2em; left: -3em; color: #ccc; }
 .highlight .c { color: #999988; font-style: italic } /* Comment */
 .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */