Permalink
Browse files

Checkpoint select documentation.

  • Loading branch information...
1 parent 8095516 commit c09dad72811c938defd4df60e7d05ae8ba0d3574 @mbostock mbostock committed Sep 30, 2010
Showing with 102 additions and 3 deletions.
  1. BIN button-overlay.png
  2. +81 −3 docs/select.markdown
  3. +20 −0 style.css
  4. +1 −0 syntax.css
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
@@ -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>
View
@@ -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;
+}
View
@@ -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 */

0 comments on commit c09dad7

Please sign in to comment.