DOCSP-1458 - Integrating Compass tab into Update Documents tutorial

Author: jeff-allen-mongo

conf.py

@@ -65,7 +65,8 @@ def has(self, *args):
     '.. |hardlink| replace:: {0}/{1}'.format(conf.project.url, conf.git.branches.current),
     '.. |branch| replace:: ``{0}``'.format(conf.git.branches.current),
     '.. |bi| replace:: MongoDB Connector for BI',
-    '.. |version| replace:: {0}'.format(version)
+    '.. |version| replace:: {0}'.format(version),
+    '.. |compass| replace:: MongoDB Compass'
 ])
 
 pygments_style = 'sphinx'

source/images/compass-edit-inv-tab-click.png

@@ -17,14 +17,34 @@
                { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" },
                { item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
                { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" }
-            ]);
+            ] );
 
          .. only:: website
 
             You can run the operation in the web shell below:
 
             .. include:: /includes/fact-mws.rst
 
+     - id: compass
+       content: |
+         .. code-block:: javascript
+
+            [
+               { item: "canvas", qty: 100, size: { h: 28, w: 35.5, uom: "cm" }, status: "A" },
+               { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
+               { item: "mat", qty: 85, size: { h: 27.9, w: 35.5, uom: "cm" }, status: "A" },
+               { item: "mousepad", qty: 25, size: { h: 19, w: 22.85, uom: "cm" }, status: "P" },
+               { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" },
+               { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" },
+               { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" },
+               { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" },
+               { item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
+               { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" }
+            ]
+
+         For instructions on inserting documents using |compass|, see
+         :doc:`Insert Documents </tutorial/insert-documents/>`.
+
      - id: python
        content: |
          .. class:: copyable-code

source/images/compass-edit-paper-add-field-after.png

@@ -14,6 +14,99 @@
                }
             )
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
+     - id: compass
+       content: |
+         Modify the target document as follows:
+
+         - Change the ``status`` field from ``D`` to ``P``.
+
+         - Change the ``size.uom`` field from ``in`` to ``cm``.
+
+         - Add a new field called ``lastModified`` whose value will
+           be today's date.
+
+         1. Click the :guilabel:`Table` button in the top navigation
+            to access the :ref:`Table View <documents-table-view>`:
+
+            .. figure:: /images/compass-table-btn-click.png
+               :alt: Access Table View
+
+         #. Use the Compass :ref:`query bar <query-bar-filter>` to
+            locate the target document.
+
+            Copy the following filter document into the query bar and click
+            :guilabel:`Find`:
+
+            .. class:: copyable-code
+            .. code-block:: javascript
+
+               { item: "paper" }
+
+            .. figure:: /images/compass-update-paper-filter.png
+               :alt: Find Paper document
+
+         #. Hover over the ``status`` field and click the pencil icon
+            which appears on the right side of the document to enter
+            edit mode:
+
+            .. figure:: /images/compass-edit-paper-example.png
+               :alt: Click edit button
+
+         #. Change the value of the field to ``"P"``.
+
+         #. Click the :guilabel:`Update` button below the field to
+            save your changes.
+
+         #. Hover over the ``size`` field and click the
+            outward-pointing arrows which appear on the right side of
+            the field. This opens a new tab which displays the fields
+            within the ``size`` object:
+
+            .. figure:: /images/compass-edit-paper-expand.png
+               :alt: Expand size object
+
+         #. Using the same process outlined in steps 3-5 for editing the
+            ``status`` field, change the value of the ``size.uom`` field
+            to ``"cm"``.
+
+         #. Click the left-most tab above the table labelled
+            ``inventory`` to return to the original table view, which
+            displays the top-level document:
+
+            .. figure:: /images/compass-edit-inv-tab-click.png
+               :alt: Click inventory tab
+
+         #. Hover over the ``status`` field and click the pencil icon
+            which appears on the right side of the document to re-enter
+            edit mode.
+
+         #. Click inside of the ``status`` field and click the
+            :guilabel:`plus button` icon which appears in the edit menu.
+
+            Click the :guilabel:`Add Field After status` button which
+            appears below the plus button:
+
+            .. figure:: /images/compass-edit-paper-add-field-after.png
+               :alt: Add field after status
+
+         #. Add a new field called ``lastModified`` with a value of
+            today's date. Set the field type to ``Date``:
+
+            .. figure:: /images/compass-edit-paper-add-last-modified.png
+               :alt: Submit update
+
+         #. Click the :guilabel:`Update` button below the field to
+            save your changes.
+
+            .. note::
+
+               Because |compass| does not support
+               :update:`$currentDate` or any other
+               :doc:`Field Update Operators </reference/operator/update-field>`,
+               you must manually enter the date value in Compass.
+
      - id: python
        content: |
          .. class:: copyable-code
@@ -23,6 +116,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: java-sync
        content: |
          .. class:: copyable-code
@@ -32,6 +127,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: java-async
        content: |
          .. class:: copyable-code
@@ -41,6 +138,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: nodejs
        content: |
          .. class:: copyable-code
@@ -50,6 +149,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: php
        content: |
          .. class:: copyable-code
@@ -59,6 +160,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: perl
        content: |
          .. class:: copyable-code
@@ -68,6 +171,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: ruby
        content: |
          .. class:: copyable-code
@@ -77,6 +182,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: scala
        content: |
          .. class:: copyable-code
@@ -86,6 +193,8 @@
             :start-after: Start Example 52
             :end-before: End Example 52
 
+         .. include:: /includes/fact-update-operation-uses.rst
+
      - id: csharp
        content: |
          .. class:: copyable-code
@@ -94,3 +203,5 @@
             :dedent: 12
             :start-after: Start Example 52
             :end-before: End Example 52
+
+         .. include:: /includes/fact-update-operation-uses.rst

source/images/compass-edit-paper-add-last-modified.png

@@ -14,6 +14,8 @@
                }
             )
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: python
        content: |
          .. class:: copyable-code
@@ -23,6 +25,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: java-sync
        content: |
          .. class:: copyable-code
@@ -32,6 +36,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: java-async
        content: |
          .. class:: copyable-code
@@ -41,6 +47,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: nodejs
        content: |
          .. class:: copyable-code
@@ -50,6 +58,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: php
        content: |
          .. class:: copyable-code
@@ -59,6 +69,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: perl
        content: |
          .. class:: copyable-code
@@ -68,6 +80,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: ruby
        content: |
          .. class:: copyable-code
@@ -77,6 +91,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: scala
        content: |
          .. class:: copyable-code
@@ -86,6 +102,8 @@
             :start-after: Start Example 53
             :end-before: End Example 53
 
+         .. include:: /includes/fact-update-many-operation-uses.rst
+
      - id: csharp
        content: |
          .. class:: copyable-code
@@ -94,3 +112,5 @@
             :dedent: 12
             :start-after: Start Example 53
             :end-before: End Example 53
+
+         .. include:: /includes/fact-update-many-operation-uses.rst

source/images/compass-edit-paper-example.png

@@ -0,0 +1,11 @@
+The update operation:
+
+- uses the :update:`$set` operator to update the value of the
+  ``size.uom`` field to ``"in"`` and the value of the ``status``
+  field to ``"P"``,
+
+- uses the :update:`$currentDate` operator to update the value
+  of the ``lastModified`` field to the current date. If
+  ``lastModified`` field does not exist,
+  :update:`$currentDate` will create the field. See
+  :update:`$currentDate` for details.

source/images/compass-edit-paper-expand.png

@@ -0,0 +1,11 @@
+The update operation:
+
+- uses the :update:`$set` operator to update the value of the
+  ``size.uom`` field to ``"cm"`` and the value of the ``status``
+  field to ``"P"``,
+
+- uses the :update:`$currentDate` operator to update the value
+  of the ``lastModified`` field to the current date. If
+  ``lastModified`` field does not exist,
+  :update:`$currentDate` will create the field. See
+  :update:`$currentDate` for details.

source/images/compass-table-btn-click.png

@@ -0,0 +1,13 @@
+When replacing a document, the replacement document must consist of only
+field/value pairs; i.e. do not include :manual:`update operators
+</reference/operator/update>` expressions.
+
+The replacement document can have different fields from the original
+document. In the replacement document, you can omit the ``_id`` field
+since the ``_id`` field is immutable; however, if you do include the
+``_id`` field, it must have the same value as the current value.
+
+.. _write-op-replaceOne:
+
+The following example replaces the *first* document from the
+``inventory`` collection where ``item: "paper"``:

source/images/compass-update-doc-button.png

@@ -0,0 +1,4 @@
+Some update operators, such as :update:`$set`, will create the field if
+the field does not exist. See the individual
+:manual:`update operator </reference/operator/update>` reference for
+details.