DOCSP-28331 Create View Mode tabs in Agg Pipeline Builder Page (#466)

* DOCSP-28331 Create View Mode tabs in Agg Pipeline Builder Page

* add step for preview toggle

* fix capitalization

* JA edits + edits to text view mode

* JA edits 2

* remove unused screenshots

* nit edit

* BC feedback

* resolve build error

Author: ajhuh-mdb

source/aggregation-pipeline-builder.txt

@@ -89,69 +89,226 @@ Limitations
 Create an Aggregation Pipeline
 ------------------------------
 
-Aggregation pipelines can be created in two seperate modes:
+|compass| provides different modes to create aggregation pipelines:
 
-- Stage View Mode, a visual click-based pipeline editor that 
-  preloads pipeline syntax based on your selected stages.
+- Stage View Mode, a visual pipeline editor that preloads pipeline syntax based 
+  on your selected stages.
+
+- Focus Mode, a feature of Stage View Mode where you edit one pipeline stage at 
+  a time. Focus Mode helps you manage complex or deeply nested aggregation 
+  pipeline stages.
 
 - Text View Mode, a text-based pipeline editor that accepts raw
   pipeline syntax. 
 
-.. _create-agg-pipeline-stageview:
-
-Stage View Mode
-~~~~~~~~~~~~~~~
-|
-
-.. include:: /includes/steps/create-agg-pipeline.rst
-
-.. _create-agg-pipeline-textview:
-
-Text View Mode
-~~~~~~~~~~~~~~
-|
-
-.. procedure::
-   :style: normal
-
-   .. step:: In the aggregation pipeline pane, click the 
-      :guilabel:`</> Text` toggle switch to enable text mode for 
-      pipeline editing.
-
-      .. figure:: /images/compass/agg-builder-textview-toggle-on.png
-         :alt: Toggle textmode on
-
-   .. step:: Enter valid aggregation syntax in the text editor. 
-      The following example pipeline limits the query results to ``4`` 
-      documents.
-
-      .. code-block:: javascript
-
-         [ { "$limit" : 4 } ]
-
-      .. figure:: /images/compass/agg-builder-textview-edit.png
-         :alt: Edit the text aggregation pipeline
-
-   .. step:: **(Optional)** If preview mode is enabled, you can 
-      click :guilabel:`Output Options` in the Pipeline Output pane to 
-      expand all nested fields and documents within the 
-      preview results.
-
-      .. figure:: /images/compass/agg-builder-textview-expand-pipeline-preview.png
-         :alt: Pipeline Output preview
-
-   .. step:: Click :guilabel:`Run` at the top right of the pipeline builder. 
-      |compass-short| returns your results in the document view.
-
-      .. figure:: /images/compass/agg-builder-textview-agg-results.png
-         :alt: Results after Running Aggregation
-
-   .. step:: **(Optional)** Click the :guilabel:`Output Options` dropdown 
-      and select :guilabel:`Expand all fields` to expand all nested 
-      fields and documents within the query results.
-
-      .. figure:: /images/compass/agg-builder-textview-expand-results.png
-         :alt: Expand the aggregation pipeline results
+To see how to create an aggregation pipeline, select the tab corresponding to 
+your chosen view mode:
+
+.. tabs:: 
+
+   .. tab:: Stage View Mode 
+      :tabid: stage 
+
+      .. procedure:: 
+         :style: normal
+
+         .. step:: In the aggregation pipeline pane, ensure the 
+            :guilabel:`{} Stages` toggle switch is selected.
+
+            .. figure:: /images/compass/agg-builder-stageview-toggle-on.png
+               :alt: Toggle on stage view mode 
+
+         .. step:: At the bottom of the aggregation pipeline pane, select the 
+            :guilabel:`+ Add Stage` button to open a new aggregation stage 
+            modal.
+            
+         .. step:: At the lower-left corner of the aggregation pipeline pane, 
+            click the :guilabel:`Select...` dropdown and select the 
+            :manual:`aggregation pipeline stage 
+            </reference/operator/aggregation-pipeline/>` to use for the first 
+            stage of the pipeline. 
+
+         .. step:: Fill in your selected pipeline stage. 
+            
+            If you enable :guilabel:`Preview`, preview documents update 
+            automatically to the right of the stage to reflect the results of 
+            your pipeline as it progresses. You can adjust the width of the 
+            pipeline stage by dragging its border to the right.
+            
+            .. figure:: /images/compass/agg-builder-match-stage.png 
+               :alt: Aggregation Builder match stage example
+         
+         .. step:: Click :guilabel:`Add Stage` to add additional aggregation 
+            stages below your most recently added aggregation stage. Repeat 
+            steps 1 and 2 for each additional stage.
+
+            .. note::
+               
+               .. include:: /includes/fact-agg-pipeline-preview-toggle.rst 
+               
+               For example, the following pipeline excludes the first 
+               :manual:`$match </reference/operator/aggregation/match/>` stage 
+               and only includes the 
+               :manual:`$project </reference/operator/aggregation/project/>`
+               stage:
+               
+               .. figure:: /images/compass/agg-builder-exclude-stage-example.png 
+                  :alt: Aggregation Builder exclude stage example
+
+         .. step:: Click :guilabel:`Run` at the top right of the pipeline 
+            builder. |compass-short| returns your results in the document view. 
+            
+            .. warning:: 
+               
+               When you click :guilabel:`Run`, the aggregation runs against the 
+               entire collection.
+
+         .. step:: To edit the pipeline, click :guilabel:`Edit` at the top of 
+            your pipeline toolbar to return to the aggregation pipeline builder
+            and make changes to your pipeline. 
+
+   .. tab:: Focus Mode 
+      :tabid: focus 
+
+      .. procedure::
+         :style: normal
+         
+         .. step:: Select the :guilabel:`Stages` view.
+            
+            In the aggregation pipeline pane, ensure the 
+            :guilabel:`{} Stages` toggle switch is selected.
+
+            .. figure:: /images/compass/agg-builder-stageview-toggle-on.png
+               :alt: Toggle on stage view mode 
+
+         .. step:: Add an aggregation stage.
+            
+            If you have not already created an aggregation stage, click the 
+            :guilabel:`+ Add Stage` button at the bottom of the aggregation 
+            pipeline pane.
+
+         .. step:: Open Focus Mode. 
+            
+            On the upper-right corner of the stage card, click the 
+            Focus Mode icon.
+
+            .. figure:: /images/compass/focus-mode-button.png 
+               :alt: Select the Focus Mode button
+         
+         .. step:: Select an aggregation pipeline stage.
+            
+            Click the :guilabel:`Select` dropdown and select the 
+            :manual:`aggregation pipeline stage 
+            </reference/operator/aggregation-pipeline/>` to use for the first 
+            stage of the pipeline. 
+
+         .. step:: Fill in your pipeline stage. 
+
+            Fill in your selected  stage. |compass-short| populates the 
+            :guilabel:`Stage Output` with up to ten sample output documents. 
+
+            You can adjust the width of the :guilabel:`Stage Input`, stage 
+            editor, and the :guilabel:`Stage Output` by dragging their border to 
+            the desired size.
+
+            .. note:: 
+
+               .. include:: /includes/fact-agg-pipeline-preview-toggle.rst
+
+         .. step:: Add additional pipeline stages.
+            
+            Click the :guilabel:`Add Stage` dropdown to add additional 
+            aggregation stages before or after your last aggregation stage. 
+            Repeat steps 4 and 5 for each additional stage.
+
+            You can add stages with the following keyboard shortcuts: 
+
+            - To add a stage after the current stage: 
+
+              - Windows / Linux: :guilabel:`Ctrl + Shift + A`
+
+              - Mac: :guilabel:`⌘ + Shift + A`
+            
+            - To add a stage before the current stage: 
+              
+              - Windows / Linux: :guilabel:`Ctrl + Shift + B`
+
+              - Mac: :guilabel:`⌘ + Shift + B` 
+
+         .. step:: Navigate between stages. 
+            
+            To navigate between different stages, select the stage you 
+            want to edit from the :guilabel:`Stage` dropdown in the upper-right 
+            corner of the Focus Mode modal. 
+
+            You can navigate between stages with the following keyboard 
+            shortcuts: 
+
+            - To go to the stage before the current stage: 
+
+              - Windows / Linux: :guilabel:`Ctrl + Shift + 9`
+
+              - Mac: :guilabel:`⌘ + Shift + 9`
+            
+            - To add a stage before the current stage: 
+              
+              - Windows / Linux: :guilabel:`Ctrl + Shift + 0`
+
+              - Mac: :guilabel:`⌘ + Shift + 0` 
+
+         .. step:: Run the pipeline.
+            
+            Click :guilabel:`x` to exit Focus Mode and select 
+            :guilabel:`Run` at the top right of the pipeline builder. 
+            |compass-short| returns your results in the document view. 
+
+   .. tab:: Text View Mode 
+      :tabid: text 
+
+      .. procedure::
+         :style: normal
+         
+         .. step:: Select the :guilabel:`Text` view.
+            
+            In the aggregation pipeline pane, click the 
+            :guilabel:`</> Text` toggle switch to enable text mode for pipeline 
+            editing.
+            
+            .. figure:: /images/compass/agg-builder-textview-toggle-on.png
+               :alt: Toggle textmode on
+         
+         .. step:: Enter your aggregation pipeline.
+            
+            Enter valid aggregation syntax in the text editor. The 
+            following example pipeline limits the query results to ``4`` 
+            documents.
+            
+            .. code-block:: javascript
+               
+               [ { "$limit" : 4 } ]
+               
+            .. note:: 
+               
+               To expand all embedded fields and documents within the preview 
+               results, click :guilabel:`Output Options` and select 
+               :guilabel:`Expand all fields`. 
+
+               .. figure:: /images/compass/agg-builder-textview-expand-pipeline-preview.png
+                  :alt: Pipeline Output preview
+               
+         .. step:: Run the pipeline.
+            
+            Click :guilabel:`Run` at the top right of the pipeline 
+            builder. |compass-short| returns your results in the document view. 
+            
+            .. note:: 
+               
+               To expand all embedded fields and documents within the preview 
+               results, click :guilabel:`Output Options` and select 
+               :guilabel:`Expand all fields`.
+               
+               .. figure:: /images/compass/agg-builder-textview-expand-results.png
+                  :alt: Expand the aggregation pipeline results
 
 .. _save-agg-pipeline:
 

source/images/compass/agg-builder-textview-agg-results.png

@@ -0,0 +1,3 @@
+The toggle to the right of the name of each pipeline stage dictates whether that 
+stage is included in the pipeline. Toggling a pipeline stage also updates the 
+pipeline preview, which updates based on whether or not that stage is included.