Merge pull request #471 from fujidana/patch-1

docs: Add 'full-json' docs, examples

Author: camdecoster

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

@@ -602,6 +602,10 @@ <h4 id="plotly-purge"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-refer
 <h4 id="plotly-toImage"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlytoimage">Plotly.toImage</a></h4>
 
 <code>toImage</code> will generate a promise to an image of the plot in data URL format.
+
+<code>format</code> takes one of <code>png</code>, <code>jpeg</code>, <code>webp</code>, <code>svg</code>, or <code>full-json</code>. The default is <code>png</code>.
+<code>full-json</code> returns the figure as JSON instead of a rendered image. The JSON holds the data, layout, frames, and config, with every default value filled in.
+Set <code>imageDataOnly</code> to <code>true</code> to get the raw JSON string rather than a <code>data:application/json</code> URL.
 <pre><code class="language-javascript hljs" data-lang="javascript">
 // Plotly.toImage will turn the plot in the given div into a data URL string
 // toImage takes the div as the first argument and an object specifying image properties as the other
@@ -616,6 +620,8 @@ <h4 id="plotly-toImage"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-ref
 <h4 id="plotly-downloadImage"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlydownloadimage">Plotly.downloadImage</a></h4>
 
 <code>downloadImage</code> will trigger a request to download the image of a Plotly plot.
+
+<code>format</code> takes the same values as <code>Plotly.toImage</code>.
 <pre><code class="language-javascript hljs" data-lang="javascript">
 // downloadImage will accept the div as the first argument and an object specifying image properties as the other
 Plotly.downloadImage(graphDiv, {format: 'png', width: 800, height: 600, filename: 'newplot'});

_posts/plotly_js/fundamentals/config-options/2015-09-24-config-opt-toImageButtonOptions.html

@@ -26,7 +26,7 @@
 
 var config = {
   toImageButtonOptions: {
-    format: 'svg', // one of png, svg, jpeg, webp
+    format: 'svg', // one of png, svg, jpeg, webp, full-json
     filename: 'custom_image',
     height: 500,
     width: 700,

_posts/plotly_js/fundamentals/static-image-export/2016-05-20-static-image.md

@@ -1,7 +1,7 @@
 ---
 description: How to export graphs as static images in JavaScript. The Plotly JavaScript
-  graphing library supports `.jpg`, `.png`, and `.svg` as formats for static image
-  export.
+  graphing library supports `.jpg`, `.png`, `.webp`, and `.svg` as formats for static
+  image export.
 display_as: file_settings
 language: plotly_js
 layout: base
@@ -15,57 +15,75 @@ thumbnail: thumbnail/png-export.png
 
 You can save graphs created with `plotly.js` to static images and view them in your browser. Consider the following example:
 
-    var img_jpg= d3.select('#jpg-export');
-
-    // Plotting the Graph
-
-    var trace={x:[3,9,8,10,4,6,5],y:[5,7,6,7,8,9,8],type:"scatter"};
-    var trace1={x:[3,4,1,6,8,9,5],y:[4,2,5,2,1,7,3],type:"scatter"};
-    var data = [trace,trace1];
-    var layout = {title : "Simple JavaScript Graph"};
-    Plotly.newPlot(
-      'plotly_div',
-       data,
-       layout)
-
-    // static image in jpg format
-
-    .then(
-        function(gd)
-         {
-          Plotly.toImage(gd,{height:300,width:300})
-             .then(
-                 function(url)
-             {
-                 img_jpg.attr("src", url);
-             }
-             )
-        });
+    const imgJpg = document.getElementById('jpg-export');
+
+    const trace = {x: [3, 9, 8, 10, 4, 6, 5], y: [5, 7, 6, 7, 8, 9, 8], type: 'scatter'};
+    const trace1 = {x: [3, 4, 1, 6, 8, 9, 5], y: [4, 2, 5, 2, 1, 7, 3], type: 'scatter'};
+    const data = [trace, trace1];
+    const layout = {title: {text: 'Simple JavaScript Graph'}};
+
+    Plotly.newPlot('plotly_div', data, layout)
+      .then((gd) => Plotly.toImage(gd, {format: 'jpeg', height: 300, width: 300}))
+      .then((url) => {
+        imgJpg.src = url;
+      });
+
 To view this image in your page include following HTML tag:
 
-    <img id="jpg-export"></img>
+    <img id="jpg-export">
 
 Height and width of the image can be adjusted by specifying the same in `toImage` call:
 
-    Plotly.toImage(
-    gd,{
-      format:'jpeg',
-      height:desired_height,
-      width:desired_width,
+    Plotly.toImage(gd, {
+      format: 'jpeg',
+      height: desiredHeight,
+      width: desiredWidth
     });
 
 You can also save the image using different formats.
 
 # Formats Supported
 
-The common image formats: 'PNG', 'JPG/JPEG' are supported. In addition, formats like 'EPS', 'SVG' and 'PDF' are also available for user with a Personal or Professional subscription. You can get more details on our [pricing page] (https://plotly.com/products/cloud/)
+`Plotly.toImage` and `Plotly.downloadImage` take one of five values for `format`:
 
-**Note:** It is important to note that any figures containing WebGL traces (i.e. of type scattergl, scatter3d, surface, mesh3d, scatterpolargl, cone, streamtube, splom, or parcoords) that are exported in a vector format like SVG or PDF will include encapsulated rasters instead of vectors for some parts of the image.
+- `png` - raster image, and the default format
+- `jpeg` - raster image with no transparency
+- `webp` - raster image
+- `svg` - vector image
+- `full-json` - the figure specification as JSON, not a rendered image
+
+**Note:** A figure that contains a WebGL trace (of type scattergl, scatter3d, surface, mesh3d, scatterpolargl, cone, streamtube, splom, or parcoords) holds encapsulated rasters instead of vectors for some parts of an SVG export.
 
 ## Saving as PNG ##
-      img_png.attr("src", url);
-      Plotly.toImage(gd,{format:'png',height:400,width:400});
+
+    const imgPng = document.getElementById('png-export');
+
+    Plotly.toImage(gd, {format: 'png', height: 400, width: 400}).then((url) => {
+      imgPng.src = url;
+    });
 
 ## Saving as SVG ##
-    img_svg.attr("src", url);
-    Plotly.toImage(gd,{format:'svg',height:800,width:800});
+
+    const imgSvg = document.getElementById('svg-export');
+
+    Plotly.toImage(gd, {format: 'svg', height: 800, width: 800}).then((url) => {
+      imgSvg.src = url;
+    });
+
+## Saving as JSON ##
+
+The `full-json` format returns the figure with every default value filled in, including data, layout, frames, config, and the plotly.js `version`.
+
+    // toImage returns a data:application/json URL
+    Plotly.toImage(gd, {format: 'full-json'}).then((dataUrl) => {
+      console.log(dataUrl);
+    });
+
+    // Set imageDataOnly to get the raw JSON string instead
+    Plotly.toImage(gd, {format: 'full-json', imageDataOnly: true}).then((json) => {
+      console.log(JSON.parse(json));
+    });
+
+`Plotly.downloadImage` downloads the figure JSON instead, and saves it as `newplot.full.json`:
+
+    Plotly.downloadImage(gd, {format: 'full-json', filename: 'newplot'});