Merge pull request #1118 from plotly/templates

add makeTemplate and validateTemplate to plotly_js function reference.

Author: michaelbabyn

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

@@ -361,6 +361,77 @@ <h4 id="plotly-validate"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-re
 // "In data trace 0, key orientation is set to an invalid value (horizontal)"
 </code></pre>
 
+<h4 id="plotly-makeTemplate"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlymaketemplate">Plotly.makeTemplate</a></h4>
+
+<code>Plotly.makeTemplate</code> copies the style information from a figure. It does this by returning a <code>template</code> object which can be passed to the <code>layout.template</code> attribute of another figure.
+<br /><br />
+<fieldset class="signatures">
+<legend>Signature</legend>
+<dl>
+  <dt><code>Plotly.makeTemplate(figure)</code></dt>
+  <dd>
+    <dl>
+      <dt><code>figure</code></dt>
+      <dd>a plot object, with <code>{data, layout}</code> members
+    </dl>
+  </dd>
+</dl>
+</fieldset>
+<br /><br />
+
+<pre><code class="language-javascript hljs" data-lang="javascript">
+var figure = {
+  data: [{
+    type: 'bar',
+    marker: {color: 'red'},
+    y: [2, 1, 3, 2],
+  }],
+  layout:{
+    title: 'Quarterly Earnings'
+  }
+};
+
+var template = Plotly.makeTemplate(figure);
+
+newData = [{
+  type:'bar',
+  y:[3,2,5,8]
+}]
+layoutWithTemplate = {template:template}
+
+Plotly.newPlot(graphDiv,newData,layoutTemplate)
+
+</code></pre>
+
+<h4 id="plotly-validate-template"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlyvalidatetemplate">Plotly.validateTemplate</a></h4>
+
+<code>Plotly.validateTemplate</code> allows users to Test for consistency between the given figure and a template,
+either already included in the figure or given separately. Note that not every issue identified here is necessarily
+a problem, it depends on what you're using the template for.
+<br /><br />
+<fieldset class="signatures">
+<legend>Signature</legend>
+<dl>
+  <dt><code>Plotly.validateTemplate(figure, template)</code></dt>
+  <dd>
+    <dl>
+      <dt><code>figure</code> or <code>DOM Node</code></dt>
+      <dd>where <code>figure</code> is a plot object, with <code>{data, layout}</code> members.
+      <dt><code>template</code></dt>
+      <dd>the template, with its own <code>{data, layout}</code>, to test.
+          If omitted, we will look for a template already attached as
+        the plot's <code>layout.template</code> attribute.
+    </dl>
+  </dd>
+</dl>
+</fieldset>
+<br /><br />
+
+<pre><code class="language-javascript hljs" data-lang="javascript">
+var out = Plotly.validateTemplate(figure, template);
+console.log(out[0].msg)
+// "The template has 1 traces of type bar but there are none in the data."
+</code></pre>
 
 <h4 id="plotly-addtraces"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlyaddtraces">Plotly.addTraces</a></h4>
 <em>This function has comparable performance to <a href="#plotlyreact"><code>Plotly.react</code></a> and is faster than redrawing the whole plot with <a href="#plotlynewplot"><code>Plotly.newPlot</code></a>.</em><br /><br />