Created
November 16, 2019 07:13
-
-
Save EmbraceLife/0370573fd65a636bb7536b3bd89eb4b7 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="utf-8"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| <title>d3-selection</title> | |
| <link rel="stylesheet" href="https://stackedit.io/style.css" /> | |
| </head> | |
| <body class="stackedit"> | |
| <div class="stackedit__left"> | |
| <div class="stackedit__toc"> | |
| <ul> | |
| <li><a href="#d3-selection">d3-selection</a> | |
| <ul> | |
| <li><a href="#installing">Installing</a></li> | |
| <li><a href="#api-reference">API Reference</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div class="stackedit__right"> | |
| <div class="stackedit__html"> | |
| <h1 id="d3-selection">d3-selection</h1> | |
| <p>Selections allow powerful data-driven transformation of the document object model (DOM): set <a href="#selection_attr">attributes</a>, <a href="#selection_style">styles</a>, <a href="#selection_property">properties</a>, <a href="#selection_html">HTML</a> or <a href="#selection_text">text</a> content, and more. Using the <a href="#joining-data">data join</a>’s <a href="#selection_enter">enter</a> and <a href="#selection_enter">exit</a> selections, you can also <a href="#selection_append">add</a> or <a href="#selection_remove">remove</a> elements to correspond to data.</p> | |
| <p>Selection methods typically return the current selection, or a new selection, allowing the concise application of multiple operations on a given selection via method chaining. For example, to set the class and color style of all paragraph elements in the current document:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"class"</span><span class="token punctuation">,</span> <span class="token string">"graf"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"color"</span><span class="token punctuation">,</span> <span class="token string">"red"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> p <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| p<span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"class"</span><span class="token punctuation">,</span> <span class="token string">"graf"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| p<span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"color"</span><span class="token punctuation">,</span> <span class="token string">"red"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>By convention, selection methods that return the current selection use <em>four</em> spaces of indent, while methods that return a new selection use only <em>two</em>. This helps reveal changes of context by making them stick out of the chain:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"body"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"svg"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"width"</span><span class="token punctuation">,</span> <span class="token number">960</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"height"</span><span class="token punctuation">,</span> <span class="token number">500</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"g"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"transform"</span><span class="token punctuation">,</span> <span class="token string">"translate(20,20)"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"rect"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"width"</span><span class="token punctuation">,</span> <span class="token number">920</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"height"</span><span class="token punctuation">,</span> <span class="token number">460</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Selections are immutable. All selection methods that affect which elements are selected (or their order) return a new selection rather than modifying the current selection. However, note that elements are necessarily mutable, as selections drive transformations of the document!</p> | |
| <h2 id="installing">Installing</h2> | |
| <p>If you use NPM, <code>npm install d3-selection</code>. Otherwise, download the <a href="https://github.com/d3/d3-selection/releases/latest">latest release</a>. You can also load directly from <a href="https://d3js.org">d3js.org</a>, either as a <a href="https://d3js.org/d3-selection.v1.min.js">standalone library</a> or as part of <a href="https://github.com/d3/d3">D3 4.0</a>. AMD, CommonJS, and vanilla environments are supported. In vanilla, a <code>d3</code> global is exported:</p> | |
| <pre class=" language-html"><code class="prism language-html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>script</span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>https://d3js.org/d3-selection.v1.min.js<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token script language-javascript"></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>script</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>script</span><span class="token punctuation">></span></span><span class="token script language-javascript"> | |
| <span class="token keyword">var</span> div <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>script</span><span class="token punctuation">></span></span> | |
| </code></pre> | |
| <p><a href="https://tonicdev.com/npm/d3-selection">Try d3-selection in your browser.</a></p> | |
| <h2 id="api-reference">API Reference</h2> | |
| <ul> | |
| <li><a href="#selecting-elements">Selecting Elements</a></li> | |
| <li><a href="#modifying-elements">Modifying Elements</a></li> | |
| <li><a href="#joining-data">Joining Data</a></li> | |
| <li><a href="#handling-events">Handling Events</a></li> | |
| <li><a href="#control-flow">Control Flow</a></li> | |
| <li><a href="#local-variables">Local Variables</a></li> | |
| <li><a href="#namespaces">Namespaces</a></li> | |
| </ul> | |
| <h3 id="selecting-elements">Selecting Elements</h3> | |
| <p>Selection methods accept <a href="http://www.w3.org/TR/selectors-api/">W3C selector strings</a> such as <code>.fancy</code> to select elements with the class <em>fancy</em>, or <code>div</code> to select DIV elements. Selection methods come in two forms: select and selectAll: the former selects only the first matching element, while the latter selects all matching elements in document order. The top-level selection methods, <a href="#select">d3.select</a> and <a href="#selectAll">d3.selectAll</a>, query the entire document; the subselection methods, <a href="#selection_select"><em>selection</em>.select</a> and <a href="#selection_selectAll"><em>selection</em>.selectAll</a>, restrict selection to descendants of the selected elements.</p> | |
| <p><a href="#selection">#</a> d3.<b>selection</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/index.js#L38" title="Source"><></a></p> | |
| <p><a href="#select">Selects</a> the root element, <code>document.documentElement</code>. This function can also be used to test for selections (<code>instanceof d3.selection</code>) or to extend the selection prototype. For example, to add a method to check checkboxes:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span>selection<span class="token punctuation">.</span>prototype<span class="token punctuation">.</span><span class="token function-variable function">checked</span> <span class="token operator">=</span> <span class="token keyword">function</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> arguments<span class="token punctuation">.</span>length <span class="token operator"><</span> <span class="token number">1</span> | |
| <span class="token operator">?</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">property</span><span class="token punctuation">(</span><span class="token string">"checked"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">:</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">property</span><span class="token punctuation">(</span><span class="token string">"checked"</span><span class="token punctuation">,</span> <span class="token operator">!</span><span class="token operator">!</span>value<span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>And then to use:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"input[type=checkbox]"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">checked</span><span class="token punctuation">(</span><span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#select">#</a> d3.<b>select</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/select.js#L3" title="Source"><></a></p> | |
| <p>Selects the first element that matches the specified <em>selector</em> string. If no elements match the <em>selector</em>, returns an empty selection. If multiple elements match the <em>selector</em>, only the first matching element (in document order) will be selected. For example, to select the first anchor element:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> anchor <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"a"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the <em>selector</em> is not a string, instead selects the specified node; this is useful if you already have a reference to a node, such as <code>this</code> within an event listener or a global such as <code>document.body</code>. For example, to make a clicked paragraph red:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> <span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"color"</span><span class="token punctuation">,</span> <span class="token string">"red"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#selectAll">#</a> d3.<b>selectAll</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selectAll.js#L3" title="Source"><></a></p> | |
| <p>Selects all elements that match the specified <em>selector</em> string. The elements will be selected in document order (top-to-bottom). If no elements in the document match the <em>selector</em>, or if the <em>selector</em> is null or undefined, returns an empty selection. For example, to select all paragraphs:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> paragraph <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the <em>selector</em> is not a string, instead selects the specified array of nodes; this is useful if you already have a reference to nodes, such as <code>this.childNodes</code> within an event listener or a global such as <code>document.links</code>. The nodes may instead be a pseudo-array such as a <code>NodeList</code> or <code>arguments</code>. For example, to color all links red:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span>document<span class="token punctuation">.</span>links<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"color"</span><span class="token punctuation">,</span> <span class="token string">"red"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#selection_select">#</a> <i>selection</i>.<b>select</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/select.js" title="Source"><></a></p> | |
| <p>For each selected element, selects the first descendant element that matches the specified <em>selector</em> string. If no element matches the specified selector for the current element, the element at the current index will be null in the returned selection. (If the <em>selector</em> is null, every element in the returned selection will be null, resulting in an empty selection.) If the current element has associated data, this data is propagated to the corresponding selected element. If multiple elements match the selector, only the first matching element in document order is selected. For example, to select the first bold element in every paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> b <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"b"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the <em>selector</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). It must return an element, or null if there is no matching element. For example, to select the previous sibling of each paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> previous <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span>previousElementSibling<span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Unlike <a href="#selection_selectAll"><em>selection</em>.selectAll</a>, <em>selection</em>.select does not affect grouping: it preserves the existing group structure and indexes, and propagates data (if any) to selected children. Grouping plays an important role in the <a href="#joining-data">data join</a>. See <a href="http://bost.ocks.org/mike/nest/">Nested Selections</a> and <a href="http://bost.ocks.org/mike/selection/">How Selections Work</a> for more on this topic.</p> | |
| <p><a href="#selection_selectAll">#</a> <i>selection</i>.<b>selectAll</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/selectAll.js" title="Source"><></a></p> | |
| <p>For each selected element, selects the descendant elements that match the specified <em>selector</em> string. The elements in the returned selection are grouped by their corresponding parent node in this selection. If no element matches the specified selector for the current element, or if the <em>selector</em> is null, the group at the current index will be empty. The selected elements do not inherit data from this selection; use <a href="#selection_data"><em>selection</em>.data</a> to propagate data to children. For example, to select the bold elements in every paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> b <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"b"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the <em>selector</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). It must return an array of elements (or a pseudo-array, such as a NodeList), or the empty array if there are no matching elements. For example, to select the previous and next siblings of each paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> sibling <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> <span class="token punctuation">[</span> | |
| <span class="token keyword">this</span><span class="token punctuation">.</span>previousElementSibling<span class="token punctuation">,</span> | |
| <span class="token keyword">this</span><span class="token punctuation">.</span>nextElementSibling | |
| <span class="token punctuation">]</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Unlike <a href="#selection_select"><em>selection</em>.select</a>, <em>selection</em>.selectAll does affect grouping: each selected descendant is grouped by the parent element in the originating selection. Grouping plays an important role in the <a href="#joining-data">data join</a>. See <a href="http://bost.ocks.org/mike/nest/">Nested Selections</a> and <a href="http://bost.ocks.org/mike/selection/">How Selections Work</a> for more on this topic.</p> | |
| <p><a href="#selection_filter">#</a> <i>selection</i>.<b>filter</b>(<i>filter</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/filter.js" title="Source"><></a></p> | |
| <p>Filters the selection, returning a new selection that contains only the elements for which the specified <em>filter</em> is true. The <em>filter</em> may be specified either as a selector string or a function. If the <em>filter</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]).</p> | |
| <p>For example, to filter a selection of table rows to contain only even rows:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> even <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"tr"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">filter</span><span class="token punctuation">(</span><span class="token string">":nth-child(even)"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This is approximately equivalent to using <a href="#selectAll">d3.selectAll</a> directly, although the indexes may be different:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> even <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"tr:nth-child(even)"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Similarly, using a function:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> even <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"tr"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">filter</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">,</span> i<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> i <span class="token operator">&</span> <span class="token number">1</span><span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Or using <a href="#selection_select"><em>selection</em>.select</a>:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> even <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"tr"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">,</span> i<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> i <span class="token operator">&</span> <span class="token number">1</span> <span class="token operator">?</span> <span class="token keyword">this</span> <span class="token punctuation">:</span> <span class="token keyword">null</span><span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Note that the <code>:nth-child</code> pseudo-class is a one-based index rather than a zero-based index. Also, the above filter functions do not have precisely the same meaning as <code>:nth-child</code>; they rely on the selection index rather than the number of preceding sibling elements in the DOM.</p> | |
| <p>The returned filtered selection preserves the parents of this selection, but like <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter"><em>array</em>.filter</a>, it does not preserve indexes as some elements may be removed; use <a href="#selection_select"><em>selection</em>.select</a> to preserve the index, if needed.</p> | |
| <p><a href="#selection_merge">#</a> <i>selection</i>.<b>merge</b>(<i>other</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/merge.js" title="Source"><></a></p> | |
| <p>Returns a new selection merging this selection with the specified <em>other</em> selection. The returned selection has the same number of groups and the same parents as this selection. Any missing (null) elements in this selection are filled with the corresponding element, if present (not null), from the specified <em>selection</em>. (If the <em>other</em> selection has additional groups or parents, they are ignored.)</p> | |
| <p>This method is used internally by <a href="#selection_join"><em>selection</em>.join</a> to merge the <a href="#selection_enter">enter</a> and <a href="#selection_data">update</a> selections after <a href="#joining-data">binding data</a>. You can also merge explicitly. For example:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> circle <span class="token operator">=</span> svg<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span>data<span class="token punctuation">)</span> <span class="token comment">// UPDATE</span> | |
| <span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"blue"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| circle<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">remove</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// EXIT</span> | |
| circle <span class="token operator">=</span> circle<span class="token punctuation">.</span><span class="token function">enter</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span> <span class="token comment">// ENTER</span> | |
| <span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"green"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">merge</span><span class="token punctuation">(</span>circle<span class="token punctuation">)</span> <span class="token comment">// ENTER + UPDATE</span> | |
| <span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"stroke"</span><span class="token punctuation">,</span> <span class="token string">"black"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>See <a href="#selection_data"><em>selection</em>.data</a> for more.</p> | |
| <p>This method is not intended for concatenating arbitrary selections, however: if both this selection and the specified <em>other</em> selection have (non-null) elements at the same index, this selection’s element is returned in the merge and the <em>other</em> selection’s element is ignored.</p> | |
| <p><a href="#matcher">#</a> d3.<b>matcher</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/matcher.js" title="Source"><></a></p> | |
| <p>Given the specified <em>selector</em>, returns a function which returns true if <code>this</code> element <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/matches">matches</a> the specified selector. This method is used internally by <a href="#selection_filter"><em>selection</em>.filter</a>. For example, this:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">filter</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">filter</span><span class="token punctuation">(</span>d3<span class="token punctuation">.</span><span class="token function">matcher</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>(Although D3 is not a compatibility layer, this implementation does support vendor-prefixed implementations due to the recent standardization of <em>element</em>.matches.)</p> | |
| <p><a href="#selector">#</a> d3.<b>selector</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selector.js" title="Source"><></a></p> | |
| <p>Given the specified <em>selector</em>, returns a function which returns the first descendant of <code>this</code> element that matches the specified selector. This method is used internally by <a href="#selection_select"><em>selection</em>.select</a>. For example, this:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span>d3<span class="token punctuation">.</span><span class="token function">selector</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#selectorAll">#</a> d3.<b>selectorAll</b>(<i>selector</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selectAll.js" title="Source"><></a></p> | |
| <p>Given the specified <em>selector</em>, returns a function which returns all descendants of <code>this</code> element that match the specified selector. This method is used internally by <a href="#selection_selectAll"><em>selection</em>.selectAll</a>. For example, this:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> selection<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span>d3<span class="token punctuation">.</span><span class="token function">selectorAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#window">#</a> d3.<b>window</b>(<i>node</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/window.js" title="Source"><></a></p> | |
| <p>Returns the owner window for the specified <em>node</em>. If <em>node</em> is a node, returns the owner document’s default view; if <em>node</em> is a document, returns its default view; otherwise returns the <em>node</em>.</p> | |
| <p><a href="#style">#</a> d3.<b>style</b>(<i>node</i>, <i>name</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/style.js#L32" title="Source"><></a></p> | |
| <p>Returns the value of the style property with the specified <em>name</em> for the specified <em>node</em>. If the <em>node</em> has an inline style with the specified <em>name</em>, its value is returned; otherwise, the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/computed_value">computed property value</a> is returned. See also <a href="#selection_style"><em>selection</em>.style</a>.</p> | |
| <h3 id="modifying-elements">Modifying Elements</h3> | |
| <p>After selecting elements, use the selection’s transformation methods to affect document content. For example, to set the name attribute and color style of an anchor element:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"a"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"name"</span><span class="token punctuation">,</span> <span class="token string">"fred"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">style</span><span class="token punctuation">(</span><span class="token string">"color"</span><span class="token punctuation">,</span> <span class="token string">"red"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>To experiment with selections, visit <a href="https://d3js.org">d3js.org</a> and open your browser’s developer console! (In Chrome, open the console with ⌥⌘J.) Select elements and then inspect the returned selection to see which elements are selected and how they are grouped. Call selection methods and see how the page content changes.</p> | |
| <p><a href="#selection_attr">#</a> <i>selection</i>.<b>attr</b>(<i>name</i>[, <i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/attr.js" title="Source"><></a></p> | |
| <p>If a <em>value</em> is specified, sets the attribute with the specified <em>name</em> to the specified value on the selected elements and returns this selection. If the <em>value</em> is a constant, all elements are given the same attribute value; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to set each element’s attribute. A null value will remove the specified attribute.</p> | |
| <p>If a <em>value</em> is not specified, returns the current value of the specified attribute for the first (non-null) element in the selection. This is generally useful only if you know that the selection contains exactly one element.</p> | |
| <p>The specified <em>name</em> may have a namespace prefix, such as <code>xlink:href</code> to specify the <code>href</code> attribute in the XLink namespace. See <a href="#namespaces">namespaces</a> for the map of supported namespaces; additional namespaces can be registered by adding to the map.</p> | |
| <p><a href="#selection_classed">#</a> <i>selection</i>.<b>classed</b>(<i>names</i>[, <i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/classed.js" title="Source"><></a></p> | |
| <p>If a <em>value</em> is specified, assigns or unassigns the specified CSS class <em>names</em> on the selected elements by setting the <code>class</code> attribute or modifying the <code>classList</code> property and returns this selection. The specified <em>names</em> is a string of space-separated class names. For example, to assign the classes <code>foo</code> and <code>bar</code> to the selected elements:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">classed</span><span class="token punctuation">(</span><span class="token string">"foo bar"</span><span class="token punctuation">,</span> <span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the <em>value</em> is truthy, then all elements are assigned the specified classes; otherwise, the classes are unassigned. If the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to assign or unassign classes on each element. For example, to randomly associate the class <em>foo</em> with on average half the selected elements:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">classed</span><span class="token punctuation">(</span><span class="token string">"foo"</span><span class="token punctuation">,</span> <span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> Math<span class="token punctuation">.</span><span class="token function">random</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">></span> <span class="token number">0.5</span><span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If a <em>value</em> is not specified, returns true if and only if the first (non-null) selected element has the specified <em>classes</em>. This is generally useful only if you know the selection contains exactly one element.</p> | |
| <p><a href="#selection_style">#</a> <i>selection</i>.<b>style</b>(<i>name</i>[, <i>value</i>[, <i>priority</i>]]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/style.js" title="Source"><></a></p> | |
| <p>If a <em>value</em> is specified, sets the style property with the specified <em>name</em> to the specified value on the selected elements and returns this selection. If the <em>value</em> is a constant, then all elements are given the same style property value; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to set each element’s style property. A null value will remove the style property. An optional <em>priority</em> may also be specified, either as null or the string <code>important</code> (without the exclamation point).</p> | |
| <p>If a <em>value</em> is not specified, returns the current value of the specified style property for the first (non-null) element in the selection. The current value is defined as the element’s inline value, if present, and otherwise its <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/computed_value">computed value</a>. Accessing the current style value is generally useful only if you know the selection contains exactly one element.</p> | |
| <p>Caution: unlike many SVG attributes, CSS styles typically have associated units. For example, <code>3px</code> is a valid stroke-width property value, while <code>3</code> is not. Some browsers implicitly assign the <code>px</code> (pixel) unit to numeric values, but not all browsers do: IE, for example, throws an “invalid arguments” error!</p> | |
| <p><a href="#selection_property">#</a> <i>selection</i>.<b>property</b>(<i>name</i>[, <i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/property.js" title="Source"><></a></p> | |
| <p>Some HTML elements have special properties that are not addressable using attributes or styles, such as a form field’s text <code>value</code> and a checkbox’s <code>checked</code> boolean. Use this method to get or set these properties.</p> | |
| <p>If a <em>value</em> is specified, sets the property with the specified <em>name</em> to the specified value on selected elements. If the <em>value</em> is a constant, then all elements are given the same property value; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to set each element’s property. A null value will delete the specified property.</p> | |
| <p>If a <em>value</em> is not specified, returns the value of the specified property for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.</p> | |
| <p><a href="#selection_text">#</a> <i>selection</i>.<b>text</b>([<i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/text.js" title="Source"><></a></p> | |
| <p>If a <em>value</em> is specified, sets the <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Node3-textContent">text content</a> to the specified value on all selected elements, replacing any existing child elements. If the <em>value</em> is a constant, then all elements are given the same text content; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to set each element’s text content. A null value will clear the content.</p> | |
| <p>If a <em>value</em> is not specified, returns the text content for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.</p> | |
| <p><a href="#selection_html">#</a> <i>selection</i>.<b>html</b>([<i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/html.js" title="Source"><></a></p> | |
| <p>If a <em>value</em> is specified, sets the <a href="http://dev.w3.org/html5/spec-LC/apis-in-html-documents.html#innerhtml">inner HTML</a> to the specified value on all selected elements, replacing any existing child elements. If the <em>value</em> is a constant, then all elements are given the same inner HTML; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function’s return value is then used to set each element’s inner HTML. A null value will clear the content.</p> | |
| <p>If a <em>value</em> is not specified, returns the inner HTML for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.</p> | |
| <p>Use <a href="#selection_append"><em>selection</em>.append</a> or <a href="#selection_insert"><em>selection</em>.insert</a> instead to create data-driven content; this method is intended for when you want a little bit of HTML, say for rich formatting. Also, <em>selection</em>.html is only supported on HTML elements. SVG elements and other non-HTML elements do not support the innerHTML property, and thus are incompatible with <em>selection</em>.html. Consider using <a href="https://developer.mozilla.org/en-US/docs/XMLSerializer">XMLSerializer</a> to convert a DOM subtree to text. See also the <a href="https://code.google.com/p/innersvg/">innersvg polyfill</a>, which provides a shim to support the innerHTML property on SVG elements.</p> | |
| <p><a href="#selection_append">#</a> <i>selection</i>.<b>append</b>(<i>type</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/append.js" title="Source"><></a></p> | |
| <p>If the specified <em>type</em> is a string, appends a new element of this type (tag name) as the last child of each selected element, or before the next following sibling in the update selection if this is an <a href="#selection_enter">enter selection</a>. The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data; however, note that <a href="#selection_order"><em>selection</em>.order</a> may still be required if updating elements change order (<em>i.e.</em>, if the order of new data is inconsistent with old data).</p> | |
| <p>If the specified <em>type</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). This function should return an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) For example, to append a DIV element to each paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Which is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as <a href="#selection_select"><em>selection</em>.select</a>.</p> | |
| <p>The specified <em>name</em> may have a namespace prefix, such as <code>svg:text</code> to specify a <code>text</code> attribute in the SVG namespace. See <a href="#namespaces">namespaces</a> for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, <code>svg</code> implies <code>svg:svg</code>).</p> | |
| <p><a href="#selection_insert">#</a> <i>selection</i>.<b>insert</b>(<i>type</i>[, <i>before</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/insert.js" title="Source"><></a></p> | |
| <p>If the specified <em>type</em> is a string, inserts a new element of this type (tag name) before the first element matching the specified <em>before</em> selector for each selected element. For example, a <em>before</em> selector <code>:first-child</code> will prepend nodes before the first child. If <em>before</em> is not specified, it defaults to null. (To append elements in an order consistent with <a href="#joining-data">bound data</a>, use <a href="#selection_append"><em>selection</em>.append</a>.)</p> | |
| <p>Both <em>type</em> and <em>before</em> may instead be specified as functions which are evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The <em>type</em> function should return an element to be inserted; the <em>before</em> function should return the child element before which the element should be inserted. For example, to append a DIV element to each paragraph:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">insert</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">insert</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Which is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"p"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">insertBefore</span><span class="token punctuation">(</span>document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token keyword">null</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as <a href="#selection_select"><em>selection</em>.select</a>.</p> | |
| <p>The specified <em>name</em> may have a namespace prefix, such as <code>svg:text</code> to specify a <code>text</code> attribute in the SVG namespace. See <a href="#namespaces">namespaces</a> for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, <code>svg</code> implies <code>svg:svg</code>).</p> | |
| <p><a href="#selection_remove">#</a> <i>selection</i>.<b>remove</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/remove.js" title="Source"><></a></p> | |
| <p>Removes the selected elements from the document. Returns this selection (the removed elements) which are now detached from the DOM. There is not currently a dedicated API to add removed elements back to the document; however, you can pass a function to <a href="#selection_append"><em>selection</em>.append</a> or <a href="#selection_insert"><em>selection</em>.insert</a> to re-add elements.</p> | |
| <p><a href="#selection_clone">#</a> <i>selection</i>.<b>clone</b>([<i>deep</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/clone.js" title="Source"><></a></p> | |
| <p>Inserts clones of the selected elements immediately following the selected elements and returns a selection of the newly added clones. If <em>deep</em> is truthy, the descendant nodes of the selected elements will be cloned as well. Otherwise, only the elements themselves will be cloned. Equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span>parentNode<span class="token punctuation">.</span><span class="token function">insertBefore</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">cloneNode</span><span class="token punctuation">(</span>deep<span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token keyword">this</span><span class="token punctuation">.</span>nextSibling<span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#selection_sort">#</a> <i>selection</i>.<b>sort</b>(<i>compare</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/sort.js" title="Source"><></a></p> | |
| <p>Returns a new selection that contains a copy of each group in this selection sorted according to the <em>compare</em> function. After sorting, re-inserts elements to match the resulting order (per <a href="#selection_order"><em>selection</em>.order</a>).</p> | |
| <p>The compare function, which defaults to <a href="https://github.com/d3/d3-array#ascending">ascending</a>, is passed two elements’ data <em>a</em> and <em>b</em> to compare. It should return either a negative, positive, or zero value. If negative, then <em>a</em> should be before <em>b</em>; if positive, then <em>a</em> should be after <em>b</em>; otherwise, <em>a</em> and <em>b</em> are considered equal and the order is arbitrary.</p> | |
| <p>Note that sorting is not guaranteed to be stable; however, it is guaranteed to have the same behavior as your browser’s built-in <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a> method on arrays.</p> | |
| <p><a href="#selection_order">#</a> <i>selection</i>.<b>order</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/order.js" title="Source"><></a></p> | |
| <p>Re-inserts elements into the document such that the document order of each group matches the selection order. This is equivalent to calling <a href="#selection_sort"><em>selection</em>.sort</a> if the data is already sorted, but much faster.</p> | |
| <p><a href="#selection_raise">#</a> <i>selection</i>.<b>raise</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/raise.js" title="Source"><></a></p> | |
| <p>Re-inserts each selected element, in order, as the last child of its parent. Equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">each</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">this</span><span class="token punctuation">.</span>parentNode<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#selection_lower">#</a> <i>selection</i>.<b>lower</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/lower.js" title="Source"><></a></p> | |
| <p>Re-inserts each selected element, in order, as the first child of its parent. Equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">each</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| <span class="token keyword">this</span><span class="token punctuation">.</span>parentNode<span class="token punctuation">.</span><span class="token function">insertBefore</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">,</span> <span class="token keyword">this</span><span class="token punctuation">.</span>parentNode<span class="token punctuation">.</span>firstChild<span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#create">#</a> d3.<b>create</b>(<i>name</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/create.js" title="Source"><></a></p> | |
| <p>Given the specified element <em>name</em>, returns a single-element selection containing a detached element of the given name in the current document.</p> | |
| <p><a href="#creator">#</a> d3.<b>creator</b>(<i>name</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/creator.js" title="Source"><></a></p> | |
| <p>Given the specified element <em>name</em>, returns a function which creates an element of the given name, assuming that <code>this</code> is the parent element. This method is used internally by <a href="#selection_append"><em>selection</em>.append</a> and <a href="#selection_insert"><em>selection</em>.insert</a> to create new elements. For example, this:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Is equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span>d3<span class="token punctuation">.</span><span class="token function">creator</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>See <a href="#namespace">namespace</a> for details on supported namespace prefixes, such as for SVG elements.</p> | |
| <h3 id="joining-data">Joining Data</h3> | |
| <p>For an introduction to D3’s data joins, see <a href="http://bost.ocks.org/mike/join/">Thinking With Joins</a>. Also see the <a href="http://bl.ocks.org/mbostock/3808218">General Update Pattern</a> examples.</p> | |
| <p><a href="#selection_data">#</a> <i>selection</i>.<b>data</b>([<i>data</i>[, <i>key</i>]]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/data.js" title="Source"><></a></p> | |
| <p>Binds the specified array of <em>data</em> with the selected elements, returning a new selection that represents the <em>update</em> selection: the elements successfully bound to data. Also defines the <a href="#selection_enter">enter</a> and <a href="#selection_exit">exit</a> selections on the returned selection, which can be used to add or remove elements to correspond to the new data. The specified <em>data</em> is an array of arbitrary values (<em>e.g.</em>, numbers or objects), or a function that returns an array of values for each group. When data is assigned to an element, it is stored in the property <code>__data__</code>, thus making the data “sticky” and available on re-selection.</p> | |
| <p>The <em>data</em> is specified <strong>for each group</strong> in the selection. If the selection has multiple groups (such as <a href="#selectAll">d3.selectAll</a> followed by <a href="#selection_selectAll"><em>selection</em>.selectAll</a>), then <em>data</em> should typically be specified as a function. This function will be evaluated for each group in order, being passed the group’s parent datum (<em>d</em>, which may be undefined), the group index (<em>i</em>), and the selection’s parent nodes (<em>nodes</em>), with <em>this</em> as the group’s parent element.</p> | |
| <p>In conjunction with <a href="#selection_join"><em>selection</em>.join</a> (or more explicitly with <a href="#selection_enter"><em>selection</em>.enter</a>, <a href="#selection_exit"><em>selection</em>.exit</a>, <a href="#selection_append"><em>selection</em>.append</a> and <a href="#selection_remove"><em>selection</em>.remove</a>), <em>selection</em>.data can be used to enter, update and exit elements to match data. For example, to create an HTML table from a matrix of numbers:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> matrix <span class="token operator">=</span> <span class="token punctuation">[</span> | |
| <span class="token punctuation">[</span><span class="token number">11975</span><span class="token punctuation">,</span> <span class="token number">5871</span><span class="token punctuation">,</span> <span class="token number">8916</span><span class="token punctuation">,</span> <span class="token number">2868</span><span class="token punctuation">]</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">[</span> <span class="token number">1951</span><span class="token punctuation">,</span> <span class="token number">10048</span><span class="token punctuation">,</span> <span class="token number">2060</span><span class="token punctuation">,</span> <span class="token number">6171</span><span class="token punctuation">]</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">[</span> <span class="token number">8010</span><span class="token punctuation">,</span> <span class="token number">16145</span><span class="token punctuation">,</span> <span class="token number">8090</span><span class="token punctuation">,</span> <span class="token number">8045</span><span class="token punctuation">]</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">[</span> <span class="token number">1013</span><span class="token punctuation">,</span> <span class="token number">990</span><span class="token punctuation">,</span> <span class="token number">940</span><span class="token punctuation">,</span> <span class="token number">6907</span><span class="token punctuation">]</span> | |
| <span class="token punctuation">]</span><span class="token punctuation">;</span> | |
| <span class="token keyword">var</span> tr <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"body"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"table"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"tr"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span>matrix<span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">join</span><span class="token punctuation">(</span><span class="token string">"tr"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token keyword">var</span> td <span class="token operator">=</span> tr<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"td"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">join</span><span class="token punctuation">(</span><span class="token string">"td"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">text</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>In this example the <em>data</em> function is the identity function: for each table row, it returns the corresponding row from the data matrix.</p> | |
| <p>If a <em>key</em> function is not specified, then the first datum in <em>data</em> is assigned to the first selected element, the second datum to the second selected element, and so on. A <em>key</em> function may be specified to control which datum is assigned to which element, replacing the default join-by-index, by computing a string identifier for each datum and element. This key function is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]); the returned string is the element’s key. The key function is then also evaluated for each new datum in <em>data</em>, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the group’s new <em>data</em>, with <em>this</em> as the group’s parent DOM element; the returned string is the datum’s key. The datum for a given key is assigned to the element with the matching key. If multiple elements have the same key, the duplicate elements are put into the exit selection; if multiple data have the same key, the duplicate data are put into the enter selection.</p> | |
| <p>For example, given this document:</p> | |
| <pre class=" language-html"><code class="prism language-html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Ford<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Jarrah<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Kwon<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Locke<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Reyes<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Shephard<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| </code></pre> | |
| <p>You could join data by key as follows:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> data <span class="token operator">=</span> <span class="token punctuation">[</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Locke"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">4</span><span class="token punctuation">}</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Reyes"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">8</span><span class="token punctuation">}</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Ford"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">15</span><span class="token punctuation">}</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Jarrah"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">16</span><span class="token punctuation">}</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Shephard"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">23</span><span class="token punctuation">}</span><span class="token punctuation">,</span> | |
| <span class="token punctuation">{</span>name<span class="token punctuation">:</span> <span class="token string">"Kwon"</span><span class="token punctuation">,</span> number<span class="token punctuation">:</span> <span class="token number">42</span><span class="token punctuation">}</span> | |
| <span class="token punctuation">]</span><span class="token punctuation">;</span> | |
| d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span>data<span class="token punctuation">,</span> <span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d <span class="token operator">?</span> d<span class="token punctuation">.</span>name <span class="token punctuation">:</span> <span class="token keyword">this</span><span class="token punctuation">.</span>id<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">text</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">.</span>number<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This example key function uses the datum <em>d</em> if present, and otherwise falls back to the element’s id property. Since these elements were not previously bound to data, the datum <em>d</em> is null when the key function is evaluated on selected elements, and non-null when the key function is evaluated on the new data.</p> | |
| <p>The <em>update</em> and <em>enter</em> selections are returned in data order, while the <em>exit</em> selection preserves the selection order prior to the join. If a key function is specified, the order of elements in the selection may not match their order in the document; use <a href="#order"><em>selection</em>.order</a> or <a href="#sort"><em>selection</em>.sort</a> as needed. For more on how the key function affects the join, see <a href="http://bost.ocks.org/mike/bar/2/">A Bar Chart, Part 2</a> and <a href="http://bost.ocks.org/mike/constancy/">Object Constancy</a>.</p> | |
| <p>If <em>data</em> is not specified, this method returns the array of data for the selected elements.</p> | |
| <p>This method cannot be used to clear bound data; use <a href="#selection_datum"><em>selection</em>.datum</a> instead.</p> | |
| <p><a href="#selection_join">#</a> <i>selection</i>.<b>join</b>(<i>enter</i>[, <i>update</i>][, <i>exit</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/join.js" title="Source"><></a></p> | |
| <p>Appends, removes and reorders elements as necessary to match the data that was previously bound by <a href="#selection_data"><em>selection</em>.data</a>, returning the <a href="#selection_merge">merged</a> enter and update selection. This method is a convenient alternative to the more explicit <a href="#selection_enter"><em>selection</em>.enter</a>, <a href="#selection_exit"><em>selection</em>.exit</a>, <a href="#selection_append"><em>selection</em>.append</a> and <a href="#selection_remove"><em>selection</em>.remove</a>). For example:</p> | |
| <pre class=" language-js"><code class="prism language-js">svg<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span>data<span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">join</span><span class="token punctuation">(</span> | |
| enter <span class="token operator">=></span> enter<span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"green"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> | |
| update <span class="token operator">=></span> update<span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"blue"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"stroke"</span><span class="token punctuation">,</span> <span class="token string">"black"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>See the <a href="https://beta.observablehq.com/d/6c522dda5dd9daa3"><em>selection</em>.join Observable notebook</a> for more examples.</p> | |
| <p>This is equivalent to the <a href="http://bl.ocks.org/mbostock/3808218">General Update Pattern</a>:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> circle <span class="token operator">=</span> svg<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span> <span class="token comment">// 1</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span>data<span class="token punctuation">)</span> <span class="token comment">// 2</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"blue"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 3</span> | |
| circle<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">remove</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 4</span> | |
| circle <span class="token operator">=</span> circle<span class="token punctuation">.</span><span class="token function">enter</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"circle"</span><span class="token punctuation">)</span> <span class="token comment">// 5, 9</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"fill"</span><span class="token punctuation">,</span> <span class="token string">"green"</span><span class="token punctuation">)</span> <span class="token comment">// 6</span> | |
| <span class="token punctuation">.</span><span class="token function">merge</span><span class="token punctuation">(</span>circle<span class="token punctuation">)</span> <span class="token comment">// 7</span> | |
| <span class="token punctuation">.</span><span class="token function">order</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment">// 8</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"stroke"</span><span class="token punctuation">,</span> <span class="token string">"black"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 9</span> | |
| </code></pre> | |
| <p>Breaking this down into discrete steps:</p> | |
| <ol> | |
| <li>Any existing circles (that are descendants of the <code>svg</code> selection) are <a href="#selection_selectAll">selected</a>.</li> | |
| <li>These circles are <a href="#selection_data">joined to new <code>data</code></a>, returning the matching circles: the <em>update</em> selection.</li> | |
| <li>These updating circles are given a blue fill.</li> | |
| <li>Any existing circles that do <em>not</em> match new data—the <em>exit</em> selection—are removed.</li> | |
| <li>New circles are <a href="#selection_append">appended</a> for any new data that do <em>not</em> match any existing circle: the <em>enter</em> selection.</li> | |
| <li>These entering circles are given a green fill.</li> | |
| <li>A new selection representing the <a href="#selection_merge">union</a> of entering and updating circles is created.</li> | |
| <li>These entering and updating circles are reordered to match the data (if necessary).</li> | |
| <li>The circles are given a black stroke.</li> | |
| <li>The circles are stored in the variable <code>circle</code>.</li> | |
| </ol> | |
| <p>As described in the preceding paragraphs, the “matching” logic is determined by the key function passed to <em>selection</em>.data; since no key function is used in the above code sample, the elements and data are joined by index.</p> | |
| <p><a href="#selection_enter">#</a> <i>selection</i>.<b>enter</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/enter.js" title="Source"><></a></p> | |
| <p>Returns the enter selection: placeholder nodes for each datum that had no corresponding DOM element in the selection. (The enter selection is empty for selections not returned by <a href="#selection_data"><em>selection</em>.data</a>.)</p> | |
| <p>The enter selection is typically used to create “missing” elements corresponding to new data. For example, to create DIV elements from an array of numbers:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> div <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token string">"body"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">4</span><span class="token punctuation">,</span> <span class="token number">8</span><span class="token punctuation">,</span> <span class="token number">15</span><span class="token punctuation">,</span> <span class="token number">16</span><span class="token punctuation">,</span> <span class="token number">23</span><span class="token punctuation">,</span> <span class="token number">42</span><span class="token punctuation">]</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">enter</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">text</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If the body is initially empty, the above code will create six new DIV elements, append them to the body in-order, and assign their text content as the associated (string-coerced) number:</p> | |
| <pre class=" language-html"><code class="prism language-html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>4<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>8<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>15<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>16<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>23<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>42<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| </code></pre> | |
| <p>Conceptually, the enter selection’s placeholders are pointers to the parent element (in this example, the document body). The enter selection is typically only used transiently to append elements, and is often <a href="#selection_merge">merged</a> with the update selection after appending, such that modifications can be applied to both entering and updating elements.</p> | |
| <p><a href="#selection_exit">#</a> <i>selection</i>.<b>exit</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/exit.js" title="Source"><></a></p> | |
| <p>Returns the exit selection: existing DOM elements in the selection for which no new datum was found. (The exit selection is empty for selections not returned by <a href="#selection_data"><em>selection</em>.data</a>.)</p> | |
| <p>The exit selection is typically used to remove “superfluous” elements corresponding to old data. For example, to update the DIV elements created previously with a new array of numbers:</p> | |
| <pre class=" language-js"><code class="prism language-js">div <span class="token operator">=</span> div<span class="token punctuation">.</span><span class="token function">data</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token number">4</span><span class="token punctuation">,</span> <span class="token number">8</span><span class="token punctuation">,</span> <span class="token number">16</span><span class="token punctuation">,</span> <span class="token number">32</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Since a key function was specified (as the identity function), and the new data contains the numbers [4, 8, 16] which match existing elements in the document, the update selection contains three DIV elements. Leaving those elements as-is, we can append new elements for [1, 2, 32] using the enter selection:</p> | |
| <pre class=" language-js"><code class="prism language-js">div<span class="token punctuation">.</span><span class="token function">enter</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">text</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Likewise, to remove the exiting elements [15, 23, 42]:</p> | |
| <pre class=" language-js"><code class="prism language-js">div<span class="token punctuation">.</span><span class="token function">exit</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">remove</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Now the document body looks like this:</p> | |
| <pre class=" language-html"><code class="prism language-html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>1<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>2<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>4<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>8<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>16<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>32<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> | |
| </code></pre> | |
| <p>The order of the DOM elements matches the order of the data because the old data’s order and the new data’s order were consistent. If the new data’s order is different, use <a href="#selection_order"><em>selection</em>.order</a> to reorder the elements in the DOM. See the <a href="http://bl.ocks.org/mbostock/3808218">General Update Pattern</a> example thread for more on data joins.</p> | |
| <p><a href="#selection_datum">#</a> <i>selection</i>.<b>datum</b>([<i>value</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/datum.js" title="Source"><></a></p> | |
| <p>Gets or sets the bound data for each selected element. Unlike <a href="#selection_data"><em>selection</em>.data</a>, this method does not compute a join and does not affect indexes or the enter and exit selections.</p> | |
| <p>If a <em>value</em> is specified, sets the element’s bound data to the specified value on all selected elements. If the <em>value</em> is a constant, all elements are given the same datum; otherwise, if the <em>value</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). The function is then used to set each element’s new data. A null value will delete the bound data.</p> | |
| <p>If a <em>value</em> is not specified, returns the bound datum for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.</p> | |
| <p>This method is useful for accessing HTML5 <a href="http://www.w3.org/TR/html5/dom.html#custom-data-attribute">custom data attributes</a>. For example, given the following elements:</p> | |
| <pre class=" language-html"><code class="prism language-html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ul</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>list<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span> <span class="token attr-name">data-username</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>shawnbot<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Shawn Allen<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span> <span class="token attr-name">data-username</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>mbostock<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Mike Bostock<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> | |
| <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ul</span><span class="token punctuation">></span></span> | |
| </code></pre> | |
| <p>You can expose the custom data attributes by setting each element’s data as the built-in <a href="http://www.w3.org/TR/html5/dom.html#dom-dataset">dataset</a> property:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">datum</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> <span class="token keyword">this</span><span class="token punctuation">.</span>dataset<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> | |
| </code></pre> | |
| <h3 id="handling-events">Handling Events</h3> | |
| <p>For interaction, selections allow listening for and dispatching of events.</p> | |
| <p><a href="#selection_on">#</a> <i>selection</i>.<b>on</b>(<i>typenames</i>[, <i>listener</i>[, <i>options</i>]]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/on.js" title="Source"><></a></p> | |
| <p>Adds or removes a <em>listener</em> to each selected element for the specified event <em>typenames</em>. The <em>typenames</em> is a string event type, such as <code>click</code>, <code>mouseover</code>, or <code>submit</code>; any <a href="https://developer.mozilla.org/en-US/docs/Web/Events#Standard_events">DOM event type</a> supported by your browser may be used. The type may be optionally followed by a period (<code>.</code>) and a name; the optional name allows multiple callbacks to be registered to receive events of the same type, such as <code>click.foo</code> and <code>click.bar</code>. To specify multiple typenames, separate typenames with spaces, such as <code>input change</code> or <code>click.foo click.bar</code>.</p> | |
| <p>When a specified event is dispatched on a selected element, the specified <em>listener</em> will be evaluated for the element, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). Listeners always see the latest datum for their element, but the index is a property of the selection and is fixed when the listener is assigned; to update the index, re-assign the listener. To access the current event within a listener, use <a href="#event">d3.event</a>.</p> | |
| <p>If an event listener was previously registered for the same <em>typename</em> on a selected element, the old listener is removed before the new listener is added. To remove a listener, pass null as the <em>listener</em>. To remove all listeners for a given name, pass null as the <em>listener</em> and <code>.foo</code> as the <em>typename</em>, where <code>foo</code> is the name; to remove all listeners with no name, specify <code>.</code> as the <em>typename</em>.</p> | |
| <p>An optional <em>options</em> object may specify characteristics about the event listener, such as whether it is capturing or passive; see <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener"><em>element</em>.addEventListener</a>.</p> | |
| <p>If a <em>listener</em> is not specified, returns the currently-assigned listener for the specified event <em>typename</em> on the first (non-null) selected element, if any. If multiple typenames are specified, the first matching listener is returned.</p> | |
| <p><a href="#selection_dispatch">#</a> <i>selection</i>.<b>dispatch</b>(<i>type</i>[, <i>parameters</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/dispatch.js" title="Source"><></a></p> | |
| <p>Dispatches a <a href="http://www.w3.org/TR/dom/#interface-customevent">custom event</a> of the specified <em>type</em> to each selected element, in order. An optional <em>parameters</em> map may be specified to set additional properties of the event. It may contain the following fields:</p> | |
| <ul> | |
| <li><a href="https://www.w3.org/TR/dom/#dom-event-bubbles"><code>bubbles</code></a> - if true, the event is dispatched to ancestors in reverse tree order.</li> | |
| <li><a href="https://www.w3.org/TR/dom/#dom-event-cancelable"><code>cancelable</code></a> - if true, <em>event</em>.preventDefault is allowed.</li> | |
| <li><a href="https://www.w3.org/TR/dom/#dom-customevent-detail"><code>detail</code></a> - any custom data associated with the event.</li> | |
| </ul> | |
| <p>If <em>parameters</em> is a function, it is evaluated for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). It must return the parameters map for the current element.</p> | |
| <p><a href="#event">#</a> d3.<b>event</b></p> | |
| <p>The current <a href="https://developer.mozilla.org/en-US/docs/DOM/event">event</a>, if any. This is set during the invocation of an event listener, and is reset after the listener terminates. Use this to access standard event fields such as <a href="https://www.w3.org/TR/dom/#dom-event-timestamp"><em>event</em>.timeStamp</a> and methods such as <a href="https://www.w3.org/TR/dom/#dom-event-preventdefault"><em>event</em>.preventDefault</a>. While you can use the native <a href="https://developer.mozilla.org/en/DOM/event.pageX"><em>event</em>.pageX</a> and <a href="https://developer.mozilla.org/en/DOM/event.pageY"><em>event</em>.pageY</a>, it is often more convenient to transform the event position to the local coordinate system of the container that received the event using <a href="#mouse">d3.mouse</a>, <a href="#touch">d3.touch</a> or <a href="#touches">d3.touches</a>.</p> | |
| <p>If you use Babel, Webpack, or another ES6-to-ES5 bundler, be aware that the value of d3.event changes during an event! An import of d3.event must be a <a href="http://www.2ality.com/2015/07/es6-module-exports.html">live binding</a>, so you may need to configure the bundler to import from D3’s ES6 modules rather than from the generated UMD bundle; not all bundlers observe <a href="https://github.com/rollup/rollup/wiki/jsnext:main">jsnext:main</a>. Also beware of conflicts with the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/event"><em>window</em>.event</a> global.</p> | |
| <p><a href="#customEvent">#</a> d3.<b>customEvent</b>(<i>event</i>, <i>listener</i>[, <i>that</i>[, <i>arguments</i>]]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/on.js#L98" title="Source"><></a></p> | |
| <p>Invokes the specified <em>listener</em>, using the specified <em>that</em> <code>this</code> context and passing the specified <em>arguments</em>, if any. During the invocation, <a href="#event">d3.event</a> is set to the specified <em>event</em>; after the listener returns (or throws an error), d3.event is restored to its previous value. In addition, sets <em>event</em>.sourceEvent to the prior value of d3.event, allowing custom events to retain a reference to the originating native event. Returns the value returned by the <em>listener</em>.</p> | |
| <p><a href="#mouse">#</a> d3.<b>mouse</b>(<i>container</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/mouse.js" title="Source"><></a></p> | |
| <p>Returns the <em>x</em> and <em>y</em> coordinates of the <a href="#event">current event</a> relative to the specified <em>container</em>. The container may be an HTML or SVG container element, such as a <a href="http://www.w3.org/TR/SVG/struct.html#Groups">G element</a> or an <a href="http://www.w3.org/TR/SVG/struct.html#SVGElement">SVG element</a>. The coordinates are returned as a two-element array of numbers [<em>x</em>, <em>y</em>].</p> | |
| <p><a href="#touch">#</a> d3.<b>touch</b>(<i>container</i>[, <i>touches</i>], <i>identifier</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/touch.js" title="Source"><></a></p> | |
| <p>Returns the <em>x</em> and <em>y</em> coordinates of the touch with the specified <em>identifier</em> associated with the <a href="#event">current event</a> relative to the specified <em>container</em>. The container may be an HTML or SVG container element, such as a <a href="http://www.w3.org/TR/SVG/struct.html#Groups">G element</a> or an <a href="http://www.w3.org/TR/SVG/struct.html#SVGElement">SVG element</a>. The coordinates are returned as a two-element array of numbers [<em>x</em>, <em>y</em>]. If there is no touch with the specified identifier in <em>touches</em>, returns null; this can be useful for ignoring touchmove events where the only some touches have moved. If <em>touches</em> is not specified, it defaults to the current event’s <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/changedTouches">changedTouches</a> property.</p> | |
| <p><a href="#touches">#</a> d3.<b>touches</b>(<i>container</i>[, <i>touches</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/touches.js" title="Source"><></a></p> | |
| <p>Returns the <em>x</em> and <em>y</em> coordinates of the touches associated with the <a href="#event">current event</a> relative to the specified <em>container</em>. The container may be an HTML or SVG container element, such as a <a href="http://www.w3.org/TR/SVG/struct.html#Groups">G element</a> or an <a href="http://www.w3.org/TR/SVG/struct.html#SVGElement">SVG element</a>. The coordinates are returned as an array of two-element arrays of numbers [[<em>x1</em>, <em>y1</em>], [<em>x2</em>, <em>y2</em>], …]. If <em>touches</em> is not specified, it defaults to the current event’s <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/touches">touches</a> property.</p> | |
| <p><a href="#clientPoint">#</a> d3.<b>clientPoint</b>(<i>container</i>, <i>event</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/point.js" title="Source"><></a></p> | |
| <p>Returns the <em>x</em> and <em>y</em> coordinates of the specified <em>event</em> relative to the specified <em>container</em>. (The <em>event</em> may also be a <a href="https://www.w3.org/TR/touch-events/#touch-interface">touch</a>.) The container may be an HTML or SVG container element, such as a <a href="http://www.w3.org/TR/SVG/struct.html#Groups">G element</a> or an <a href="http://www.w3.org/TR/SVG/struct.html#SVGElement">SVG element</a>. The coordinates are returned as a two-element array of numbers [<em>x</em>, <em>y</em>].</p> | |
| <h3 id="control-flow">Control Flow</h3> | |
| <p>For advanced usage, selections provide methods for custom control flow.</p> | |
| <p><a href="#selection_each">#</a> <i>selection</i>.<b>each</b>(<i>function</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/each.js" title="Source"><></a></p> | |
| <p>Invokes the specified <em>function</em> for each selected element, in order, being passed the current datum (<em>d</em>), the current index (<em>i</em>), and the current group (<em>nodes</em>), with <em>this</em> as the current DOM element (<em>nodes</em>[<em>i</em>]). This method can be used to invoke arbitrary code for each selected element, and is useful for creating a context to access parent and child data simultaneously, such as:</p> | |
| <pre class=" language-js"><code class="prism language-js">parent<span class="token punctuation">.</span><span class="token function">each</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>p<span class="token punctuation">,</span> j<span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| d3<span class="token punctuation">.</span><span class="token function">select</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">".child"</span><span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">text</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">,</span> i<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> <span class="token string">"child "</span> <span class="token operator">+</span> d<span class="token punctuation">.</span>name <span class="token operator">+</span> <span class="token string">" of "</span> <span class="token operator">+</span> p<span class="token punctuation">.</span>name<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>See <a href="http://bl.ocks.org/mbostock/4c5fad723c87d2fd8273">Sized Donut Multiples</a> for an example.</p> | |
| <p><a href="#selection_call">#</a> <i>selection</i>.<b>call</b>(<i>function</i>[, <i>arguments…</i>]) <a href="https://github.com/d3/d3-selection/blob/master/src/selection/call.js" title="Source"><></a></p> | |
| <p>Invokes the specified <em>function</em> exactly once, passing in this selection along with any optional <em>arguments</em>. Returns this selection. This is equivalent to invoking the function by hand but facilitates method chaining. For example, to set several styles in a reusable function:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">function</span> <span class="token function">name</span><span class="token punctuation">(</span>selection<span class="token punctuation">,</span> first<span class="token punctuation">,</span> last<span class="token punctuation">)</span> <span class="token punctuation">{</span> | |
| selection | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"first-name"</span><span class="token punctuation">,</span> first<span class="token punctuation">)</span> | |
| <span class="token punctuation">.</span><span class="token function">attr</span><span class="token punctuation">(</span><span class="token string">"last-name"</span><span class="token punctuation">,</span> last<span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| <span class="token punctuation">}</span> | |
| </code></pre> | |
| <p>Now say:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">call</span><span class="token punctuation">(</span>name<span class="token punctuation">,</span> <span class="token string">"John"</span><span class="token punctuation">,</span> <span class="token string">"Snow"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>This is roughly equivalent to:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token function">name</span><span class="token punctuation">(</span>d3<span class="token punctuation">.</span><span class="token function">selectAll</span><span class="token punctuation">(</span><span class="token string">"div"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token string">"John"</span><span class="token punctuation">,</span> <span class="token string">"Snow"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>The only difference is that <em>selection</em>.call always returns the <em>selection</em> and not the return value of the called <em>function</em>, <code>name</code>.</p> | |
| <p><a href="#selection_empty">#</a> <i>selection</i>.<b>empty</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/empty.js" title="Source"><></a></p> | |
| <p>Returns true if this selection contains no (non-null) elements.</p> | |
| <p><a href="#selection_nodes">#</a> <i>selection</i>.<b>nodes</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/nodes.js" title="Source"><></a></p> | |
| <p>Returns an array of all (non-null) elements in this selection.</p> | |
| <p><a href="#selection_node">#</a> <i>selection</i>.<b>node</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/node.js" title="Source"><></a></p> | |
| <p>Returns the first (non-null) element in this selection. If the selection is empty, returns null.</p> | |
| <p><a href="#selection_size">#</a> <i>selection</i>.<b>size</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/selection/size.js" title="Source"><></a></p> | |
| <p>Returns the total number of elements in this selection.</p> | |
| <h3 id="local-variables">Local Variables</h3> | |
| <p>D3 locals allow you to define local state independent of data. For instance, when rendering <a href="http://bl.ocks.org/mbostock/e1192fe405703d8321a5187350910e08">small multiples</a> of time-series data, you might want the same <em>x</em>-scale for all charts but distinct <em>y</em>-scales to compare the relative performance of each metric. D3 locals are scoped by DOM elements: on set, the value is stored on the given element; on get, the value is retrieved from given element or the nearest ancestor that defines it.</p> | |
| <p><a href="#local">#</a> d3.<b>local</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/local.js" title="Source"><></a></p> | |
| <p>Declares a new local variable. For example:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token keyword">var</span> foo <span class="token operator">=</span> d3<span class="token punctuation">.</span><span class="token function">local</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>Like <code>var</code>, each local is a distinct symbolic reference; unlike <code>var</code>, the value of each local is also scoped by the DOM.</p> | |
| <p><a href="#local_set">#</a> <i>local</i>.<b>set</b>(<i>node</i>, <i>value</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/local.js#L18" title="Source"><></a></p> | |
| <p>Sets the value of this local on the specified <em>node</em> to the <em>value</em>, and returns the specified <em>value</em>. This is often performed using <a href="#selection_each"><em>selection</em>.each</a>:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">each</span><span class="token punctuation">(</span><span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> foo<span class="token punctuation">.</span><span class="token keyword">set</span><span class="token punctuation">(</span><span class="token keyword">this</span><span class="token punctuation">,</span> d<span class="token punctuation">.</span>value<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p>If you are just setting a single variable, consider using <a href="#selection_property"><em>selection</em>.property</a>:</p> | |
| <pre class=" language-js"><code class="prism language-js">selection<span class="token punctuation">.</span><span class="token function">property</span><span class="token punctuation">(</span>foo<span class="token punctuation">,</span> <span class="token keyword">function</span><span class="token punctuation">(</span>d<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token keyword">return</span> d<span class="token punctuation">.</span>value<span class="token punctuation">;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> | |
| </code></pre> | |
| <p><a href="#local_get">#</a> <i>local</i>.<b>get</b>(<i>node</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/local.js#L13" title="Source"><></a></p> | |
| <p>Returns the value of this local on the specified <em>node</em>. If the <em>node</em> does not define this local, returns the value from the nearest ancestor that defines it. Returns undefined if no ancestor defines this local.</p> | |
| <p><a href="#local_remove">#</a> <i>local</i>.<b>remove</b>(<i>node</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/local.js#L21" title="Source"><></a></p> | |
| <p>Deletes this local’s value from the specified <em>node</em>. Returns true if the <em>node</em> defined this local prior to removal, and false otherwise. If ancestors also define this local, those definitions are unaffected, and thus <a href="#local_get"><em>local</em>.get</a> will still return the inherited value.</p> | |
| <p><a href="#local_toString">#</a> <i>local</i>.<b>toString</b>() <a href="https://github.com/d3/d3-selection/blob/master/src/local.js#L24" title="Source"><></a></p> | |
| <p>Returns the automatically-generated identifier for this local. This is the name of the property that is used to store the local’s value on elements, and thus you can also set or get the local’s value using <em>element</em>[<em>local</em>] or by using <a href="#selection_property"><em>selection</em>.property</a>.</p> | |
| <h3 id="namespaces">Namespaces</h3> | |
| <p>XML namespaces are fun! Right? Fortunately you can mostly ignore them.</p> | |
| <p><a href="#namespace">#</a> d3.<b>namespace</b>(<i>name</i>) <a href="https://github.com/d3/d3-selection/blob/master/src/namespace.js" title="Source"><></a></p> | |
| <p>Qualifies the specified <em>name</em>, which may or may not have a namespace prefix. If the name contains a colon (<code>:</code>), the substring before the colon is interpreted as the namespace prefix, which must be registered in <a href="#namespaces">d3.namespaces</a>. Returns an object <code>space</code> and <code>local</code> attributes describing the full namespace URL and the local name. For example:</p> | |
| <pre class=" language-js"><code class="prism language-js">d3<span class="token punctuation">.</span><span class="token function">namespace</span><span class="token punctuation">(</span><span class="token string">"svg:text"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// {space: "http://www.w3.org/2000/svg", local: "text"}</span> | |
| </code></pre> | |
| <p>If the name does not contain a colon, this function merely returns the input name.</p> | |
| <p><a href="#namespaces">#</a> d3.<b>namespaces</b> <a href="https://github.com/d3/d3-selection/blob/master/src/namespaces.js" title="Source"><></a></p> | |
| <p>The map of registered namespace prefixes. The initial value is:</p> | |
| <pre class=" language-js"><code class="prism language-js"><span class="token punctuation">{</span> | |
| svg<span class="token punctuation">:</span> <span class="token string">"http://www.w3.org/2000/svg"</span><span class="token punctuation">,</span> | |
| xhtml<span class="token punctuation">:</span> <span class="token string">"http://www.w3.org/1999/xhtml"</span><span class="token punctuation">,</span> | |
| xlink<span class="token punctuation">:</span> <span class="token string">"http://www.w3.org/1999/xlink"</span><span class="token punctuation">,</span> | |
| xml<span class="token punctuation">:</span> <span class="token string">"http://www.w3.org/XML/1998/namespace"</span><span class="token punctuation">,</span> | |
| xmlns<span class="token punctuation">:</span> <span class="token string">"http://www.w3.org/2000/xmlns/"</span> | |
| <span class="token punctuation">}</span> | |
| </code></pre> | |
| <p>Additional prefixes may be assigned as needed to create elements or attributes in other namespaces.</p> | |
| <blockquote> | |
| <p>Written with <a href="https://stackedit.io/">StackEdit</a>.</p> | |
| </blockquote> | |
| </div> | |
| </div> | |
| </body> | |
| </html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment