Merge pull request #700 from plotly/plotlyjs-null-vs-undefined

Add docs and a codepen explaining null vs. undefined in restyle

Author: rreusser

_posts/reference_pages/2016-06-03-plotly_js_function_ref.html

@@ -156,6 +156,18 @@ <h4 id="plotly-restyle"><a href="#plotly-restyle">Plotly.restyle</a></h4>
 <p data-height="528" data-theme-id="15263" data-slug-hash="LpMBOy" data-default-tab="result" data-user="plotly" class='codepen' data-preview="true">See the Pen <a href='http://codepen.io/plotly/pen/LpMBOy/'>Plotly.restyle Attribute strings </a> by plotly (<a href='http://codepen.io/plotly'>@plotly</a>) on <a href='http://codepen.io'>CodePen</a>.</p>
 <script async src="//assets.codepen.io/assets/embed/ei.js"></script>
 
+Finally, you may wish to selectively reset or ignore certain properties when restyling. This may be useful when specifying multiple properties for multiple traces so that you can carefully target what is and is not affected. In general `null` resets a property to the default while `undefined` applies no change to the current state.
+
+<pre><code class="language-javascript hljs" data-lang="javascript">
+// Set the first trace's line to red, the second to the default, and ignore the third
+Plotly.restyle(graphDiv, {
+  'line.color': ['red', null, undefined]
+}, [0, 1, 2])
+</code></pre>
+
+<p data-height="528" data-theme-id="15263" data-slug-hash="XMWRqj" data-default-tab="result" data-user="plotly" class='codepen' data-preview="true">See the Pen <a href='http://codepen.io/plotly/pen/XMWRqj/'>null vs. undefined in Plotly.restyle</a> by plotly (<a href='http://codepen.io/plotly'>@plotly</a>) on <a href='http://codepen.io'>CodePen</a>.</p>
+<script async src="//assets.codepen.io/assets/embed/ei.js"></script>
+
 <h4 id="plotly-relayout"><a href="#plotly-relayout">Plotly.relayout</a></h4>
 
 A more efficient means of updating just the layout in a graphDiv. The call signature and arguments for relayout are similar (but simpler) to restyle. Because there are no indices to deal with, arrays need not be wrapped. Also, no argument specifying applicable trace indices is passed in.