(DOCSP-6310): Adding docs for auto refresh embedded charts (#218)

* (DOCSP-6310): Adding docs for auto refresh embedded charts

* Updates per Jon's comments

* Update source/embedded-chart-options.txt

Co-Authored-By: jdestefano-mongo <[email protected]>

Author: jeff-allen-mongo

config/sphinx_local.yaml

@@ -24,8 +24,9 @@ theme:
      - /chart-type-reference/data-table
      - /chart-type-reference/geo-spatial
      - /chart-type-reference/choropleth
-     - /customize-charts
      - /chart-type-reference/grid-charts
+     - /customize-charts
+     - /embedding-charts
 sidebars:
   '**':
     - 'pagenav.html'

source/embedded-chart-options.txt

@@ -0,0 +1,70 @@
+======================
+Embedded Chart Options
+======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can customize your embedded charts by appending various
+query parameters to their iframe URLs.
+
+.. note::
+
+   To embed charts from your dashboards, you must configure embedding
+   options on your data sources. For instructions, see
+   :ref:`embedding-charts`. 
+
+Specify Refresh Interval
+------------------------
+
+Use the ``autorefresh`` query parameter to define the interval,
+in seconds, at which the chart refreshes with the latest data from
+its :ref:`data source <data-sources>`. If you do not specify
+this option, your embedded chart loads once when the iframe
+loads and does not automatically refresh.
+
+Example
+~~~~~~~
+
+The following iframe embeds a chart which automatically refreshes
+every 30 seconds as defined by the ``autorefresh=30`` query parameter:
+
+.. code-block:: none
+
+   <iframe style="border: none;border-radius: 2px;box-shadow: 0 2px
+   10px 0 rgba(70, 76, 79, .2);" width="640" height="480" src="
+   {charts-host}/embed/charts?id=b3ca720f-4b4a-40b4-a726-e7dc0c49aa1c&
+   tenant=c184f559-a6d6-4c17-a524-fde31193e498&autorefresh=30"></iframe>
+
+Considerations
+~~~~~~~~~~~~~~
+
+- The minimum automatic refresh interval is 10 seconds. If you specify
+  an ``autorefresh`` value less than 10, the chart refreshes every 10
+  seconds.
+
+- If you specify an ``autorefresh`` value which is not an integer or
+  less than 0, an :ref:`error <embedded-errors>` is returned.
+
+- If your data source requires a
+  :ref:`Verified Signature <embedding-procedure>`, the signature
+  validity (including the expiry date) is checked on each refresh. If
+  the signature's expiry date passed, the host web page must
+  regenerate a new signature to continue rendering charts. For
+  code examples using verified signatures, see
+  `MongoDB Charts Embedding Examples <https://github.com/mongodb/charts-embedding-examples>`__
+  on GitHub.
+
+  .. example::
+
+     If you specify an automatic refresh interval of one minute and the
+     expiry date of the signature is in 1 hour, the chart refreshes
+     every minute for an hour. Once one hour has elapsed, the chart
+     will not render and an error will be displayed as the signature is
+     no longer valid. The host web page must regenerate a new signature
+     to resume rendering the chart.

source/embedding-charts.txt

@@ -9,7 +9,7 @@ Embed Charts in Your Web Application
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 2
+   :depth: 1
    :class: singlecol
 
 Overview
@@ -57,6 +57,8 @@ Procedure
 
          .. include:: /includes/steps/embed-chart-verified.rst
 
+.. _embedded-errors:
+
 Embedded Charts Error Codes
 ---------------------------
 
@@ -93,3 +95,14 @@ If an embedded chart fails to render, an error code is displayed:
    * - ``5``
      - Invalid payload. Your application server is not creating a
        usable :ref:`signature <admin-settings>`.
+
+   * - ``6``
+     - Invalid ``autorefresh`` value specified. The ``autorefresh``
+       value must be an integer greater than 0.
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /embedded-chart-options