(dashboard-filtering): documenting Charts dashboard filtering feature (#290)

* (dashboard-filtering): initial commit

* (dashboard-filtering): checkpoint commit 1

* (dashboard-filtering): fix typo

* (dashboard-filtering): copy review feedback

* (dashboard-filtering): more copy review feedback

* (dashboard-filtering): final copy review changes

* (dashboard-filtering): tech review feedback

* (dashboard-filtering): replacing outdated dashboard permissions image

* (dashboard-filterting): more tech review feedbacl

Author: jwilliams-mongo

source/dashboard-filtering.txt

@@ -0,0 +1,215 @@
+.. _dashboard-filtering:
+
+=================================
+Filter Dashboards by Field Values
+=================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Dashboard Filters
+-----------------
+
+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. Any dashboard users can filter 
+based on values they specify and save their own default filter values.
+
+.. figure:: /images/charts/dashboard-filter-cards.png
+   :figwidth: 720px
+   :alt: An image of a dashboard. Two filter cards are highlighted. The
+         charts only display data that corresponds to the selected field
+         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.
+
+Use Case
+~~~~~~~~
+
+A dashboard ``Author`` creates a dashboard with charts that contain
+sales data for all of a company's customers. The author creates a 
+filter allowing dashboard viewers to select which region(s) to 
+display data from. Members of a sales team use this filter to display 
+customer data only for the region(s) that they cover.
+
+Filter Persistence Per Dashboard Viewer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|charts-short| persists the following states for each dashboard viewer 
+across reloads and user sessions: 
+
+- which filters are enabled or disabled
+- field values chosen to filter dashboards
+- whether the :guilabel:`Dashboard Filters` is expanded or collapsed.
+
+The changes that a dashboard viewer makes to filters don't affect other 
+|charts-short| users. A viewer's saved filters are not affected when a 
+dashboard ``Author`` or ``Owner`` modifies a filter's default values 
+unless you :ref:`reset a filter <revert-dashboard-filters>`. 
+
+The :guilabel:`Dashboard Filters` Pane
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :guilabel:`Dashboard Filters` icon indicates the number of active 
+filters. Click the icon to expand the :guilabel:`Dashboard Filters` 
+pane. 
+
+.. figure:: /images/charts/expand-filter-pane.png
+   :figwidth: 720px
+   :alt: An image of a dashboard. The :guilabel:`Dashboard Filters` icon
+         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. 
+
+In the following example, a dashboard ``Author`` creates filters on 
+the ``genres`` and ``year`` fields for a sample movie dataset. 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 
+refine chart data based on their interests.
+
+.. figure:: /images/charts/edit-dashboard-filters.png
+   :figwidth: 720px
+   :alt: An image of a dashboard. The :guilabel:`Edit Dashboard Filters`
+         pane is highlighted. 
+
+To learn about filtering options for each field data type, see 
+:ref:`filter-tab`.
+
+.. _manage-dashboard-filters:
+
+Manage Dashboard Filters
+------------------------
+
+Dashboard ``Authors`` and ``Owners`` can add, edit, and delete dashboard 
+filters.
+
+.. _add-dashboard-filters:
+
+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.
+
+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.
+
+   .. tip::
+      
+      To search for specific data fields, use the search bar at the
+      upper left corner of the :guilabel:`Edit Dashboard Filters` pane.
+ 
+#. (*Optional*) Supply default values for the field in the filter card.
+   All dashboard viewers see chart data that matches the default field 
+   values you provide until they provide their own filter values or 
+   disable the filter card.
+   
+   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`.
+
+#. Use the toggle to disable or enable the filter card by default. If
+   disabled, each dashboard user must enable the filter card to display
+   data the filter refines.
+
+#. 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
+~~~~~~~~~~~~~~~~~~~~~~
+
+After you create a dashboard filter, you can:
+
+- Enable or disable filter cards.
+- Add or remove fields.
+- Change the default field values.
+
+To edit a dashboard filter:
+
+1. Expand the :guilabel:`Dashboard Filters` pane on the desired 
+   dashboard, then click :guilabel:`Edit`.
+#. Make the changes you want to each filter card.
+#. Click :guilabel:`Apply Filters`.
+
+.. _delete-dashboard-filters:
+
+Delete Dashboard Filters
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Expand the :guilabel:`Dashboard Filters` pane on the desired 
+   dashboard, then click :guilabel:`Edit`.
+#. Hover of the filter card you want to delete, then click 
+   :icon-fa4:`trash-o`.
+#. Click :guilabel:`Apply Filters`.
+
+Use Dashboard Filters
+----------------------
+
+Any user with at least the ``Viewer`` role on a dashboard *and* the data 
+source backing a field can view the filter card and provide their own 
+values for the filter.
+
+.. _filter-dashboards:  
+
+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.
+
+To filter dashboard data based on filterable fields:
+
+1. Expand the :guilabel:`Dashboard Filters` pane on the desired 
+   dashboard.
+#. If a filter card is disabled, click the toggle to enable it.
+#. Modify the values of the provided fields to update the dashboard's 
+   charts based on the filter values you provided.
+
+   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`.   
+   
+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`.
+

source/dashboard-permissions.txt

@@ -27,17 +27,24 @@ following dashboard permissions are available:
      - Description
 
    * - Viewer
-     - Can open a dashboard and view charts provided they have the
-       ``Viewer`` role on the data source backing this dashboard. If
-       the user does not have the ``Viewer`` role on a chart's backing
-       data source, the chart doesn't render in the dashboard.
+     - Can perform the following actions:
+       
+       - Open a dashboard and view charts that are backed by a data 
+         source the user has permission to view. If the user doesn't 
+         have the :ref:`Viewer <data-source-roles>` role on a chart's 
+         backing data source, the dashboard doesn't render the chart.
+
+         ``Viewers`` cannot make any modifications to the dashboard.
 
-       ``Viewers`` cannot make any modifications to the dashboard.
+       - Filter dashboards based on available fields. 
 
    * - Author
      - Can perform the following actions:
 
        - Add, modify, and delete charts,
+       - :ref:`Add <add-dashboard-filters>`, 
+         :ref:`edit <edit-dashboard-filters>`, 
+         and :ref:`delete <delete-dashboard-filters>` dashboard filters,
        - Specify which fields can be used for
          :ref:`Unauthenticated embedded chart filters
          <specify-filter-fields>`,

source/dashboards.txt

@@ -169,5 +169,6 @@ top-right of the dashboard or press the escape key.
    .. toctree::
       :titlesonly:
 
+      /dashboard-filtering
       /manage-dashboards
       /dashboard-permissions

source/images/charts/dashboard-access-button.png

@@ -55,6 +55,7 @@ To duplicate a dashboard from the Dashboards tab:
    user of the newly duplicated dashboard. To grant other users access,
    update the dashboard's :doc:`permissions </dashboard-permissions>`.
 
+
 Author Actions
 --------------