doc and dist update

bitinn · Jul 11, 2015 · b103292 · b103292
1 parent da9f7b3
commit b103292
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 15 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,7 +5,11 @@ Changelog
 
 # 1.x release
 
-## v1.0.3 (master)
+## v1.1.0 (master)
+
+- Feature: allow optional attribute for key lookup
+
+## v1.0.3
 
 - Fix: default namespace should be `null`
 

diff --git a/README.md b/README.md
@@ -22,8 +22,9 @@ Hence `vdom-parser`, a small module that bridges the gap between server-side and
 
 # Features
 
-- Use [DOMParser](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser) for better performance and smaller filesize.
+- Use [DOMParser](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser) for better performance and smaller filesize (around 10KB when minified).
 - No direct dependency, peer-dependent on `virtual-dom` major version (v2 currently).
+- Key support to minimize re-rendering.
 - 100% test coverage, covering common usage such as inline svg, style and script tags (unfortunately `phantomjs` still lack HTML support on DOMParser, so our coverage is only 99%).
 
 
@@ -62,7 +63,7 @@ See [test cases](https://github.com/bitinn/vdom-parser/blob/master/test/test.js)
 
 # API
 
-## parser(node)
+## parser(node, key)
 
 Returns a `VNode` or `VText`, see [virtual-dom documentation](https://github.com/Matt-Esch/virtual-dom/tree/master/docs).
 
@@ -72,6 +73,10 @@ Should be a DOM Element or HTML String.
 
 Note: for string input, `<html>`, `<body>`, `<head>` will return empty VText as we only support nodes under `document.body` or `document.head`. DOM element input doesn't have this limit.
 
+### key
+
+Optional attribute for [VNode key](https://github.com/Matt-Esch/virtual-dom/blob/master/docs/vnode.md) lookup, exposing VNode key as html attribute to minimize client-side patching.
+
 
 # License
 

diff --git a/dist.js b/dist.js
@@ -22,10 +22,11 @@ module.exports = parser;
 /**
  * DOM/html string to vdom parser
  *
- * @param   Mixed   el  DOM element or html string 
- * @return  Object      VNode or VText
+ * @param   Mixed   el    DOM element or html string
+ * @param   String  attr  Attribute name that contains vdom key
+ * @return  Object        VNode or VText
  */
-function parser(el) {
+function parser(el, attr) {
 	// empty input fallback to empty text node
 	if (!el) {
 		return createNode(document.createTextNode(''));
@@ -56,23 +57,24 @@ function parser(el) {
 		throw new Error('invalid dom node', el);
 	}
 
-	return createNode(el);
+	return createNode(el, attr);
 }
 
 /**
  * Create vdom from dom node
  *
- * @param   Object  el  DOM element
- * @return  Object      VNode or VText
+ * @param   Object  el    DOM element
+ * @param   String  attr  Attribute name that contains vdom key
+ * @return  Object        VNode or VText
  */
-function createNode(el) {
+function createNode(el, attr) {
 	// html comment is not currently supported by virtual-dom
 	if (el.nodeType === 3) {
 		return createVirtualTextNode(el);
 
 	// cdata or doctype is not currently supported by virtual-dom
 	} else if (el.nodeType === 1 || el.nodeType === 9) {
-		return createVirtualDomNode(el);
+		return createVirtualDomNode(el, attr);
 	}
 
 	// default to empty text node
@@ -92,17 +94,19 @@ function createVirtualTextNode(el) {
 /**
  * Create vnode from dom node
  *
- * @param   Object  el  DOM element
- * @return  Object      VNode
+ * @param   Object  el    DOM element
+ * @param   String  attr  Attribute name that contains vdom key
+ * @return  Object        VNode
  */
-function createVirtualDomNode(el) {
+function createVirtualDomNode(el, attr) {
 	var ns = el.namespaceURI !== HTML_NAMESPACE ? el.namespaceURI : null;
+	var key = attr && el.getAttribute(attr) ? el.getAttribute(attr) : null;
 
 	return new VNode(
 		el.tagName
 		, createProperties(el)
 		, createChildren(el)
-		, null
+		, key
 		, ns
 	);
 }