(DOCSP-15010): Using Change Listeners In Your Components - React Native SDK (#996)

* (DOCSP-15010): Reacting to changes from components

* removed unneeded text

* update

* add instructions to class components

* separated react content from react-to-changes

* added rn files to its own examples folder under node + excluded them from jest suite

* fix file names

* added generated files

* Add emphasize lines

* re-add class component

* re-add functional component

* fix toc tree

* update wording

* fix grammar

* updated title to avoid gerunds

* fix typo our->your

* replace {+realm+} objects with {+service-short+} objects

* fix wording

* update

* removed redudant class component example

* Update source/sdk/react-native/examples/react-to-changes.txt

Co-authored-by: nate contino <[email protected]>

* fix spacing

* fixed Reactjs -> React.js

* update wording

* typo fix

* update wording

* switched component name

* add example directive

* fix example paragraph

* fix wording and grammar

* fix grammar

* fix typo

* Update source/sdk/react-native/examples/use-change-listeners-in-components.txt

Co-authored-by: nate contino <[email protected]>

* Update source/sdk/react-native/examples/use-change-listeners-in-components.txt

Co-authored-by: nate contino <[email protected]>

* Update source/sdk/react-native/examples/use-change-listeners-in-components.txt

Co-authored-by: nate contino <[email protected]>

* added emphasize to non-generated file

Co-authored-by: Mohammad Hunan Chughtai <[email protected]>
Co-authored-by: nate contino <[email protected]>

Author: 3 people

examples/node/Examples/rn/using-change-listeners-functional-component.js

@@ -0,0 +1,57 @@
+import React, {useEffect, useState} from 'react';
+import {Text} from 'react-native';
+import Realm from 'realm';
+// :code-block-start: using-change-listeners-functional-component
+const TaskList = () => {
+  const [tasks, setTasks] = useState([]);
+  // :emphasize-start:
+  useEffect(() => {
+  // :emphasize-end:
+    Realm.open({
+      schema: [TaskSchema], // predefined schema
+    }).then(realm => {
+
+      const tasks = realm.objects('Task');
+      // set state to the initial value of your realm objects
+      setTasks([...tasks]);
+
+      // :emphasize-start:
+      tasks.addListener(() => {
+        // update state of tasks to the updated value
+        setTasks([...tasks]);
+      });
+      // :emphasize-end:
+
+      realm.write(() => {
+        // the following tasks will trigger the change listener and update the UI
+        realm.create('Task', {
+          name: 'Go to the grocery store',
+        });
+        realm.create('Task', {
+          name: 'Exercise in the gym',
+        });
+      });
+
+      // cleanup function
+      // :emphasize-start:
+      return () => {
+        const tasks = realm.objects('Task');
+        // Remember to remove the listener when you're done!
+        tasks.removeAllListeners();
+      // :emphasize-end:
+        // Call the close() method when done with a realm instance to avoid memory leaks.
+        realm.close();
+      };
+    });
+  }, []);
+
+  return (
+    <>
+      {tasks.map(task => (
+        <Text key={task.name}>{task.name}</Text>
+      ))}
+    </>
+  );
+};
+// :code-block-end:
+export default TaskList;

examples/node/jest.config.js

@@ -6,27 +6,21 @@ module.exports = {
   projects: [
     {
       displayName: "JavaScript",
-      moduleFileExtensions: ['js'],
-      testMatch: [
-        "<rootDir>/Examples/**/*.js",
-      ],
-      setupFilesAfterEnv: [
-        '<rootDir>/testSetup.js',
-      ],
+      moduleFileExtensions: ["js"],
+      testMatch: ["<rootDir>/Examples/**/*.js"],
+      setupFilesAfterEnv: ["<rootDir>/testSetup.js"],
+      modulePathIgnorePatterns: ["<rootDir>/Examples/rn"],
     },
     {
       displayName: "TypeScript",
-      moduleFileExtensions: ['ts', 'js'],
-      preset: 'ts-jest/presets/js-with-ts',
-      setupFilesAfterEnv: [
-        '<rootDir>/testSetup.js',
-      ],
-      testMatch: [
-        "<rootDir>/Examples/**/*.ts",
-      ],
-      "transform": {
-        "^.+\\.ts$": "ts-jest"
+      moduleFileExtensions: ["ts", "js"],
+      preset: "ts-jest/presets/js-with-ts",
+      setupFilesAfterEnv: ["<rootDir>/testSetup.js"],
+      modulePathIgnorePatterns: ["<rootDir>/Examples/rn"],
+      testMatch: ["<rootDir>/Examples/**/*.ts"],
+      transform: {
+        "^.+\\.ts$": "ts-jest",
       },
     },
-  ]
+  ],
 };

source/examples/generated/rn/using-change-listeners-functional-component.codeblock.using-change-listeners-functional-component.js.code-block.rst

@@ -0,0 +1,48 @@
+.. code-block:: javascript
+   :emphasize-lines: 3, 12-15, 28-31
+
+   const TaskList = () => {
+     const [tasks, setTasks] = useState([]);
+     useEffect(() => {
+       Realm.open({
+         schema: [TaskSchema], // predefined schema
+       }).then(realm => {
+
+         const tasks = realm.objects('Task');
+         // set state to the initial value of your realm objects
+         setTasks([...tasks]);
+
+         tasks.addListener(() => {
+           // update state of tasks to the updated value
+           setTasks([...tasks]);
+         });
+
+         realm.write(() => {
+           // the following tasks will trigger the change listener and update the UI
+           realm.create('Task', {
+             name: 'Go to the grocery store',
+           });
+           realm.create('Task', {
+             name: 'Exercise in the gym',
+           });
+         });
+
+         // cleanup function
+         return () => {
+           const tasks = realm.objects('Task');
+           // Remember to remove the listener when you're done!
+           tasks.removeAllListeners();
+           // Call the close() method when done with a realm instance to avoid memory leaks.
+           realm.close();
+         };
+       });
+     }, []);
+
+     return (
+       <>
+         {tasks.map(task => (
+           <Text key={task.name}>{task.name}</Text>
+         ))}
+       </>
+     );
+   };

source/sdk/react-native/examples.txt

@@ -10,6 +10,7 @@ Usage Examples - React Native SDK
    Open & Close a Local Realm </sdk/react-native/examples/open-and-close-a-local-realm>
    Read & Write Data </sdk/react-native/examples/read-and-write-data>
    React to Changes </sdk/react-native/examples/react-to-changes>
+   Use Change Listeners In Components </sdk/react-native/examples/use-change-listeners-in-components>
    Modify an Object Schema </sdk/react-native/examples/modify-an-object-schema>
    Connect to a MongoDB Realm Backend App </sdk/react-native/examples/connect-to-mongodb-realm-backend-app>
    Authenticate Users </sdk/react-native/examples/authenticate-users>
@@ -26,6 +27,7 @@ Realm-Database (Non-Sync)
 - :doc:`Open & Close a Local Realm </sdk/react-native/examples/open-and-close-a-local-realm>`
 - :doc:`Read & Write Data </sdk/react-native/examples/read-and-write-data>`
 - :doc:`React to Changes </sdk/react-native/examples/react-to-changes>`
+- :doc:`Use Change Listeners In Components </sdk/react-native/examples/use-change-listeners-in-components>`
 - :doc:`Modify an Object Schema </sdk/react-native/examples/modify-an-object-schema>`
 
 Application Services (Sync)

source/sdk/react-native/examples/react-to-changes.txt

@@ -89,4 +89,9 @@ call the instance's ``removeAllListeners()`` function:
 - :js-sdk:`Realm.Object.removeAllListeners() <Realm.Object.html#removeAllListeners>`
 
 .. literalinclude:: /examples/generated/node/react-to-changes.codeblock.react-to-changes-remove-all-listeners.js
-  :language: javascript
+  :language: javascript
+
+Registering and Removing Listeners From Your React Components
+-------------------------------------------------------------
+To learn how to register and remove listeners within your application, check out
+the documentation on how to :ref:`use change listeners in React components <react-native-use-listeners-in-components>`.

source/sdk/react-native/examples/use-change-listeners-in-components.txt

@@ -0,0 +1,63 @@
+.. _react-native-use-listeners-in-components:
+
+=====================================================
+Use Change Listeners In Components - React Native SDK
+=====================================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+
+Overview
+--------
+You can copy your {+service-short+} objects to your component's :reactjs:`state
+<docs/state-and-lifecycle.html>`. However, since {+service-short+} objects are
+live and automatically update in response to changes, you must update the copies
+of them to prevent your UI from drifting out of date with underlying data. You can do this by
+registering a :ref:`change listener <react-native-change-notifications>` in your
+component and updating the state variable when that listener fires.  
+
+.. warning::
+
+   Failing to update copies of {+service-short+} objects leads to out-of-date data displayed
+   in your UI as objects are deleted or changed.
+
+Procedure
+~~~~~~~~~
+To keep your UI up-to-date with changes to underlying {+service-short+} objects,
+declare a state variable for your {+service-short+} objects using the
+:reactjs:`useState() <docs/hooks-state.html>` hook.
+
+Within the :reactjs:`useEffect() <docs/hooks-effect.html>` hook, set the state variable to
+the initial value of your objects. Then declare a change listener on the
+{+service-short+} objects.
+
+Finally, return an anonymous cleanup function that you can use to remove the
+change listener and close the {+service-short+}. React.js will call this cleanup function when
+the component unmounts.
+
+.. example::
+
+   In the following example, a developer creates an application to manage
+   tasks. Within a ``TaskList`` component, define a state variable called
+   ``tasks``. The developer wants to display the initial list of tasks already
+   saved in the database after the component mounts. To do this, they :ref:`open
+   a realm <react-native-open-a-local-realm>` within a ``useEffect`` function and
+   then set the ``tasks`` state variable to the initial value of the ``tasks``
+   stored in the {+service-short+}. 
+
+   The developer registers a change listener to update the state variable when
+   changes to the ``tasks`` have been made in the {+client-database+}. The
+   developer then creates some additional tasks. 
+
+   Once the component unmounts, the developer wants to unregister the change
+   listener. To do this, they return a cleanup function and call ``task.removeAllListeners()``. 
+   Finally they :ref:`close the realm <react-native-close-a-realm>`.
+   
+   .. include:: /examples/generated/rn/using-change-listeners-functional-component.codeblock.using-change-listeners-functional-component.js.code-block.rst
+