Text.wholeText

  • Revision slug: DOM/Text.wholeText
  • Revision title: Text.wholeText
  • Revision id: 138405
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment no wording changes

Revision Content

{{ DomRef() }}

{{ fx_minversion_header("3") }}

Summary

Returns all text of all Text nodes logically adjacent to the node.  The text is concatenated in document order.  This allows you to specify any text node and obtain all adjacent text as a single string.

Syntax

str = textnode.wholeText;

Notes and example

Suppose you have the following simple paragraph within your webpage (with some whitespace added to aid formatting throughout the code samples here), whose DOM node is stored in the variable para:

<p>Thru-hiking is great!  <strong>No insipid election coverage!</strong>
  However, <a href="http://en.wikipedia.org/wiki/Absentee_ballot">casting a
  ballot</a> is tricky.</p>

You decide you don’t like the middle sentence, so you remove it:

para.removeChild(para.childNodes[1]);

Later, you decide to rephrase things to, “Thru-hiking is great, but casting a ballot is tricky.” while preserving the hyperlink. So you try this:

para.firstChild.data = "Thru-hiking is great, but ";

All set, right? Wrong! What happened was you removed the strong element, but the removed sentence’s element separated two text nodes, one for the first sentence and one for the first word of the last. Instead, you now effectively have this:

<p>Thru-hiking is great, but However, <a
  href="http://en.wikipedia.org/wiki/Absentee_ballot">casting a
  ballot</a> is tricky.</p>

You’d really prefer to treat all those adjacent text nodes as a single one. That’s where wholeText comes in: if you have multiple adjacent text nodes, you can access the contents of all of them using wholeText. Let’s pretend you never made that last mistake. In that case, we have:

assert(para.firstChild.wholeText == "Thru-hiking is great!    However, ");

wholeText is just a property of text nodes that returns the string of data making up all the adjacent (i.e. not separated by an element boundary) text nodes together.

Now let’s return to our original problem. What we want is to be able to replace the whole text with new text. That’s where replaceWholeText() comes in:

para.firstChild.replaceWholeText("Thru-hiking is great, but ");

We’re removing every adjacent text node (all the ones that constituted the whole text) but the one on which replaceWholeText() is called, and we’re changing the remaining one to the new text. What we have now is this:

<p>Thru-hiking is great, but <a
  href="http://en.wikipedia.org/wiki/Absentee_ballot">casting a
  ballot</a> is tricky.</p>

Some uses of the whole-text functionality may be better served by using Node.textContent or the longstanding innerHTML; that’s fine and probably clearer in most circumstances. If you have to work with mixed content within an element as here, however, wholeText and replaceWholeText() may be useful.

Specification

DOM Level 3 Core: Text.wholeText

See also

Revision Source

<p>{{ DomRef() }}</p>
<p>{{ fx_minversion_header("3") }}</p>
<h3 name="Summary">Summary</h3>
<p>Returns all text of all <a class="internal" href="/En/DOM/Text" title="En/DOM/Text"><code>Text</code></a> nodes logically adjacent to the node.  The text is concatenated in document order.  This allows you to specify any text node and obtain all adjacent text as a single string.</p>
<h3 name="Syntax">Syntax</h3>
<pre class="eval"><em>str</em> = textnode.wholeText;
</pre>
<h3 name="Example">Notes and example</h3>
<p>Suppose you have the following simple paragraph within your webpage (with some whitespace added to aid formatting throughout the code samples here), whose DOM node is stored in the variable <code>para</code>:</p>
<pre class="brush: html">&lt;p&gt;Thru-hiking is great!  &lt;strong&gt;No insipid election coverage!&lt;/strong&gt;
  However, &lt;a href="http://en.wikipedia.org/wiki/Absentee_ballot"&gt;casting a
  ballot&lt;/a&gt; is tricky.&lt;/p&gt;
</pre>
<p>You decide you don’t like the middle sentence, so you remove it:</p>
<pre class="brush: js">para.removeChild(para.childNodes[1]);
</pre>
<p>Later, you decide to rephrase things to, “Thru-hiking is great, but casting a ballot is tricky.” <em>while preserving the hyperlink</em>. So you try this:</p>
<pre class="brush: js">para.firstChild.data = "Thru-hiking is great, but ";
</pre>
<p>All set, right? <em>Wrong!</em> What happened was you removed the <code>strong</code> element, but the removed sentence’s element separated two text nodes, one for the first sentence and one for the first word of the last. Instead, you now effectively have this:</p>
<pre class="brush: html">&lt;p&gt;Thru-hiking is great, but However, &lt;a
  href="http://en.wikipedia.org/wiki/Absentee_ballot"&gt;casting a
  ballot&lt;/a&gt; is tricky.&lt;/p&gt;
</pre>
<p>You’d really prefer to treat all those adjacent text nodes as a single one. That’s where <code>wholeText</code> comes in: if you have multiple adjacent text nodes, you can access the contents of all of them using <code>wholeText</code>. Let’s pretend you never made that last mistake. In that case, we have:</p>
<pre class="brush: js">assert(para.firstChild.wholeText == "Thru-hiking is great!    However, ");
</pre>
<p><code>wholeText</code> is just a property of text nodes that returns the string of data making up all the adjacent (i.e. not separated by an element boundary) text nodes together.</p>
<p>Now let’s return to our original problem. What we want is to be able to <em>replace</em> the whole text with new text. That’s where <a class="internal" href="/En/DOM/Text.replaceWholeText" title="En/DOM/Text.replaceWholeText"><code>replaceWholeText()</code></a> comes in:</p>
<pre class="brush: js">para.firstChild.replaceWholeText("Thru-hiking is great, but ");
</pre>
<p>We’re removing every adjacent text node (all the ones that constituted the whole text) but the one on which <code>replaceWholeText()</code> is called, and we’re changing the remaining one to the new text. What we have now is this:</p>
<pre class="brush: html">&lt;p&gt;Thru-hiking is great, but &lt;a
  href="http://en.wikipedia.org/wiki/Absentee_ballot"&gt;casting a
  ballot&lt;/a&gt; is tricky.&lt;/p&gt;
</pre>
<p>Some uses of the whole-text functionality may be better served by using <code>Node.textContent</code> or the longstanding <a class="internal" href="/en/DOM/element.innerHTML" title="En/DOM/Element.innerHTML"><code>innerHTML</code></a>; that’s fine and probably clearer in most circumstances. If you have to work with mixed content within an element as here, however, <code>wholeText</code> and <a class="internal" href="/En/DOM/Text.replaceWholeText" title="En/DOM/Text.replaceWholeText"><code>replaceWholeText()</code></a> may be useful.</p>
<h3 name="Specification">Specification</h3>
<p><a class="external" href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Text3-wholeText" title="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Text3-wholeText">DOM Level 3 Core: Text.wholeText</a></p>
<h3>See also</h3>
<ul> <li><a class="internal" href="/En/DOM/Text.replaceWholeText" title="En/DOM/Text.replaceWholeText"><code>text.replaceWholeText()</code></a></li>
</ul>
Revert to this revision