(DOCSP-8900): As an author, I can link a filter to a field from anoth… (#307)

* (DOCSP-8900): As an author, I can link a filter to a field from another data source

* (DOCSP-8900): copy review feedback

* (DOCSP-8900): tech review feedback

* (DOCSP-8900): updates from DOCSP-9060

Author: jwilliams-mongo

.gitignore

@@ -10,3 +10,4 @@ build/*
 giza.log
 screenshots-temp/*
 screenshot-scripts/.properties.ini
+.vscode/*

source/dashboard-filtering.txt

@@ -19,11 +19,10 @@ Dashboard filters refine data across all charts in a dashboard,
 allowing you to view a common subset of data in all of a dashboard's 
 charts.
 
-Dashboard ``Authors`` or ``Owners`` set the fields that any dashboard 
-users can filter data with. ``Authors`` or ``Owners`` can also set 
-initial default values for each filter. Authenticated dashboard users 
-can filter based on values they specify and save their own default 
-filter values.
+Dashboard ``Authors`` or ``Owners`` set the fields that any dashboard
+users can filter data with. ``Authors`` or ``Owners`` can also set
+initial default values for each filter. All dashboard users can filter
+based on values they specify and save their own default filter values.
 
 .. note::
 
@@ -40,11 +39,12 @@ filter values.
 .. note::
 
    Dashboard ``Authors`` or ``Owners`` define filters using specific 
-   data sources. A single filter might not refine all dashboard charts 
-   if it contains charts mapped to more than one data source.
+   data sources. A single filter might not refine all charts if the 
+   dashboard contains charts mapped to data sources that the filter 
+   doesn't use.
 
-Use Case
-~~~~~~~~
+Example Scenario
+~~~~~~~~~~~~~~~~
 
 A dashboard ``Author`` creates a dashboard with charts that contain
 sales data for all of a company's customers. The author creates a 
@@ -87,12 +87,14 @@ pane.
          is highlighted.
 
 The :guilabel:`Dashboard Filters` pane displays a filter card for 
-each field you can use to filter chart data. When you update a field 
-value, |charts-short| updates dashboard charts to display data that 
-matches the field values you provide. 
+each field you can use to filter chart data. You can configure filter 
+cards to use related fields from multiple data sources. When you update 
+a field value, |charts-short| updates dashboard charts to display data 
+that matches the field values you provide from all configured data 
+sources.
 
 In the following example, a dashboard ``Author`` creates filters on 
-the ``genres`` and ``year`` fields for a sample movie dataset. The 
+the ``genres`` and ``year`` fields from two sample movie datasets. The 
 ``Author`` sets default values for these fields to only display Science 
 Fiction and Horror movies released in or after 1968. Dashboard 
 ``Viewers`` can provide their own values for the filterable fields to 
@@ -120,24 +122,72 @@ Add Dashboard Filters
 ~~~~~~~~~~~~~~~~~~~~~
 
 You can specify fields that any dashboard users can filter data with. 
-When you create a dashboard filter, you select a field from a data 
-source that a dashboard chart uses. You can add dashboard filters based 
-on any number of data sources that a dashboard chart uses.
+When you create a dashboard filter, you select related fields from the 
+data sources that a dashboard chart uses. You can add dashboard filters 
+based on any number of data sources that a dashboard chart uses.
+
+Filter cards that use multiple data sources query each chart using 
+the name of the field from the applicable data set.
+
+.. example::
+
+   Chart ``A`` uses data set ``A``. Chart ``B`` uses data set ``B``.
+   Field ``A`` in data set ``A`` and field ``B`` in data set ``B`` 
+   contain related information. You add both fields to a single 
+   filter card.
+
+   When a filter affects chart ``A``, the query for that chart uses 
+   field ``A`` only. When a filter affects chart ``B``, the query for
+   that chart uses field ``B`` only.
 
 To add a dashboard filter:
 
 1. Expand the :guilabel:`Dashboard Filters` pane on the desired 
    dashboard.
 #. If a dashboard has no filers, click :guilabel:`Add Filters`. 
    Otherwise, click :guilabel:`Edit`.
-#. Expand the data source that contains the fields you want to add a 
-   filter for.
-#. Drag a field from the data source to the drop zone.
+#. Expand a data source that contains fields you want to add a filter 
+   for.
+#. Drag a field from the data source to the :guilabel:`+ filter` drop 
+   zone.
 
    .. tip::
 
       To search for specific data fields, use the search bar at the
       upper left corner of the :guilabel:`Edit Dashboard Filters` pane.
+
+   The data source name appears below the field name in the filter card.
+
+#. (*Optional*) You can stack fields from other data sources. This 
+   allows you to use a single filter to refine chart data from related
+   fields from multiple data sources.
+
+   .. admonition:: To stack fields in a filter card:
+      :class: note
+
+      - Each field must be of the same :ref:`data type <filter-tab>` as 
+        the other fields on the filter card.
+
+      - The filter card must not have another field from the selected 
+        data source on it.
+
+   To stack fields from other data sources:
+   
+   a. Expand another data source that contains a related field. 
+   
+   b. Drag a field from the data source to the 
+      :guilabel:`+ another field` drop zone on the same filter card.
+
+   The data source name appears below the field name and the other data 
+   sources you selected fields from in the filter card.
+
+   .. note::
+
+      The field names might differ from each data source. The filter 
+      card lists the field name you used to create the filter.
+
+   Click :icon-fa4:`trash-o` next to a data source to remove its field
+   from a filter card.
 
 #. (*Optional*) Supply default values for the field in the filter card.
    All dashboard viewers see chart data that matches the default field 
@@ -155,10 +205,6 @@ To add a dashboard filter:
 #. Repeat for each field you want users to filter data by. 
 #. Click :guilabel:`Apply Filters`.
 
-You can optionally provide default values for each field. |charts-short|
-filters dashboard charts using these values until a user provides their
-own values.
-
 .. _edit-dashboard-filters:
 
 Edit Dashboard Filters
@@ -168,6 +214,7 @@ After you create a dashboard filter, you can:
 
 - Enable or disable filter cards.
 - Add or remove fields.
+- Stack fields from other data sources.
 - Change the default field values.
 
 To edit a dashboard filter:
@@ -203,8 +250,10 @@ Filter Dashboards
 You can filter the dashboard data based on the filterable fields
 that an ``Author`` or ``Owner`` configured. |charts-short| filters 
 data based on default field values if the dashboard ``Author`` or 
-``Owner`` configured them. You can provide your own field values to 
-customize the data the charts display.
+``Owner`` configured them. Dashboard ``Authors`` or ``Owners`` can 
+configure filter cards to use related fields from multiple data sources. 
+You can provide your own field values to customize the data the charts 
+display. 
 
 To filter dashboard data based on filterable fields:
 
@@ -216,14 +265,22 @@ To filter dashboard data based on filterable fields:
 
    The filter card options are based on the data type of the field.
    To learn about filtering options for each field data type, see 
-   :ref:`filter-tab`.   
+   :ref:`filter-tab`.
+
+   .. note::
+
+      If the filter card field is a ``String`` or ``ObjectId``, 
+      |charts-short| only samples field values from the first data 
+      source that was added to the filter. 
+
+   Updating the filter value refines chart data based on all data 
+   sources linked to the filter card.
 
-The charts refresh immediately after you modify a field value. 
+The charts refresh immediately after you modify a field value.
 
 .. _revert-dashboard-filters:
 
 Revert Dashboard Filters to Default Values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To revert a filter card to its default values, click :icon-fa4:`undo`.
-