(DOCSP-10968) Add Section to Filter Embedded Charts for Filter Injection (#384)

* (DOCSP-10968) Add Section to Filter Embedded Charts for Filter Injection

* Updates from copy review

* Single source example, use on both pages

Author: zach-carr

source/filter-embedded-charts.txt

@@ -23,6 +23,30 @@ with the |charts-short| Embedding SDK.
 
    - :ref:`embedding-charts`
 
+.. _inject-filter-per-user:
+
+Inject User-Specific Filters
+----------------------------
+
+When you embed a chart requiring :guilabel:`Authenticated` access, you 
+can use the :guilabel:`Inject Filter Per User` setting to inject a 
+MongoDB filter document specific to each user who views 
+the chart. The function has access to your Embedding Authentication 
+Provider's token via ``context.token``, and can filter the chart data 
+based on the token.
+
+This filter ensures that viewers of an embedded chart see only their
+own data, which is useful when embedding charts with potentially
+sensitive information.
+
+To inject a filter specific to each user, in the 
+:guilabel:`Authenticated` tab of the the :guilabel:`Embed Chart` 
+dialog, set the :guilabel:`Inject Filter Per User`
+setting to :guilabel:`On`. Specify a function and click 
+:guilabel:`Save`.
+
+.. include:: /includes/example-user-filter-function.rst
+
 .. _specify-filter-fields:
 
 Specify Filterable Fields
@@ -99,11 +123,12 @@ Use the ``filter`` query parameter to only display data that matches a
 specified :abbr:`MQL (MongoDB Query Language)` filter in your
 chart embedded in an iframe. 
 
-You can use the ``filter`` query parameter on both Unauthenticated
-charts and charts which require a Verified Signature. The filtering
+You can use the ``filter`` query parameter on both 
+:guilabel:`Unauthenticated`
+and :guilabel:`Verified Signature` charts. The filtering
 behavior differs with each authentication setting:
 
-- With Unauthenticated charts, the chart
+- With unauthenticated charts, the chart
   :ref:`Author <dashboard-roles>` specifies the fields that can be
   included in filters set by the embedding application code or added by
   chart viewers. To learn how to specify filterable fields, see
@@ -118,7 +143,8 @@ Filter Syntax
 ~~~~~~~~~~~~~
 
 Select the appropriate tab to see an example of how to filter data in
-an Unauthenticated chart and a Verified Signature chart:
+an :guilabel:`Unauthenticated` chart and a 
+:guilabel:`Verified Signature` chart:
 
 .. tabs::
 

source/includes/example-user-filter-function.rst

@@ -0,0 +1,11 @@
+.. example::
+
+   The following filter function only renders data where the
+   ``ownerId`` field of a document matches the value of
+   the Embedding Authentication Provider's token's ``sub`` field:
+
+   .. code-block:: javascript
+
+      function getFilter(context) {
+        return { ownerId: context.token.sub };
+      }

source/includes/steps-embed-chart-authenticated.yaml

@@ -41,25 +41,15 @@ ref:
 level: 4
 content: |
    You can specify a function to inject a MongoDB filter document for
-   each user who views the chart. The function has access to your
-   Embedding Authentication Provider's token via ``context.token``, and
-   can filter the chart data based on the token.
+   each user who views the chart. This is useful for rendering 
+   user-specific charts.
 
-   This filter ensures that viewers of an embedded chart see only their
-   own data, which is useful when embedding charts with potentially
-   sensitive information.
+   .. include:: /includes/example-user-filter-function.rst
 
-   .. example::
+   .. seealso::
 
-      The following filter function only renders data where the
-      ``ownerId`` field of a document matches the value of
-      the Embedding Authentication Provider's token's ``sub`` field:
-
-      .. code-block:: javascript
-
-         function getFilter(context) {
-           return { ownerId: context.token.sub };
-         }
+      To learn more about injecting filters per user, see 
+      :ref:`inject-filter-per-user`.
 ---
 title: (*Optional*) Specify filterable fields for your chart.
 ref: authenticated-filterable-fields
@@ -69,8 +59,10 @@ content: |
    default, no fields are whitelisted, meaning the chart cannot be
    filtered until you explicitly whitelist at least one field.
 
-   To learn more about filterable fields, see
-   :ref:`specify-filter-fields`.
+   .. seealso::
+   
+      To learn more about filterable fields, see 
+      :ref:`specify-filter-fields`.
 ---
 title: Copy the :guilabel:`Chart ID` and :guilabel:`Chart Base URL`
 ref: copy-chart-attributes