(DOCSP-6316): Adding absolute date time zone option (#221)

* (DOCSP-6316): Adding absolute date time zone option

* fixing not working ref

Author: jeff-allen-mongo

source/filter-documents.txt

@@ -150,106 +150,136 @@ Filter Date Fields
 When you drag a date field to the filter panel, you can filter based
 on a specified date range. This range can either be:
 
-- A :ref:`relative date <relative-date>` range, which specifies a range
+- A relative date range, which specifies a range
   relative to the time the chart is rendered (e.g., the last six
   months).
 
-- An :ref:`absolute date <absolute-date>` range, which is a range
+- An absolute date range, which is a range
   between specific beginning and end dates.
 
-.. _relative-date:
+Select the appropriate tab for more information on the date filter:
 
-Relative Date Filter
-````````````````````
+.. tabs::
 
-Relative date filters specify a range relative to the 
-time the chart is rendered. To define the date range, specify a period
-of time in the past and/or a period of time in the future relative to
-the current date. :guilabel:`Relative` is the default date filtering
-option.
+   .. tab:: Relative Date Filter
+      :tabid: relative-date
 
-To set a lower bound for a relative date filter:
+      Relative date filters specify a range relative to the 
+      time the chart is rendered. To define the date range, specify a period
+      of time in the past and/or a period of time in the future relative to
+      the current date. :guilabel:`Relative` is the default date filtering
+      option.
 
-1. Turn on the :guilabel:`From` toggle.
+      .. list-table::
+         :header-rows: 1
 
-#. Set the lower bound for your relative date. This timespan is
-   relative to the current date.
+         * - To set a lower bound for the date filter:
+           - To set an upper bound for the date filter:
 
-To set an upper bound for a relative date filter:
+         * - 1. Turn on the :guilabel:`From` toggle.
 
-1. Turn on the :guilabel:`Until` toggle.
+             #. Set the lower bound for your relative date. This
+                timespan is relative to the current date.
 
-#. Set the upper bound for your relative date. This timespan is
-   relative to the current date.
+           - 1. Turn on the :guilabel:`Until` toggle.
 
-.. example::
+             #. Set the upper bound for your relative date. This
+                timespan is relative to the current date.
 
-   The following relative date filter only shows documents
-   with a ``Workout Date (As Date)`` field that is more recent than one year
-   ago from the current date:
+      .. example::
 
-   .. figure:: /images/charts/relative-date.png
-      :scale: 100%
-      :alt: Image showing relative date filter
+         The following relative date filter only shows documents
+         with a ``Workout Date (As Date)`` field that is more recent than one year
+         ago from the current date:
 
-.. _absolute-date:
+         .. figure:: /images/charts/relative-date.png
+            :scale: 100%
+            :alt: Image showing relative date filter
 
-Absolute Date Filter
-````````````````````
+   .. tab:: Absolute Date Filter
+      :tabid: absolute-date
 
-Absolute date filters use absolute dates to define their upper and lower
-bounds. To define an absolute date range, select :guilabel:`Absolute`
-at the top of your date filter card. The dates specified in the filter
-are assumed to be in :abbr:`UTC (Coordinated Universal Time)`, matching
-the raw data in the collection.
+      Absolute date filters use absolute dates to define their upper and lower
+      bounds. To define an absolute date range, select :guilabel:`Absolute`
+      at the top of your date filter card. By default, the dates specified in the filter
+      are assumed to be in :abbr:`UTC (Coordinated Universal Time)`, matching
+      the raw data in the collection. You can
+      specify a timezone for your filter to adjust the date values as
+      desired.
 
-To define a lower bound for your absolute date filter:
+      .. list-table::
+         :header-rows: 1
 
-1. Turn on the :guilabel:`From` toggle.
+         * - To set a lower bound for the date filter:
+           - To set an upper bound for the date filter:
 
-#. Enter a date for your lower bound, or
-   select a date from the calendar below the input field.
+         * - 1. Turn on the :guilabel:`From` toggle.
 
-#. Enter a time for your lower bound, or select a time
-   from the list below the input field.
+             #. Enter a date for your lower bound, or
+                select a date from the calendar below the input field.
 
-#. Set :guilabel:`Inclusive` to dictate whether to include
-   the specified date.
+             #. Enter a time for your lower bound, or select a time
+                from the list below the input field.
 
-To define an upper bound for your absolute date filter:
+             #. Set :guilabel:`Inclusive` to dictate whether to include
+                the specified date.
 
-1. Turn on the :guilabel:`To` toggle.
+           - 1. Turn on the :guilabel:`To` toggle.
 
-#. Enter a date for your upper bound, or
-   select a date from the calendar below the input field.
+             #. Enter a date for your upper bound, or
+                select a date from the calendar below the input field.
 
-#. Enter a time for your upper bound, or select a time
-   from the list below the input field.
+             #. Enter a time for your upper bound, or select a time
+                from the list below the input field.
 
-#. Set :guilabel:`Inclusive` to dictate whether to include
-   the specified date.
+             #. Set :guilabel:`Inclusive` to dictate whether to include
+                the specified date.
 
-.. example::
+      .. note::
 
-   The following absolute date filter only shows documents
-   with a ``Workout Date (As Date)`` field from the year
-   ``2018``:
+         The date and time formats used in your bounds depend
+         on your location, as determined from your browser settings.
 
-   .. figure:: /images/charts/absolute-date.png
-      :scale: 100%
-      :alt: Image showing absolute date filter
+      .. example::
 
-   |
+         The following absolute date filter only shows documents
+         with a ``Workout Date (As Date)`` field from the year
+         ``2018``:
 
-   The filter returns all documents with a
-   ``Workout Date (As Date)`` field from ``January 1, 2018 12:00:00
-   AM`` inclusively, to ``January 1, 2019 12:00:00 AM`` exclusively.
+         .. figure:: /images/charts/absolute-date.png
+            :scale: 60%
+            :alt: Image showing absolute date filter
 
-.. note::
+         |
+
+         The filter returns all documents with a
+         ``Workout Date (As Date)`` field from ``January 1, 2018 12:00:00
+         AM`` inclusively, to ``January 1, 2019 12:00:00 AM`` exclusively.
+
+      Specify a Time Zone
+      ```````````````````
+
+      Use the :guilabel:`Time Zone` dropdown at the bottom of the
+      filter card to specify a time zone for your absolute date filter.
+      
+      By default, MongoDB stores date values in
+      :abbr:`UTC (Coordinated Universal Time)`. When you change the
+      time zone, |charts-short| modifies your date values with respect
+      to the selected time zone. As a result, different documents may be
+      returned by your absolute date filter depending on the time
+      zone selected.
+
+      .. example::
 
-   The date and time formats used in your bounds depend
-   on your location, as determined from your browser settings.
- 
+         Consider an absolute date filter which spans from
+         January 1, 2018 12:00:00 AM inclusively to 
+         January 1, 2019 12:00:00 AM exclusively. By default, a
+         document with a UTC date of January 1, 2019 2:00:00 AM
+         would not be included in this date range. However, if we
+         adjust the time zone to
+         :guilabel:`Central America (UTC-06:00)`, this document
+         would be returned because the adjusted date is
+         December 31, 2018 8:00:00 PM.
 
 .. _filter-boolean: