DOCSP-39185 Require local files in playgrounds (#85)

Author: jeff-allen-mongo

snooty.toml

@@ -5,7 +5,12 @@ intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv",
                "https://www.mongodb.com/docs/atlas/objects.inv"
               ]
 
-toc_landing_pages = ["/playgrounds", "/crud-ops", "/playground-databases"]
+toc_landing_pages = [
+    "/playgrounds",
+    "/crud-ops",
+    "/playground-databases",
+    "/require-playgrounds"
+]
 
 [constants]
 

source/playgrounds.txt

@@ -266,4 +266,4 @@ Consideration for Authentication
    /run-agg-pipelines
    /enable-autocomplete-for-string-literals
    /export-to-language
-   /require-modules
+   /require-playgrounds

source/require-playgrounds.txt

@@ -0,0 +1,62 @@
+.. _vsce-require-landing:
+
+============================
+Use require() in Playgrounds
+============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can use the `require()
+<https://nodejs.org/api/modules.html#modules_require_id>`__ function in
+your playgrounds to reuse code in your playgrounds. The code you
+include with ``require()`` can be either:
+
+- A native Node module (such as `fs
+  <https://nodejs.org/api/fs.html#fs_file_system>`__)
+
+- An external Node module downloaded from `npm
+  <https://www.npmjs.com/>`__
+
+- A local JavaScript file
+
+Use Cases
+---------
+
+Using ``require()`` to import code helps keep your playgrounds
+organized. If you are often performing the same tasks in your
+playgrounds, you can use ``require()`` to reuse code and avoid writing
+full functions in each of your playgrounds.
+
+For example, consider the following scenarios where reusing code can
+simplify logic and improve productivity:
+
+- You need to ensure that documents are inserted with a consistent
+  structure. You can import a JavaScript file to validate the data
+  format before the playground script performs the insert.
+
+- You store monetary data and want to convert values between different
+  currencies. You can import a JavaScript function to perform conversion
+  calculations.
+
+- You need to import data from files on your local computer. You can use
+  the native Node module ``fs`` to read data from local files.
+
+Get Started
+-----------
+
+To learn how to use ``require()`` in your playgrounds, see the following
+tutorials:
+
+- :ref:`vsce-require`
+
+- :ref:`vsce-require-local`
+
+.. toctree::
+   :titlesonly:
+
+   /require-playgrounds/require-modules
+   /require-playgrounds/require-local

source/require-playgrounds/require-local.txt

@@ -0,0 +1,134 @@
+.. _vsce-require-local:
+
+=================================
+Use require() to Load Local Files
+=================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can use the `require()
+<https://nodejs.org/api/modules.html#modules_require_id>`__ function in
+your MongoDB Playgrounds to include code from local files. You can store
+your code in a single location and reuse that code in different
+playgrounds.
+
+About this Task
+---------------
+
+This tutorial shows how to use ``require()`` to load local scripts. You
+can also use ``require()`` to load Node modules, like those downloaded
+from `npm <https://www.npmjs.com/>`__. For more information, see
+:ref:`vsce-require`.
+
+Steps
+-----
+
+.. procedure::
+   :style: normal
+   
+   .. step:: Create a script file
+
+      The following script file validates documents to ensure that the
+      required fields are present. Save the script to your local
+      filesystem as ``validate.js``:
+
+      .. code-block:: javascript
+
+         // validate.js
+
+         const required_fields = [ 'name', 'email' ]
+
+         const validate_data = (document) => {
+
+            let is_valid = true;
+
+            for (const field of required_fields) {
+               if (document[field] == null) {
+                     is_valid = false;
+               }
+            };
+            return is_valid;
+         };
+
+         module.exports = validate_data;
+
+   .. step:: Create a playground that uses the validation script
+
+      The following playground uses ``require()`` to call the
+      ``validate_data`` function specified in ``validate.js``. The
+      ``validate_data`` function is called on two sample documents. If
+      the document contains the required fields ``name`` and ``email``,
+      it is inserted into the ``people`` collection.
+
+      .. important::
+
+         Update the first line of the playground with the path to the
+         ``validate.js`` file:
+
+      .. code-block:: javascript
+         :emphasize-lines: 3
+
+         // playground-1.mongodb.js
+
+         const validate = require('/path/to/validate.js');
+
+         use('mongodbVSCodePlaygroundDB');
+
+         const doc1 = { _id: 1, 'name': 'Taylor', 'email': '[email protected]' };
+
+         const doc2 = { _id: 2, 'name': 'Taylor' };
+
+         const docs = [ doc1, doc2 ];
+
+         let inserted_count = 0;
+
+         for (const doc of docs) {
+            if (validate(doc)) {
+               db.getCollection('people').insertOne(doc);
+               inserted_count++;
+            }
+         };
+
+         console.log("Inserted " + inserted_count + " documents");
+
+   .. step:: Run the playground
+
+      .. include:: /includes/run-playground.rst
+
+Results
+-------
+
+Only ``doc1`` contains both required fields and is inserted into the
+collection. ``doc2`` does not contain the required field ``email``, and
+is not inserted.
+
+To confirm that the correct document was inserted, query the ``people``
+collection:
+
+.. code-block:: javascript
+
+   use mongodbVSCodePlaygroundDB
+
+   db.people.find()
+
+Output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      { _id: 1, name: 'Taylor', email: '[email protected]' }
+   ]
+
+Learn More
+----------
+
+- :ref:`schema-validation-overview`
+
+- :ref:`vsce-require`
+
+- :ref:`vsce-playground-databases`

source/require-modules.txt renamed to source/require-playgrounds/require-modules.txt

@@ -1,8 +1,8 @@
 .. _vsce-require:
 
-=============================================
-Use ``require()`` to Include External Modules
-=============================================
+========================================
+Use require() to Include Node.js Modules
+========================================
 
 .. default-domain:: mongodb
 
@@ -19,10 +19,11 @@ Use ``require()`` to Include External Modules
    function is out of scope for this tutorial. To learn more, refer to
    the `Node.js Documentation <https://nodejs.org/api/modules.html>`__.
 
-You can use the
-`require() <https://nodejs.org/api/modules.html#modules_require_id>`__
-function in your MongoDB Playgrounds to
-include modules which exist in separate files.
+You can use the `require()
+<https://nodejs.org/api/modules.html#modules_require_id>`__ function in
+your MongoDB Playgrounds to include functionality from Node.js modules.
+You can use modules to import reusable code to simplify your
+playgrounds.
 
 Require Native Modules
 ----------------------