Add skip function to allow skipping subtrees dynamically.

index.js

@@ -23,6 +23,7 @@ export {
   elementOpen,
   elementClose,
   elementPlaceholder,
+  skip,
   text,
   attr,
 } from './src/virtual_elements';

src/context.js

@@ -119,13 +119,14 @@ var getContext = function() {
   return context;
 };
 
+
 /**
  * Gets the current Element being patched.
  * @return {!Node}
  */
 var currentElement = function() {
   if (process.env.NODE_ENV !== 'production' && !context) {
-    throw new Error('cannot call currentElement() while not in patch');
+    throw new Error('Cannot call currentElement() while not in patch.');
   }
   return context.walker.currentParent;
 };

src/virtual_elements.js

@@ -20,7 +20,10 @@ import {
 } from './alignment';
 import { updateAttribute } from './attributes';
 import { getData } from './node_data';
-import { getContext } from './context';
+import {
+  getContext,
+  currentElement
+} from './context';
 import {
     firstChild,
     nextSibling,
@@ -116,6 +119,18 @@ if (process.env.NODE_ENV !== 'production') {
 }
 
 
+/**
+ * Skips the children in a subtree, allowing an Element to be closed without
+ * clearing out the children.
+ */
+var skip = function() {
+  var openElement = currentElement();
+  var data = getData(openElement);
+
+  data.lastVisitedChild = openElement.lastChild;
+};
+
+
 /**
  * @param {string} tag The element's tag.
  * @param {?string=} key The key used to identify this element. This can be an
@@ -307,10 +322,9 @@ var elementPlaceholder = function(tag, key, statics, var_args) {
     assertPlaceholderKeySpecified(key);
   }
 
-  var node = elementOpen.apply(null, arguments);
-  updateAttribute(node, symbols.placeholder, true);
-  elementClose.apply(null, arguments);
-  return node;
+  elementOpen.apply(null, arguments);
+  skip();
+  return elementClose.apply(null, arguments);
 };
 
 
@@ -355,6 +369,7 @@ export {
   elementVoid,
   elementClose,
   elementPlaceholder,
+  skip,
   text,
   attr
 };

test/functional/skip.js

@@ -0,0 +1,56 @@
+/**
+ * Copyright 2015 The Incremental DOM Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS-IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+    patch,
+    elementOpen,
+    elementClose,
+    skip,
+    text
+} from '../../index';
+
+describe('skip', () => {
+  var container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container);
+  });
+
+  function render(data) {
+    elementOpen('div');
+      if (data.skip) {
+        skip();
+      } else {
+        text('some ');
+        text('text');
+      }
+    elementClose('div');
+  }
+
+  it('should keep any DOM nodes in the subtree', () => {
+    patch(container, render, { skip: false });
+    patch(container, render, { skip: true });
+
+    expect(container.textContent).to.equal('some text');
+  });
+
+});
+