From 76f874916b4b4dabef3065b81315a4948a234a87 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 15:43:08 -0400 Subject: [PATCH 01/40] testing providers and hooks --- source/frameworks.txt | 12 +++++---- source/frameworks/react.txt | 30 +++++++++++++++++++++ source/frameworks/react/providers-hooks.txt | 25 +++++++++++++++++ 3 files changed, 62 insertions(+), 5 deletions(-) create mode 100644 source/frameworks/react.txt create mode 100644 source/frameworks/react/providers-hooks.txt diff --git a/source/frameworks.txt b/source/frameworks.txt index eb5aeacefe..e149bc4ed1 100644 --- a/source/frameworks.txt +++ b/source/frameworks.txt @@ -13,19 +13,21 @@ Build with Frameworks .. toctree:: :titlesonly: + React + React Native + Next.js Electron Flutter Maui - .NET - React Native SwiftUI The following pages contain information about building with specific frameworks using Atlas Device SDK: +- :ref:`sdks-build-with-react` +- :ref:`sdks-build-with-react-native` +- :ref:`sdks-build-with-nextjs` - :ref:`sdks-build-with-electron` - :ref:`sdks-build-with-flutter` - :ref:`sdks-build-with-maui` -- :ref:`sdks-build-with-dotnet` -- :ref:`sdks-build-with-react-native` -- :ref:`sdks-build-with-swiftui` +- :ref:`sdks-build-with-swiftui` \ No newline at end of file diff --git a/source/frameworks/react.txt b/source/frameworks/react.txt new file mode 100644 index 0000000000..910f2507ff --- /dev/null +++ b/source/frameworks/react.txt @@ -0,0 +1,30 @@ +.. _sdks-build-with-react: + +================ +Build with React +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. toctree:: + :titlesonly: + + Install + Quick Start + Providers & Hooks + Model Data + Open & Manage Database Files + Read & Write Data + React to Changes + Access Atlas + Manage Users + Sync Data + Test & Debug + API Reference + +Placeholder page for information about building with React. (This may +be a directory depending on how much content we have/need.) \ No newline at end of file diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt new file mode 100644 index 0000000000..0760751669 --- /dev/null +++ b/source/frameworks/react/providers-hooks.txt @@ -0,0 +1,25 @@ +.. _sdks-react-providers-hooks: + +================= +Providers & Hooks +================= + +.. meta:: + :description: Develop apps using the Providers and Hooks available in the @realm/react library. + :keywords: Realm, Javascript SDK, React, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: javascript + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +test lol \ No newline at end of file From 22f66f3b70523c3c4bec3420ba37e26a3a8da5dd Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 16:01:01 -0400 Subject: [PATCH 02/40] initial providers and hooks page --- source/frameworks/react/providers-hooks.txt | 59 ++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 0760751669..6c88a65983 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -22,4 +22,61 @@ Providers & Hooks :depth: 2 :class: singlecol -test lol \ No newline at end of file + +The @realm/react library offers custom React components called Providers to simplify the app +development process. + +Atlas App Services offers pathways that support user creation, user authentication, and data +management. However, manually integrating these processes into your app introduces a new layer +of complexity. Instead of manually integrating these features, you can use the RealmProvider, +AppProvider, and UserProvider to manage the logic needed to run your app. + +- RealmProvider provides access to the configured realm +- AppProvider provides access to the App Services App +- UserProvider provides access to the logged-in user object + +These Providers are available to all frameworks used to build with the JavaScript SDK. + +Providers as Components +----------------------- + +Components are the basic building blocks of React applications and resemble JavaScript +functions. They allow you to separate your app’s functionality and views into smaller chunks +you can manipulate and assemble to create the complete app. You call components using html +opening and closing tags, and they take parameters called Props as input. Providers are +specialized components and so you can interact with them as you would any other component. + +You can nest components within another’s tags, creating a parent-child relationship between +them. The props passed into the parent component help create the context that its child +components need to execute their logic. Child components can access this context using hooks. + +Hooks +----- + +Hooks act as functions you can use to access states in your app. React has built-in hooks you +can import and use in any component. The @realm/react library also has custom hooks for each +provider you can import. You can use a Provider’s hooks within its component and any of its +child components. There are two important rules to consider when working with hooks: + +Hooks can only be used at the top level of a React component. +Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions. + +To use a state in a component you’re creating, call the related hook at the top of your +component definition and save the return value to a variable. This variable containing the +state can now be used throughout the component. + +Wrapping your App +----------------- + +Most applications built using the @realm/react library organize their app by using an App +component. You build your app’s functionality in the App component by assembling the custom +components you make. To make your Providers context available to your entire app, you can +create an App Wrapper by nesting the Providers in each other, then netting the App component in +this wrapper. + +You *must* nest the Providers as shown below when making a wrapper to ensure each Provider can +access the context it needs to function. + +[insert heading here :P] (maybe a tab switch option?) +Below is a brief overview of the Props and Hooks available for each Provider. For more details, +please see the API Reference for each provider. \ No newline at end of file From b0922188ac8e28247a510079a0590717d487a2b0 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 16:08:00 -0400 Subject: [PATCH 03/40] formatting --- source/frameworks/react/providers-hooks.txt | 22 +++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 6c88a65983..65dc10228c 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -23,19 +23,19 @@ Providers & Hooks :class: singlecol -The @realm/react library offers custom React components called Providers to simplify the app +The ``@realm/react`` library offers custom React components called Providers to simplify the app development process. Atlas App Services offers pathways that support user creation, user authentication, and data management. However, manually integrating these processes into your app introduces a new layer -of complexity. Instead of manually integrating these features, you can use the RealmProvider, -AppProvider, and UserProvider to manage the logic needed to run your app. +of complexity. Instead of manually integrating these features, you can use the the Providers +to manage the logic needed to run your app. -- RealmProvider provides access to the configured realm -- AppProvider provides access to the App Services App -- UserProvider provides access to the logged-in user object +- ``RealmProvider`` provides access to the configured realm +- ``AppProvider`` provides access to the App Services App +- ``UserProvider`` provides access to the logged-in user object -These Providers are available to all frameworks used to build with the JavaScript SDK. +The Providers are available to all frameworks used to build with the JavaScript SDK. Providers as Components ----------------------- @@ -54,7 +54,7 @@ Hooks ----- Hooks act as functions you can use to access states in your app. React has built-in hooks you -can import and use in any component. The @realm/react library also has custom hooks for each +can import and use in any component. The ``@realm/react`` library also has custom hooks for each provider you can import. You can use a Provider’s hooks within its component and any of its child components. There are two important rules to consider when working with hooks: @@ -68,7 +68,7 @@ state can now be used throughout the component. Wrapping your App ----------------- -Most applications built using the @realm/react library organize their app by using an App +Most applications built using the ``@realm/react`` library organize their app by using an App component. You build your app’s functionality in the App component by assembling the custom components you make. To make your Providers context available to your entire app, you can create an App Wrapper by nesting the Providers in each other, then netting the App component in @@ -77,6 +77,8 @@ this wrapper. You *must* nest the Providers as shown below when making a wrapper to ensure each Provider can access the context it needs to function. -[insert heading here :P] (maybe a tab switch option?) +Props and Hooks +--------------- + Below is a brief overview of the Props and Hooks available for each Provider. For more details, please see the API Reference for each provider. \ No newline at end of file From 61afc28ed60d0784bbad7f613434ee3edb984a37 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 16:48:34 -0400 Subject: [PATCH 04/40] re-formatted --- examples/web/src/__tests__/providers-hooks.js | 16 ++++++++ source/frameworks/react/providers-hooks.txt | 38 +++++++++++-------- 2 files changed, 38 insertions(+), 16 deletions(-) create mode 100644 examples/web/src/__tests__/providers-hooks.js diff --git a/examples/web/src/__tests__/providers-hooks.js b/examples/web/src/__tests__/providers-hooks.js new file mode 100644 index 0000000000..e0ea522103 --- /dev/null +++ b/examples/web/src/__tests__/providers-hooks.js @@ -0,0 +1,16 @@ +import React from "react"; +import * as Realm from "realm-web"; +import { APP_ID } from "../realm.config.json"; +import {AppProvider, UserProvider, RealmProvider} from "@realm/react"; + +export const AppWrapper = () => { + return ( + {/* pass in your App ID as a prop */} + + + + + + + ); + }; \ No newline at end of file diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 65dc10228c..33f6024f30 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -31,47 +31,53 @@ management. However, manually integrating these processes into your app introduc of complexity. Instead of manually integrating these features, you can use the the Providers to manage the logic needed to run your app. -- ``RealmProvider`` provides access to the configured realm -- ``AppProvider`` provides access to the App Services App -- ``UserProvider`` provides access to the logged-in user object +- ``RealmProvider`` grants access to the configured realm +- ``AppProvider`` grants access to the App Services App +- ``UserProvider`` grants access to the logged-in user object The Providers are available to all frameworks used to build with the JavaScript SDK. -Providers as Components ------------------------ +Components and Hooks +-------------------- + +Providers are specialized React components, so you can interact with them as you would any other +component. As with components, you can use hooks to access states from Providers. + +Components +~~~~~~~~~~ Components are the basic building blocks of React applications and resemble JavaScript functions. They allow you to separate your app’s functionality and views into smaller chunks you can manipulate and assemble to create the complete app. You call components using html -opening and closing tags, and they take parameters called Props as input. Providers are -specialized components and so you can interact with them as you would any other component. +opening and closing tags, and they take parameters called Props as input. You can nest components within another’s tags, creating a parent-child relationship between them. The props passed into the parent component help create the context that its child components need to execute their logic. Child components can access this context using hooks. Hooks ------ +~~~~~ Hooks act as functions you can use to access states in your app. React has built-in hooks you can import and use in any component. The ``@realm/react`` library also has custom hooks for each provider you can import. You can use a Provider’s hooks within its component and any of its child components. There are two important rules to consider when working with hooks: -Hooks can only be used at the top level of a React component. -Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions. +- Hooks can only be used at the top level of a React component. +- Hooks can only be called in a React component or a custom hook, not in regular JavaScript + functions. To use a state in a component you’re creating, call the related hook at the top of your -component definition and save the return value to a variable. This variable containing the -state can now be used throughout the component. +component definition and save the return value to a variable. You can then use this variable +containing the state throughout your component. -Wrapping your App ------------------ +Using Providers +--------------- -Most applications built using the ``@realm/react`` library organize their app by using an App +Most applications built using the ``@realm/react`` library organize their app in an App component. You build your app’s functionality in the App component by assembling the custom components you make. To make your Providers context available to your entire app, you can -create an App Wrapper by nesting the Providers in each other, then netting the App component in +create an App Wrapper by nesting the Providers in each other, then nesting the App component in this wrapper. You *must* nest the Providers as shown below when making a wrapper to ensure each Provider can From 6cb92c3851321fc51c503287d83cb495ee7f19c4 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 16:58:13 -0400 Subject: [PATCH 05/40] re-formatted --- source/frameworks/react/providers-hooks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 33f6024f30..5318fd151a 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -51,7 +51,7 @@ functions. They allow you to separate your app’s functionality and views into you can manipulate and assemble to create the complete app. You call components using html opening and closing tags, and they take parameters called Props as input. -You can nest components within another’s tags, creating a parent-child relationship between +You can nest components within another components tags, creating a parent-child relationship between them. The props passed into the parent component help create the context that its child components need to execute their logic. Child components can access this context using hooks. From 5ca9db118209b882a7fdab6771e8f65a987b1b5d Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 17:37:59 -0400 Subject: [PATCH 06/40] added code example --- examples/web/src/__tests__/providers-hooks.js | 17 ++++++++++---- .../providers-hooks.snippet.use-providers.js | 15 ++++++++++++ source/frameworks/react/providers-hooks.txt | 23 +++++++++++-------- 3 files changed, 41 insertions(+), 14 deletions(-) create mode 100644 source/examples/generated/react/providers-hooks.snippet.use-providers.js diff --git a/examples/web/src/__tests__/providers-hooks.js b/examples/web/src/__tests__/providers-hooks.js index e0ea522103..42cc54ea59 100644 --- a/examples/web/src/__tests__/providers-hooks.js +++ b/examples/web/src/__tests__/providers-hooks.js @@ -1,16 +1,25 @@ +// :snippet-start:use-providers import React from "react"; -import * as Realm from "realm-web"; import { APP_ID } from "../realm.config.json"; -import {AppProvider, UserProvider, RealmProvider} from "@realm/react"; +import { AppProvider, UserProvider, RealmProvider, useRealm, useUser } from "@realm/react"; export const AppWrapper = () => { return ( {/* pass in your App ID as a prop */} - + {/* call any app components here */} ); - }; \ No newline at end of file + }; +// :snippet-end: + +// export const TestComponent = () => { +// const user = useUser(); // hooks called at top level of a component declaration + +// return ( +// user?.id +// ); +// }; \ No newline at end of file diff --git a/source/examples/generated/react/providers-hooks.snippet.use-providers.js b/source/examples/generated/react/providers-hooks.snippet.use-providers.js new file mode 100644 index 0000000000..c6f6567bb6 --- /dev/null +++ b/source/examples/generated/react/providers-hooks.snippet.use-providers.js @@ -0,0 +1,15 @@ +import React from "react"; +import { APP_ID } from "../realm.config.json"; +import { AppProvider, UserProvider, RealmProvider, useRealm, useUser } from "@realm/react"; + +export const AppWrapper = () => { + return ( + {/* pass in your App ID as a prop */} + + + {/* call any app components here */} + + + + ); + }; diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 5318fd151a..d24fced625 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -67,22 +67,25 @@ child components. There are two important rules to consider when working with ho - Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions. -To use a state in a component you’re creating, call the related hook at the top of your -component definition and save the return value to a variable. You can then use this variable -containing the state throughout your component. - Using Providers --------------- -Most applications built using the ``@realm/react`` library organize their app in an App -component. You build your app’s functionality in the App component by assembling the custom -components you make. To make your Providers context available to your entire app, you can -create an App Wrapper by nesting the Providers in each other, then nesting the App component in -this wrapper. +To make your Providers context available to your entire app, you can create an App Wrapper by +nesting the Providers in each other. You can then nest any of your custom components in this wrapper. +Most applications built using the ``@realm/react`` library assemble their custom components in +an ``App`` component for better organization. + +. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js -You *must* nest the Providers as shown below when making a wrapper to ensure each Provider can +You *must* nest the Providers as shown when making a wrapper to ensure each Provider can access the context it needs to function. +To use a state in a component you’re creating, call the related hook at the top of your +component definition and save the return value to a variable. You can then use this variable +containing the state throughout your component. + +``CODE EXAMPLE COMING`` + Props and Hooks --------------- From da0e86dc3afd4c51a03a2fb707adfc1d134710e1 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 17:37:59 -0400 Subject: [PATCH 07/40] added code example --- source/frameworks/react/providers-hooks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index d24fced625..9229284e66 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -75,7 +75,7 @@ nesting the Providers in each other. You can then nest any of your custom compon Most applications built using the ``@realm/react`` library assemble their custom components in an ``App`` component for better organization. -. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js +.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js You *must* nest the Providers as shown when making a wrapper to ensure each Provider can access the context it needs to function. From 44d996d0a294162a1d08df41143af0e34125fcb7 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 17:42:42 -0400 Subject: [PATCH 08/40] test --- source/frameworks/react/providers-hooks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 9229284e66..d24fced625 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -75,7 +75,7 @@ nesting the Providers in each other. You can then nest any of your custom compon Most applications built using the ``@realm/react`` library assemble their custom components in an ``App`` component for better organization. -.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js +. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js You *must* nest the Providers as shown when making a wrapper to ensure each Provider can access the context it needs to function. From dae36cefae2c7efc10683a817097e8538d58d843 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 17:45:07 -0400 Subject: [PATCH 09/40] lol --- source/frameworks/react/providers-hooks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index d24fced625..9229284e66 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -75,7 +75,7 @@ nesting the Providers in each other. You can then nest any of your custom compon Most applications built using the ``@realm/react`` library assemble their custom components in an ``App`` component for better organization. -. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js +.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js You *must* nest the Providers as shown when making a wrapper to ensure each Provider can access the context it needs to function. From 9b15971d2ab8389f79bdd91e9c8b1e6ae057277b Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 18:00:25 -0400 Subject: [PATCH 10/40] added api references --- source/frameworks/react/api-reference.txt | 13 + .../react/api-reference/app-provider.txt | 659 ++++++++++++++++++ .../react/api-reference/realm-provider.txt | 293 ++++++++ .../react/api-reference/user-provider.txt | 83 +++ source/frameworks/react/providers-hooks.txt | 8 +- 5 files changed, 1054 insertions(+), 2 deletions(-) create mode 100644 source/frameworks/react/api-reference.txt create mode 100644 source/frameworks/react/api-reference/app-provider.txt create mode 100644 source/frameworks/react/api-reference/realm-provider.txt create mode 100644 source/frameworks/react/api-reference/user-provider.txt diff --git a/source/frameworks/react/api-reference.txt b/source/frameworks/react/api-reference.txt new file mode 100644 index 0000000000..a5c57e30d9 --- /dev/null +++ b/source/frameworks/react/api-reference.txt @@ -0,0 +1,13 @@ +.. _sdks-react-api-reference: + +=================================== +API Reference +=================================== + +.. toctree:: + :titlesonly: + + JavaScript SDK Reference (@realm) + RealmProvider (@realm/react) + AppProvider (@realm/react) + UserProvider (@realm/react) \ No newline at end of file diff --git a/source/frameworks/react/api-reference/app-provider.txt b/source/frameworks/react/api-reference/app-provider.txt new file mode 100644 index 0000000000..ead05c1f68 --- /dev/null +++ b/source/frameworks/react/api-reference/app-provider.txt @@ -0,0 +1,659 @@ +.. _react-app-provider: + +========================== +AppProvider (@realm/react) +========================== + +.. meta:: + :description: Learn how to use the AppProvider ReactElement hooks to work with an App Services App. + :keywords: code example + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. code:: typescript + :copyable: false + :caption: Type signature + + AppProvider(props, context?): null | ReactElement + +Components nested within ``AppProvider`` can access your App Services App +and use the ``AppProvider`` hooks. + +Props +----- + +All properties of :realm-react-sdk:`AppConfiguration +` can be passed as props to ``AppProvider``. + +Configure AppProvider +--------------------- + +To set up your App client, pass the App ID string +to the ``id`` prop of the ``AppProvider``. +Wrap any components that need to access the App with ``AppProvider``. + +.. literalinclude:: /examples/generated/react-native/ts/app-provider.test.snippet.app-provider.tsx + :language: typescript + +.. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst + +Hooks Used with AppProvider +--------------------------- + +.. _react-native-use-auth: + +useAuth() +~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useAuth(): UseAuth + +``useAuth`` has an authentication method for every App Services +authentication provider. + +result +`````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + result: AuthResult + +Result of authentication hook operation. For example, ``result.operation`` gives +you the name of the current operation. + +*Enum values* + +- ``state``. Can be "not-started", "pending", "success", "error". +- ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. +- ``pending``. Can be ``true`` or ``false``. +- ``success``. Can be ``true`` or ``false``. +- ``error``. Error-based object or undefined. + +logIn(credentials) +`````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logIn(credentials: Realm.Credentials): void + +*Parameters* + +- ``credentials``. A Realm credential supplied by any supported Realm + authentication. + +*Example* + +Logs in a user with any authentication mechanism supported by +Realm. If called when a user is logged in, the current user switches to +the new user. Usually, it's better to use the more specific login +methods. + +.. code:: typescript + + const {logIn, result} = useAuth(); + + useEffect(() => logIn(Realm.Credentials.anonymous()), []); + + if(result.pending) { + return () + } + + if(result.error) { + return () + } + + if(result.success) { + return () + } + //... + +logInWithAnonymous() +```````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithAnonymous(): void + +*Example* + +Log in with the anonymous authentication provider. + +.. code:: typescript + + const {logInWithAnonymous, result} = useAuth(); + const performLogin = () => { + logInWithAnonymous(); + }; + +logInWithApiKey(key) +```````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithApiKey(key: string): void + +*Parameters* + +- ``key``. A string that is linked to an App Services user. + +*Example* + +Log in with an API key. + +.. code:: typescript + + const {logInWithApiKey, result} = useAuth(); + const performLogin = () => { + const key = getApiKey(); // user defined function + logInWithApiKey(key); + }; + +logInWithEmailPassword(credentials) +``````````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithEmailPassword(credentials: { + email: string; + password: string; + }): void + +*Parameters* + +- ``credentials``. An object with ``email`` and ``password`` fields. + +*Example* + +Log in with Email/Password. + +.. code:: typescript + + const {logInWithEmailPassword, result} = useAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performLogin = () => { + logInWithEmailPassword({email, password}); + }; + +logInWithJWT(credentials) +````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithJWT(token: string): void + +*Parameters* + +- ``credentials``. A string representation of a user's JWT. + +*Example* + +Log in with a JSON Web Token (JWT). + +.. code:: typescript + + const {logInWithJWT, result} = useAuth(); + + const performLogin = () => { + const token = authorizeWithCustomerProvider(); // user defined function + logInWithJWT(token); + }; + +logInWithGoogle(credentials) +```````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithGoogle(credentials: { + idToken: string; + } | { + authCode: string; + }): void; + +*Parameters* + +- ``credentials``. An object with an ``idToken`` or ``authCode`` field that + should contain the string token you get from Google Identity Services. + +*Example* + +Log in with Google. + +.. code:: typescript + + const {logInWithGoogle, result} = useAuth(); + + const performLogin = () => { + const token = getGoogleToken(); // user defined function + logInWithGoogle({idToken: token}); + }; + +logInWithApple(idToken) +``````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithApple(idToken: string): void; + +*Parameters* + +- ``idToken``. A string you get from the Apple SDK. + +*Example* + +Log in with Apple. + +.. code:: typescript + + const {logInWithApple, result} = useAuth(); + + const performLogin = () => { + const token = getAppleToken(); // user defined function + logInWithApple(token); + }; + +logInWithFacebook(accessToken) +`````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithFacebook(accessToken: string): void; + +*Parameters* + +- ``accessToken``. A string you get from the Facebook SDK. + +*Example* + +Log in with Facebook. + +.. code:: typescript + + const {logInWithFacebook, result} = useAuth(); + + const performLogin = () => { + const token = getFacebookToken(); // user defined function + logInWithFacebook(token); + }; + +logInWithFunction(payload) +`````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithFunction>(payload: PayloadType): void; + +*Parameters* + +- ``payload``. An object that contains user information you want to pass to + the App Services function that processes log in requests. + +*Example* + +Log in with a custom function. + +.. code:: typescript + + const {logInWithFunction, result} = useAuth(); + + const performLogin = () => { + const customPayload = getAuthParams(); // user defined arguments + logInWithFunction(customPayload); + }; + +logOut() +```````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logOut(): void; + +*Example* + +Logs out the current user. + +.. code:: typescript + + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } + +.. _react-native-use-emailpassword-auth: + +useEmailPasswordAuth() +~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + result: AuthResult + +Result of authentication hook operation. For example, ``result.operation`` gives +you the name of the current operation. + +*Enum values* + +- ``state``. Can be "not-started", "pending", "success", "error". +- ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. +- ``pending``. Can be ``true`` or ``false``. +- ``success``. Can be ``true`` or ``false``. +- ``error``. Error-based object or undefined. + +logIn(credentials) +`````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logIn(credentials: { email: string; password: string }): void; + +*Parameters* + +- ``credentials``. An object that contains ``email`` and ``password`` properties. + +*Example* + +Logs a user in using an email and password. You could also call +``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a +``Realm.User`` instance of the logged-in user. + +.. code:: typescript + + const {logIn, result} = useEmailPasswordAuth(); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performLogin = () => { + logIn({email, password}); + }; + + if(result.pending) { + return () + } + + if(result.error) { + return () + } + + if(result.success) { + return () + } + //... + +logOut() +```````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + logOut(): void; + +*Example* + +Logs out the current user. + +.. code:: typescript + + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } + +register(args) +`````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + register(args: { email: string; password: string }): void; + +*Parameters* + +- ``args``. An object that contains ``email`` and ``password`` properties. + +*Example* + +Registers a new user. Requires a user email and password. + +.. code:: typescript + + const {register, result} = useEmailPasswordAuth(); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performRegister = () => { + register({email, password}); + }; + +confirm(args) +````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + confirm(args: { token: string; tokenId: string }): void; + +*Parameters* + +- ``args``. An object that contains ``token`` and ``tokenId`` properties. + +*Example* + +Confirms a user account. Requires a ``token`` and ``tokenId``. + +.. code:: typescript + + const {confirm, result} = useEmailPasswordAuth(); + + const performConfirmation = () => { + confirm({token, tokenId}); + }; + +resendConfirmationEmail(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + resendConfirmationEmail(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Resends a confirmation email. + +.. code:: typescript + + const {resendConfirmationEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performResendConfirmationEmail = () => { + resendConfirmationEmail({email}); + }; + +retryCustomConfirmation(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + retryCustomConfirmation(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Retries confirmation with a custom function. + +.. code:: typescript + + const {retryCustomConfirmation, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performRetryCustomConfirmation = () => { + retryCustomConfirmation({email}); + }; + +sendResetPasswordEmail(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + sendResetPasswordEmail(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Sends a password reset email. + +.. code:: typescript + + const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performSendResetPasswordEmail = () => { + sendResetPasswordEmail({email}); + }; + +resetPassword(args) +``````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + resetPassword(args: { token: string; tokenId: string; password: string }): void; + +*Parameters* + +- ``args``. An object that contains ``token``, ``tokenId``, and ``password`` + properties. + +*Example* + +Resets a user's password. + +.. code:: typescript + + const {resetPassword, result} = useEmailPasswordAuth(); + const [password, setPassword] = useState(''); + + const performResetPassword = () => { + resetPassword({token, tokenId, password}); + }; + +callResetPasswordFunction(args, restArgs) +````````````````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + callResetPasswordFunction( + args: { + email: string; + password: string; + }, + ...restArgs: Args + ): void; + +*Parameters* + +- ``args``. An object that contains ``email`` and ``password`` properties. +- ``restArgs``. Additional arguments that you need to pass to your custom + reset password function. + +*Example* + +Calls your App Services backend password reset function. Can pass arguments to +the function as needed. + +.. code:: typescript + + const {callResetPasswordFunction, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performResetPassword = () => { + callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); + }; + +.. _react-native-use-app-hook: + +useApp() +~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useApp(): Realm.App + +*Example* + +The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` +instance. + +.. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst +.. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst + +*Returns* + +- ``Realm.App`` + An instance of the current ``Realm.App`` created by ``AppProvider``. \ No newline at end of file diff --git a/source/frameworks/react/api-reference/realm-provider.txt b/source/frameworks/react/api-reference/realm-provider.txt new file mode 100644 index 0000000000..1d37610c9c --- /dev/null +++ b/source/frameworks/react/api-reference/realm-provider.txt @@ -0,0 +1,293 @@ +.. _react-realm-provider: + +============================ +RealmProvider (@realm/react) +============================ + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. code:: typescript + :copyable: false + :caption: Type signature + + RealmProvider(props, context?): null | ReactElement + +Components nested within ``RealmProvider`` can access the configured realm +and use the ``RealmProvider`` hooks. + +Props +----- + +All properties of :realm-react-sdk:`BaseConfiguration +` can be passed as props. + +``RealmProvider`` has more props that define its behavior: + +- ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + + The fallback component to render while the Realm is opening. +- ``closeOnUnmount?: boolean`` + + Default is ``true``. If set to ``false``, realm will not close when the + component unmounts. +- ``realmRef?: React.MutableRefObject`` + + A ref to the realm instance. This is useful if you need to access the realm + instance outside of the scope of the realm. +- ``children: React.ReactNode`` + +Configure a Realm with RealmProvider +------------------------------------ + +You can configure a ``RealmProvider`` in two ways: + +- Import ``RealmProvider`` directly from ``@realm/react`` +- Use ``createRealmContext()`` to configure a ``RealmProvider`` and create hooks + +This section details how to configure a ``RealmProvider`` imported directly from +``@realm/react``. For information about using ``createRealmContext()``, refer +to :ref:`Create Context with createRealmContext() `. + +Object models are part of most realm configurations. To learn more about Realm and +data models, refer to :ref:`Define a Realm Object Model +`. + +.. tabs:: + + .. tab:: Configure realm with sync + :tabid: configure-sync-realm + + :ref:`RealmProvider ` is a wrapper + that exposes a realm to its child components. You configure your realm by + passing props to ``RealmProvider``. + + When ``RealmProvider`` is rendered, it opens the realm. This means that + the child components can't access the realm if rendering fails. + + In addition to ``RealmProvider``, you also need to configure + :ref:`AppProvider ` and :ref:`UserProvider + `. + + By default, Realm syncs all data from the server before returning anything. + If you want to sync data in the background, read :ref:`Configure a Synced + Realm While Offline `. + + To configure a synced realm: + + #. Import providers from ``@realm/react``. + #. Configure ``AppProvider``. + #. Configure ``UserProvider`` and nest it within ``AppProvider``. + #. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. + #. Pass your object models to the ``schema`` prop. + #. Add other :realm-react-sdk:`Configuration object ` + properties as props to ``RealmProvider``. + + You must set up a sync subscription. The example below uses an initial subscription, + but you can also set up subscriptions in ``RealmProvider`` child components. + + You must nest providers as in the following example: + + .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx + :language: javascript + + For more information about configuring a synced realm, refer to + :ref:`Configure a Synced Realm `. + + .. tab:: Configure realm without sync + :tabid: configure-non-sync-realm + + :ref:`RealmProvider ` is a wrapper + that exposes a realm to its child components. You configure your realm by + passing props to ``RealmProvider``. + + When ``RealmProvider`` is rendered, it opens the realm. This means that + the child components can't access the realm if rendering fails. + + To configure a non-synced realm: + + #. Import ``RealmProvider`` from ``@realm/react``. + #. Pass your object models to the ``schema`` prop. + #. Add other :realm-react-sdk:`Configuration object ` + properties as props to ``RealmProvider``. + + .. literalinclude:: /examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx + :language: typescript + +Configure More Than One Realm +----------------------------- + +When you import ``RealmProvider`` from ``@realm/react``, that Provider has a +specific context and is associated with a single realm. If you need to configure +more than one realm, use ``createRealmContext()`` to instantiate a new Provider +for each realm. + +If you import ``useRealm()``, ``useQuery()``, or ``useObject()`` directly from +``@realm/react``, those hooks use the default realm context. To work with more +than one realm, you need to destructure a new realm Provider and its associated +hooks from the result of ``createRealmContext()``. You should namespace providers +to avoid confusion about which Provider and hooks you're working with. + +For a detailed guide, refer to :ref:`Expose More Than One Realm +`. + +For details about ``createRealmContext()``, refer to "Create Context with +createRealmContext()" on this page. + +RealmProvider Hooks +------------------- + +.. _react-native-use-realm-hook: + +useRealm() +~~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useRealm(): Realm + +The ``useRealm()`` hook returns an opened realm instance. The realm instance +gives you access to realm methods and properties. For example, you can call +``realm.write()`` to add a realm object to your realm. + +To learn more about modifying Realm data, refer to :ref:`Write Transactions +`. + +.. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx + :language: typescript + :emphasize-lines: 3, 6-8, 15 + +*Returns* + +- ``Realm`` + Returns a realm instance. This is the realm created by the hook's parent, + ``RealmProvider``. + +.. _react-native-use-object-hook: + +useObject() +~~~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useObject(type, primaryKey): T & Realm.Object | null + +The ``useObject()`` hook returns a Realm object for a given +:ref:`primary key `. You can pass an object class +or the class name as a string and the primary key. + +The ``useObject()`` method returns null if the object doesn't exist or you have +deleted it. The hook will automatically subscribe to updates and rerender the +component using the hook on any change to the object. + +.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx + :language: typescript + +*Parameters* + +- ``type: string`` + A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. +- ``primaryKey: T[keyof T]`` + The primary key of the desired object. + +*Returns* + +- ``Realm.Object | null`` + A Realm Object or ``null`` if no object is found. + +.. _react-native-use-query-hook: + +useQuery() +~~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useQuery(type, query?, deps?): Realm.Results> + +The ``useQuery()`` hook returns a collection of realm objects of a given type. +These are the results of your query. A query can be an object class or the class +name as a string. + +The ``useQuery()`` method subscribes to updates to any objects in the collection +and rerenders the component using it on any change to the results. + +You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query +results. You should do this in the ``query`` argument of ``useQuery`` so that +they only run when there are changes in the dependency array. For more examples, +refer to the :ref:`CRUD - Read ` docs. + +.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx + :language: typescript + :emphasize-lines: 3-5, 8-14 + +*Parameters* + +- ``type: string`` + A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. +- ``query?: QueryCallback`` + A query function that can filter and sort query results. Builds on + ``useCallback`` to memoize the query function. +- ``deps?: DependencyList`` + A list of query function dependencies that's used to memoize + the query function. + +*Returns* + +- ``Realm.Results`` + A Realm Object or ``null`` if no object is found. + +.. _react-native-realm-context: + +Create Context with createRealmContext() +---------------------------------------- + +.. code:: typescript + :copyable: false + :caption: Type signature + + createRealmContext(realmConfig?): RealmContext + +Most of the time, you will only use ``createRealmContext()`` if you need to +configure more than one realm. Otherwise, you should import ``RealmProvider`` +and hooks directly from ``@realm/react``. + +The ``createRealmContext()`` method creates a :reactjs:`React Context +` object for a realm with a given +:realm-react-sdk:`Configuration `. The +``Context`` object contains the following: + +- A :reactjs:`Context Provider ` (referred to + as ``RealmProvider`` elsewhere) component that wraps around child components + and provides them with access to hooks. +- Various prebuilt :reactjs:`Hooks ` that access the + configured realm. + +For a detailed guide, refer to :ref:`Expose More Than One Realm +`. + +*Parameters* + +- ``realmConfig?: Realm.Configuration`` + All properties of :realm-react-sdk:`BaseConfiguration + ` can be used. + +*Returns* + +- ``RealmContext`` + An object containing a ``RealmProvider`` component, and the ``useRealm``, + ``useQuery`` and ``useObject`` hooks. \ No newline at end of file diff --git a/source/frameworks/react/api-reference/user-provider.txt b/source/frameworks/react/api-reference/user-provider.txt new file mode 100644 index 0000000000..00f5d232de --- /dev/null +++ b/source/frameworks/react/api-reference/user-provider.txt @@ -0,0 +1,83 @@ +.. _react-user-provider: + +=========================== +UserProvider (@realm/react) +=========================== + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. code:: typescript + :copyable: false + :caption: Type signature + + UserProvider(props): null | ReactElement + +Components nested within ``UserProvider`` can access the logged-in user object +and use the ``UserProvider`` hooks. + +Props +----- + +- ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + The fallback component to render if there is no authorized user. This can be + used to render a log in screen or otherwise handle authentication. + +Configure UserProvider +---------------------- + +Components wrapped by :realm-react-sdk:`AppProvider ` +can access the :realm-react-sdk:`useApp ` and +:realm-react-sdk:`useAuth ` hooks. These components only +render if ``AppProvider`` successfully connects to your App Services backend. + +Components wrapped by :realm-react-sdk:`UserProvider ` +can access authenticated users with the :realm-react-sdk:`useUser +` hook. These components only render if your app has an +authenticated user. + +To configure user authentication: + +#. Wrap all components that need to access App Services in ``AppProvider``. +#. Inside of ``AppProvider``, wrap all components that you want to have access + to an authenticated user with ``UserProvider``. +#. In ``UserProvider``, include a ``fallback`` prop with a component + that logs a user in. The app renders this component if there + is no authenticated user. + +.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.configure-user-provider.tsx.rst + +UserProvider Hooks +------------------ + +.. _react-native-use-user-hook: + +useUser() +~~~~~~~~~ + +.. code:: typescript + :copyable: false + :caption: Type signature + + useUser(): Realm.User + +The ``useUser()`` hook provides access to the logged-in user. For example, +you can use ``useUser()`` to log the current user out. + +When changes to the user object happen, this hook will rerender its parent +component. For example, if you call ``user.refreshCustomData`` to get updated +custom user data, the ``useUser()`` parent component will rerender. + +.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.log-user-out.tsx.rst + +*Returns* + +- ``Realm.User`` + An instance of the currently-authenticated Realm user. \ No newline at end of file diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 9229284e66..c32f3052ff 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -89,5 +89,9 @@ containing the state throughout your component. Props and Hooks --------------- -Below is a brief overview of the Props and Hooks available for each Provider. For more details, -please see the API Reference for each provider. \ No newline at end of file +For more detail about configuration each provider and to see the props and hooks available for +each, please refer their the API references: + +- :ref:`react-realm-provider` +- :ref:`react-user-provider` +- :ref:`react-app-provider` \ No newline at end of file From 574a12442d924c9c71f9e0fc463867151c1aa8e8 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Tue, 30 Jul 2024 16:47:08 -0400 Subject: [PATCH 11/40] first round of reviews --- source/frameworks/react/providers-hooks.txt | 126 ++++++++++++-------- source/frameworks/react/temp.txt | 95 +++++++++++++++ 2 files changed, 170 insertions(+), 51 deletions(-) create mode 100644 source/frameworks/react/temp.txt diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index c32f3052ff..ed16600935 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -22,76 +22,100 @@ Providers & Hooks :depth: 2 :class: singlecol +The ``@realm/react`` offers custom React components that eliminate the boilerplate needed to +develop a React app. The components leverage the Provider design pattern to manage user +creation, user authentication, and data management. -The ``@realm/react`` library offers custom React components called Providers to simplify the app -development process. +- ``RealmProvider``: Work with the configured database. -Atlas App Services offers pathways that support user creation, user authentication, and data -management. However, manually integrating these processes into your app introduces a new layer -of complexity. Instead of manually integrating these features, you can use the the Providers -to manage the logic needed to run your app. +- ``AppProvider``: Connect to your App Client for user authentication, only necessary when + using Device Sync. -- ``RealmProvider`` grants access to the configured realm -- ``AppProvider`` grants access to the App Services App -- ``UserProvider`` grants access to the logged-in user object +- ``UserProvider``: Access to the logged-in user object, only necessary when using Device Sync. The Providers are available to all frameworks used to build with the JavaScript SDK. -Components and Hooks --------------------- +Configure your Providers +------------------------ -Providers are specialized React components, so you can interact with them as you would any other -component. As with components, you can use hooks to access states from Providers. +Like all React components, you call Providers using html opening and closing tags. They take +parameters called Props as input, passed into the opening tag. -Components -~~~~~~~~~~ +Nesting components within each other creates a parent-child relationship between them. The +props passed into the parent component help create the context inherited by the components it +wraps. Thus, any component wrapped by the Providers can access their context. -Components are the basic building blocks of React applications and resemble JavaScript -functions. They allow you to separate your app’s functionality and views into smaller chunks -you can manipulate and assemble to create the complete app. You call components using html -opening and closing tags, and they take parameters called Props as input. +You can configure a ``RealmProvider`` in two ways: -You can nest components within another components tags, creating a parent-child relationship between -them. The props passed into the parent component help create the context that its child -components need to execute their logic. Child components can access this context using hooks. +- Import ``RealmProvider`` directly from ``@realm/react`` +- Use ``createRealmContext()`` to configure a ``Realm -Hooks -~~~~~ +This section details how to configure a ``RealmProvider`` imported directly from +``@realm/react`` to expose a single realm. For information about using +``createRealmContext()``, refer to :ref:`Create Context with createRealmContext() +`. For information about using +configuring more than one realm, refer to Expose More Than One Realm. -Hooks act as functions you can use to access states in your app. React has built-in hooks you -can import and use in any component. The ``@realm/react`` library also has custom hooks for each -provider you can import. You can use a Provider’s hooks within its component and any of its -child components. There are two important rules to consider when working with hooks: +``sentence about when you may need a synced vs non-synced realm`` -- Hooks can only be used at the top level of a React component. -- Hooks can only be called in a React component or a custom hook, not in regular JavaScript - functions. +.. tabs:: -Using Providers ---------------- + .. tab:: Configure realm with sync + :tabid: configure-sync-realm -To make your Providers context available to your entire app, you can create an App Wrapper by -nesting the Providers in each other. You can then nest any of your custom components in this wrapper. -Most applications built using the ``@realm/react`` library assemble their custom components in -an ``App`` component for better organization. + If you are developing an app using sync, you will need to use ``RealmProvider``, + ``AppProvider``, and ``UserProvider``. -.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js + By default, Realm syncs all data from the server before returning anything. If you want + to sync data in the background, read Configure a Synced Realm While Offline [link]. -You *must* nest the Providers as shown when making a wrapper to ensure each Provider can -access the context it needs to function. + To configure a synced realm: -To use a state in a component you’re creating, call the related hook at the top of your -component definition and save the return value to a variable. You can then use this variable -containing the state throughout your component. + #. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. + + #. Configure ``AppProvider``. -``CODE EXAMPLE COMING`` + Pass your App ID string to the ``id`` prop of the ``AppProvider``. + + #. Configure ``UserProvider`` and nest it within ``AppProvider``. -Props and Hooks ---------------- + Pass a component that logs a user in into the ``fallback`` prop. The app renders this component if there is no authenticated user. + + #. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. -For more detail about configuration each provider and to see the props and hooks available for -each, please refer their the API references: + Pass your object models to the ``schema`` prop. (link out) -- :ref:`react-realm-provider` -- :ref:`react-user-provider` -- :ref:`react-app-provider` \ No newline at end of file + Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. + + Add other Configuration object properties as props to ``RealmProvider``. + + Once your Providers have been configured, nest your app components within the ``RealmProvider``. + + You *must* nest the Providers and app components as described. This ensures each Provider can + access the context it needs to function and all your app components can access the App Client, authenticated user object, and opened realm. + + [Code example here] + + .. tab:: Configure realm without sync + :tabid: configure-non-sync-realm + + If you are developing an app without sync, you only need to configure your ``RealmProvider``. + + To configure a non-synced realm: + + #. Import ``RealmProvider`` from ``@realm/react``. + + #. Pass your object models to the ``schema`` prop. (link out) + + #. Add other Configuration object properties as props to ``RealmProvider`` + + Once your ``RealmProvider`` has been configured, nest your app components within it to + give them access to the realm opened. + + [code example - unsynced] + + +Working in your Providers +------------------------- + +[insert text here lol] \ No newline at end of file diff --git a/source/frameworks/react/temp.txt b/source/frameworks/react/temp.txt new file mode 100644 index 0000000000..6c95befa3f --- /dev/null +++ b/source/frameworks/react/temp.txt @@ -0,0 +1,95 @@ +================= +Providers & Hooks +================= + +.. meta:: + :description: Develop apps using the Providers and Hooks available in the @realm/react library. + :keywords: Realm, Javascript SDK, React, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: javascript + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + + +The ``@realm/react`` library offers custom React components called Providers to simplify the app +development process. + +Atlas App Services offers pathways that support user creation, user authentication, and data +management. However, manually integrating these processes into your app introduces a new layer +of complexity. Instead of manually integrating these features, you can use the the Providers +to manage the logic needed to run your app. + +- ``RealmProvider`` grants access to the configured realm +- ``AppProvider`` grants access to the App Services App +- ``UserProvider`` grants access to the logged-in user object + +The Providers are available to all frameworks used to build with the JavaScript SDK. + +Components and Hooks +-------------------- + +Providers are specialized React components, so you can interact with them as you would any other +component. As with components, you can use hooks to access states from Providers. + +Components +~~~~~~~~~~ + +Components are the basic building blocks of React applications and resemble JavaScript +functions. They allow you to separate your app’s functionality and views into smaller chunks +you can manipulate and assemble to create the complete app. You call components using html +opening and closing tags, and they take parameters called Props as input. + +You can nest components within another components tags, creating a parent-child relationship between +them. The props passed into the parent component help create the context that its child +components need to execute their logic. Child components can access this context using hooks. + +Hooks +~~~~~ + +Hooks act as functions you can use to access states in your app. React has built-in hooks you +can import and use in any component. The ``@realm/react`` library also has custom hooks for each +provider you can import. You can use a Provider’s hooks within its component and any of its +child components. There are two important rules to consider when working with hooks: + +- Hooks can only be used at the top level of a React component. +- Hooks can only be called in a React component or a custom hook, not in regular JavaScript + functions. + +Using Providers +--------------- + +To make your Providers context available to your entire app, you can create an App Wrapper by +nesting the Providers in each other. You can then nest any of your custom components in this wrapper. +Most applications built using the ``@realm/react`` library assemble their custom components in +an ``App`` component for better organization. + +.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js + +You *must* nest the Providers as shown when making a wrapper to ensure each Provider can +access the context it needs to function. + +To use a state in a component you’re creating, call the related hook at the top of your +component definition and save the return value to a variable. You can then use this variable +containing the state throughout your component. + +``CODE EXAMPLE COMING`` + +Props and Hooks +--------------- + +For more detail about configuration each provider and to see the props and hooks available for +each, please refer their the API references: + +- :ref:`react-realm-provider` +- :ref:`react-user-provider` +- :ref:`react-app-provider` \ No newline at end of file From 34b01903f174866a68ef69d78eaff52dd9851d94 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 10:37:13 -0400 Subject: [PATCH 12/40] added hooks --- source/frameworks/react/providers-hooks.txt | 771 +++++++++++++++++++- 1 file changed, 769 insertions(+), 2 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index ed16600935..90130ea7dc 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -86,7 +86,7 @@ configuring more than one realm, refer to Expose More Than One Realm. Pass your object models to the ``schema`` prop. (link out) Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. - + Add other Configuration object properties as props to ``RealmProvider``. Once your Providers have been configured, nest your app components within the ``RealmProvider``. @@ -118,4 +118,771 @@ configuring more than one realm, refer to Expose More Than One Realm. Working in your Providers ------------------------- -[insert text here lol] \ No newline at end of file +To use the Provider's context in your app's components, you can use hooks [link]. + +Hooks act as functions used to access states in your app. React offers built-in hooks you can +use either on their own or to build custom hooks. + +There are two important rules to consider when working with hooks: + +- Hooks can only be used at the top level of a React component. +- Hooks can only be called in a React component or a custom hook, not in regular JavaScript + functions. + +The ``@realm/react`` library has custom hooks for each Provider you can import and +use in any wrapped component. + +.. tabs:: + + .. tab:: RealmProvider Hooks + :tabid: realm-provider-hooks + + .. _react-native-use-realm-hook: + + useRealm() + ~~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useRealm(): Realm + + The ``useRealm()`` hook returns an opened realm instance. The realm instance + gives you access to realm methods and properties. For example, you can call + ``realm.write()`` to add a realm object to your realm. + + To learn more about modifying Realm data, refer to :ref:`Write Transactions + `. + + .. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx + :language: typescript + :emphasize-lines: 3, 6-8, 15 + + *Returns* + + - ``Realm`` + Returns a realm instance. This is the realm created by the hook's parent, + ``RealmProvider``. + + .. _react-native-use-object-hook: + + useObject() + ~~~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useObject(type, primaryKey): T & Realm.Object | null + + The ``useObject()`` hook returns a Realm object for a given + :ref:`primary key `. You can pass an object class + or the class name as a string and the primary key. + + The ``useObject()`` method returns null if the object doesn't exist or you have + deleted it. The hook will automatically subscribe to updates and rerender the + component using the hook on any change to the object. + + .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx + :language: typescript + + *Parameters* + + - ``type: string`` + A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. + - ``primaryKey: T[keyof T]`` + The primary key of the desired object. + + *Returns* + + - ``Realm.Object | null`` + A Realm Object or ``null`` if no object is found. + + .. _react-native-use-query-hook: + + useQuery() + ~~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useQuery(type, query?, deps?): Realm.Results> + + The ``useQuery()`` hook returns a collection of realm objects of a given type. + These are the results of your query. A query can be an object class or the class + name as a string. + + The ``useQuery()`` method subscribes to updates to any objects in the collection + and rerenders the component using it on any change to the results. + + You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query + results. You should do this in the ``query`` argument of ``useQuery`` so that + they only run when there are changes in the dependency array. For more examples, + refer to the :ref:`CRUD - Read ` docs. + + .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx + :language: typescript + :emphasize-lines: 3-5, 8-14 + + *Parameters* + + - ``type: string`` + A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. + - ``query?: QueryCallback`` + A query function that can filter and sort query results. Builds on + ``useCallback`` to memoize the query function. + - ``deps?: DependencyList`` + A list of query function dependencies that's used to memoize + the query function. + + *Returns* + + - ``Realm.Results`` + A Realm Object or ``null`` if no object is found. + + .. _react-native-realm-context: + + .. tab:: AppProvider Hooks + :tabid: app-provider-hooks + + .. _react-native-use-auth: + + useAuth() + ~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useAuth(): UseAuth + + ``useAuth`` has an authentication method for every App Services + authentication provider. + + result + `````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + result: AuthResult + + Result of authentication hook operation. For example, ``result.operation`` gives + you the name of the current operation. + + *Enum values* + + - ``state``. Can be "not-started", "pending", "success", "error". + - ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. + - ``pending``. Can be ``true`` or ``false``. + - ``success``. Can be ``true`` or ``false``. + - ``error``. Error-based object or undefined. + + logIn(credentials) + `````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logIn(credentials: Realm.Credentials): void + + *Parameters* + + - ``credentials``. A Realm credential supplied by any supported Realm + authentication. + + *Example* + + Logs in a user with any authentication mechanism supported by + Realm. If called when a user is logged in, the current user switches to + the new user. Usually, it's better to use the more specific login + methods. + + .. code:: typescript + + const {logIn, result} = useAuth(); + + useEffect(() => logIn(Realm.Credentials.anonymous()), []); + + if(result.pending) { + return () + } + + if(result.error) { + return () + } + + if(result.success) { + return () + } + //... + + logInWithAnonymous() + ```````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithAnonymous(): void + + *Example* + + Log in with the anonymous authentication provider. + + .. code:: typescript + + const {logInWithAnonymous, result} = useAuth(); + const performLogin = () => { + logInWithAnonymous(); + }; + + logInWithApiKey(key) + ```````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithApiKey(key: string): void + + *Parameters* + + - ``key``. A string that is linked to an App Services user. + + *Example* + + Log in with an API key. + + .. code:: typescript + + const {logInWithApiKey, result} = useAuth(); + const performLogin = () => { + const key = getApiKey(); // user defined function + logInWithApiKey(key); + }; + + logInWithEmailPassword(credentials) + ``````````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithEmailPassword(credentials: { + email: string; + password: string; + }): void + + *Parameters* + + - ``credentials``. An object with ``email`` and ``password`` fields. + + *Example* + + Log in with Email/Password. + + .. code:: typescript + + const {logInWithEmailPassword, result} = useAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performLogin = () => { + logInWithEmailPassword({email, password}); + }; + + logInWithJWT(credentials) + ````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithJWT(token: string): void + + *Parameters* + + - ``credentials``. A string representation of a user's JWT. + + *Example* + + Log in with a JSON Web Token (JWT). + + .. code:: typescript + + const {logInWithJWT, result} = useAuth(); + + const performLogin = () => { + const token = authorizeWithCustomerProvider(); // user defined function + logInWithJWT(token); + }; + + logInWithGoogle(credentials) + ```````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithGoogle(credentials: { + idToken: string; + } | { + authCode: string; + }): void; + + *Parameters* + + - ``credentials``. An object with an ``idToken`` or ``authCode`` field that + should contain the string token you get from Google Identity Services. + + *Example* + + Log in with Google. + + .. code:: typescript + + const {logInWithGoogle, result} = useAuth(); + + const performLogin = () => { + const token = getGoogleToken(); // user defined function + logInWithGoogle({idToken: token}); + }; + + logInWithApple(idToken) + ``````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithApple(idToken: string): void; + + *Parameters* + + - ``idToken``. A string you get from the Apple SDK. + + *Example* + + Log in with Apple. + + .. code:: typescript + + const {logInWithApple, result} = useAuth(); + + const performLogin = () => { + const token = getAppleToken(); // user defined function + logInWithApple(token); + }; + + logInWithFacebook(accessToken) + `````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithFacebook(accessToken: string): void; + + *Parameters* + + - ``accessToken``. A string you get from the Facebook SDK. + + *Example* + + Log in with Facebook. + + .. code:: typescript + + const {logInWithFacebook, result} = useAuth(); + + const performLogin = () => { + const token = getFacebookToken(); // user defined function + logInWithFacebook(token); + }; + + logInWithFunction(payload) + `````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logInWithFunction>(payload: PayloadType): void; + + *Parameters* + + - ``payload``. An object that contains user information you want to pass to + the App Services function that processes log in requests. + + *Example* + + Log in with a custom function. + + .. code:: typescript + + const {logInWithFunction, result} = useAuth(); + + const performLogin = () => { + const customPayload = getAuthParams(); // user defined arguments + logInWithFunction(customPayload); + }; + + logOut() + ```````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logOut(): void; + + *Example* + + Logs out the current user. + + .. code:: typescript + + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } + + .. _react-native-use-emailpassword-auth: + + useEmailPasswordAuth() + ~~~~~~~~~~~~~~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + result: AuthResult + + Result of authentication hook operation. For example, ``result.operation`` gives + you the name of the current operation. + + *Enum values* + + - ``state``. Can be "not-started", "pending", "success", "error". + - ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. + - ``pending``. Can be ``true`` or ``false``. + - ``success``. Can be ``true`` or ``false``. + - ``error``. Error-based object or undefined. + + logIn(credentials) + `````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logIn(credentials: { email: string; password: string }): void; + + *Parameters* + + - ``credentials``. An object that contains ``email`` and ``password`` properties. + + *Example* + + Logs a user in using an email and password. You could also call + ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a + ``Realm.User`` instance of the logged-in user. + + .. code:: typescript + + const {logIn, result} = useEmailPasswordAuth(); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performLogin = () => { + logIn({email, password}); + }; + + if(result.pending) { + return () + } + + if(result.error) { + return () + } + + if(result.success) { + return () + } + //... + + logOut() + ```````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + logOut(): void; + + *Example* + + Logs out the current user. + + .. code:: typescript + + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } + + register(args) + `````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + register(args: { email: string; password: string }): void; + + *Parameters* + + - ``args``. An object that contains ``email`` and ``password`` properties. + + *Example* + + Registers a new user. Requires a user email and password. + + .. code:: typescript + + const {register, result} = useEmailPasswordAuth(); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performRegister = () => { + register({email, password}); + }; + + confirm(args) + ````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + confirm(args: { token: string; tokenId: string }): void; + + *Parameters* + + - ``args``. An object that contains ``token`` and ``tokenId`` properties. + + *Example* + + Confirms a user account. Requires a ``token`` and ``tokenId``. + + .. code:: typescript + + const {confirm, result} = useEmailPasswordAuth(); + + const performConfirmation = () => { + confirm({token, tokenId}); + }; + + resendConfirmationEmail(args) + ````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + resendConfirmationEmail(args: { email: string }): void; + + *Parameters* + + - ``args``. An object that contains an ``email`` property. + + *Example* + + Resends a confirmation email. + + .. code:: typescript + + const {resendConfirmationEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performResendConfirmationEmail = () => { + resendConfirmationEmail({email}); + }; + + retryCustomConfirmation(args) + ````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + retryCustomConfirmation(args: { email: string }): void; + + *Parameters* + + - ``args``. An object that contains an ``email`` property. + + *Example* + + Retries confirmation with a custom function. + + .. code:: typescript + + const {retryCustomConfirmation, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performRetryCustomConfirmation = () => { + retryCustomConfirmation({email}); + }; + + sendResetPasswordEmail(args) + ````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + sendResetPasswordEmail(args: { email: string }): void; + + *Parameters* + + - ``args``. An object that contains an ``email`` property. + + *Example* + + Sends a password reset email. + + .. code:: typescript + + const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performSendResetPasswordEmail = () => { + sendResetPasswordEmail({email}); + }; + + resetPassword(args) + ``````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + resetPassword(args: { token: string; tokenId: string; password: string }): void; + + *Parameters* + + - ``args``. An object that contains ``token``, ``tokenId``, and ``password`` + properties. + + *Example* + + Resets a user's password. + + .. code:: typescript + + const {resetPassword, result} = useEmailPasswordAuth(); + const [password, setPassword] = useState(''); + + const performResetPassword = () => { + resetPassword({token, tokenId, password}); + }; + + callResetPasswordFunction(args, restArgs) + ````````````````````````````````````````` + + .. code:: typescript + :copyable: false + :caption: Type signature + + callResetPasswordFunction( + args: { + email: string; + password: string; + }, + ...restArgs: Args + ): void; + + *Parameters* + + - ``args``. An object that contains ``email`` and ``password`` properties. + - ``restArgs``. Additional arguments that you need to pass to your custom + reset password function. + + *Example* + + Calls your App Services backend password reset function. Can pass arguments to + the function as needed. + + .. code:: typescript + + const {callResetPasswordFunction, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performResetPassword = () => { + callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); + }; + + .. _react-native-use-app-hook: + + useApp() + ~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useApp(): Realm.App + + *Example* + + The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` + instance. + + .. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst + .. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst + + *Returns* + + - ``Realm.App`` + An instance of the current ``Realm.App`` created by ``AppProvider``. + + .. tab:: UserProvider Hooks + :tabid: user-provider-hooks + + .. _react-native-use-user-hook: + + useUser() + ~~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useUser(): Realm.User + + The ``useUser()`` hook provides access to the logged-in user. For example, + you can use ``useUser()`` to log the current user out. + + When changes to the user object happen, this hook will rerender its parent + component. For example, if you call ``user.refreshCustomData`` to get updated + custom user data, the ``useUser()`` parent component will rerender. + + .. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.log-user-out.tsx.rst + + *Returns* + + - ``Realm.User`` + An instance of the currently-authenticated Realm user. \ No newline at end of file From d79054376c705166d61e14948bdd3feb214f7f7b Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 11:43:43 -0400 Subject: [PATCH 13/40] small --- .../react/api-reference/realm-provider.txt | 6 +-- source/frameworks/react/providers-hooks.txt | 52 ++++++++++++++++--- 2 files changed, 49 insertions(+), 9 deletions(-) diff --git a/source/frameworks/react/api-reference/realm-provider.txt b/source/frameworks/react/api-reference/realm-provider.txt index 1d37610c9c..15f7d63e33 100644 --- a/source/frameworks/react/api-reference/realm-provider.txt +++ b/source/frameworks/react/api-reference/realm-provider.txt @@ -32,16 +32,16 @@ All properties of :realm-react-sdk:`BaseConfiguration ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the Realm is opening. -- ``closeOnUnmount?: boolean`` +- ``closeOnUnmount?: boolean`` Default is ``true``. If set to ``false``, realm will not close when the component unmounts. -- ``realmRef?: React.MutableRefObject`` +- ``realmRef?: React.MutableRefObject`` A ref to the realm instance. This is useful if you need to access the realm instance outside of the scope of the realm. + - ``children: React.ReactNode`` Configure a Realm with RealmProvider diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 90130ea7dc..4447ff3236 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -22,7 +22,7 @@ Providers & Hooks :depth: 2 :class: singlecol -The ``@realm/react`` offers custom React components that eliminate the boilerplate needed to +The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to develop a React app. The components leverage the Provider design pattern to manage user creation, user authentication, and data management. @@ -38,12 +38,52 @@ The Providers are available to all frameworks used to build with the JavaScript Configure your Providers ------------------------ -Like all React components, you call Providers using html opening and closing tags. They take -parameters called Props as input, passed into the opening tag. +Like all React components, you call Providers using html opening and closing tags. Nesting a +component within in another component's tags creates a parent-child relationship between them, +where child components can access the context created by its parent component. -Nesting components within each other creates a parent-child relationship between them. The -props passed into the parent component help create the context inherited by the components it -wraps. Thus, any component wrapped by the Providers can access their context. +Props +~~~~~ + +Components take parameters called Props as input, passed into the opening tag. The props passed +into a parent component help create the context inherited by the components it wraps. Each +Provider has different props you can use for configuration. + +.. tabs:: + + .. tab:: RealmProvider Props + :tabid: realm-provider-props + + All properties of :realm-react-sdk:`BaseConfiguration + ` can be passed as props. + + ``RealmProvider`` has more props that define its behavior: + + - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + The fallback component to render while the Realm is opening. + + - ``closeOnUnmount?: boolean`` + Default is ``true``. If set to ``false``, realm will not close when the + component unmounts. + + - ``realmRef?: React.MutableRefObject`` + A ref to the realm instance. This is useful if you need to access the realm + instance outside of the scope of the realm. + + - ``children: React.ReactNode`` + + .. tab:: AppProvider Props + :tabid: app-provider-props + + All properties of :realm-react-sdk:`AppConfiguration + ` can be passed as props to ``AppProvider``. + + .. tab:: UserProvider Props + :tabid: user-provider-props + + - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + The fallback component to render if there is no authorized user. This can be + used to render a log in screen or otherwise handle authentication. You can configure a ``RealmProvider`` in two ways: From b3aa8769609b86d6d9eea0833e4f1d597436d878 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 12:09:45 -0400 Subject: [PATCH 14/40] fleshed out and adjusted props --- source/frameworks/react/providers-hooks.txt | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 4447ff3236..c20a694b1d 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -54,8 +54,16 @@ Provider has different props you can use for configuration. .. tab:: RealmProvider Props :tabid: realm-provider-props - All properties of :realm-react-sdk:`BaseConfiguration - ` can be passed as props. + All properties of :realm-react-sdk:`BaseConfiguration ` can be passed as props. + + The most common BaseConfiguration properties used are: + + - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` + Specifies all the object schemas in this Realm. Required when first creating a Realm. + If omitted, the schema will be read from the existing Realm file. + + - ``sync?: SyncConfiguration`` + Configures a synced realm. ``RealmProvider`` has more props that define its behavior: @@ -78,6 +86,11 @@ Provider has different props you can use for configuration. All properties of :realm-react-sdk:`AppConfiguration ` can be passed as props to ``AppProvider``. + The most common AppConfiguration property used is: + + - ``id: string`` + Specifies the App ID. + .. tab:: UserProvider Props :tabid: user-provider-props @@ -114,7 +127,6 @@ configuring more than one realm, refer to Expose More Than One Realm. #. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. #. Configure ``AppProvider``. - Pass your App ID string to the ``id`` prop of the ``AppProvider``. #. Configure ``UserProvider`` and nest it within ``AppProvider``. From f0ab34e0d6c9de13d27bf74eceb671ba2f5df0ff Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 13:45:17 -0400 Subject: [PATCH 15/40] added alternate realm configurations --- source/frameworks/react/providers-hooks.txt | 96 ++++++++++++++++----- 1 file changed, 76 insertions(+), 20 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index c20a694b1d..7e7bba9bed 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -35,8 +35,8 @@ creation, user authentication, and data management. The Providers are available to all frameworks used to build with the JavaScript SDK. -Configure your Providers ------------------------- +Getting Started with Providers +------------------------------ Like all React components, you call Providers using html opening and closing tags. Nesting a component within in another component's tags creates a parent-child relationship between them, @@ -98,27 +98,21 @@ Provider has different props you can use for configuration. The fallback component to render if there is no authorized user. This can be used to render a log in screen or otherwise handle authentication. -You can configure a ``RealmProvider`` in two ways: - -- Import ``RealmProvider`` directly from ``@realm/react`` -- Use ``createRealmContext()`` to configure a ``Realm +Configure your Providers +~~~~~~~~~~~~~~~~~~~~~~~~ -This section details how to configure a ``RealmProvider`` imported directly from -``@realm/react`` to expose a single realm. For information about using -``createRealmContext()``, refer to :ref:`Create Context with createRealmContext() -`. For information about using -configuring more than one realm, refer to Expose More Than One Realm. +This section details how to configure and expose a single realm using a ``RealmProvider`` +imported directly from ``@realm/react``. For information about using ``createRealmContext()`` +to configure a realm or exposing more than one realm, refer to their respective sections below. -``sentence about when you may need a synced vs non-synced realm`` +If you are developing an app using sync, you will need to use all three Providers. If you are +developing an app without sync, you only need to use ``RealmProvider``. .. tabs:: .. tab:: Configure realm with sync :tabid: configure-sync-realm - If you are developing an app using sync, you will need to use ``RealmProvider``, - ``AppProvider``, and ``UserProvider``. - By default, Realm syncs all data from the server before returning anything. If you want to sync data in the background, read Configure a Synced Realm While Offline [link]. @@ -141,18 +135,21 @@ configuring more than one realm, refer to Expose More Than One Realm. Add other Configuration object properties as props to ``RealmProvider``. + You must set up a sync subscription. The example below uses an initial subscription, + but you can also set up subscriptions in ``RealmProvider`` child components. + + .. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst + Once your Providers have been configured, nest your app components within the ``RealmProvider``. - You *must* nest the Providers and app components as described. This ensures each Provider can - access the context it needs to function and all your app components can access the App Client, authenticated user object, and opened realm. + You *must* nest the Providers and app components as shown below to ensure each component + has access to its required context: [Code example here] .. tab:: Configure realm without sync :tabid: configure-non-sync-realm - If you are developing an app without sync, you only need to configure your ``RealmProvider``. - To configure a non-synced realm: #. Import ``RealmProvider`` from ``@realm/react``. @@ -937,4 +934,63 @@ use in any wrapped component. *Returns* - ``Realm.User`` - An instance of the currently-authenticated Realm user. \ No newline at end of file + An instance of the currently-authenticated Realm user. + +Create Context with createRealmContext() +---------------------------------------- + +.. code:: typescript + :copyable: false + :caption: Type signature + + createRealmContext(realmConfig?): RealmContext + +Most of the time, you will only use ``createRealmContext()`` if you need to +configure more than one realm. Otherwise, you should import ``RealmProvider`` +and hooks directly from ``@realm/react``. + +The ``createRealmContext()`` method creates a :reactjs:`React Context +` object for a realm with a given +:realm-react-sdk:`Configuration `. The +``Context`` object contains the following: + +- A :reactjs:`Context Provider ` (referred to + as ``RealmProvider`` elsewhere) component that wraps around child components + and provides them with access to hooks. +- Various prebuilt :reactjs:`Hooks ` that access the + configured realm. + +For a detailed guide, refer to :ref:`Expose More Than One Realm +`. + +*Parameters* + +- ``realmConfig?: Realm.Configuration`` + All properties of :realm-react-sdk:`BaseConfiguration + ` can be used. + +*Returns* + +- ``RealmContext`` + An object containing a ``RealmProvider`` component, and the ``useRealm``, + ``useQuery`` and ``useObject`` hooks. + +Configure More Than One Realm +----------------------------- + +When you import ``RealmProvider`` from ``@realm/react``, that Provider has a +specific context and is associated with a single realm. If you need to configure +more than one realm, use ``createRealmContext()`` to instantiate a new Provider +for each realm. + +If you import ``useRealm()``, ``useQuery()``, or ``useObject()`` directly from +``@realm/react``, those hooks use the default realm context. To work with more +than one realm, you need to destructure a new realm Provider and its associated +hooks from the result of ``createRealmContext()``. You should namespace providers +to avoid confusion about which Provider and hooks you're working with. + +For a detailed guide, refer to :ref:`Expose More Than One Realm +`. + +For details about ``createRealmContext()``, refer to "Create Context with +createRealmContext()" on this page. \ No newline at end of file From dc7c2f1492ae0edf6301071dc6e944373d84acc4 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 13:48:13 -0400 Subject: [PATCH 16/40] switched configuration intro --- source/frameworks/react/providers-hooks.txt | 58 +++++++++++---------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 7e7bba9bed..6eadd6e99f 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -59,24 +59,24 @@ Provider has different props you can use for configuration. The most common BaseConfiguration properties used are: - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` - Specifies all the object schemas in this Realm. Required when first creating a Realm. - If omitted, the schema will be read from the existing Realm file. + Specifies all the object schemas in this Realm. Required when first creating a Realm. + If omitted, the schema will be read from the existing Realm file. - ``sync?: SyncConfiguration`` - Configures a synced realm. + Configures a synced realm. ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the Realm is opening. + The fallback component to render while the Realm is opening. - ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, realm will not close when the - component unmounts. + Default is ``true``. If set to ``false``, realm will not close when the + component unmounts. - ``realmRef?: React.MutableRefObject`` - A ref to the realm instance. This is useful if you need to access the realm - instance outside of the scope of the realm. + A ref to the realm instance. This is useful if you need to access the realm + instance outside of the scope of the realm. - ``children: React.ReactNode`` @@ -89,14 +89,14 @@ Provider has different props you can use for configuration. The most common AppConfiguration property used is: - ``id: string`` - Specifies the App ID. + Specifies the App ID. .. tab:: UserProvider Props :tabid: user-provider-props - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render if there is no authorized user. This can be - used to render a log in screen or otherwise handle authentication. + The fallback component to render if there is no authorized user. This can be + used to render a log in screen or otherwise handle authentication. Configure your Providers ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -105,38 +105,38 @@ This section details how to configure and expose a single realm using a ``RealmP imported directly from ``@realm/react``. For information about using ``createRealmContext()`` to configure a realm or exposing more than one realm, refer to their respective sections below. -If you are developing an app using sync, you will need to use all three Providers. If you are -developing an app without sync, you only need to use ``RealmProvider``. - .. tabs:: .. tab:: Configure realm with sync :tabid: configure-sync-realm + If you are developing an app using sync, you will need to use all three Providers. + By default, Realm syncs all data from the server before returning anything. If you want to sync data in the background, read Configure a Synced Realm While Offline [link]. To configure a synced realm: - #. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. - - #. Configure ``AppProvider``. - Pass your App ID string to the ``id`` prop of the ``AppProvider``. + 1. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. - #. Configure ``UserProvider`` and nest it within ``AppProvider``. + 2. Configure ``AppProvider``. - Pass a component that logs a user in into the ``fallback`` prop. The app renders this component if there is no authenticated user. + a. Pass your App ID string to the ``id`` prop of the ``AppProvider``. - #. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. + 3. Configure ``UserProvider`` and nest it within ``AppProvider``. + + a. Pass a component that logs a user in into the ``fallback`` prop. The app renders this component if there is no authenticated user. + + 4. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. - Pass your object models to the ``schema`` prop. (link out) + a. Pass your object models to the ``schema`` prop. (link out) - Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. + b. Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. - Add other Configuration object properties as props to ``RealmProvider``. + c. Add other Configuration object properties as props to ``RealmProvider``. - You must set up a sync subscription. The example below uses an initial subscription, - but you can also set up subscriptions in ``RealmProvider`` child components. + d. You must set up a sync subscription. The example below uses an initial subscription, + but you can also set up subscriptions in ``RealmProvider`` child components. .. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst @@ -150,6 +150,8 @@ developing an app without sync, you only need to use ``RealmProvider``. .. tab:: Configure realm without sync :tabid: configure-non-sync-realm + If you are developing an app without sync, you only need to use ``RealmProvider``. + To configure a non-synced realm: #. Import ``RealmProvider`` from ``@realm/react``. @@ -164,8 +166,8 @@ developing an app without sync, you only need to use ``RealmProvider``. [code example - unsynced] -Working in your Providers -------------------------- +Working with Providers using Hooks +---------------------------------- To use the Provider's context in your app's components, you can use hooks [link]. From c9de1e5b374e4adee6828c4b732e5d5ae0d36442 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 16:24:43 -0400 Subject: [PATCH 17/40] added configuration code examples --- source/frameworks/react/providers-hooks.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 6eadd6e99f..e506157410 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -59,22 +59,27 @@ Provider has different props you can use for configuration. The most common BaseConfiguration properties used are: - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` + Specifies all the object schemas in this Realm. Required when first creating a Realm. If omitted, the schema will be read from the existing Realm file. - ``sync?: SyncConfiguration`` + Configures a synced realm. ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + The fallback component to render while the Realm is opening. - ``closeOnUnmount?: boolean`` + Default is ``true``. If set to ``false``, realm will not close when the component unmounts. - ``realmRef?: React.MutableRefObject`` + A ref to the realm instance. This is useful if you need to access the realm instance outside of the scope of the realm. @@ -89,12 +94,14 @@ Provider has different props you can use for configuration. The most common AppConfiguration property used is: - ``id: string`` + Specifies the App ID. .. tab:: UserProvider Props :tabid: user-provider-props - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` + The fallback component to render if there is no authorized user. This can be used to render a log in screen or otherwise handle authentication. @@ -145,7 +152,8 @@ to configure a realm or exposing more than one realm, refer to their respective You *must* nest the Providers and app components as shown below to ensure each component has access to its required context: - [Code example here] + .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx + :language: javascript .. tab:: Configure realm without sync :tabid: configure-non-sync-realm @@ -163,7 +171,8 @@ to configure a realm or exposing more than one realm, refer to their respective Once your ``RealmProvider`` has been configured, nest your app components within it to give them access to the realm opened. - [code example - unsynced] + .. literalinclude:: /examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx + :language: typescript Working with Providers using Hooks From aac36eb1bf986799c27aab5cca92646f1d15b64d Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 16:51:00 -0400 Subject: [PATCH 18/40] fixed small formatting issues --- source/frameworks/react/providers-hooks.txt | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index e506157410..5050b773e7 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -101,7 +101,7 @@ Provider has different props you can use for configuration. :tabid: user-provider-props - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - + The fallback component to render if there is no authorized user. This can be used to render a log in screen or otherwise handle authentication. @@ -120,7 +120,8 @@ to configure a realm or exposing more than one realm, refer to their respective If you are developing an app using sync, you will need to use all three Providers. By default, Realm syncs all data from the server before returning anything. If you want - to sync data in the background, read Configure a Synced Realm While Offline [link]. + to sync data in the background, read :ref:`Configure a Synced Realm While Offline + `. To configure a synced realm: @@ -136,7 +137,7 @@ to configure a realm or exposing more than one realm, refer to their respective 4. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. - a. Pass your object models to the ``schema`` prop. (link out) + a. Pass your object models to the ``schema`` prop. b. Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. @@ -147,8 +148,11 @@ to configure a realm or exposing more than one realm, refer to their respective .. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst - Once your Providers have been configured, nest your app components within the ``RealmProvider``. - + Once your Providers have been configured, nest your app components within the + ``RealmProvider``. The rendering of each component is dependent on the successful + execution of its parent components' functionality. For example, if ``AppProvider`` cannot + connect to your app's App Services backend, the components it wraps will not render. + You *must* nest the Providers and app components as shown below to ensure each component has access to its required context: @@ -178,7 +182,7 @@ to configure a realm or exposing more than one realm, refer to their respective Working with Providers using Hooks ---------------------------------- -To use the Provider's context in your app's components, you can use hooks [link]. +To use the Provider's context in your app's components, you can use hooks. Hooks act as functions used to access states in your app. React offers built-in hooks you can use either on their own or to build custom hooks. @@ -977,12 +981,14 @@ For a detailed guide, refer to :ref:`Expose More Than One Realm *Parameters* - ``realmConfig?: Realm.Configuration`` + All properties of :realm-react-sdk:`BaseConfiguration ` can be used. *Returns* - ``RealmContext`` + An object containing a ``RealmProvider`` component, and the ``useRealm``, ``useQuery`` and ``useObject`` hooks. From d3a25851b9867fca50c11203dc8d5a913fec3698 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 17:23:23 -0400 Subject: [PATCH 19/40] testing app provider hooks condesning --- source/frameworks/react/providers-hooks.txt | 336 +++++++------------- 1 file changed, 108 insertions(+), 228 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 5050b773e7..df9c1c685d 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -324,8 +324,8 @@ use in any wrapped component. useAuth(): UseAuth - ``useAuth`` has an authentication method for every App Services - authentication provider. + ``useAuth`` returns ``result`` and an authentication method you specify, as shown below. There is an authentication + method for every App Services authentication provider. result `````` @@ -342,284 +342,164 @@ use in any wrapped component. *Enum values* - ``state``. Can be "not-started", "pending", "success", "error". - - ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. - - ``pending``. Can be ``true`` or ``false``. - - ``success``. Can be ``true`` or ``false``. - - ``error``. Error-based object or undefined. - - logIn(credentials) - `````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logIn(credentials: Realm.Credentials): void - - *Parameters* - - - ``credentials``. A Realm credential supplied by any supported Realm - authentication. - - *Example* - - Logs in a user with any authentication mechanism supported by - Realm. If called when a user is logged in, the current user switches to - the new user. Usually, it's better to use the more specific login - methods. - - .. code:: typescript - - const {logIn, result} = useAuth(); - - useEffect(() => logIn(Realm.Credentials.anonymous()), []); - - if(result.pending) { - return () - } - - if(result.error) { - return () - } - - if(result.success) { - return () - } - //... - - logInWithAnonymous() - ```````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logInWithAnonymous(): void - - *Example* - - Log in with the anonymous authentication provider. - - .. code:: typescript - - const {logInWithAnonymous, result} = useAuth(); - const performLogin = () => { - logInWithAnonymous(); - }; - - logInWithApiKey(key) - ```````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApiKey(key: string): void - - *Parameters* - - - ``key``. A string that is linked to an App Services user. - - *Example* - - Log in with an API key. - - .. code:: typescript - - const {logInWithApiKey, result} = useAuth(); - const performLogin = () => { - const key = getApiKey(); // user defined function - logInWithApiKey(key); - }; - - logInWithEmailPassword(credentials) - ``````````````````````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logInWithEmailPassword(credentials: { - email: string; - password: string; - }): void - - *Parameters* - - - ``credentials``. An object with ``email`` and ``password`` fields. - - *Example* - - Log in with Email/Password. - - .. code:: typescript - const {logInWithEmailPassword, result} = useAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + - ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. - const performLogin = () => { - logInWithEmailPassword({email, password}); - }; + - ``pending``. Can be ``true`` or ``false``. - logInWithJWT(credentials) - ````````````````````````` + - ``success``. Can be ``true`` or ``false``. - .. code:: typescript - :copyable: false - :caption: Type signature + - ``error``. Error-based object or undefined. - logInWithJWT(token: string): void + Authentication Methods + `````````````````````` - *Parameters* + Below is a list of authentication methods and their Type signatures. An example of using + an authentication method is provided for ``logIn(credentials)``. You use the other authentication + methods in the same way. - - ``credentials``. A string representation of a user's JWT. + .. glossary:: - *Example* + **logIn(credentials)** + .. code:: typescript + :copyable: false + :caption: Type signature - Log in with a JSON Web Token (JWT). - - .. code:: typescript + logIn(credentials: Realm.Credentials): void - const {logInWithJWT, result} = useAuth(); + *Parameters* - const performLogin = () => { - const token = authorizeWithCustomerProvider(); // user defined function - logInWithJWT(token); - }; + - ``credentials``. A Realm credential supplied by any supported Realm + authentication. - logInWithGoogle(credentials) - ```````````````````````````` + *Example* - .. code:: typescript - :copyable: false - :caption: Type signature + Logs in a user with any authentication mechanism supported by + Realm. If called when a user is logged in, the current user switches to + the new user. Usually, it's better to use the more specific login + methods. - logInWithGoogle(credentials: { - idToken: string; - } | { - authCode: string; - }): void; + .. code:: typescript - *Parameters* + const {logIn, result} = useAuth(); - - ``credentials``. An object with an ``idToken`` or ``authCode`` field that - should contain the string token you get from Google Identity Services. + useEffect(() => logIn(Realm.Credentials.anonymous()), []); - *Example* + if(result.pending) { + return () + } - Log in with Google. - - .. code:: typescript + if(result.error) { + return () + } - const {logInWithGoogle, result} = useAuth(); + if(result.success) { + return () + } + //... - const performLogin = () => { - const token = getGoogleToken(); // user defined function - logInWithGoogle({idToken: token}); - }; - logInWithApple(idToken) - ``````````````````````` + logInWithAnonymous() + .. code:: typescript + :copyable: false + :caption: Type signature - .. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApple(idToken: string): void; - - *Parameters* + logInWithAnonymous(): void - - ``idToken``. A string you get from the Apple SDK. + logInWithApiKey(key) + .. code:: typescript + :copyable: false + :caption: Type signature - *Example* + logInWithApiKey(key: string): void - Log in with Apple. - - .. code:: typescript + *Parameters* - const {logInWithApple, result} = useAuth(); + - ``key``. A string that is linked to an App Services user. - const performLogin = () => { - const token = getAppleToken(); // user defined function - logInWithApple(token); - }; + + logInWithEmailPassword(credentials) + .. code:: typescript + :copyable: false + :caption: Type signature - logInWithFacebook(accessToken) - `````````````````````````````` + logInWithEmailPassword(credentials: { + email: string; + password: string; + }): void - .. code:: typescript - :copyable: false - :caption: Type signature + *Parameters* - logInWithFacebook(accessToken: string): void; + - ``credentials``. An object with ``email`` and ``password`` fields. - *Parameters* + logInWithJWT(credentials) + .. code:: typescript + :copyable: false + :caption: Type signature - - ``accessToken``. A string you get from the Facebook SDK. + logInWithJWT(token: string): void - *Example* + *Parameters* - Log in with Facebook. - - .. code:: typescript + - ``credentials``. A string representation of a user's JWT. - const {logInWithFacebook, result} = useAuth(); + logInWithGoogle(credentials) + .. code:: typescript + :copyable: false + :caption: Type signature - const performLogin = () => { - const token = getFacebookToken(); // user defined function - logInWithFacebook(token); - }; + logInWithGoogle(credentials: { + idToken: string; + } | { + authCode: string; + }): void; - logInWithFunction(payload) - `````````````````````````` + *Parameters* - .. code:: typescript - :copyable: false - :caption: Type signature + - ``credentials``. An object with an ``idToken`` or ``authCode`` field that + should contain the string token you get from Google Identity Services. - logInWithFunction>(payload: PayloadType): void; + logInWithApple(idToken) + .. code:: typescript + :copyable: false + :caption: Type signature - *Parameters* + logInWithApple(idToken: string): void; - - ``payload``. An object that contains user information you want to pass to - the App Services function that processes log in requests. + *Parameters* - *Example* + - ``idToken``. A string you get from the Apple SDK. - Log in with a custom function. - - .. code:: typescript + logInWithFacebook(accessToken) + .. code:: typescript + :copyable: false + :caption: Type signature - const {logInWithFunction, result} = useAuth(); + logInWithFacebook(accessToken: string): void; - const performLogin = () => { - const customPayload = getAuthParams(); // user defined arguments - logInWithFunction(customPayload); - }; + *Parameters* - logOut() - ```````` + - ``accessToken``. A string you get from the Facebook SDK. - .. code:: typescript - :copyable: false - :caption: Type signature + logInWithFunction(payload) + .. code:: typescript + :copyable: false + :caption: Type signature - logOut(): void; + logInWithFunction>(payload: PayloadType): void; - *Example* + *Parameters* - Logs out the current user. - - .. code:: typescript + - ``payload``. An object that contains user information you want to pass to + the App Services function that processes log in requests. - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } + logOut() + .. code:: typescript + :copyable: false + :caption: Type signature - .. _react-native-use-emailpassword-auth: + logOut(): void; useEmailPasswordAuth() ~~~~~~~~~~~~~~~~~~~~~~ From a90048bb4c19c99e23250381587529ed05201013 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 18:10:33 -0400 Subject: [PATCH 20/40] auth email password methods --- source/frameworks/react/providers-hooks.txt | 324 +++++++------------- 1 file changed, 109 insertions(+), 215 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index df9c1c685d..ce1fecca61 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -361,7 +361,7 @@ use in any wrapped component. .. glossary:: - **logIn(credentials)** + logIn(credentials) .. code:: typescript :copyable: false :caption: Type signature @@ -504,6 +504,12 @@ use in any wrapped component. useEmailPasswordAuth() ~~~~~~~~~~~~~~~~~~~~~~ + ``useEmailPasswordAuth`` returns ``result`` and an authentication method you specify, as + shown below. + + result + `````` + .. code:: typescript :copyable: false :caption: Type signature @@ -516,270 +522,158 @@ use in any wrapped component. *Enum values* - ``state``. Can be "not-started", "pending", "success", "error". - - ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. - - ``pending``. Can be ``true`` or ``false``. - - ``success``. Can be ``true`` or ``false``. - - ``error``. Error-based object or undefined. - - logIn(credentials) - `````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logIn(credentials: { email: string; password: string }): void; - - *Parameters* - - - ``credentials``. An object that contains ``email`` and ``password`` properties. - - *Example* - - Logs a user in using an email and password. You could also call - ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a - ``Realm.User`` instance of the logged-in user. - - .. code:: typescript - - const {logIn, result} = useEmailPasswordAuth(); - - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performLogin = () => { - logIn({email, password}); - }; - - if(result.pending) { - return () - } - - if(result.error) { - return () - } - - if(result.success) { - return () - } - //... - - logOut() - ```````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - logOut(): void; - - *Example* - - Logs out the current user. - - .. code:: typescript - - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } - register(args) - `````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - register(args: { email: string; password: string }): void; - - *Parameters* - - - ``args``. An object that contains ``email`` and ``password`` properties. - - *Example* - - Registers a new user. Requires a user email and password. - - .. code:: typescript - - const {register, result} = useEmailPasswordAuth(); - - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performRegister = () => { - register({email, password}); - }; - - confirm(args) - ````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature - - confirm(args: { token: string; tokenId: string }): void; - - *Parameters* - - - ``args``. An object that contains ``token`` and ``tokenId`` properties. - - *Example* - - Confirms a user account. Requires a ``token`` and ``tokenId``. - - .. code:: typescript - - const {confirm, result} = useEmailPasswordAuth(); - - const performConfirmation = () => { - confirm({token, tokenId}); - }; - - resendConfirmationEmail(args) - ````````````````````````````` - - .. code:: typescript - :copyable: false - :caption: Type signature + - ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. - resendConfirmationEmail(args: { email: string }): void; + - ``pending``. Can be ``true`` or ``false``. - *Parameters* + - ``success``. Can be ``true`` or ``false``. - - ``args``. An object that contains an ``email`` property. + - ``error``. Error-based object or undefined. - *Example* + Authentication Methods + ````````````````` - Resends a confirmation email. + Below is a list of authentication methods and their Type signatures. An example of using + an authentication method is provided for ``logIn(credentials)``. You use the other authentication + methods in the same way. - .. code:: typescript + .. glossary:: - const {resendConfirmationEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); + logIn(credentials) + .. code:: typescript + :copyable: false + :caption: Type signature - const performResendConfirmationEmail = () => { - resendConfirmationEmail({email}); - }; + logIn(credentials: { email: string; password: string }): void; - retryCustomConfirmation(args) - ````````````````````````````` + *Parameters* - .. code:: typescript - :copyable: false - :caption: Type signature + - ``credentials``. An object that contains ``email`` and ``password`` properties. - retryCustomConfirmation(args: { email: string }): void; + *Example* - *Parameters* + Logs a user in using an email and password. You could also call + ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a + ``Realm.User`` instance of the logged-in user. - - ``args``. An object that contains an ``email`` property. + .. code:: typescript - *Example* + const {logIn, result} = useEmailPasswordAuth(); - Retries confirmation with a custom function. + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); - .. code:: typescript + const performLogin = () => { + logIn({email, password}); + }; - const {retryCustomConfirmation, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); + if(result.pending) { + return () + } - const performRetryCustomConfirmation = () => { - retryCustomConfirmation({email}); - }; + if(result.error) { + return () + } - sendResetPasswordEmail(args) - ````````````````````````````` + if(result.success) { + return () + } + //... - .. code:: typescript - :copyable: false - :caption: Type signature + logOut() + .. code:: typescript + :copyable: false + :caption: Type signature - sendResetPasswordEmail(args: { email: string }): void; + logOut(): void; - *Parameters* + register(args) + .. code:: typescript + :copyable: false + :caption: Type signature - - ``args``. An object that contains an ``email`` property. + register(args: { email: string; password: string }): void; - *Example* + *Parameters* - Sends a password reset email. + - ``args``. An object that contains ``email`` and ``password`` properties. - .. code:: typescript + confirm(args) + .. code:: typescript + :copyable: false + :caption: Type signature - const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); + confirm(args: { token: string; tokenId: string }): void; - const performSendResetPasswordEmail = () => { - sendResetPasswordEmail({email}); - }; + *Parameters* - resetPassword(args) - ``````````````````` + - ``args``. An object that contains ``token`` and ``tokenId`` properties. - .. code:: typescript - :copyable: false - :caption: Type signature + resendConfirmationEmail(args) + .. code:: typescript + :copyable: false + :caption: Type signature - resetPassword(args: { token: string; tokenId: string; password: string }): void; + resendConfirmationEmail(args: { email: string }): void; - *Parameters* + *Parameters* - - ``args``. An object that contains ``token``, ``tokenId``, and ``password`` - properties. + - ``args``. An object that contains an ``email`` property. - *Example* + retryCustomConfirmation(args) + .. code:: typescript + :copyable: false + :caption: Type signature - Resets a user's password. + retryCustomConfirmation(args: { email: string }): void; - .. code:: typescript + *Parameters* - const {resetPassword, result} = useEmailPasswordAuth(); - const [password, setPassword] = useState(''); + - ``args``. An object that contains an ``email`` property. - const performResetPassword = () => { - resetPassword({token, tokenId, password}); - }; + sendResetPasswordEmail(args) + .. code:: typescript + :copyable: false + :caption: Type signature - callResetPasswordFunction(args, restArgs) - ````````````````````````````````````````` + sendResetPasswordEmail(args: { email: string }): void; - .. code:: typescript - :copyable: false - :caption: Type signature + *Parameters* - callResetPasswordFunction( - args: { - email: string; - password: string; - }, - ...restArgs: Args - ): void; + - ``args``. An object that contains an ``email`` property. - *Parameters* + resetPassword(args) + .. code:: typescript + :copyable: false + :caption: Type signature - - ``args``. An object that contains ``email`` and ``password`` properties. - - ``restArgs``. Additional arguments that you need to pass to your custom - reset password function. + resetPassword(args: { token: string; tokenId: string; password: string }): void; - *Example* + *Parameters* - Calls your App Services backend password reset function. Can pass arguments to - the function as needed. + - ``args``. An object that contains ``token``, ``tokenId``, and ``password`` + properties. - .. code:: typescript + callResetPasswordFunction(args, restArgs) + .. code:: typescript + :copyable: false + :caption: Type signature - const {callResetPasswordFunction, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + callResetPasswordFunction( + args: { + email: string; + password: string; + }, + ...restArgs: Args + ): void; - const performResetPassword = () => { - callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); - }; + *Parameters* - .. _react-native-use-app-hook: + - ``args``. An object that contains ``email`` and ``password`` properties. + - ``restArgs``. Additional arguments that you need to pass to your custom + reset password function. useApp() ~~~~~~~~ From 0f494821bf4e1172f036585cc2531da702971ae3 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 18:13:51 -0400 Subject: [PATCH 21/40] reordered app provider hooks --- source/frameworks/react/providers-hooks.txt | 46 ++++++++++----------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index ce1fecca61..52eefe5027 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -182,7 +182,7 @@ to configure a realm or exposing more than one realm, refer to their respective Working with Providers using Hooks ---------------------------------- -To use the Provider's context in your app's components, you can use hooks. +To use the Provider's context in your app's components, you can use :react.dev:`hooks `. Hooks act as functions used to access states in your app. React offers built-in hooks you can use either on their own or to build custom hooks. @@ -315,6 +315,28 @@ use in any wrapped component. .. _react-native-use-auth: + useApp() + ~~~~~~~~ + + .. code:: typescript + :copyable: false + :caption: Type signature + + useApp(): Realm.App + + *Example* + + The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` + instance. + + .. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst + .. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst + + *Returns* + + - ``Realm.App`` + An instance of the current ``Realm.App`` created by ``AppProvider``. + useAuth() ~~~~~~~~~ @@ -675,28 +697,6 @@ use in any wrapped component. - ``restArgs``. Additional arguments that you need to pass to your custom reset password function. - useApp() - ~~~~~~~~ - - .. code:: typescript - :copyable: false - :caption: Type signature - - useApp(): Realm.App - - *Example* - - The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` - instance. - - .. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst - .. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst - - *Returns* - - - ``Realm.App`` - An instance of the current ``Realm.App`` created by ``AppProvider``. - .. tab:: UserProvider Hooks :tabid: user-provider-hooks From 6db5790cb5a68e65f0ee6ac2e3f6dff658f80ed5 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Wed, 31 Jul 2024 18:26:53 -0400 Subject: [PATCH 22/40] deleted files --- source/frameworks/react/api-reference.txt | 13 - .../react/api-reference/app-provider.txt | 659 ------------------ .../react/api-reference/realm-provider.txt | 293 -------- .../react/api-reference/user-provider.txt | 83 --- source/frameworks/react/temp.txt | 95 --- 5 files changed, 1143 deletions(-) delete mode 100644 source/frameworks/react/api-reference.txt delete mode 100644 source/frameworks/react/api-reference/app-provider.txt delete mode 100644 source/frameworks/react/api-reference/realm-provider.txt delete mode 100644 source/frameworks/react/api-reference/user-provider.txt delete mode 100644 source/frameworks/react/temp.txt diff --git a/source/frameworks/react/api-reference.txt b/source/frameworks/react/api-reference.txt deleted file mode 100644 index a5c57e30d9..0000000000 --- a/source/frameworks/react/api-reference.txt +++ /dev/null @@ -1,13 +0,0 @@ -.. _sdks-react-api-reference: - -=================================== -API Reference -=================================== - -.. toctree:: - :titlesonly: - - JavaScript SDK Reference (@realm) - RealmProvider (@realm/react) - AppProvider (@realm/react) - UserProvider (@realm/react) \ No newline at end of file diff --git a/source/frameworks/react/api-reference/app-provider.txt b/source/frameworks/react/api-reference/app-provider.txt deleted file mode 100644 index ead05c1f68..0000000000 --- a/source/frameworks/react/api-reference/app-provider.txt +++ /dev/null @@ -1,659 +0,0 @@ -.. _react-app-provider: - -========================== -AppProvider (@realm/react) -========================== - -.. meta:: - :description: Learn how to use the AppProvider ReactElement hooks to work with an App Services App. - :keywords: code example - -.. facet:: - :name: genre - :values: reference - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - -.. code:: typescript - :copyable: false - :caption: Type signature - - AppProvider(props, context?): null | ReactElement - -Components nested within ``AppProvider`` can access your App Services App -and use the ``AppProvider`` hooks. - -Props ------ - -All properties of :realm-react-sdk:`AppConfiguration -` can be passed as props to ``AppProvider``. - -Configure AppProvider ---------------------- - -To set up your App client, pass the App ID string -to the ``id`` prop of the ``AppProvider``. -Wrap any components that need to access the App with ``AppProvider``. - -.. literalinclude:: /examples/generated/react-native/ts/app-provider.test.snippet.app-provider.tsx - :language: typescript - -.. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst - -Hooks Used with AppProvider ---------------------------- - -.. _react-native-use-auth: - -useAuth() -~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useAuth(): UseAuth - -``useAuth`` has an authentication method for every App Services -authentication provider. - -result -`````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - result: AuthResult - -Result of authentication hook operation. For example, ``result.operation`` gives -you the name of the current operation. - -*Enum values* - -- ``state``. Can be "not-started", "pending", "success", "error". -- ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. -- ``pending``. Can be ``true`` or ``false``. -- ``success``. Can be ``true`` or ``false``. -- ``error``. Error-based object or undefined. - -logIn(credentials) -`````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logIn(credentials: Realm.Credentials): void - -*Parameters* - -- ``credentials``. A Realm credential supplied by any supported Realm - authentication. - -*Example* - -Logs in a user with any authentication mechanism supported by -Realm. If called when a user is logged in, the current user switches to -the new user. Usually, it's better to use the more specific login -methods. - -.. code:: typescript - - const {logIn, result} = useAuth(); - - useEffect(() => logIn(Realm.Credentials.anonymous()), []); - - if(result.pending) { - return () - } - - if(result.error) { - return () - } - - if(result.success) { - return () - } - //... - -logInWithAnonymous() -```````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithAnonymous(): void - -*Example* - -Log in with the anonymous authentication provider. - -.. code:: typescript - - const {logInWithAnonymous, result} = useAuth(); - const performLogin = () => { - logInWithAnonymous(); - }; - -logInWithApiKey(key) -```````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApiKey(key: string): void - -*Parameters* - -- ``key``. A string that is linked to an App Services user. - -*Example* - -Log in with an API key. - -.. code:: typescript - - const {logInWithApiKey, result} = useAuth(); - const performLogin = () => { - const key = getApiKey(); // user defined function - logInWithApiKey(key); - }; - -logInWithEmailPassword(credentials) -``````````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithEmailPassword(credentials: { - email: string; - password: string; - }): void - -*Parameters* - -- ``credentials``. An object with ``email`` and ``password`` fields. - -*Example* - -Log in with Email/Password. - -.. code:: typescript - - const {logInWithEmailPassword, result} = useAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performLogin = () => { - logInWithEmailPassword({email, password}); - }; - -logInWithJWT(credentials) -````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithJWT(token: string): void - -*Parameters* - -- ``credentials``. A string representation of a user's JWT. - -*Example* - -Log in with a JSON Web Token (JWT). - -.. code:: typescript - - const {logInWithJWT, result} = useAuth(); - - const performLogin = () => { - const token = authorizeWithCustomerProvider(); // user defined function - logInWithJWT(token); - }; - -logInWithGoogle(credentials) -```````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithGoogle(credentials: { - idToken: string; - } | { - authCode: string; - }): void; - -*Parameters* - -- ``credentials``. An object with an ``idToken`` or ``authCode`` field that - should contain the string token you get from Google Identity Services. - -*Example* - -Log in with Google. - -.. code:: typescript - - const {logInWithGoogle, result} = useAuth(); - - const performLogin = () => { - const token = getGoogleToken(); // user defined function - logInWithGoogle({idToken: token}); - }; - -logInWithApple(idToken) -``````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApple(idToken: string): void; - -*Parameters* - -- ``idToken``. A string you get from the Apple SDK. - -*Example* - -Log in with Apple. - -.. code:: typescript - - const {logInWithApple, result} = useAuth(); - - const performLogin = () => { - const token = getAppleToken(); // user defined function - logInWithApple(token); - }; - -logInWithFacebook(accessToken) -`````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithFacebook(accessToken: string): void; - -*Parameters* - -- ``accessToken``. A string you get from the Facebook SDK. - -*Example* - -Log in with Facebook. - -.. code:: typescript - - const {logInWithFacebook, result} = useAuth(); - - const performLogin = () => { - const token = getFacebookToken(); // user defined function - logInWithFacebook(token); - }; - -logInWithFunction(payload) -`````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithFunction>(payload: PayloadType): void; - -*Parameters* - -- ``payload``. An object that contains user information you want to pass to - the App Services function that processes log in requests. - -*Example* - -Log in with a custom function. - -.. code:: typescript - - const {logInWithFunction, result} = useAuth(); - - const performLogin = () => { - const customPayload = getAuthParams(); // user defined arguments - logInWithFunction(customPayload); - }; - -logOut() -```````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logOut(): void; - -*Example* - -Logs out the current user. - -.. code:: typescript - - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } - -.. _react-native-use-emailpassword-auth: - -useEmailPasswordAuth() -~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - result: AuthResult - -Result of authentication hook operation. For example, ``result.operation`` gives -you the name of the current operation. - -*Enum values* - -- ``state``. Can be "not-started", "pending", "success", "error". -- ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. -- ``pending``. Can be ``true`` or ``false``. -- ``success``. Can be ``true`` or ``false``. -- ``error``. Error-based object or undefined. - -logIn(credentials) -`````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logIn(credentials: { email: string; password: string }): void; - -*Parameters* - -- ``credentials``. An object that contains ``email`` and ``password`` properties. - -*Example* - -Logs a user in using an email and password. You could also call -``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a -``Realm.User`` instance of the logged-in user. - -.. code:: typescript - - const {logIn, result} = useEmailPasswordAuth(); - - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performLogin = () => { - logIn({email, password}); - }; - - if(result.pending) { - return () - } - - if(result.error) { - return () - } - - if(result.success) { - return () - } - //... - -logOut() -```````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logOut(): void; - -*Example* - -Logs out the current user. - -.. code:: typescript - - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } - -register(args) -`````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - register(args: { email: string; password: string }): void; - -*Parameters* - -- ``args``. An object that contains ``email`` and ``password`` properties. - -*Example* - -Registers a new user. Requires a user email and password. - -.. code:: typescript - - const {register, result} = useEmailPasswordAuth(); - - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performRegister = () => { - register({email, password}); - }; - -confirm(args) -````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - confirm(args: { token: string; tokenId: string }): void; - -*Parameters* - -- ``args``. An object that contains ``token`` and ``tokenId`` properties. - -*Example* - -Confirms a user account. Requires a ``token`` and ``tokenId``. - -.. code:: typescript - - const {confirm, result} = useEmailPasswordAuth(); - - const performConfirmation = () => { - confirm({token, tokenId}); - }; - -resendConfirmationEmail(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - resendConfirmationEmail(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Resends a confirmation email. - -.. code:: typescript - - const {resendConfirmationEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - - const performResendConfirmationEmail = () => { - resendConfirmationEmail({email}); - }; - -retryCustomConfirmation(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - retryCustomConfirmation(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Retries confirmation with a custom function. - -.. code:: typescript - - const {retryCustomConfirmation, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - - const performRetryCustomConfirmation = () => { - retryCustomConfirmation({email}); - }; - -sendResetPasswordEmail(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - sendResetPasswordEmail(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Sends a password reset email. - -.. code:: typescript - - const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - - const performSendResetPasswordEmail = () => { - sendResetPasswordEmail({email}); - }; - -resetPassword(args) -``````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - resetPassword(args: { token: string; tokenId: string; password: string }): void; - -*Parameters* - -- ``args``. An object that contains ``token``, ``tokenId``, and ``password`` - properties. - -*Example* - -Resets a user's password. - -.. code:: typescript - - const {resetPassword, result} = useEmailPasswordAuth(); - const [password, setPassword] = useState(''); - - const performResetPassword = () => { - resetPassword({token, tokenId, password}); - }; - -callResetPasswordFunction(args, restArgs) -````````````````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - callResetPasswordFunction( - args: { - email: string; - password: string; - }, - ...restArgs: Args - ): void; - -*Parameters* - -- ``args``. An object that contains ``email`` and ``password`` properties. -- ``restArgs``. Additional arguments that you need to pass to your custom - reset password function. - -*Example* - -Calls your App Services backend password reset function. Can pass arguments to -the function as needed. - -.. code:: typescript - - const {callResetPasswordFunction, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performResetPassword = () => { - callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); - }; - -.. _react-native-use-app-hook: - -useApp() -~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useApp(): Realm.App - -*Example* - -The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` -instance. - -.. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst -.. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst - -*Returns* - -- ``Realm.App`` - An instance of the current ``Realm.App`` created by ``AppProvider``. \ No newline at end of file diff --git a/source/frameworks/react/api-reference/realm-provider.txt b/source/frameworks/react/api-reference/realm-provider.txt deleted file mode 100644 index 15f7d63e33..0000000000 --- a/source/frameworks/react/api-reference/realm-provider.txt +++ /dev/null @@ -1,293 +0,0 @@ -.. _react-realm-provider: - -============================ -RealmProvider (@realm/react) -============================ - -.. facet:: - :name: genre - :values: reference - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - -.. code:: typescript - :copyable: false - :caption: Type signature - - RealmProvider(props, context?): null | ReactElement - -Components nested within ``RealmProvider`` can access the configured realm -and use the ``RealmProvider`` hooks. - -Props ------ - -All properties of :realm-react-sdk:`BaseConfiguration -` can be passed as props. - -``RealmProvider`` has more props that define its behavior: - -- ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the Realm is opening. - -- ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, realm will not close when the - component unmounts. - -- ``realmRef?: React.MutableRefObject`` - A ref to the realm instance. This is useful if you need to access the realm - instance outside of the scope of the realm. - -- ``children: React.ReactNode`` - -Configure a Realm with RealmProvider ------------------------------------- - -You can configure a ``RealmProvider`` in two ways: - -- Import ``RealmProvider`` directly from ``@realm/react`` -- Use ``createRealmContext()`` to configure a ``RealmProvider`` and create hooks - -This section details how to configure a ``RealmProvider`` imported directly from -``@realm/react``. For information about using ``createRealmContext()``, refer -to :ref:`Create Context with createRealmContext() `. - -Object models are part of most realm configurations. To learn more about Realm and -data models, refer to :ref:`Define a Realm Object Model -`. - -.. tabs:: - - .. tab:: Configure realm with sync - :tabid: configure-sync-realm - - :ref:`RealmProvider ` is a wrapper - that exposes a realm to its child components. You configure your realm by - passing props to ``RealmProvider``. - - When ``RealmProvider`` is rendered, it opens the realm. This means that - the child components can't access the realm if rendering fails. - - In addition to ``RealmProvider``, you also need to configure - :ref:`AppProvider ` and :ref:`UserProvider - `. - - By default, Realm syncs all data from the server before returning anything. - If you want to sync data in the background, read :ref:`Configure a Synced - Realm While Offline `. - - To configure a synced realm: - - #. Import providers from ``@realm/react``. - #. Configure ``AppProvider``. - #. Configure ``UserProvider`` and nest it within ``AppProvider``. - #. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. - #. Pass your object models to the ``schema`` prop. - #. Add other :realm-react-sdk:`Configuration object ` - properties as props to ``RealmProvider``. - - You must set up a sync subscription. The example below uses an initial subscription, - but you can also set up subscriptions in ``RealmProvider`` child components. - - You must nest providers as in the following example: - - .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx - :language: javascript - - For more information about configuring a synced realm, refer to - :ref:`Configure a Synced Realm `. - - .. tab:: Configure realm without sync - :tabid: configure-non-sync-realm - - :ref:`RealmProvider ` is a wrapper - that exposes a realm to its child components. You configure your realm by - passing props to ``RealmProvider``. - - When ``RealmProvider`` is rendered, it opens the realm. This means that - the child components can't access the realm if rendering fails. - - To configure a non-synced realm: - - #. Import ``RealmProvider`` from ``@realm/react``. - #. Pass your object models to the ``schema`` prop. - #. Add other :realm-react-sdk:`Configuration object ` - properties as props to ``RealmProvider``. - - .. literalinclude:: /examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx - :language: typescript - -Configure More Than One Realm ------------------------------ - -When you import ``RealmProvider`` from ``@realm/react``, that Provider has a -specific context and is associated with a single realm. If you need to configure -more than one realm, use ``createRealmContext()`` to instantiate a new Provider -for each realm. - -If you import ``useRealm()``, ``useQuery()``, or ``useObject()`` directly from -``@realm/react``, those hooks use the default realm context. To work with more -than one realm, you need to destructure a new realm Provider and its associated -hooks from the result of ``createRealmContext()``. You should namespace providers -to avoid confusion about which Provider and hooks you're working with. - -For a detailed guide, refer to :ref:`Expose More Than One Realm -`. - -For details about ``createRealmContext()``, refer to "Create Context with -createRealmContext()" on this page. - -RealmProvider Hooks -------------------- - -.. _react-native-use-realm-hook: - -useRealm() -~~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useRealm(): Realm - -The ``useRealm()`` hook returns an opened realm instance. The realm instance -gives you access to realm methods and properties. For example, you can call -``realm.write()`` to add a realm object to your realm. - -To learn more about modifying Realm data, refer to :ref:`Write Transactions -`. - -.. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx - :language: typescript - :emphasize-lines: 3, 6-8, 15 - -*Returns* - -- ``Realm`` - Returns a realm instance. This is the realm created by the hook's parent, - ``RealmProvider``. - -.. _react-native-use-object-hook: - -useObject() -~~~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useObject(type, primaryKey): T & Realm.Object | null - -The ``useObject()`` hook returns a Realm object for a given -:ref:`primary key `. You can pass an object class -or the class name as a string and the primary key. - -The ``useObject()`` method returns null if the object doesn't exist or you have -deleted it. The hook will automatically subscribe to updates and rerender the -component using the hook on any change to the object. - -.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx - :language: typescript - -*Parameters* - -- ``type: string`` - A string that matches your object model's class name or a reference to a - class that extends :js-sdk:`Realm.Object `. -- ``primaryKey: T[keyof T]`` - The primary key of the desired object. - -*Returns* - -- ``Realm.Object | null`` - A Realm Object or ``null`` if no object is found. - -.. _react-native-use-query-hook: - -useQuery() -~~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useQuery(type, query?, deps?): Realm.Results> - -The ``useQuery()`` hook returns a collection of realm objects of a given type. -These are the results of your query. A query can be an object class or the class -name as a string. - -The ``useQuery()`` method subscribes to updates to any objects in the collection -and rerenders the component using it on any change to the results. - -You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query -results. You should do this in the ``query`` argument of ``useQuery`` so that -they only run when there are changes in the dependency array. For more examples, -refer to the :ref:`CRUD - Read ` docs. - -.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx - :language: typescript - :emphasize-lines: 3-5, 8-14 - -*Parameters* - -- ``type: string`` - A string that matches your object model's class name or a reference to a - class that extends :js-sdk:`Realm.Object `. -- ``query?: QueryCallback`` - A query function that can filter and sort query results. Builds on - ``useCallback`` to memoize the query function. -- ``deps?: DependencyList`` - A list of query function dependencies that's used to memoize - the query function. - -*Returns* - -- ``Realm.Results`` - A Realm Object or ``null`` if no object is found. - -.. _react-native-realm-context: - -Create Context with createRealmContext() ----------------------------------------- - -.. code:: typescript - :copyable: false - :caption: Type signature - - createRealmContext(realmConfig?): RealmContext - -Most of the time, you will only use ``createRealmContext()`` if you need to -configure more than one realm. Otherwise, you should import ``RealmProvider`` -and hooks directly from ``@realm/react``. - -The ``createRealmContext()`` method creates a :reactjs:`React Context -` object for a realm with a given -:realm-react-sdk:`Configuration `. The -``Context`` object contains the following: - -- A :reactjs:`Context Provider ` (referred to - as ``RealmProvider`` elsewhere) component that wraps around child components - and provides them with access to hooks. -- Various prebuilt :reactjs:`Hooks ` that access the - configured realm. - -For a detailed guide, refer to :ref:`Expose More Than One Realm -`. - -*Parameters* - -- ``realmConfig?: Realm.Configuration`` - All properties of :realm-react-sdk:`BaseConfiguration - ` can be used. - -*Returns* - -- ``RealmContext`` - An object containing a ``RealmProvider`` component, and the ``useRealm``, - ``useQuery`` and ``useObject`` hooks. \ No newline at end of file diff --git a/source/frameworks/react/api-reference/user-provider.txt b/source/frameworks/react/api-reference/user-provider.txt deleted file mode 100644 index 00f5d232de..0000000000 --- a/source/frameworks/react/api-reference/user-provider.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. _react-user-provider: - -=========================== -UserProvider (@realm/react) -=========================== - -.. facet:: - :name: genre - :values: reference - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - -.. code:: typescript - :copyable: false - :caption: Type signature - - UserProvider(props): null | ReactElement - -Components nested within ``UserProvider`` can access the logged-in user object -and use the ``UserProvider`` hooks. - -Props ------ - -- ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render if there is no authorized user. This can be - used to render a log in screen or otherwise handle authentication. - -Configure UserProvider ----------------------- - -Components wrapped by :realm-react-sdk:`AppProvider ` -can access the :realm-react-sdk:`useApp ` and -:realm-react-sdk:`useAuth ` hooks. These components only -render if ``AppProvider`` successfully connects to your App Services backend. - -Components wrapped by :realm-react-sdk:`UserProvider ` -can access authenticated users with the :realm-react-sdk:`useUser -` hook. These components only render if your app has an -authenticated user. - -To configure user authentication: - -#. Wrap all components that need to access App Services in ``AppProvider``. -#. Inside of ``AppProvider``, wrap all components that you want to have access - to an authenticated user with ``UserProvider``. -#. In ``UserProvider``, include a ``fallback`` prop with a component - that logs a user in. The app renders this component if there - is no authenticated user. - -.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.configure-user-provider.tsx.rst - -UserProvider Hooks ------------------- - -.. _react-native-use-user-hook: - -useUser() -~~~~~~~~~ - -.. code:: typescript - :copyable: false - :caption: Type signature - - useUser(): Realm.User - -The ``useUser()`` hook provides access to the logged-in user. For example, -you can use ``useUser()`` to log the current user out. - -When changes to the user object happen, this hook will rerender its parent -component. For example, if you call ``user.refreshCustomData`` to get updated -custom user data, the ``useUser()`` parent component will rerender. - -.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.log-user-out.tsx.rst - -*Returns* - -- ``Realm.User`` - An instance of the currently-authenticated Realm user. \ No newline at end of file diff --git a/source/frameworks/react/temp.txt b/source/frameworks/react/temp.txt deleted file mode 100644 index 6c95befa3f..0000000000 --- a/source/frameworks/react/temp.txt +++ /dev/null @@ -1,95 +0,0 @@ -================= -Providers & Hooks -================= - -.. meta:: - :description: Develop apps using the Providers and Hooks available in the @realm/react library. - :keywords: Realm, Javascript SDK, React, code example - -.. facet:: - :name: genre - :values: reference - -.. facet:: - :name: programming_language - :values: javascript - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - - -The ``@realm/react`` library offers custom React components called Providers to simplify the app -development process. - -Atlas App Services offers pathways that support user creation, user authentication, and data -management. However, manually integrating these processes into your app introduces a new layer -of complexity. Instead of manually integrating these features, you can use the the Providers -to manage the logic needed to run your app. - -- ``RealmProvider`` grants access to the configured realm -- ``AppProvider`` grants access to the App Services App -- ``UserProvider`` grants access to the logged-in user object - -The Providers are available to all frameworks used to build with the JavaScript SDK. - -Components and Hooks --------------------- - -Providers are specialized React components, so you can interact with them as you would any other -component. As with components, you can use hooks to access states from Providers. - -Components -~~~~~~~~~~ - -Components are the basic building blocks of React applications and resemble JavaScript -functions. They allow you to separate your app’s functionality and views into smaller chunks -you can manipulate and assemble to create the complete app. You call components using html -opening and closing tags, and they take parameters called Props as input. - -You can nest components within another components tags, creating a parent-child relationship between -them. The props passed into the parent component help create the context that its child -components need to execute their logic. Child components can access this context using hooks. - -Hooks -~~~~~ - -Hooks act as functions you can use to access states in your app. React has built-in hooks you -can import and use in any component. The ``@realm/react`` library also has custom hooks for each -provider you can import. You can use a Provider’s hooks within its component and any of its -child components. There are two important rules to consider when working with hooks: - -- Hooks can only be used at the top level of a React component. -- Hooks can only be called in a React component or a custom hook, not in regular JavaScript - functions. - -Using Providers ---------------- - -To make your Providers context available to your entire app, you can create an App Wrapper by -nesting the Providers in each other. You can then nest any of your custom components in this wrapper. -Most applications built using the ``@realm/react`` library assemble their custom components in -an ``App`` component for better organization. - -.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js - -You *must* nest the Providers as shown when making a wrapper to ensure each Provider can -access the context it needs to function. - -To use a state in a component you’re creating, call the related hook at the top of your -component definition and save the return value to a variable. You can then use this variable -containing the state throughout your component. - -``CODE EXAMPLE COMING`` - -Props and Hooks ---------------- - -For more detail about configuration each provider and to see the props and hooks available for -each, please refer their the API references: - -- :ref:`react-realm-provider` -- :ref:`react-user-provider` -- :ref:`react-app-provider` \ No newline at end of file From f27b8548eaaa6714fb4b0e9ceb288f84f4dc5191 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 01:29:23 -0400 Subject: [PATCH 23/40] some feedback --- source/frameworks/react/providers-hooks.txt | 82 +++++++++++---------- 1 file changed, 42 insertions(+), 40 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 52eefe5027..6b6b4cb166 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -5,7 +5,7 @@ Providers & Hooks ================= .. meta:: - :description: Develop apps using the Providers and Hooks available in the @realm/react library. + :description: Develop apps using the providers and Hooks available in the @realm/react library. :keywords: Realm, Javascript SDK, React, code example .. facet:: @@ -23,24 +23,27 @@ Providers & Hooks :class: singlecol The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to -develop a React app. The components leverage the Provider design pattern to manage user -creation, user authentication, and data management. +develop a React app. The components leverage the provider design pattern to manage your Atlas +connection, user creation and authentication, and data management. -- ``RealmProvider``: Work with the configured database. +- ``RealmProvider``: Work with the configured `database `__. -- ``AppProvider``: Connect to your App Client for user authentication, only necessary when - using Device Sync. +- ``AppProvider``: Connect to your `App Services App Client `__. -- ``UserProvider``: Access to the logged-in user object, only necessary when using Device Sync. +- ``UserProvider``: Access the logged-in `user object `__. -The Providers are available to all frameworks used to build with the JavaScript SDK. +The providers are available to all frameworks used to build with the JavaScript SDK. Getting Started with Providers ------------------------------ -Like all React components, you call Providers using html opening and closing tags. Nesting a -component within in another component's tags creates a parent-child relationship between them, -where child components can access the context created by its parent component. +Like all React components, you call providers using HTML opening and closing tags. Nesting a +component within another component's tags creates a parent-child relationship between them, +where child components can access the context created by its parent component. + +Context refers to the information made accessible by a provider. For example, the +``RealmProvider`` context is the database it connects to, so all components nested in the +``RealmProvider`` have access to that database. Props ~~~~~ @@ -60,28 +63,28 @@ Provider has different props you can use for configuration. - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` - Specifies all the object schemas in this Realm. Required when first creating a Realm. + Specifies all the object schemas in this database. Required when first creating a database. If omitted, the schema will be read from the existing Realm file. - ``sync?: SyncConfiguration`` - Configures a synced realm. + Configures a synced database. ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the Realm is opening. + The fallback component to render while the connecting to the database. - ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, realm will not close when the + Default is ``true``. If set to ``false``, the database connection will not close when the component unmounts. - ``realmRef?: React.MutableRefObject`` - A ref to the realm instance. This is useful if you need to access the realm - instance outside of the scope of the realm. + A ref to the database instance. This is useful if you need to access the database + instance outside of the scope of the Realm. - ``children: React.ReactNode`` @@ -108,18 +111,19 @@ Provider has different props you can use for configuration. Configure your Providers ~~~~~~~~~~~~~~~~~~~~~~~~ -This section details how to configure and expose a single realm using a ``RealmProvider`` -imported directly from ``@realm/react``. For information about using ``createRealmContext()`` -to configure a realm or exposing more than one realm, refer to their respective sections below. +This section details how to configure and expose a single database using a ``RealmProvider`` +imported directly from ``@realm/react``. +For information about using ``createRealmContext()`` to configure a database or exposing more +than one database, refer to their respective sections below. .. tabs:: - .. tab:: Configure realm with sync - :tabid: configure-sync-realm + .. tab:: Configure a database with sync + :tabid: configure-sync-database - If you are developing an app using sync, you will need to use all three Providers. + If you are developing an app using sync, you will need to use all three providers. - By default, Realm syncs all data from the server before returning anything. If you want + By default, Atlas syncs all data from the server before returning anything. If you want to sync data in the background, read :ref:`Configure a Synced Realm While Offline `. @@ -146,14 +150,12 @@ to configure a realm or exposing more than one realm, refer to their respective d. You must set up a sync subscription. The example below uses an initial subscription, but you can also set up subscriptions in ``RealmProvider`` child components. - .. include:: /includes/note-rn-multiple-app-clients-and-app-config-cache.rst - - Once your Providers have been configured, nest your app components within the + Once your providers have been configured, nest your app components within the ``RealmProvider``. The rendering of each component is dependent on the successful execution of its parent components' functionality. For example, if ``AppProvider`` cannot connect to your app's App Services backend, the components it wraps will not render. - You *must* nest the Providers and app components as shown below to ensure each component + You *must* nest the providers and app components as shown below to ensure each component has access to its required context: .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx @@ -168,7 +170,7 @@ to configure a realm or exposing more than one realm, refer to their respective #. Import ``RealmProvider`` from ``@realm/react``. - #. Pass your object models to the ``schema`` prop. (link out) + #. Pass your object models to the ``schema`` prop. #. Add other Configuration object properties as props to ``RealmProvider`` @@ -182,10 +184,10 @@ to configure a realm or exposing more than one realm, refer to their respective Working with Providers using Hooks ---------------------------------- -To use the Provider's context in your app's components, you can use :react.dev:`hooks `. +To use the provider's context in your app's components, you can use Hooks. Hooks act as functions used to access states in your app. React offers built-in hooks you can -use either on their own or to build custom hooks. +use either on their own or to build custom Hooks. There are two important rules to consider when working with hooks: @@ -193,7 +195,7 @@ There are two important rules to consider when working with hooks: - Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions. -The ``@realm/react`` library has custom hooks for each Provider you can import and +The ``@realm/react`` library has custom Hooks for each provider you can import and use in any wrapped component. .. tabs:: @@ -736,16 +738,16 @@ Create Context with createRealmContext() Most of the time, you will only use ``createRealmContext()`` if you need to configure more than one realm. Otherwise, you should import ``RealmProvider`` -and hooks directly from ``@realm/react``. +and Hooks directly from ``@realm/react``. The ``createRealmContext()`` method creates a :reactjs:`React Context ` object for a realm with a given :realm-react-sdk:`Configuration `. The ``Context`` object contains the following: -- A :reactjs:`Context Provider ` (referred to +- A :reactjs:`Context provider ` (referred to as ``RealmProvider`` elsewhere) component that wraps around child components - and provides them with access to hooks. + and provides them with access to Hooks. - Various prebuilt :reactjs:`Hooks ` that access the configured realm. @@ -764,21 +766,21 @@ For a detailed guide, refer to :ref:`Expose More Than One Realm - ``RealmContext`` An object containing a ``RealmProvider`` component, and the ``useRealm``, - ``useQuery`` and ``useObject`` hooks. + ``useQuery`` and ``useObject`` Hooks. Configure More Than One Realm ----------------------------- -When you import ``RealmProvider`` from ``@realm/react``, that Provider has a +When you import ``RealmProvider`` from ``@realm/react``, that provider has a specific context and is associated with a single realm. If you need to configure -more than one realm, use ``createRealmContext()`` to instantiate a new Provider +more than one realm, use ``createRealmContext()`` to instantiate a new provider for each realm. If you import ``useRealm()``, ``useQuery()``, or ``useObject()`` directly from ``@realm/react``, those hooks use the default realm context. To work with more -than one realm, you need to destructure a new realm Provider and its associated +than one realm, you need to destructure a new realm provider and its associated hooks from the result of ``createRealmContext()``. You should namespace providers -to avoid confusion about which Provider and hooks you're working with. +to avoid confusion about which provider and hooks you're working with. For a detailed guide, refer to :ref:`Expose More Than One Realm `. From f967226f708df3736e03eecbb178ce409c424f3c Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 01:56:39 -0400 Subject: [PATCH 24/40] took away tabs --- source/frameworks/react/providers-hooks.txt | 928 ++++++++++++-------- 1 file changed, 573 insertions(+), 355 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 6b6b4cb166..ec81c39d4b 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -19,7 +19,7 @@ Providers & Hooks .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to @@ -198,534 +198,752 @@ There are two important rules to consider when working with hooks: The ``@realm/react`` library has custom Hooks for each provider you can import and use in any wrapped component. -.. tabs:: +RealmProvider Hooks +~~~~~~~~~~~~~~~~~~~ + +useRealm() +`````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + useRealm(): Realm + +The ``useRealm()`` hook returns an opened realm instance. The realm instance +gives you access to realm methods and properties. For example, you can call +``realm.write()`` to add a realm object to your realm. + +To learn more about modifying Realm data, refer to :ref:`Write Transactions +`. + +.. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx + :language: typescript + :emphasize-lines: 3, 6-8, 15 + +*Returns* - .. tab:: RealmProvider Hooks - :tabid: realm-provider-hooks +- ``Realm`` +Returns a realm instance. This is the realm created by the hook's parent, +``RealmProvider``. - .. _react-native-use-realm-hook: +.. _react-native-use-object-hook: - useRealm() - ~~~~~~~~~~ +useObject() +``````````` - .. code:: typescript - :copyable: false - :caption: Type signature +.. code:: typescript + :copyable: false + :caption: Type signature - useRealm(): Realm + useObject(type, primaryKey): T & Realm.Object | null - The ``useRealm()`` hook returns an opened realm instance. The realm instance - gives you access to realm methods and properties. For example, you can call - ``realm.write()`` to add a realm object to your realm. +The ``useObject()`` hook returns a Realm object for a given +:ref:`primary key `. You can pass an object class +or the class name as a string and the primary key. - To learn more about modifying Realm data, refer to :ref:`Write Transactions - `. +The ``useObject()`` method returns null if the object doesn't exist or you have +deleted it. The hook will automatically subscribe to updates and rerender the +component using the hook on any change to the object. - .. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx +.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx :language: typescript - :emphasize-lines: 3, 6-8, 15 - *Returns* +*Parameters* - - ``Realm`` - Returns a realm instance. This is the realm created by the hook's parent, - ``RealmProvider``. +- ``type: string`` +A string that matches your object model's class name or a reference to a +class that extends :js-sdk:`Realm.Object `. +- ``primaryKey: T[keyof T]`` +The primary key of the desired object. - .. _react-native-use-object-hook: +*Returns* - useObject() - ~~~~~~~~~~~ +- ``Realm.Object | null`` +A Realm Object or ``null`` if no object is found. - .. code:: typescript - :copyable: false - :caption: Type signature +.. _react-native-use-query-hook: - useObject(type, primaryKey): T & Realm.Object | null +useQuery() +`````````` - The ``useObject()`` hook returns a Realm object for a given - :ref:`primary key `. You can pass an object class - or the class name as a string and the primary key. +.. code:: typescript + :copyable: false + :caption: Type signature - The ``useObject()`` method returns null if the object doesn't exist or you have - deleted it. The hook will automatically subscribe to updates and rerender the - component using the hook on any change to the object. + useQuery(type, query?, deps?): Realm.Results> - .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx - :language: typescript +The ``useQuery()`` hook returns a collection of realm objects of a given type. +These are the results of your query. A query can be an object class or the class +name as a string. - *Parameters* +The ``useQuery()`` method subscribes to updates to any objects in the collection +and rerenders the component using it on any change to the results. - - ``type: string`` - A string that matches your object model's class name or a reference to a - class that extends :js-sdk:`Realm.Object `. - - ``primaryKey: T[keyof T]`` - The primary key of the desired object. +You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query +results. You should do this in the ``query`` argument of ``useQuery`` so that +they only run when there are changes in the dependency array. For more examples, +refer to the :ref:`CRUD - Read ` docs. - *Returns* +.. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx + :language: typescript + :emphasize-lines: 3-5, 8-14 - - ``Realm.Object | null`` - A Realm Object or ``null`` if no object is found. +*Parameters* - .. _react-native-use-query-hook: +- ``type: string`` +A string that matches your object model's class name or a reference to a +class that extends :js-sdk:`Realm.Object `. +- ``query?: QueryCallback`` +A query function that can filter and sort query results. Builds on +``useCallback`` to memoize the query function. +- ``deps?: DependencyList`` +A list of query function dependencies that's used to memoize +the query function. - useQuery() - ~~~~~~~~~~ +*Returns* - .. code:: typescript - :copyable: false - :caption: Type signature +- ``Realm.Results`` +A Realm Object or ``null`` if no object is found. - useQuery(type, query?, deps?): Realm.Results> +.. _react-native-realm-context: - The ``useQuery()`` hook returns a collection of realm objects of a given type. - These are the results of your query. A query can be an object class or the class - name as a string. +UserProvider Hooks +~~~~~~~~~~~~~~~~~~ - The ``useQuery()`` method subscribes to updates to any objects in the collection - and rerenders the component using it on any change to the results. +useUser() +````````` - You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query - results. You should do this in the ``query`` argument of ``useQuery`` so that - they only run when there are changes in the dependency array. For more examples, - refer to the :ref:`CRUD - Read ` docs. +.. code:: typescript + :copyable: false + :caption: Type signature - .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx - :language: typescript - :emphasize-lines: 3-5, 8-14 + useUser(): Realm.User - *Parameters* +The ``useUser()`` hook provides access to the logged-in user. For example, +you can use ``useUser()`` to log the current user out. - - ``type: string`` - A string that matches your object model's class name or a reference to a - class that extends :js-sdk:`Realm.Object `. - - ``query?: QueryCallback`` - A query function that can filter and sort query results. Builds on - ``useCallback`` to memoize the query function. - - ``deps?: DependencyList`` - A list of query function dependencies that's used to memoize - the query function. +When changes to the user object happen, this hook will rerender its parent +component. For example, if you call ``user.refreshCustomData`` to get updated +custom user data, the ``useUser()`` parent component will rerender. - *Returns* +.. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.log-user-out.tsx.rst - - ``Realm.Results`` - A Realm Object or ``null`` if no object is found. +*Returns* - .. _react-native-realm-context: +- ``Realm.User`` +An instance of the currently-authenticated Realm user. - .. tab:: AppProvider Hooks - :tabid: app-provider-hooks +AppProvider Hooks +~~~~~~~~~~~~~~~~~ - .. _react-native-use-auth: +useApp() +```````` - useApp() - ~~~~~~~~ +.. code:: typescript + :copyable: false + :caption: Type signature - .. code:: typescript - :copyable: false - :caption: Type signature + useApp(): Realm.App - useApp(): Realm.App +*Example* - *Example* +The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` +instance. - The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` - instance. +.. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst +.. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst - .. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst - .. include:: /examples/generated/react-native/v12/use-app.snippet.use-app.tsx.rst +*Returns* - *Returns* +- ``Realm.App`` +An instance of the current ``Realm.App`` created by ``AppProvider``. - - ``Realm.App`` - An instance of the current ``Realm.App`` created by ``AppProvider``. +useAuth() +~~~~~~~~~ - useAuth() - ~~~~~~~~~ +.. code:: typescript + :copyable: false + :caption: Type signature - .. code:: typescript - :copyable: false - :caption: Type signature + useAuth(): UseAuth - useAuth(): UseAuth +``useAuth`` has an authentication method for every App Services +authentication provider. - ``useAuth`` returns ``result`` and an authentication method you specify, as shown below. There is an authentication - method for every App Services authentication provider. +result +`````` - result - `````` +.. code:: typescript + :copyable: false + :caption: Type signature - .. code:: typescript - :copyable: false - :caption: Type signature + result: AuthResult - result: AuthResult +Result of authentication hook operation. For example, ``result.operation`` gives +you the name of the current operation. - Result of authentication hook operation. For example, ``result.operation`` gives - you the name of the current operation. +*Enum values* - *Enum values* +- ``state``. Can be "not-started", "pending", "success", "error". +- ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. +- ``pending``. Can be ``true`` or ``false``. +- ``success``. Can be ``true`` or ``false``. +- ``error``. Error-based object or undefined. - - ``state``. Can be "not-started", "pending", "success", "error". +logIn(credentials) +`````````````````` - - ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. +.. code:: typescript + :copyable: false + :caption: Type signature - - ``pending``. Can be ``true`` or ``false``. + logIn(credentials: Realm.Credentials): void - - ``success``. Can be ``true`` or ``false``. +*Parameters* - - ``error``. Error-based object or undefined. +- ``credentials``. A Realm credential supplied by any supported Realm + authentication. - Authentication Methods - `````````````````````` +*Example* - Below is a list of authentication methods and their Type signatures. An example of using - an authentication method is provided for ``logIn(credentials)``. You use the other authentication - methods in the same way. +Logs in a user with any authentication mechanism supported by +Realm. If called when a user is logged in, the current user switches to +the new user. Usually, it's better to use the more specific login +methods. - .. glossary:: +.. code:: typescript - logIn(credentials) - .. code:: typescript - :copyable: false - :caption: Type signature + const {logIn, result} = useAuth(); - logIn(credentials: Realm.Credentials): void + useEffect(() => logIn(Realm.Credentials.anonymous()), []); - *Parameters* + if(result.pending) { + return () + } - - ``credentials``. A Realm credential supplied by any supported Realm - authentication. + if(result.error) { + return () + } - *Example* + if(result.success) { + return () + } + //... - Logs in a user with any authentication mechanism supported by - Realm. If called when a user is logged in, the current user switches to - the new user. Usually, it's better to use the more specific login - methods. +logInWithAnonymous() +```````````````````` - .. code:: typescript +.. code:: typescript + :copyable: false + :caption: Type signature - const {logIn, result} = useAuth(); + logInWithAnonymous(): void - useEffect(() => logIn(Realm.Credentials.anonymous()), []); +*Example* - if(result.pending) { - return () - } +Log in with the anonymous authentication provider. - if(result.error) { - return () - } +.. code:: typescript - if(result.success) { - return () - } - //... + const {logInWithAnonymous, result} = useAuth(); + const performLogin = () => { + logInWithAnonymous(); + }; +logInWithApiKey(key) +```````````````````` - logInWithAnonymous() - .. code:: typescript - :copyable: false - :caption: Type signature +.. code:: typescript + :copyable: false + :caption: Type signature - logInWithAnonymous(): void + logInWithApiKey(key: string): void - logInWithApiKey(key) - .. code:: typescript - :copyable: false - :caption: Type signature +*Parameters* - logInWithApiKey(key: string): void +- ``key``. A string that is linked to an App Services user. - *Parameters* +*Example* - - ``key``. A string that is linked to an App Services user. +Log in with an API key. - - logInWithEmailPassword(credentials) - .. code:: typescript - :copyable: false - :caption: Type signature +.. code:: typescript - logInWithEmailPassword(credentials: { - email: string; - password: string; - }): void + const {logInWithApiKey, result} = useAuth(); + const performLogin = () => { + const key = getApiKey(); // user defined function + logInWithApiKey(key); + }; - *Parameters* +logInWithEmailPassword(credentials) +``````````````````````````````````` - - ``credentials``. An object with ``email`` and ``password`` fields. +.. code:: typescript + :copyable: false + :caption: Type signature - logInWithJWT(credentials) - .. code:: typescript - :copyable: false - :caption: Type signature + logInWithEmailPassword(credentials: { + email: string; + password: string; + }): void - logInWithJWT(token: string): void +*Parameters* - *Parameters* +- ``credentials``. An object with ``email`` and ``password`` fields. - - ``credentials``. A string representation of a user's JWT. +*Example* - logInWithGoogle(credentials) - .. code:: typescript - :copyable: false - :caption: Type signature +Log in with Email/Password. - logInWithGoogle(credentials: { - idToken: string; - } | { - authCode: string; - }): void; +.. code:: typescript - *Parameters* + const {logInWithEmailPassword, result} = useAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); - - ``credentials``. An object with an ``idToken`` or ``authCode`` field that - should contain the string token you get from Google Identity Services. + const performLogin = () => { + logInWithEmailPassword({email, password}); + }; - logInWithApple(idToken) - .. code:: typescript - :copyable: false - :caption: Type signature +logInWithJWT(credentials) +````````````````````````` - logInWithApple(idToken: string): void; +.. code:: typescript + :copyable: false + :caption: Type signature - *Parameters* + logInWithJWT(token: string): void - - ``idToken``. A string you get from the Apple SDK. +*Parameters* - logInWithFacebook(accessToken) - .. code:: typescript - :copyable: false - :caption: Type signature +- ``credentials``. A string representation of a user's JWT. - logInWithFacebook(accessToken: string): void; +*Example* - *Parameters* +Log in with a JSON Web Token (JWT). + +.. code:: typescript - - ``accessToken``. A string you get from the Facebook SDK. + const {logInWithJWT, result} = useAuth(); - logInWithFunction(payload) - .. code:: typescript - :copyable: false - :caption: Type signature + const performLogin = () => { + const token = authorizeWithCustomerProvider(); // user defined function + logInWithJWT(token); + }; - logInWithFunction>(payload: PayloadType): void; +logInWithGoogle(credentials) +```````````````````````````` - *Parameters* +.. code:: typescript + :copyable: false + :caption: Type signature - - ``payload``. An object that contains user information you want to pass to - the App Services function that processes log in requests. + logInWithGoogle(credentials: { + idToken: string; + } | { + authCode: string; + }): void; - logOut() - .. code:: typescript - :copyable: false - :caption: Type signature +*Parameters* - logOut(): void; +- ``credentials``. An object with an ``idToken`` or ``authCode`` field that + should contain the string token you get from Google Identity Services. - useEmailPasswordAuth() - ~~~~~~~~~~~~~~~~~~~~~~ +*Example* - ``useEmailPasswordAuth`` returns ``result`` and an authentication method you specify, as - shown below. - - result - `````` +Log in with Google. + +.. code:: typescript - .. code:: typescript - :copyable: false - :caption: Type signature + const {logInWithGoogle, result} = useAuth(); - result: AuthResult + const performLogin = () => { + const token = getGoogleToken(); // user defined function + logInWithGoogle({idToken: token}); + }; - Result of authentication hook operation. For example, ``result.operation`` gives - you the name of the current operation. +logInWithApple(idToken) +``````````````````````` - *Enum values* +.. code:: typescript + :copyable: false + :caption: Type signature + + logInWithApple(idToken: string): void; - - ``state``. Can be "not-started", "pending", "success", "error". +*Parameters* - - ``operation``. For a list of all operation names, refer to the - :realm-react-sdk:`API documentation `. +- ``idToken``. A string you get from the Apple SDK. - - ``pending``. Can be ``true`` or ``false``. +*Example* - - ``success``. Can be ``true`` or ``false``. +Log in with Apple. + +.. code:: typescript - - ``error``. Error-based object or undefined. + const {logInWithApple, result} = useAuth(); - Authentication Methods - ````````````````` + const performLogin = () => { + const token = getAppleToken(); // user defined function + logInWithApple(token); + }; - Below is a list of authentication methods and their Type signatures. An example of using - an authentication method is provided for ``logIn(credentials)``. You use the other authentication - methods in the same way. +logInWithFacebook(accessToken) +`````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature - .. glossary:: + logInWithFacebook(accessToken: string): void; - logIn(credentials) - .. code:: typescript - :copyable: false - :caption: Type signature +*Parameters* - logIn(credentials: { email: string; password: string }): void; +- ``accessToken``. A string you get from the Facebook SDK. - *Parameters* +*Example* - - ``credentials``. An object that contains ``email`` and ``password`` properties. +Log in with Facebook. + +.. code:: typescript - *Example* + const {logInWithFacebook, result} = useAuth(); - Logs a user in using an email and password. You could also call - ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a - ``Realm.User`` instance of the logged-in user. + const performLogin = () => { + const token = getFacebookToken(); // user defined function + logInWithFacebook(token); + }; - .. code:: typescript +logInWithFunction(payload) +`````````````````````````` - const {logIn, result} = useEmailPasswordAuth(); +.. code:: typescript + :copyable: false + :caption: Type signature - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + logInWithFunction>(payload: PayloadType): void; - const performLogin = () => { - logIn({email, password}); - }; +*Parameters* - if(result.pending) { - return () - } +- ``payload``. An object that contains user information you want to pass to + the App Services function that processes log in requests. - if(result.error) { - return () - } +*Example* - if(result.success) { - return () - } - //... +Log in with a custom function. + +.. code:: typescript - logOut() - .. code:: typescript - :copyable: false - :caption: Type signature + const {logInWithFunction, result} = useAuth(); - logOut(): void; + const performLogin = () => { + const customPayload = getAuthParams(); // user defined arguments + logInWithFunction(customPayload); + }; - register(args) - .. code:: typescript - :copyable: false - :caption: Type signature +logOut() +```````` - register(args: { email: string; password: string }): void; +.. code:: typescript + :copyable: false + :caption: Type signature - *Parameters* + logOut(): void; - - ``args``. An object that contains ``email`` and ``password`` properties. +*Example* - confirm(args) - .. code:: typescript - :copyable: false - :caption: Type signature +Logs out the current user. + +.. code:: typescript - confirm(args: { token: string; tokenId: string }): void; + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } - *Parameters* +.. _react-native-use-emailpassword-auth: - - ``args``. An object that contains ``token`` and ``tokenId`` properties. +useEmailPasswordAuth() +~~~~~~~~~~~~~~~~~~~~~~ - resendConfirmationEmail(args) - .. code:: typescript - :copyable: false - :caption: Type signature +.. code:: typescript + :copyable: false + :caption: Type signature - resendConfirmationEmail(args: { email: string }): void; + result: AuthResult - *Parameters* +Result of authentication hook operation. For example, ``result.operation`` gives +you the name of the current operation. - - ``args``. An object that contains an ``email`` property. +*Enum values* - retryCustomConfirmation(args) - .. code:: typescript - :copyable: false - :caption: Type signature +- ``state``. Can be "not-started", "pending", "success", "error". +- ``operation``. For a list of all operation names, refer to the + :realm-react-sdk:`API documentation `. +- ``pending``. Can be ``true`` or ``false``. +- ``success``. Can be ``true`` or ``false``. +- ``error``. Error-based object or undefined. - retryCustomConfirmation(args: { email: string }): void; +logIn(credentials) +`````````````````` - *Parameters* +.. code:: typescript + :copyable: false + :caption: Type signature - - ``args``. An object that contains an ``email`` property. + logIn(credentials: { email: string; password: string }): void; - sendResetPasswordEmail(args) - .. code:: typescript - :copyable: false - :caption: Type signature +*Parameters* - sendResetPasswordEmail(args: { email: string }): void; +- ``credentials``. An object that contains ``email`` and ``password`` properties. - *Parameters* +*Example* - - ``args``. An object that contains an ``email`` property. +Logs a user in using an email and password. You could also call +``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a +``Realm.User`` instance of the logged-in user. - resetPassword(args) - .. code:: typescript - :copyable: false - :caption: Type signature +.. code:: typescript - resetPassword(args: { token: string; tokenId: string; password: string }): void; + const {logIn, result} = useEmailPasswordAuth(); - *Parameters* + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); - - ``args``. An object that contains ``token``, ``tokenId``, and ``password`` - properties. + const performLogin = () => { + logIn({email, password}); + }; - callResetPasswordFunction(args, restArgs) - .. code:: typescript - :copyable: false - :caption: Type signature + if(result.pending) { + return () + } - callResetPasswordFunction( - args: { - email: string; - password: string; - }, - ...restArgs: Args - ): void; + if(result.error) { + return () + } - *Parameters* + if(result.success) { + return () + } + //... - - ``args``. An object that contains ``email`` and ``password`` properties. - - ``restArgs``. Additional arguments that you need to pass to your custom - reset password function. +logOut() +```````` - .. tab:: UserProvider Hooks - :tabid: user-provider-hooks +.. code:: typescript + :copyable: false + :caption: Type signature - .. _react-native-use-user-hook: + logOut(): void; - useUser() - ~~~~~~~~~ +*Example* - .. code:: typescript - :copyable: false - :caption: Type signature +Logs out the current user. + +.. code:: typescript - useUser(): Realm.User + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } - The ``useUser()`` hook provides access to the logged-in user. For example, - you can use ``useUser()`` to log the current user out. +register(args) +`````````````` - When changes to the user object happen, this hook will rerender its parent - component. For example, if you call ``user.refreshCustomData`` to get updated - custom user data, the ``useUser()`` parent component will rerender. +.. code:: typescript + :copyable: false + :caption: Type signature + + register(args: { email: string; password: string }): void; + +*Parameters* + +- ``args``. An object that contains ``email`` and ``password`` properties. + +*Example* + +Registers a new user. Requires a user email and password. + +.. code:: typescript + + const {register, result} = useEmailPasswordAuth(); + + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); + + const performRegister = () => { + register({email, password}); + }; + +confirm(args) +````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + confirm(args: { token: string; tokenId: string }): void; + +*Parameters* + +- ``args``. An object that contains ``token`` and ``tokenId`` properties. + +*Example* + +Confirms a user account. Requires a ``token`` and ``tokenId``. + +.. code:: typescript + + const {confirm, result} = useEmailPasswordAuth(); + + const performConfirmation = () => { + confirm({token, tokenId}); + }; + +resendConfirmationEmail(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + resendConfirmationEmail(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Resends a confirmation email. + +.. code:: typescript + + const {resendConfirmationEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performResendConfirmationEmail = () => { + resendConfirmationEmail({email}); + }; + +retryCustomConfirmation(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + retryCustomConfirmation(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Retries confirmation with a custom function. + +.. code:: typescript + + const {retryCustomConfirmation, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performRetryCustomConfirmation = () => { + retryCustomConfirmation({email}); + }; + +sendResetPasswordEmail(args) +````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + sendResetPasswordEmail(args: { email: string }): void; + +*Parameters* + +- ``args``. An object that contains an ``email`` property. + +*Example* + +Sends a password reset email. + +.. code:: typescript + + const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + + const performSendResetPasswordEmail = () => { + sendResetPasswordEmail({email}); + }; + +resetPassword(args) +``````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + resetPassword(args: { token: string; tokenId: string; password: string }): void; + +*Parameters* + +- ``args``. An object that contains ``token``, ``tokenId``, and ``password`` + properties. + +*Example* + +Resets a user's password. + +.. code:: typescript + + const {resetPassword, result} = useEmailPasswordAuth(); + const [password, setPassword] = useState(''); + + const performResetPassword = () => { + resetPassword({token, tokenId, password}); + }; + +callResetPasswordFunction(args, restArgs) +````````````````````````````````````````` + +.. code:: typescript + :copyable: false + :caption: Type signature + + callResetPasswordFunction( + args: { + email: string; + password: string; + }, + ...restArgs: Args + ): void; + +*Parameters* + +- ``args``. An object that contains ``email`` and ``password`` properties. +- ``restArgs``. Additional arguments that you need to pass to your custom + reset password function. + +*Example* + +Calls your App Services backend password reset function. Can pass arguments to +the function as needed. + +.. code:: typescript - .. include:: /examples/generated/react-native/v12/RealmWrapper.snippet.log-user-out.tsx.rst + const {callResetPasswordFunction, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); - *Returns* + const performResetPassword = () => { + callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); + }; - - ``Realm.User`` - An instance of the currently-authenticated Realm user. +.. _react-native-use-app-hook: Create Context with createRealmContext() ---------------------------------------- From 22f265056fc724f4a17deaa8a10e1b6b0580e3bf Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 03:04:57 -0400 Subject: [PATCH 25/40] testing table --- source/frameworks/react/providers-hooks.txt | 58 +++++++++------------ 1 file changed, 26 insertions(+), 32 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index ec81c39d4b..486fc5cb94 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -360,7 +360,7 @@ instance. An instance of the current ``Realm.App`` created by ``AppProvider``. useAuth() -~~~~~~~~~ +````````` .. code:: typescript :copyable: false @@ -392,45 +392,39 @@ you the name of the current operation. - ``success``. Can be ``true`` or ``false``. - ``error``. Error-based object or undefined. -logIn(credentials) -`````````````````` -.. code:: typescript - :copyable: false - :caption: Type signature +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 20 20 60 - logIn(credentials: Realm.Credentials): void + * - Method + - Parameter + - Example -*Parameters* - -- ``credentials``. A Realm credential supplied by any supported Realm - authentication. - -*Example* - -Logs in a user with any authentication mechanism supported by -Realm. If called when a user is logged in, the current user switches to -the new user. Usually, it's better to use the more specific login -methods. - -.. code:: typescript + * - ``logIn`` + - ``credentials``: A Realm credential supplied by any supported Realm authentication. + - Logs in a user with any authentication mechanism supported by Realm. If called when a + user is logged in, the current user switches to the new user. Usually, it's better to use + the more specific login methods. - const {logIn, result} = useAuth(); + .. code:: typescript + const {logIn, result} = useAuth(); - useEffect(() => logIn(Realm.Credentials.anonymous()), []); + useEffect(() => logIn(Realm.Credentials.anonymous()), []); - if(result.pending) { - return () - } + if(result.pending) { + return () + } - if(result.error) { - return () - } + if(result.error) { + return () + } - if(result.success) { - return () - } - //... + if(result.success) { + return () + } + //... logInWithAnonymous() ```````````````````` From 4f494e28bcf0d60eb2aa7dc9c78d834a3084f554 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 04:21:21 -0400 Subject: [PATCH 26/40] finished first table --- source/frameworks/react/providers-hooks.txt | 625 +++++++------------- 1 file changed, 203 insertions(+), 422 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 486fc5cb94..0a99d7736e 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -368,11 +368,10 @@ useAuth() useAuth(): UseAuth -``useAuth`` has an authentication method for every App Services -authentication provider. +``useAuth`` has an authentication method for every App Services authentication provider. result -`````` +++++++ .. code:: typescript :copyable: false @@ -392,23 +391,25 @@ you the name of the current operation. - ``success``. Can be ``true`` or ``false``. - ``error``. Error-based object or undefined. +Authentication Methods +++++++++++++++++++++++ .. list-table:: :header-rows: 1 :stub-columns: 1 - :widths: 20 20 60 - * - Method + * - Operation - Parameter - Example - * - ``logIn`` + * - ``logIn(credentials)`` - ``credentials``: A Realm credential supplied by any supported Realm authentication. - Logs in a user with any authentication mechanism supported by Realm. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use the more specific login methods. .. code:: typescript + const {logIn, result} = useAuth(); useEffect(() => logIn(Realm.Credentials.anonymous()), []); @@ -426,241 +427,130 @@ you the name of the current operation. } //... -logInWithAnonymous() -```````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithAnonymous(): void - -*Example* - -Log in with the anonymous authentication provider. - -.. code:: typescript - - const {logInWithAnonymous, result} = useAuth(); - const performLogin = () => { - logInWithAnonymous(); - }; - -logInWithApiKey(key) -```````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApiKey(key: string): void - -*Parameters* - -- ``key``. A string that is linked to an App Services user. - -*Example* - -Log in with an API key. - -.. code:: typescript - - const {logInWithApiKey, result} = useAuth(); - const performLogin = () => { - const key = getApiKey(); // user defined function - logInWithApiKey(key); - }; - -logInWithEmailPassword(credentials) -``````````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithEmailPassword(credentials: { - email: string; - password: string; - }): void - -*Parameters* + * - ``logInWithAnonymous`` + - None + - Log in with the anonymous authentication provider. -- ``credentials``. An object with ``email`` and ``password`` fields. - -*Example* + .. code:: typescript -Log in with Email/Password. + const {logInWithAnonymous, result} = useAuth(); + const performLogin = () => { + logInWithAnonymous(); + }; -.. code:: typescript + * - ``logInWithApiKey(key)`` + - ``key``: A string that is linked to an App Services user. + - Log in with an API key. - const {logInWithEmailPassword, result} = useAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + .. code:: typescript - const performLogin = () => { - logInWithEmailPassword({email, password}); - }; + const {logInWithApiKey, result} = useAuth(); + const performLogin = () => { + const key = getApiKey(); // user defined function + logInWithApiKey(key); + }; -logInWithJWT(credentials) -````````````````````````` + * - ``logInWithEmailPassword(credentials)`` + - ``credentials``: An object with ``email`` and ``password`` fields. + - Log in with Email/Password. -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithJWT(token: string): void + .. code:: typescript -*Parameters* + const {logInWithEmailPassword, result} = useAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); -- ``credentials``. A string representation of a user's JWT. + const performLogin = () => { + logInWithEmailPassword({email, password}); + }; -*Example* - -Log in with a JSON Web Token (JWT). + * - ``logInWithJWT(credentials)`` + - ``credentials``: A string representation of a user's JWT. + - Log in with a JSON Web Token (JWT). -.. code:: typescript - - const {logInWithJWT, result} = useAuth(); - - const performLogin = () => { - const token = authorizeWithCustomerProvider(); // user defined function - logInWithJWT(token); - }; - -logInWithGoogle(credentials) -```````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithGoogle(credentials: { - idToken: string; - } | { - authCode: string; - }): void; - -*Parameters* + .. code:: typescript -- ``credentials``. An object with an ``idToken`` or ``authCode`` field that - should contain the string token you get from Google Identity Services. + const {logInWithJWT, result} = useAuth(); -*Example* + const performLogin = () => { + const token = authorizeWithCustomerProvider(); // user defined function + logInWithJWT(token); + }; -Log in with Google. + * - ``logInWithGoogle(credentials)`` + - ``credentials``; An object with an ``idToken`` or ``authCode`` field that + should contain the string token you get from Google Identity Services. + - Log in with Google. -.. code:: typescript - - const {logInWithGoogle, result} = useAuth(); - - const performLogin = () => { - const token = getGoogleToken(); // user defined function - logInWithGoogle({idToken: token}); - }; - -logInWithApple(idToken) -``````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithApple(idToken: string): void; - -*Parameters* + .. code:: typescript -- ``idToken``. A string you get from the Apple SDK. + const {logInWithGoogle, result} = useAuth(); -*Example* + const performLogin = () => { + const token = getGoogleToken(); // user defined function + logInWithGoogle({idToken: token}); + }; -Log in with Apple. + * - ``logInWithApple(idToken)`` + - ``idToken``: A string you get from the Apple SDK. + - Log in with Apple. -.. code:: typescript - - const {logInWithApple, result} = useAuth(); - - const performLogin = () => { - const token = getAppleToken(); // user defined function - logInWithApple(token); - }; - -logInWithFacebook(accessToken) -`````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithFacebook(accessToken: string): void; - -*Parameters* + .. code:: typescript -- ``accessToken``. A string you get from the Facebook SDK. + const {logInWithApple, result} = useAuth(); -*Example* + const performLogin = () => { + const token = getAppleToken(); // user defined function + logInWithApple(token); + }; -Log in with Facebook. + * - ``logInWithFacebook(accessToken)`` + - ``accessToken``: A string you get from the Facebook SDK. + - Log in with Facebook. -.. code:: typescript - - const {logInWithFacebook, result} = useAuth(); - - const performLogin = () => { - const token = getFacebookToken(); // user defined function - logInWithFacebook(token); - }; - -logInWithFunction(payload) -`````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logInWithFunction>(payload: PayloadType): void; - -*Parameters* + .. code:: typescript -- ``payload``. An object that contains user information you want to pass to - the App Services function that processes log in requests. + const {logInWithFacebook, result} = useAuth(); -*Example* + const performLogin = () => { + const token = getFacebookToken(); // user defined function + logInWithFacebook(token); + }; -Log in with a custom function. + * - ``logInWithFunction(payload)`` + - ``payload``: An object that contains user information you want to pass to + the App Services function that processes log in requests. + - Log in with a custom function. -.. code:: typescript - - const {logInWithFunction, result} = useAuth(); - - const performLogin = () => { - const customPayload = getAuthParams(); // user defined arguments - logInWithFunction(customPayload); - }; - -logOut() -```````` - -.. code:: typescript - :copyable: false - :caption: Type signature + .. code:: typescript - logOut(): void; + const {logInWithFunction, result} = useAuth(); -*Example* + const performLogin = () => { + const customPayload = getAuthParams(); // user defined arguments + logInWithFunction(customPayload); + }; -Logs out the current user. + * - ``logOut()`` + - None + - Logs out the current user. -.. code:: typescript + .. code:: typescript - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } .. _react-native-use-emailpassword-auth: useEmailPasswordAuth() -~~~~~~~~~~~~~~~~~~~~~~ +`````````````````````` + +``useEmailPasswordAuth`` has a number of operations to facilitate email and password user authentication. + +result +++++++ .. code:: typescript :copyable: false @@ -668,8 +558,8 @@ useEmailPasswordAuth() result: AuthResult -Result of authentication hook operation. For example, ``result.operation`` gives -you the name of the current operation. +Result of operation. For example, ``result.operation`` gives you the name of the current +operation. *Enum values* @@ -680,264 +570,155 @@ you the name of the current operation. - ``success``. Can be ``true`` or ``false``. - ``error``. Error-based object or undefined. -logIn(credentials) -`````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - logIn(credentials: { email: string; password: string }): void; - -*Parameters* - -- ``credentials``. An object that contains ``email`` and ``password`` properties. - -*Example* - -Logs a user in using an email and password. You could also call -``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a -``Realm.User`` instance of the logged-in user. - -.. code:: typescript +Authentication Operations ++++++++++++++++++++++++++ - const {logIn, result} = useEmailPasswordAuth(); +.. list-table:: + :header-rows: 1 + :stub-columns: 1 - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + * - Operation + - Parameter + - Example - const performLogin = () => { - logIn({email, password}); - }; + * - ``logIn(credentials)`` + - ``credentials``: An object that contains ``email`` and ``password`` properties. + - Logs a user in using an email and password. You could also call + ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a + ``Realm.User`` instance of the logged-in user. - if(result.pending) { - return () - } + .. code:: typescript - if(result.error) { - return () - } + const {logIn, result} = useEmailPasswordAuth(); - if(result.success) { - return () - } - //... + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); -logOut() -```````` + const performLogin = () => { + logIn({email, password}); + }; -.. code:: typescript - :copyable: false - :caption: Type signature + if(result.pending) { + return () + } - logOut(): void; + if(result.error) { + return () + } -*Example* + if(result.success) { + return () + } + //... -Logs out the current user. + * - ``logOut()`` + - None + - Logs out the current user. -.. code:: typescript - - const {logOut, result} = useEmailPasswordAuth(); - const performLogout = () => { - logOut(); - } - -register(args) -`````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - register(args: { email: string; password: string }): void; - -*Parameters* - -- ``args``. An object that contains ``email`` and ``password`` properties. + .. code:: typescript -*Example* + const {logOut, result} = useEmailPasswordAuth(); + const performLogout = () => { + logOut(); + } -Registers a new user. Requires a user email and password. + * - ``register(args)`` + - ``args``: An object that contains ``email`` and ``password`` properties. + - Registers a new user. Requires a user email and password. -.. code:: typescript - - const {register, result} = useEmailPasswordAuth(); - - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); - - const performRegister = () => { - register({email, password}); - }; - -confirm(args) -````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - confirm(args: { token: string; tokenId: string }): void; + .. code:: typescript -*Parameters* + const {register, result} = useEmailPasswordAuth(); -- ``args``. An object that contains ``token`` and ``tokenId`` properties. + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); -*Example* + const performRegister = () => { + register({email, password}); + }; -Confirms a user account. Requires a ``token`` and ``tokenId``. + * - ``confirm(args)`` + - ``args``: An object that contains ``token`` and ``tokenId`` properties. + - Confirms a user account. Requires a ``token`` and ``tokenId``. -.. code:: typescript - - const {confirm, result} = useEmailPasswordAuth(); - - const performConfirmation = () => { - confirm({token, tokenId}); - }; - -resendConfirmationEmail(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - resendConfirmationEmail(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Resends a confirmation email. - -.. code:: typescript - - const {resendConfirmationEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - - const performResendConfirmationEmail = () => { - resendConfirmationEmail({email}); - }; - -retryCustomConfirmation(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - retryCustomConfirmation(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Retries confirmation with a custom function. - -.. code:: typescript - - const {retryCustomConfirmation, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - - const performRetryCustomConfirmation = () => { - retryCustomConfirmation({email}); - }; - -sendResetPasswordEmail(args) -````````````````````````````` - -.. code:: typescript - :copyable: false - :caption: Type signature - - sendResetPasswordEmail(args: { email: string }): void; - -*Parameters* - -- ``args``. An object that contains an ``email`` property. - -*Example* - -Sends a password reset email. - -.. code:: typescript + .. code:: typescript - const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); + const {confirm, result} = useEmailPasswordAuth(); - const performSendResetPasswordEmail = () => { - sendResetPasswordEmail({email}); - }; + const performConfirmation = () => { + confirm({token, tokenId}); + }; -resetPassword(args) -``````````````````` + * - ``resendConfirmationEmail(args)`` + - ``args``: An object that contains an ``email`` property. + - Resends a confirmation email. -.. code:: typescript - :copyable: false - :caption: Type signature + .. code:: typescript - resetPassword(args: { token: string; tokenId: string; password: string }): void; + const {resendConfirmationEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); -*Parameters* + const performResendConfirmationEmail = () => { + resendConfirmationEmail({email}); + }; -- ``args``. An object that contains ``token``, ``tokenId``, and ``password`` - properties. + * - ``retryCustomConfirmation(args)`` + - ``args``: An object that contains an ``email`` property. + - Retries confirmation with a custom function. -*Example* + .. code:: typescript -Resets a user's password. + const {retryCustomConfirmation, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); -.. code:: typescript + const performRetryCustomConfirmation = () => { + retryCustomConfirmation({email}); + }; - const {resetPassword, result} = useEmailPasswordAuth(); - const [password, setPassword] = useState(''); + * - ``sendResetPasswordEmail(args)`` + - ``args``: An object that contains an ``email`` property. + - Sends a password reset email. - const performResetPassword = () => { - resetPassword({token, tokenId, password}); - }; + .. code:: typescript -callResetPasswordFunction(args, restArgs) -````````````````````````````````````````` + const {sendResetPasswordEmail, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); -.. code:: typescript - :copyable: false - :caption: Type signature + const performSendResetPasswordEmail = () => { + sendResetPasswordEmail({email}); + }; - callResetPasswordFunction( - args: { - email: string; - password: string; - }, - ...restArgs: Args - ): void; + * - ``resetPassword(args)`` + - ``args``: An object that contains ``token``, ``tokenId``, and ``password`` + properties. + - Resets a user's password. -*Parameters* + .. code:: typescript -- ``args``. An object that contains ``email`` and ``password`` properties. -- ``restArgs``. Additional arguments that you need to pass to your custom - reset password function. + const {resetPassword, result} = useEmailPasswordAuth(); + const [password, setPassword] = useState(''); -*Example* + const performResetPassword = () => { + resetPassword({token, tokenId, password}); + }; -Calls your App Services backend password reset function. Can pass arguments to -the function as needed. + * - ``callResetPasswordFunction(args, restArgs)`` + - ``args``: An object that contains ``email`` and ``password`` properties. -.. code:: typescript + ``restArgs``: Additional arguments that you need to pass to your custom + reset password function. + - Calls your App Services backend password reset function. Can pass arguments to + the function as needed. - const {callResetPasswordFunction, result} = useEmailPasswordAuth(); - const [email, setEmail] = useState(''); - const [password, setPassword] = useState(''); + .. code:: typescript - const performResetPassword = () => { - callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); - }; + const {callResetPasswordFunction, result} = useEmailPasswordAuth(); + const [email, setEmail] = useState(''); + const [password, setPassword] = useState(''); -.. _react-native-use-app-hook: + const performResetPassword = () => { + callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); + }; Create Context with createRealmContext() ---------------------------------------- From b1c9d0cc426da4dc34e638aaa1db2083f1e4e8ee Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 12:58:44 -0400 Subject: [PATCH 27/40] linkned to other pages --- source/frameworks/react/providers-hooks.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 0a99d7736e..f06a7930df 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -210,7 +210,7 @@ useRealm() useRealm(): Realm -The ``useRealm()`` hook returns an opened realm instance. The realm instance +The ``useRealm()`` hook returns an opened `realm instance `__. The realm instance gives you access to realm methods and properties. For example, you can call ``realm.write()`` to add a realm object to your realm. @@ -238,7 +238,7 @@ useObject() useObject(type, primaryKey): T & Realm.Object | null -The ``useObject()`` hook returns a Realm object for a given +The ``useObject()`` hook returns a :js-sdk:`Realm object ` for a given :ref:`primary key `. You can pass an object class or the class name as a string and the primary key. From e6a21924b7e521e13050b86894aceb1417fe0faf Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 13:02:02 -0400 Subject: [PATCH 28/40] linkned to other pages --- source/frameworks/react/providers-hooks.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index f06a7930df..1334435b1b 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -210,7 +210,7 @@ useRealm() useRealm(): Realm -The ``useRealm()`` hook returns an opened `realm instance `__. The realm instance +The ``useRealm()`` hook returns an opened :js-sdk:`realm instance`. The realm instance gives you access to realm methods and properties. For example, you can call ``realm.write()`` to add a realm object to your realm. From b50c034c7de14811e7e97ddedff9a31c2096a602 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Sun, 4 Aug 2024 13:28:16 -0400 Subject: [PATCH 29/40] linkned to other pages --- source/frameworks/react/providers-hooks.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 1334435b1b..d3335f6be4 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -273,9 +273,9 @@ useQuery() useQuery(type, query?, deps?): Realm.Results> -The ``useQuery()`` hook returns a collection of realm objects of a given type. -These are the results of your query. A query can be an object class or the class -name as a string. +The ``useQuery()`` hook returns a :js-sdk:`result ` that is a +collection of realm objects of a given type. These are the results of your query. A query can +be an object class or the class name as a string. The ``useQuery()`` method subscribes to updates to any objects in the collection and rerenders the component using it on any change to the results. @@ -320,7 +320,7 @@ useUser() useUser(): Realm.User -The ``useUser()`` hook provides access to the logged-in user. For example, +The ``useUser()`` hook provides access to the :js-sdk:`logged-in user `. For example, you can use ``useUser()`` to log the current user out. When changes to the user object happen, this hook will rerender its parent @@ -368,7 +368,7 @@ useAuth() useAuth(): UseAuth -``useAuth`` has an authentication method for every App Services authentication provider. +You use the `useAuth()` Hook with a result and authentication method. result ++++++ @@ -394,6 +394,8 @@ you the name of the current operation. Authentication Methods ++++++++++++++++++++++ +The authentication method specifies how you want users to login to your app. ``useAuth`` has an authentication method for every App Services authentication provider. + .. list-table:: :header-rows: 1 :stub-columns: 1 @@ -547,7 +549,7 @@ Authentication Methods useEmailPasswordAuth() `````````````````````` -``useEmailPasswordAuth`` has a number of operations to facilitate email and password user authentication. +You use the `useEmailPasswordAuth()` Hook with a result and authentication operation. result ++++++ @@ -573,6 +575,8 @@ operation. Authentication Operations +++++++++++++++++++++++++ +``useEmailPasswordAuth`` has a number of operations to facilitate email and password user authentication. + .. list-table:: :header-rows: 1 :stub-columns: 1 From fd474fa4b62252dfb648ef01e5df4d0640b50495 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 00:12:20 -0400 Subject: [PATCH 30/40] more changes --- source/frameworks/react/providers-hooks.txt | 41 +++++++++++---------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index d3335f6be4..60746a9c39 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -23,23 +23,24 @@ Providers & Hooks :class: singlecol The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to -develop a React app. The components leverage the provider design pattern to manage your Atlas +develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the provider design pattern to manage your Atlas connection, user creation and authentication, and data management. -- ``RealmProvider``: Work with the configured `database `__. +- ``RealmProvider``: Work with the configured :js-sdk:`database `. -- ``AppProvider``: Connect to your `App Services App Client `__. +- ``AppProvider``: Connect to your :js-sdk:`App Services App Client `. -- ``UserProvider``: Access the logged-in `user object `__. +- ``UserProvider``: Access the logged-in :js-sdk:`user object `. -The providers are available to all frameworks used to build with the JavaScript SDK. +The providers are available in all SDKs that support a React environment. This includes React +Native, Web, and Electron. Getting Started with Providers ------------------------------ Like all React components, you call providers using HTML opening and closing tags. Nesting a component within another component's tags creates a parent-child relationship between them, -where child components can access the context created by its parent component. +where child components can access the context created by their parent component. Context refers to the information made accessible by a provider. For example, the ``RealmProvider`` context is the database it connects to, so all components nested in the @@ -48,7 +49,7 @@ Context refers to the information made accessible by a provider. For example, th Props ~~~~~ -Components take parameters called Props as input, passed into the opening tag. The props passed +Components take parameters called props as input, passed into the opening tag. The props passed into a parent component help create the context inherited by the components it wraps. Each Provider has different props you can use for configuration. @@ -68,17 +69,17 @@ Provider has different props you can use for configuration. - ``sync?: SyncConfiguration`` - Configures a synced database. + Defines Device Sync behavior for this realm, including initial subscriptions. ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the connecting to the database. + The fallback component to render while the Realm is opening or if the Realm fails to open. - ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, the database connection will not close when the + Default is ``true``. If set to ``false``, the open realm will not close when the component unmounts. - ``realmRef?: React.MutableRefObject`` @@ -98,7 +99,7 @@ Provider has different props you can use for configuration. - ``id: string`` - Specifies the App ID. + Specifies the App Services App ID. .. tab:: UserProvider Props :tabid: user-provider-props @@ -121,7 +122,7 @@ than one database, refer to their respective sections below. .. tab:: Configure a database with sync :tabid: configure-sync-database - If you are developing an app using sync, you will need to use all three providers. + If you are developing an app using Device Sync, you will need to use all three providers. By default, Atlas syncs all data from the server before returning anything. If you want to sync data in the background, read :ref:`Configure a Synced Realm While Offline @@ -133,21 +134,21 @@ than one database, refer to their respective sections below. 2. Configure ``AppProvider``. - a. Pass your App ID string to the ``id`` prop of the ``AppProvider``. + a. Pass your App Services App ID string to the ``id`` prop of the ``AppProvider``. 3. Configure ``UserProvider`` and nest it within ``AppProvider``. - a. Pass a component that logs a user in into the ``fallback`` prop. The app renders this component if there is no authenticated user. + a. Pass a component that logs in a user to the ``fallback`` prop. The app renders this component if there is no authenticated user. - 4. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``. + 4. Configure ``RealmProvider`` for Device Sync and nest it within ``UserProvider``. a. Pass your object models to the ``schema`` prop. b. Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. - c. Add other Configuration object properties as props to ``RealmProvider``. + c. Add other configuration object properties as props to ``RealmProvider``. - d. You must set up a sync subscription. The example below uses an initial subscription, + d. To sync data, you must set up a sync subscription. The example below uses an initial subscription, but you can also set up subscriptions in ``RealmProvider`` child components. Once your providers have been configured, nest your app components within the @@ -195,8 +196,8 @@ There are two important rules to consider when working with hooks: - Hooks can only be called in a React component or a custom hook, not in regular JavaScript functions. -The ``@realm/react`` library has custom Hooks for each provider you can import and -use in any wrapped component. +The ``@realm/react`` library has custom Hooks for each provider you can +use to access a provider's context in the components it wraps. RealmProvider Hooks ~~~~~~~~~~~~~~~~~~~ @@ -742,7 +743,7 @@ The ``createRealmContext()`` method creates a :reactjs:`React Context :realm-react-sdk:`Configuration `. The ``Context`` object contains the following: -- A :reactjs:`Context provider ` (referred to +- A :reactjs:`Context Provider ` (referred to as ``RealmProvider`` elsewhere) component that wraps around child components and provides them with access to Hooks. - Various prebuilt :reactjs:`Hooks ` that access the From 61a208c849edb6b7f08e402e99c1ca4f220c9f85 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 01:34:05 -0400 Subject: [PATCH 31/40] fixed createRealmContext section --- source/frameworks/react/providers-hooks.txt | 72 +++++++++------------ 1 file changed, 30 insertions(+), 42 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 60746a9c39..100471cf74 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -114,8 +114,8 @@ Configure your Providers This section details how to configure and expose a single database using a ``RealmProvider`` imported directly from ``@realm/react``. -For information about using ``createRealmContext()`` to configure a database or exposing more -than one database, refer to their respective sections below. +For information about using ``createRealmContext()`` to configure a Realm or exposing more +than one Realm, see "Create Context with createRealmContext()" below. .. tabs:: @@ -181,7 +181,6 @@ than one database, refer to their respective sections below. .. literalinclude:: /examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx :language: typescript - Working with Providers using Hooks ---------------------------------- @@ -202,6 +201,8 @@ use to access a provider's context in the components it wraps. RealmProvider Hooks ~~~~~~~~~~~~~~~~~~~ +.. _sdks-react-use-realm-hook: + useRealm() `````````` @@ -228,7 +229,7 @@ To learn more about modifying Realm data, refer to :ref:`Write Transactions Returns a realm instance. This is the realm created by the hook's parent, ``RealmProvider``. -.. _react-native-use-object-hook: +.. _sdks-react-use-object-hook: useObject() ``````````` @@ -263,7 +264,7 @@ The primary key of the desired object. - ``Realm.Object | null`` A Realm Object or ``null`` if no object is found. -.. _react-native-use-query-hook: +.. _sdks-react-use-query-hook: useQuery() `````````` @@ -307,11 +308,11 @@ the query function. - ``Realm.Results`` A Realm Object or ``null`` if no object is found. -.. _react-native-realm-context: - UserProvider Hooks ~~~~~~~~~~~~~~~~~~ +.. _sdks-react-use-user-hook: + useUser() ````````` @@ -338,6 +339,8 @@ An instance of the currently-authenticated Realm user. AppProvider Hooks ~~~~~~~~~~~~~~~~~ +.. _sdks-react-use-app-hook: + useApp() ```````` @@ -360,6 +363,8 @@ instance. - ``Realm.App`` An instance of the current ``Realm.App`` created by ``AppProvider``. +.. _sdks-react-use-auth-hook: + useAuth() ````````` @@ -545,7 +550,7 @@ The authentication method specifies how you want users to login to your app. ``u logOut(); } -.. _react-native-use-emailpassword-auth: +.. _sdks-react-use-emailpassword-auth-hook: useEmailPasswordAuth() `````````````````````` @@ -725,6 +730,8 @@ Authentication Operations callResetPasswordFunction({email, password}, "extraArg1", "extraArg2"); }; +.. _create_context_with_createrealmcontext: + Create Context with createRealmContext() ---------------------------------------- @@ -734,24 +741,6 @@ Create Context with createRealmContext() createRealmContext(realmConfig?): RealmContext -Most of the time, you will only use ``createRealmContext()`` if you need to -configure more than one realm. Otherwise, you should import ``RealmProvider`` -and Hooks directly from ``@realm/react``. - -The ``createRealmContext()`` method creates a :reactjs:`React Context -` object for a realm with a given -:realm-react-sdk:`Configuration `. The -``Context`` object contains the following: - -- A :reactjs:`Context Provider ` (referred to - as ``RealmProvider`` elsewhere) component that wraps around child components - and provides them with access to Hooks. -- Various prebuilt :reactjs:`Hooks ` that access the - configured realm. - -For a detailed guide, refer to :ref:`Expose More Than One Realm -`. - *Parameters* - ``realmConfig?: Realm.Configuration`` @@ -766,22 +755,21 @@ For a detailed guide, refer to :ref:`Expose More Than One Realm An object containing a ``RealmProvider`` component, and the ``useRealm``, ``useQuery`` and ``useObject`` Hooks. -Configure More Than One Realm ------------------------------ - -When you import ``RealmProvider`` from ``@realm/react``, that provider has a -specific context and is associated with a single realm. If you need to configure -more than one realm, use ``createRealmContext()`` to instantiate a new provider -for each realm. +Most of the time, you will only use ``createRealmContext()`` if you need to +configure more than one realm. Otherwise, you should import ``RealmProvider`` +and Hooks directly from ``@realm/react``. -If you import ``useRealm()``, ``useQuery()``, or ``useObject()`` directly from -``@realm/react``, those hooks use the default realm context. To work with more -than one realm, you need to destructure a new realm provider and its associated -hooks from the result of ``createRealmContext()``. You should namespace providers -to avoid confusion about which provider and hooks you're working with. +The ``createRealmContext()`` method creates a `React Context +`__ object for a realm with a given +:realm-react-sdk:`Configuration `. The +``Context`` object contains the following: -For a detailed guide, refer to :ref:`Expose More Than One Realm -`. +- A Context Provider component that wraps around child components + and provides them with access to Hooks. +- Various prebuilt Hooks that access the configured realm. -For details about ``createRealmContext()``, refer to "Create Context with -createRealmContext()" on this page. \ No newline at end of file +To work with more than one realm, you need to destructure a new realm provider and its +associated hooks from the result of ``createRealmContext()``. You can call this new realm +provider and use its associated Hooks the same way you would with the ``RealmProvider`` +imported from the ``@realm/react`` library. You should namespace providers +to avoid confusion about which provider and hooks you're working with. \ No newline at end of file From 753e5964935a54f2798d0b4b95f54b70d792fe99 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 02:33:15 -0400 Subject: [PATCH 32/40] fixed create context --- source/frameworks/react/providers-hooks.txt | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 100471cf74..2260295e0b 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -26,7 +26,7 @@ The ``@realm/react`` library offers custom React components that eliminate the b develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the provider design pattern to manage your Atlas connection, user creation and authentication, and data management. -- ``RealmProvider``: Work with the configured :js-sdk:`database `. +- ``RealmProvider``: Work with the configured :js-sdk:`Realm `. - ``AppProvider``: Connect to your :js-sdk:`App Services App Client `. @@ -43,8 +43,8 @@ component within another component's tags creates a parent-child relationship be where child components can access the context created by their parent component. Context refers to the information made accessible by a provider. For example, the -``RealmProvider`` context is the database it connects to, so all components nested in the -``RealmProvider`` have access to that database. +``RealmProvider`` context is the Realm it connects to, so all components nested in the +``RealmProvider`` have access to that Realm. Props ~~~~~ @@ -64,7 +64,7 @@ Provider has different props you can use for configuration. - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` - Specifies all the object schemas in this database. Required when first creating a database. + Specifies all the object schemas in the Realm. Required when first creating a Realm. If omitted, the schema will be read from the existing Realm file. - ``sync?: SyncConfiguration`` @@ -84,7 +84,7 @@ Provider has different props you can use for configuration. - ``realmRef?: React.MutableRefObject`` - A ref to the database instance. This is useful if you need to access the database + A ref to the Realm instance. This is useful if you need to access the Realm instance outside of the scope of the Realm. - ``children: React.ReactNode`` @@ -112,15 +112,18 @@ Provider has different props you can use for configuration. Configure your Providers ~~~~~~~~~~~~~~~~~~~~~~~~ -This section details how to configure and expose a single database using a ``RealmProvider`` +Your app's needs determine what providers you use, as all three providers are not always +necessary. + +This section details how to configure and expose a single Realm using a ``RealmProvider`` imported directly from ``@realm/react``. For information about using ``createRealmContext()`` to configure a Realm or exposing more than one Realm, see "Create Context with createRealmContext()" below. .. tabs:: - .. tab:: Configure a database with sync - :tabid: configure-sync-database + .. tab:: Configure a Realm with sync + :tabid: configure-sync-realm If you are developing an app using Device Sync, you will need to use all three providers. @@ -772,4 +775,4 @@ To work with more than one realm, you need to destructure a new realm provider a associated hooks from the result of ``createRealmContext()``. You can call this new realm provider and use its associated Hooks the same way you would with the ``RealmProvider`` imported from the ``@realm/react`` library. You should namespace providers -to avoid confusion about which provider and hooks you're working with. \ No newline at end of file +to avoid confusion about which provider and Hooks you're working with. \ No newline at end of file From 45c2e43b5e43bb3739dde15c41adbf28b5df08e7 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 03:49:20 -0400 Subject: [PATCH 33/40] code examples for all three providers --- source/frameworks/react/providers-hooks.txt | 100 ++++++++------------ 1 file changed, 40 insertions(+), 60 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 2260295e0b..9885907a2f 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -26,12 +26,6 @@ The ``@realm/react`` library offers custom React components that eliminate the b develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the provider design pattern to manage your Atlas connection, user creation and authentication, and data management. -- ``RealmProvider``: Work with the configured :js-sdk:`Realm `. - -- ``AppProvider``: Connect to your :js-sdk:`App Services App Client `. - -- ``UserProvider``: Access the logged-in :js-sdk:`user object `. - The providers are available in all SDKs that support a React environment. This includes React Native, Web, and Electron. @@ -113,76 +107,62 @@ Configure your Providers ~~~~~~~~~~~~~~~~~~~~~~~~ Your app's needs determine what providers you use, as all three providers are not always -necessary. +necessary: -This section details how to configure and expose a single Realm using a ``RealmProvider`` -imported directly from ``@realm/react``. -For information about using ``createRealmContext()`` to configure a Realm or exposing more -than one Realm, see "Create Context with createRealmContext()" below. +- ``AppProvider``: Used to connect to your :js-sdk:`Atlas App Services App Client + `, including for user authentication. -.. tabs:: +- ``UserProvider``: Used to access the logged-in :js-sdk:`user object `. - .. tab:: Configure a Realm with sync - :tabid: configure-sync-realm +- ``RealmProvider``: Used to work with the configured :js-sdk:`Realm `. - If you are developing an app using Device Sync, you will need to use all three providers. +This example below walks through configuring all three providers. If your app does not need a +provider, you can skip the associated steps and omit the associated code. - By default, Atlas syncs all data from the server before returning anything. If you want - to sync data in the background, read :ref:`Configure a Synced Realm While Offline - `. +**To configure your providers:** - To configure a synced realm: +1. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. - 1. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. - - 2. Configure ``AppProvider``. +2. Configure ``AppProvider``. - a. Pass your App Services App ID string to the ``id`` prop of the ``AppProvider``. - - 3. Configure ``UserProvider`` and nest it within ``AppProvider``. - - a. Pass a component that logs in a user to the ``fallback`` prop. The app renders this component if there is no authenticated user. - - 4. Configure ``RealmProvider`` for Device Sync and nest it within ``UserProvider``. - - a. Pass your object models to the ``schema`` prop. + a. Pass your App Services App ID string to the ``id`` prop of the ``AppProvider``. - b. Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary. +3. Configure ``UserProvider`` and nest it within ``AppProvider``. + + a. Pass a component that logs in a user to the ``fallback`` prop. The app renders this component if there is no authenticated user. - c. Add other configuration object properties as props to ``RealmProvider``. +4. Configure ``RealmProvider`` and nest it within ``UserProvider``. - d. To sync data, you must set up a sync subscription. The example below uses an initial subscription, - but you can also set up subscriptions in ``RealmProvider`` child components. + a. Pass your object models to the ``schema`` prop. - Once your providers have been configured, nest your app components within the - ``RealmProvider``. The rendering of each component is dependent on the successful - execution of its parent components' functionality. For example, if ``AppProvider`` cannot - connect to your app's App Services backend, the components it wraps will not render. - - You *must* nest the providers and app components as shown below to ensure each component - has access to its required context: + b. If configuring a synced Realm, pass your sync properties into the ``sync`` prop. Your + sync properties are formatted like a JSON dictionary. + + To sync data, you must set up a sync subscription. The example below uses an initial subscription, + but you can also set up subscriptions in ``RealmProvider`` child components. - .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx - :language: javascript + c. Add other configuration object properties as props to ``RealmProvider``. - .. tab:: Configure realm without sync - :tabid: configure-non-sync-realm +Once your providers have been configured, nest your app components within the +provider whose context it needs to access. Generally, you can nest your components within the +``RealmProvider`` to ensure they have access to all three providers' contexts. - If you are developing an app without sync, you only need to use ``RealmProvider``. - - To configure a non-synced realm: - - #. Import ``RealmProvider`` from ``@realm/react``. +The rendering of each component is dependent on the successful +execution of its parent components' functionality. For example, if ``AppProvider`` cannot +connect to your app's App Services backend, the components it wraps will not render. - #. Pass your object models to the ``schema`` prop. +You *must* nest the providers as shown below to ensure each has access to its required context: - #. Add other Configuration object properties as props to ``RealmProvider`` +.. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx + :language: javascript - Once your ``RealmProvider`` has been configured, nest your app components within it to - give them access to the realm opened. +.. note:: - .. literalinclude:: /examples/generated/react-native/ts/configure-realm-local.test.snippet.configure-realm.tsx - :language: typescript + The example details how to configure and expose a single Realm using a ``RealmProvider`` + imported directly from ``@realm/react``. + For information about using ``createRealmContext()`` to configure a Realm or exposing more + than one Realm, see :ref:`Create Context with createRealmContext() + ` below. Working with Providers using Hooks ---------------------------------- @@ -292,7 +272,7 @@ refer to the :ref:`CRUD - Read ` docs. .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx :language: typescript - :emphasize-lines: 3-5, 8-14 + :emphasize-lines: 6-8, 14-18 *Parameters* @@ -377,7 +357,7 @@ useAuth() useAuth(): UseAuth -You use the `useAuth()` Hook with a result and authentication method. +You destructure the `useAuth()` Hook result into a ``result`` and authentication method. result ++++++ @@ -558,7 +538,7 @@ The authentication method specifies how you want users to login to your app. ``u useEmailPasswordAuth() `````````````````````` -You use the `useEmailPasswordAuth()` Hook with a result and authentication operation. +You destructure the `useEmailPasswordAuth()` Hook result into a ``result`` and authentication operation. result ++++++ From 2f3d9fa99c69a0555d5a82e3021e7ec820004540 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 05:04:50 -0400 Subject: [PATCH 34/40] fixed page links --- source/frameworks/react/providers-hooks.txt | 88 +++++++++------------ source/sdk/files/configure-and-open.txt | 5 ++ 2 files changed, 43 insertions(+), 50 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 9885907a2f..8d181fe8bb 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -169,13 +169,13 @@ Working with Providers using Hooks To use the provider's context in your app's components, you can use Hooks. -Hooks act as functions used to access states in your app. React offers built-in hooks you can +Hooks act as functions used to access states in your app. React offers built-in Hooks you can use either on their own or to build custom Hooks. -There are two important rules to consider when working with hooks: +There are two important rules to consider when working with Hooks: - Hooks can only be used at the top level of a React component. -- Hooks can only be called in a React component or a custom hook, not in regular JavaScript +- Hooks can only be called in a React component or a custom Hook, not in regular JavaScript functions. The ``@realm/react`` library has custom Hooks for each provider you can @@ -195,12 +195,12 @@ useRealm() useRealm(): Realm -The ``useRealm()`` hook returns an opened :js-sdk:`realm instance`. The realm instance +The ``useRealm()`` Hook returns an opened :js-sdk:`realm instance`. The realm instance gives you access to realm methods and properties. For example, you can call ``realm.write()`` to add a realm object to your realm. To learn more about modifying Realm data, refer to :ref:`Write Transactions -`. +`. .. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx :language: typescript @@ -208,9 +208,8 @@ To learn more about modifying Realm data, refer to :ref:`Write Transactions *Returns* -- ``Realm`` -Returns a realm instance. This is the realm created by the hook's parent, -``RealmProvider``. +- ``Realm`` Returns a realm instance. This is the realm created by the Hook's parent, + ``RealmProvider``. .. _sdks-react-use-object-hook: @@ -221,31 +220,28 @@ useObject() :copyable: false :caption: Type signature - useObject(type, primaryKey): T & Realm.Object | null + useObject(type, sdks-open-synced-database-offlineKey): T & Realm.Object | null -The ``useObject()`` hook returns a :js-sdk:`Realm object ` for a given -:ref:`primary key `. You can pass an object class +The ``useObject()`` Hook returns a :js-sdk:`Realm object ` for a given +:ref:`primary key `. You can pass an object class or the class name as a string and the primary key. -The ``useObject()`` method returns null if the object doesn't exist or you have -deleted it. The hook will automatically subscribe to updates and rerender the -component using the hook on any change to the object. +The ``useObject()`` Hook returns null if the object doesn't exist or you have +deleted it. The Hook will automatically subscribe to updates and rerender the +component using the Hook on any change to the object. .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-object-by-id.tsx :language: typescript *Parameters* -- ``type: string`` -A string that matches your object model's class name or a reference to a -class that extends :js-sdk:`Realm.Object `. -- ``primaryKey: T[keyof T]`` -The primary key of the desired object. +- ``type: string`` A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. +- ``primaryKey: T[keyof T]`` The primary key of the desired object. *Returns* -- ``Realm.Object | null`` -A Realm Object or ``null`` if no object is found. +- ``Realm.Object | null`` A Realm Object or ``null`` if no object is found. .. _sdks-react-use-query-hook: @@ -258,7 +254,7 @@ useQuery() useQuery(type, query?, deps?): Realm.Results> -The ``useQuery()`` hook returns a :js-sdk:`result ` that is a +The ``useQuery()`` Hook returns a :js-sdk:`result ` that is a collection of realm objects of a given type. These are the results of your query. A query can be an object class or the class name as a string. @@ -268,7 +264,7 @@ and rerenders the component using it on any change to the results. You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query results. You should do this in the ``query`` argument of ``useQuery`` so that they only run when there are changes in the dependency array. For more examples, -refer to the :ref:`CRUD - Read ` docs. +refer to the :ref:`Read Objects ` page. .. literalinclude:: /examples/generated/react-native/ts/read.test.snippet.crud-read-filter-data.tsx :language: typescript @@ -276,20 +272,16 @@ refer to the :ref:`CRUD - Read ` docs. *Parameters* -- ``type: string`` -A string that matches your object model's class name or a reference to a -class that extends :js-sdk:`Realm.Object `. -- ``query?: QueryCallback`` -A query function that can filter and sort query results. Builds on -``useCallback`` to memoize the query function. -- ``deps?: DependencyList`` -A list of query function dependencies that's used to memoize -the query function. +- ``type: string`` A string that matches your object model's class name or a reference to a + class that extends :js-sdk:`Realm.Object `. +- ``query?: QueryCallback`` A query function that can filter and sort query results. Builds on + ``useCallback`` to memoize the query function. +- ``deps?: DependencyList`` A list of query function dependencies that's used to memoize + the query function. *Returns* -- ``Realm.Results`` -A Realm Object or ``null`` if no object is found. +- ``Realm.Results`` A Realm Object or ``null`` if no object is found. UserProvider Hooks ~~~~~~~~~~~~~~~~~~ @@ -305,10 +297,10 @@ useUser() useUser(): Realm.User -The ``useUser()`` hook provides access to the :js-sdk:`logged-in user `. For example, +The ``useUser()`` Hook provides access to the :js-sdk:`logged-in user `. For example, you can use ``useUser()`` to log the current user out. -When changes to the user object happen, this hook will rerender its parent +When changes to the user object happen, this Hook will rerender its parent component. For example, if you call ``user.refreshCustomData`` to get updated custom user data, the ``useUser()`` parent component will rerender. @@ -316,8 +308,7 @@ custom user data, the ``useUser()`` parent component will rerender. *Returns* -- ``Realm.User`` -An instance of the currently-authenticated Realm user. +- ``Realm.User`` An instance of the currently-authenticated Realm user. AppProvider Hooks ~~~~~~~~~~~~~~~~~ @@ -335,7 +326,7 @@ useApp() *Example* -The ``useApp()`` hook provides access to a :js-sdk:`Realm.App ` +The ``useApp()`` Hook provides access to a :js-sdk:`Realm.App ` instance. .. include:: /examples/generated/react-native/v12/use-app.snippet.import-use-app.tsx.rst @@ -343,8 +334,7 @@ instance. *Returns* -- ``Realm.App`` -An instance of the current ``Realm.App`` created by ``AppProvider``. +- ``Realm.App`` An instance of the current ``Realm.App`` created by ``AppProvider``. .. _sdks-react-use-auth-hook: @@ -368,7 +358,7 @@ result result: AuthResult -Result of authentication hook operation. For example, ``result.operation`` gives +Result of authentication Hook operation. For example, ``result.operation`` gives you the name of the current operation. *Enum values* @@ -726,16 +716,12 @@ Create Context with createRealmContext() *Parameters* -- ``realmConfig?: Realm.Configuration`` - - All properties of :realm-react-sdk:`BaseConfiguration +- ``realmConfig?: Realm.Configuration`` All properties of :realm-react-sdk:`BaseConfiguration ` can be used. *Returns* -- ``RealmContext`` - - An object containing a ``RealmProvider`` component, and the ``useRealm``, +- ``RealmContext`` An object containing a ``RealmProvider`` component, and the ``useRealm``, ``useQuery`` and ``useObject`` Hooks. Most of the time, you will only use ``createRealmContext()`` if you need to @@ -752,7 +738,9 @@ The ``createRealmContext()`` method creates a `React Context - Various prebuilt Hooks that access the configured realm. To work with more than one realm, you need to destructure a new realm provider and its -associated hooks from the result of ``createRealmContext()``. You can call this new realm +associated Hooks from the result of ``createRealmContext()``. You can call this new realm provider and use its associated Hooks the same way you would with the ``RealmProvider`` imported from the ``@realm/react`` library. You should namespace providers -to avoid confusion about which provider and Hooks you're working with. \ No newline at end of file +to avoid confusion about which provider and Hooks you're working with. + +For a detailed guide, refer to :ref:`Expose More Than One Database `. \ No newline at end of file diff --git a/source/sdk/files/configure-and-open.txt b/source/sdk/files/configure-and-open.txt index 3d5c090a30..34625c94c7 100644 --- a/source/sdk/files/configure-and-open.txt +++ b/source/sdk/files/configure-and-open.txt @@ -42,3 +42,8 @@ Open a Database Asynchronously Provide a Subset of Models to a Database ---------------------------------------- +.. _sdks-expose-more-than-one-database: + +Expose More Than One Database +----------------------------- + From d91a3fa9333e12c81121df18f9627c958ff20595 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 05:33:39 -0400 Subject: [PATCH 35/40] fixed realm to atlas or database --- source/frameworks/react/providers-hooks.txt | 79 +++++++++++---------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 8d181fe8bb..03d7fc5cfb 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -23,8 +23,9 @@ Providers & Hooks :class: singlecol The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to -develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the provider design pattern to manage your Atlas -connection, user creation and authentication, and data management. +develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the +provider design pattern to manage your Atlas connection, user creation and authentication, and +data management. The providers are available in all SDKs that support a React environment. This includes React Native, Web, and Electron. @@ -37,8 +38,8 @@ component within another component's tags creates a parent-child relationship be where child components can access the context created by their parent component. Context refers to the information made accessible by a provider. For example, the -``RealmProvider`` context is the Realm it connects to, so all components nested in the -``RealmProvider`` have access to that Realm. +``RealmProvider`` context is the database it connects to, so all components nested in the +``RealmProvider`` have access to that database. Props ~~~~~ @@ -58,28 +59,28 @@ Provider has different props you can use for configuration. - ``schema?: (RealmObjectConstructor | ObjectSchema)[]`` - Specifies all the object schemas in the Realm. Required when first creating a Realm. - If omitted, the schema will be read from the existing Realm file. + Specifies all the object schemas in the database. Required when first creating a database. + If omitted, the schema will be read from the existing database file. - ``sync?: SyncConfiguration`` - Defines Device Sync behavior for this realm, including initial subscriptions. + Defines Device Sync behavior for this database, including initial subscriptions. ``RealmProvider`` has more props that define its behavior: - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` - The fallback component to render while the Realm is opening or if the Realm fails to open. + The fallback component to render while the database is opening or if it fails to open. - ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, the open realm will not close when the + Default is ``true``. If set to ``false``, the open datahase will not close when the component unmounts. - ``realmRef?: React.MutableRefObject`` - A ref to the Realm instance. This is useful if you need to access the Realm - instance outside of the scope of the Realm. + A ref to the database instance. This is useful if you need to access the database + instance outside of the scope of the database. - ``children: React.ReactNode`` @@ -114,10 +115,10 @@ necessary: - ``UserProvider``: Used to access the logged-in :js-sdk:`user object `. -- ``RealmProvider``: Used to work with the configured :js-sdk:`Realm `. +- ``RealmProvider``: Used to work with the configured :js-sdk:`database `. -This example below walks through configuring all three providers. If your app does not need a -provider, you can skip the associated steps and omit the associated code. +The example below walks through configuring all three providers. If your app does not need a +certain provider, you can skip the steps and omit the code for that provider. **To configure your providers:** @@ -125,7 +126,9 @@ provider, you can skip the associated steps and omit the associated code. 2. Configure ``AppProvider``. - a. Pass your App Services App ID string to the ``id`` prop of the ``AppProvider``. + a. Pass your App Services App ID string to the ``id`` prop of the ``AppProvider``. + + b. Add other configuration object properties as props to ``AppProvider`` as needed. 3. Configure ``UserProvider`` and nest it within ``AppProvider``. @@ -135,13 +138,13 @@ provider, you can skip the associated steps and omit the associated code. a. Pass your object models to the ``schema`` prop. - b. If configuring a synced Realm, pass your sync properties into the ``sync`` prop. Your + b. If configuring a synced database, pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a JSON dictionary. To sync data, you must set up a sync subscription. The example below uses an initial subscription, but you can also set up subscriptions in ``RealmProvider`` child components. - c. Add other configuration object properties as props to ``RealmProvider``. + c. Add other configuration object properties as props to ``RealmProvider`` as needed. Once your providers have been configured, nest your app components within the provider whose context it needs to access. Generally, you can nest your components within the @@ -158,10 +161,10 @@ You *must* nest the providers as shown below to ensure each has access to its re .. note:: - The example details how to configure and expose a single Realm using a ``RealmProvider`` + The example details how to configure and expose a single database using a ``RealmProvider`` imported directly from ``@realm/react``. - For information about using ``createRealmContext()`` to configure a Realm or exposing more - than one Realm, see :ref:`Create Context with createRealmContext() + For information about using ``createRealmContext()`` to configure a database or exposing more + than one database, see :ref:`Create Context with createRealmContext() ` below. Working with Providers using Hooks @@ -195,11 +198,11 @@ useRealm() useRealm(): Realm -The ``useRealm()`` Hook returns an opened :js-sdk:`realm instance`. The realm instance -gives you access to realm methods and properties. For example, you can call -``realm.write()`` to add a realm object to your realm. +The ``useRealm()`` Hook returns an opened :js-sdk:`database instance`. The database instance +gives you access to database methods and properties. For example, you can call +``realm.write()`` to add a Realm Object to your database. -To learn more about modifying Realm data, refer to :ref:`Write Transactions +To learn more about modifying data in your database, refer to :ref:`Write Transactions `. .. literalinclude:: /examples/generated/react-native/ts/create-test.test.snippet.crud-create-object.tsx @@ -208,7 +211,7 @@ To learn more about modifying Realm data, refer to :ref:`Write Transactions *Returns* -- ``Realm`` Returns a realm instance. This is the realm created by the Hook's parent, +- ``Realm`` Returns a database instance. This is the database created by the Hook's parent, ``RealmProvider``. .. _sdks-react-use-object-hook: @@ -222,11 +225,11 @@ useObject() useObject(type, sdks-open-synced-database-offlineKey): T & Realm.Object | null -The ``useObject()`` Hook returns a :js-sdk:`Realm object ` for a given +The ``useObject()`` Hook returns a :js-sdk:`Realm Object ` for a given :ref:`primary key `. You can pass an object class or the class name as a string and the primary key. -The ``useObject()`` Hook returns null if the object doesn't exist or you have +The ``useObject()`` Hook returns ``null`` if the object doesn't exist or you have deleted it. The Hook will automatically subscribe to updates and rerender the component using the Hook on any change to the object. @@ -255,7 +258,7 @@ useQuery() useQuery(type, query?, deps?): Realm.Results> The ``useQuery()`` Hook returns a :js-sdk:`result ` that is a -collection of realm objects of a given type. These are the results of your query. A query can +collection of Realm Objects of a given type. These are the results of your query. A query can be an object class or the class name as a string. The ``useQuery()`` method subscribes to updates to any objects in the collection @@ -308,7 +311,7 @@ custom user data, the ``useUser()`` parent component will rerender. *Returns* -- ``Realm.User`` An instance of the currently-authenticated Realm user. +- ``Realm.User`` An instance of the currently-authenticated Atlas user. AppProvider Hooks ~~~~~~~~~~~~~~~~~ @@ -384,8 +387,8 @@ The authentication method specifies how you want users to login to your app. ``u - Example * - ``logIn(credentials)`` - - ``credentials``: A Realm credential supplied by any supported Realm authentication. - - Logs in a user with any authentication mechanism supported by Realm. If called when a + - ``credentials``: An Atlas credential supplied by any supported Atlas authentication. + - Logs in a user with any authentication mechanism supported by Atlas. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use the more specific login methods. @@ -459,7 +462,7 @@ The authentication method specifies how you want users to login to your app. ``u }; * - ``logInWithGoogle(credentials)`` - - ``credentials``; An object with an ``idToken`` or ``authCode`` field that + - ``credentials``: An object with an ``idToken`` or ``authCode`` field that should contain the string token you get from Google Identity Services. - Log in with Google. @@ -725,20 +728,20 @@ Create Context with createRealmContext() ``useQuery`` and ``useObject`` Hooks. Most of the time, you will only use ``createRealmContext()`` if you need to -configure more than one realm. Otherwise, you should import ``RealmProvider`` -and Hooks directly from ``@realm/react``. +configure more than one database. Otherwise, you should import ``RealmProvider`` +and its associated Hooks directly from ``@realm/react``. The ``createRealmContext()`` method creates a `React Context -`__ object for a realm with a given +`__ object for a database with a given :realm-react-sdk:`Configuration `. The ``Context`` object contains the following: - A Context Provider component that wraps around child components and provides them with access to Hooks. -- Various prebuilt Hooks that access the configured realm. +- Various prebuilt Hooks that access the configured database. -To work with more than one realm, you need to destructure a new realm provider and its -associated Hooks from the result of ``createRealmContext()``. You can call this new realm +To work with more than one database, you need to destructure a new provider and its +associated Hooks from the result of ``createRealmContext()``. You can call this new database provider and use its associated Hooks the same way you would with the ``RealmProvider`` imported from the ``@realm/react`` library. You should namespace providers to avoid confusion about which provider and Hooks you're working with. From 3c4d08548da9cd9d589a94d586e670bdf3bcf5e8 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Mon, 5 Aug 2024 12:37:21 -0400 Subject: [PATCH 36/40] switched to procedure formatting --- source/frameworks/react/providers-hooks.txt | 126 +++++++++++--------- 1 file changed, 68 insertions(+), 58 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 03d7fc5cfb..521364f3ee 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -27,6 +27,12 @@ develop a React app using JavaScript-based Atlas Device SDKs. The components lev provider design pattern to manage your Atlas connection, user creation and authentication, and data management. +- :realm-react-sdk:`AppProvider (@realm/react) ` + +- :realm-react-sdk:`UserProvider (@realm/react) ` + +- :realm-react-sdk:`RealmProvider (@realm/react) ` + The providers are available in all SDKs that support a React environment. This includes React Native, Web, and Electron. @@ -99,6 +105,8 @@ Provider has different props you can use for configuration. .. tab:: UserProvider Props :tabid: user-provider-props + The only prop passed into ``UserProvider`` is an optional fallback component: + - ``fallback?: React.ComponentType | React.ReactElement | null | undefined`` The fallback component to render if there is no authorized user. This can be @@ -110,16 +118,24 @@ Configure your Providers Your app's needs determine what providers you use, as all three providers are not always necessary: -- ``AppProvider``: Used to connect to your :js-sdk:`Atlas App Services App Client - `, including for user authentication. +- ``AppProvider``: Used to connect to your :ref:`Atlas App Services App Client + `, including for user authentication. -- ``UserProvider``: Used to access the logged-in :js-sdk:`user object `. +- ``UserProvider``: Used to access the logged-in :ref:`user object `. -- ``RealmProvider``: Used to work with the configured :js-sdk:`database `. +- ``RealmProvider``: Used to work with the configured database. The example below walks through configuring all three providers. If your app does not need a certain provider, you can skip the steps and omit the code for that provider. +.. note:: Exposing more than one database using createRealmContext() + + The example details how to configure and expose a single database using a ``RealmProvider`` + imported directly from ``@realm/react``. + For information about using ``createRealmContext()`` to configure a database or exposing more + than one database, see :ref:`Create Context with createRealmContext() + ` below. + **To configure your providers:** 1. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. @@ -146,9 +162,10 @@ certain provider, you can skip the steps and omit the code for that provider. c. Add other configuration object properties as props to ``RealmProvider`` as needed. -Once your providers have been configured, nest your app components within the -provider whose context it needs to access. Generally, you can nest your components within the -``RealmProvider`` to ensure they have access to all three providers' contexts. +5. Nest you app components in the providers. + Once your providers have been configured, nest your app components within the + provider whose context it needs to access. Generally, you can nest your components within the + ``RealmProvider`` to ensure they have access to all three providers' contexts. The rendering of each component is dependent on the successful execution of its parent components' functionality. For example, if ``AppProvider`` cannot @@ -159,14 +176,6 @@ You *must* nest the providers as shown below to ensure each has access to its re .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx :language: javascript -.. note:: - - The example details how to configure and expose a single database using a ``RealmProvider`` - imported directly from ``@realm/react``. - For information about using ``createRealmContext()`` to configure a database or exposing more - than one database, see :ref:`Create Context with createRealmContext() - ` below. - Working with Providers using Hooks ---------------------------------- @@ -211,8 +220,7 @@ To learn more about modifying data in your database, refer to :ref:`Write Transa *Returns* -- ``Realm`` Returns a database instance. This is the database created by the Hook's parent, - ``RealmProvider``. +- ``Realm`` Returns a database instance from the ``RealmProvider`` context. .. _sdks-react-use-object-hook: @@ -350,7 +358,7 @@ useAuth() useAuth(): UseAuth -You destructure the `useAuth()` Hook result into a ``result`` and authentication method. +You destructure the ``useAuth()`` Hook result into a ``result`` and authentication method. result ++++++ @@ -366,12 +374,12 @@ you the name of the current operation. *Enum values* -- ``state``. Can be "not-started", "pending", "success", "error". -- ``operation``. For a list of all operation names, refer to the +- ``state``: Can be ``"not-started"``, ``"pending"``, ``"success"``, ``"error"``. +- ``operation``: For a list of all operation names, refer to the :realm-react-sdk:`API documentation `. -- ``pending``. Can be ``true`` or ``false``. -- ``success``. Can be ``true`` or ``false``. -- ``error``. Error-based object or undefined. +- ``pending``: Can be ``true`` or ``false``. +- ``success``: Can be ``true`` or ``false``. +- ``error``: Error-based object or undefined. Authentication Methods ++++++++++++++++++++++ @@ -381,12 +389,13 @@ The authentication method specifies how you want users to login to your app. ``u .. list-table:: :header-rows: 1 :stub-columns: 1 + :widths: 15 20 65 * - Operation - Parameter - Example - * - ``logIn(credentials)`` + * - logIn - ``credentials``: An Atlas credential supplied by any supported Atlas authentication. - Logs in a user with any authentication mechanism supported by Atlas. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use @@ -411,7 +420,7 @@ The authentication method specifies how you want users to login to your app. ``u } //... - * - ``logInWithAnonymous`` + * - logInWithAnonymous - None - Log in with the anonymous authentication provider. @@ -422,7 +431,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithAnonymous(); }; - * - ``logInWithApiKey(key)`` + * - logInWithApiKey - ``key``: A string that is linked to an App Services user. - Log in with an API key. @@ -434,7 +443,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithApiKey(key); }; - * - ``logInWithEmailPassword(credentials)`` + * - logInWithEmailPassword - ``credentials``: An object with ``email`` and ``password`` fields. - Log in with Email/Password. @@ -448,7 +457,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithEmailPassword({email, password}); }; - * - ``logInWithJWT(credentials)`` + * - logInWithJWT - ``credentials``: A string representation of a user's JWT. - Log in with a JSON Web Token (JWT). @@ -461,7 +470,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithJWT(token); }; - * - ``logInWithGoogle(credentials)`` + * - logInWithGoogle - ``credentials``: An object with an ``idToken`` or ``authCode`` field that should contain the string token you get from Google Identity Services. - Log in with Google. @@ -475,7 +484,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithGoogle({idToken: token}); }; - * - ``logInWithApple(idToken)`` + * - logInWithApple - ``idToken``: A string you get from the Apple SDK. - Log in with Apple. @@ -488,7 +497,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithApple(token); }; - * - ``logInWithFacebook(accessToken)`` + * - logInWithFacebook - ``accessToken``: A string you get from the Facebook SDK. - Log in with Facebook. @@ -501,7 +510,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithFacebook(token); }; - * - ``logInWithFunction(payload)`` + * - logInWithFunction - ``payload``: An object that contains user information you want to pass to the App Services function that processes log in requests. - Log in with a custom function. @@ -515,7 +524,7 @@ The authentication method specifies how you want users to login to your app. ``u logInWithFunction(customPayload); }; - * - ``logOut()`` + * - logOut - None - Logs out the current user. @@ -531,7 +540,7 @@ The authentication method specifies how you want users to login to your app. ``u useEmailPasswordAuth() `````````````````````` -You destructure the `useEmailPasswordAuth()` Hook result into a ``result`` and authentication operation. +You destructure the ``useEmailPasswordAuth()`` Hook result into a ``result`` and authentication operation. result ++++++ @@ -547,12 +556,12 @@ operation. *Enum values* -- ``state``. Can be "not-started", "pending", "success", "error". -- ``operation``. For a list of all operation names, refer to the +- ``state``: Can be ``"not-started"``, ``"pending"``, ``"success"``, ``"error"``. +- ``operation``: For a list of all operation names, refer to the :realm-react-sdk:`API documentation `. -- ``pending``. Can be ``true`` or ``false``. -- ``success``. Can be ``true`` or ``false``. -- ``error``. Error-based object or undefined. +- ``pending``: Can be ``true`` or ``false``. +- ``success``: Can be ``true`` or ``false``. +- ``error``: Error-based object or undefined. Authentication Operations +++++++++++++++++++++++++ @@ -562,12 +571,13 @@ Authentication Operations .. list-table:: :header-rows: 1 :stub-columns: 1 + :widths: 15 20 65 * - Operation - Parameter - Example - * - ``logIn(credentials)`` + * - logIn - ``credentials``: An object that contains ``email`` and ``password`` properties. - Logs a user in using an email and password. You could also call ``logIn(Realm.Credentials.emailPassword(email, password))``. Returns a @@ -597,7 +607,7 @@ Authentication Operations } //... - * - ``logOut()`` + * - logOut - None - Logs out the current user. @@ -608,7 +618,7 @@ Authentication Operations logOut(); } - * - ``register(args)`` + * - register - ``args``: An object that contains ``email`` and ``password`` properties. - Registers a new user. Requires a user email and password. @@ -623,7 +633,7 @@ Authentication Operations register({email, password}); }; - * - ``confirm(args)`` + * - confirm - ``args``: An object that contains ``token`` and ``tokenId`` properties. - Confirms a user account. Requires a ``token`` and ``tokenId``. @@ -635,7 +645,7 @@ Authentication Operations confirm({token, tokenId}); }; - * - ``resendConfirmationEmail(args)`` + * - resendConfirmationEmail - ``args``: An object that contains an ``email`` property. - Resends a confirmation email. @@ -648,7 +658,7 @@ Authentication Operations resendConfirmationEmail({email}); }; - * - ``retryCustomConfirmation(args)`` + * - retryCustomConfirmation - ``args``: An object that contains an ``email`` property. - Retries confirmation with a custom function. @@ -661,7 +671,7 @@ Authentication Operations retryCustomConfirmation({email}); }; - * - ``sendResetPasswordEmail(args)`` + * - sendResetPasswordEmail - ``args``: An object that contains an ``email`` property. - Sends a password reset email. @@ -674,7 +684,7 @@ Authentication Operations sendResetPasswordEmail({email}); }; - * - ``resetPassword(args)`` + * - resetPassword - ``args``: An object that contains ``token``, ``tokenId``, and ``password`` properties. - Resets a user's password. @@ -688,7 +698,7 @@ Authentication Operations resetPassword({token, tokenId, password}); }; - * - ``callResetPasswordFunction(args, restArgs)`` + * - callResetPasswordFunction - ``args``: An object that contains ``email`` and ``password`` properties. ``restArgs``: Additional arguments that you need to pass to your custom @@ -717,16 +727,6 @@ Create Context with createRealmContext() createRealmContext(realmConfig?): RealmContext -*Parameters* - -- ``realmConfig?: Realm.Configuration`` All properties of :realm-react-sdk:`BaseConfiguration - ` can be used. - -*Returns* - -- ``RealmContext`` An object containing a ``RealmProvider`` component, and the ``useRealm``, - ``useQuery`` and ``useObject`` Hooks. - Most of the time, you will only use ``createRealmContext()`` if you need to configure more than one database. Otherwise, you should import ``RealmProvider`` and its associated Hooks directly from ``@realm/react``. @@ -746,4 +746,14 @@ provider and use its associated Hooks the same way you would with the ``RealmPro imported from the ``@realm/react`` library. You should namespace providers to avoid confusion about which provider and Hooks you're working with. +*Parameters* + +- ``realmConfig?: Realm.Configuration`` All properties of :realm-react-sdk:`BaseConfiguration + ` can be used. + +*Returns* + +- ``RealmContext`` An object containing a ``RealmProvider`` component, and the ``useRealm``, + ``useQuery`` and ``useObject`` Hooks. + For a detailed guide, refer to :ref:`Expose More Than One Database `. \ No newline at end of file From b85b388ccc9eb80024924d751b2fcb2cbc2da2ff Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Tue, 6 Aug 2024 17:37:41 -0400 Subject: [PATCH 37/40] updated files to reflect TOC --- source/frameworks.txt | 4 +++- source/frameworks/react/access-atlas.txt | 14 ++++++++++++++ source/frameworks/react/api-reference.txt | 10 ++++++++++ source/frameworks/react/install.txt | 14 ++++++++++++++ source/frameworks/react/manage-users.txt | 14 ++++++++++++++ source/frameworks/react/model-data.txt | 14 ++++++++++++++ source/frameworks/react/model-database-files.txt | 14 ++++++++++++++ source/frameworks/react/quick-start.txt | 14 ++++++++++++++ source/frameworks/react/react-to-changes.txt | 14 ++++++++++++++ source/frameworks/react/read-write.txt | 14 ++++++++++++++ source/frameworks/react/sync-data.txt | 14 ++++++++++++++ source/frameworks/react/test-debug.txt | 14 ++++++++++++++ 12 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 source/frameworks/react/access-atlas.txt create mode 100644 source/frameworks/react/api-reference.txt create mode 100644 source/frameworks/react/install.txt create mode 100644 source/frameworks/react/manage-users.txt create mode 100644 source/frameworks/react/model-data.txt create mode 100644 source/frameworks/react/model-database-files.txt create mode 100644 source/frameworks/react/quick-start.txt create mode 100644 source/frameworks/react/react-to-changes.txt create mode 100644 source/frameworks/react/read-write.txt create mode 100644 source/frameworks/react/sync-data.txt create mode 100644 source/frameworks/react/test-debug.txt diff --git a/source/frameworks.txt b/source/frameworks.txt index e149bc4ed1..b4cb3c6631 100644 --- a/source/frameworks.txt +++ b/source/frameworks.txt @@ -19,6 +19,7 @@ Build with Frameworks Electron Flutter Maui + .NET SwiftUI The following pages contain information about building with specific @@ -26,8 +27,9 @@ frameworks using Atlas Device SDK: - :ref:`sdks-build-with-react` - :ref:`sdks-build-with-react-native` -- :ref:`sdks-build-with-nextjs` - :ref:`sdks-build-with-electron` - :ref:`sdks-build-with-flutter` - :ref:`sdks-build-with-maui` +- :ref:`sdks-build-with-dotnet` +- :ref:`sdks-build-with-react-native` - :ref:`sdks-build-with-swiftui` \ No newline at end of file diff --git a/source/frameworks/react/access-atlas.txt b/source/frameworks/react/access-atlas.txt new file mode 100644 index 0000000000..49711e60a3 --- /dev/null +++ b/source/frameworks/react/access-atlas.txt @@ -0,0 +1,14 @@ +.. _sdks-react-access-atlas: + +============ +Access Atlas +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/api-reference.txt b/source/frameworks/react/api-reference.txt new file mode 100644 index 0000000000..9440f53fcb --- /dev/null +++ b/source/frameworks/react/api-reference.txt @@ -0,0 +1,10 @@ +.. _sdks-react-api-reference: + +=================================== +API Reference +=================================== + +.. toctree:: + :titlesonly: + + JavaScript SDK Reference (@realm) \ No newline at end of file diff --git a/source/frameworks/react/install.txt b/source/frameworks/react/install.txt new file mode 100644 index 0000000000..0259df8e69 --- /dev/null +++ b/source/frameworks/react/install.txt @@ -0,0 +1,14 @@ +.. _sdks-react-install: + +=================================== +Install @realm/react in a React App +=================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/manage-users.txt b/source/frameworks/react/manage-users.txt new file mode 100644 index 0000000000..4c775c3b3f --- /dev/null +++ b/source/frameworks/react/manage-users.txt @@ -0,0 +1,14 @@ +.. _sdks-react-manage-users: + +============ +Manage Users +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/model-data.txt b/source/frameworks/react/model-data.txt new file mode 100644 index 0000000000..d9451a5f84 --- /dev/null +++ b/source/frameworks/react/model-data.txt @@ -0,0 +1,14 @@ +.. _sdks-react-model-data: + +========== +Model Data +========== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/model-database-files.txt b/source/frameworks/react/model-database-files.txt new file mode 100644 index 0000000000..dd06373449 --- /dev/null +++ b/source/frameworks/react/model-database-files.txt @@ -0,0 +1,14 @@ +.. _sdks-react-manage-database-files: + +============================ +Open & Manage Database Files +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/quick-start.txt b/source/frameworks/react/quick-start.txt new file mode 100644 index 0000000000..6eb5c218ac --- /dev/null +++ b/source/frameworks/react/quick-start.txt @@ -0,0 +1,14 @@ +.. _sdks-react-quick-start: + +============================ +Quick Start for @realm/react +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/react-to-changes.txt b/source/frameworks/react/react-to-changes.txt new file mode 100644 index 0000000000..cf7f39b459 --- /dev/null +++ b/source/frameworks/react/react-to-changes.txt @@ -0,0 +1,14 @@ +.. _sdks-react-react-to-changes: + +================ +React to Changes +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/read-write.txt b/source/frameworks/react/read-write.txt new file mode 100644 index 0000000000..36acafd058 --- /dev/null +++ b/source/frameworks/react/read-write.txt @@ -0,0 +1,14 @@ +.. _sdks-react-read-write: + +================= +Read & Write Data +================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/sync-data.txt b/source/frameworks/react/sync-data.txt new file mode 100644 index 0000000000..71c89a76cc --- /dev/null +++ b/source/frameworks/react/sync-data.txt @@ -0,0 +1,14 @@ +.. _sdks-react-sync-data: + +========= +Sync Data +========= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file diff --git a/source/frameworks/react/test-debug.txt b/source/frameworks/react/test-debug.txt new file mode 100644 index 0000000000..225137ecee --- /dev/null +++ b/source/frameworks/react/test-debug.txt @@ -0,0 +1,14 @@ +.. _sdks-react-test-debug: + +============ +Test & Debug +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Placeholder page for information about building with @realm/react. (This may +be a directory as we have two pages for this?) \ No newline at end of file From 002fa938da9f7afdc76654152caea76d20318c87 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Tue, 6 Aug 2024 17:41:11 -0400 Subject: [PATCH 38/40] fixed build errors --- source/frameworks.txt | 1 - .../{model-database-files.txt => manage-database-files.txt} | 0 source/frameworks/react/providers-hooks.txt | 2 +- 3 files changed, 1 insertion(+), 2 deletions(-) rename source/frameworks/react/{model-database-files.txt => manage-database-files.txt} (100%) diff --git a/source/frameworks.txt b/source/frameworks.txt index b4cb3c6631..baa81b32cf 100644 --- a/source/frameworks.txt +++ b/source/frameworks.txt @@ -15,7 +15,6 @@ Build with Frameworks React React Native - Next.js Electron Flutter Maui diff --git a/source/frameworks/react/model-database-files.txt b/source/frameworks/react/manage-database-files.txt similarity index 100% rename from source/frameworks/react/model-database-files.txt rename to source/frameworks/react/manage-database-files.txt diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 521364f3ee..65ff2fb4a8 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -14,7 +14,7 @@ Providers & Hooks .. facet:: :name: programming_language - :values: javascript + :values: javascript/typescript .. contents:: On this page :local: From 42cd86241816ffa1fcb4635af81d4b9b9ac74f1b Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Tue, 6 Aug 2024 17:48:38 -0400 Subject: [PATCH 39/40] deleted unused test --- examples/web/src/__tests__/providers-hooks.js | 25 ------------------- 1 file changed, 25 deletions(-) delete mode 100644 examples/web/src/__tests__/providers-hooks.js diff --git a/examples/web/src/__tests__/providers-hooks.js b/examples/web/src/__tests__/providers-hooks.js deleted file mode 100644 index 42cc54ea59..0000000000 --- a/examples/web/src/__tests__/providers-hooks.js +++ /dev/null @@ -1,25 +0,0 @@ -// :snippet-start:use-providers -import React from "react"; -import { APP_ID } from "../realm.config.json"; -import { AppProvider, UserProvider, RealmProvider, useRealm, useUser } from "@realm/react"; - -export const AppWrapper = () => { - return ( - {/* pass in your App ID as a prop */} - - - {/* call any app components here */} - - - - ); - }; -// :snippet-end: - -// export const TestComponent = () => { -// const user = useUser(); // hooks called at top level of a component declaration - -// return ( -// user?.id -// ); -// }; \ No newline at end of file From a77af233b0b95ac8c0ce8b61fb982f1120e6441f Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 8 Aug 2024 13:54:10 -0400 Subject: [PATCH 40/40] most of the final changes have been made --- source/frameworks/react/providers-hooks.txt | 138 +++++++++++--------- 1 file changed, 78 insertions(+), 60 deletions(-) diff --git a/source/frameworks/react/providers-hooks.txt b/source/frameworks/react/providers-hooks.txt index 65ff2fb4a8..f70976a96a 100644 --- a/source/frameworks/react/providers-hooks.txt +++ b/source/frameworks/react/providers-hooks.txt @@ -6,7 +6,7 @@ Providers & Hooks .. meta:: :description: Develop apps using the providers and Hooks available in the @realm/react library. - :keywords: Realm, Javascript SDK, React, code example + :keywords: Realm, JavaScript SDK, React, code example .. facet:: :name: genre @@ -24,17 +24,18 @@ Providers & Hooks The ``@realm/react`` library offers custom React components that eliminate the boilerplate needed to develop a React app using JavaScript-based Atlas Device SDKs. The components leverage the -provider design pattern to manage your Atlas connection, user creation and authentication, and +Provider design pattern to manage your Atlas connection, user creation and authentication, and data management. -- :realm-react-sdk:`AppProvider (@realm/react) ` +- ``AppProvider``: Used to connect to your :ref:`Atlas App Services App Client + `, including for user authentication. -- :realm-react-sdk:`UserProvider (@realm/react) ` +- ``UserProvider``: Used to access the logged-in :ref:`user object `. -- :realm-react-sdk:`RealmProvider (@realm/react) ` +- ``RealmProvider``: Used to work with the configured database. -The providers are available in all SDKs that support a React environment. This includes React -Native, Web, and Electron. +Use these providers to develop with frameworks and for platforms that support a React +environment, including: React Native, Web, and Electron. Getting Started with Providers ------------------------------ @@ -44,7 +45,7 @@ component within another component's tags creates a parent-child relationship be where child components can access the context created by their parent component. Context refers to the information made accessible by a provider. For example, the -``RealmProvider`` context is the database it connects to, so all components nested in the +``RealmProvider`` context is the Realm database it connects to, so all components nested in the ``RealmProvider`` have access to that database. Props @@ -80,7 +81,7 @@ Provider has different props you can use for configuration. - ``closeOnUnmount?: boolean`` - Default is ``true``. If set to ``false``, the open datahase will not close when the + Default is ``true``. If set to ``false``, the open database will not close when the component unmounts. - ``realmRef?: React.MutableRefObject`` @@ -90,6 +91,15 @@ Provider has different props you can use for configuration. - ``children: React.ReactNode`` + - ``realm?: Realm`` + + A configured Realm instance for the provider to connect to. Using this prop + eliminates the need to pass in other configuration parameters as props. + + ``closeOnUnmount`` will be set to ``false`` by default. + + For more details, see the :realm-react-sdk:`RealmProvider API Reference (@realm/react) ` + .. tab:: AppProvider Props :tabid: app-provider-props @@ -102,6 +112,15 @@ Provider has different props you can use for configuration. Specifies the App Services App ID. + ``AppProvider`` has more an additional prop that defines its behavior: + + - ``app?: Realm.App`` + + An Atlas App Services App for the provider to connect to. Using this prop + eliminates the need to pass in other configuration parameters as props. + + For more details, see the :realm-react-sdk:`AppProvider API Reference (@realm/react) ` + .. tab:: UserProvider Props :tabid: user-provider-props @@ -112,30 +131,15 @@ Provider has different props you can use for configuration. The fallback component to render if there is no authorized user. This can be used to render a log in screen or otherwise handle authentication. + For more details, see the :realm-react-sdk:`UserProvider API Reference (@realm/react) ` + Configure your Providers ~~~~~~~~~~~~~~~~~~~~~~~~ Your app's needs determine what providers you use, as all three providers are not always -necessary: - -- ``AppProvider``: Used to connect to your :ref:`Atlas App Services App Client - `, including for user authentication. - -- ``UserProvider``: Used to access the logged-in :ref:`user object `. - -- ``RealmProvider``: Used to work with the configured database. - -The example below walks through configuring all three providers. If your app does not need a +necessary. The example below walks through configuring all three providers. If your app does not need a certain provider, you can skip the steps and omit the code for that provider. -.. note:: Exposing more than one database using createRealmContext() - - The example details how to configure and expose a single database using a ``RealmProvider`` - imported directly from ``@realm/react``. - For information about using ``createRealmContext()`` to configure a database or exposing more - than one database, see :ref:`Create Context with createRealmContext() - ` below. - **To configure your providers:** 1. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``. @@ -154,28 +158,39 @@ certain provider, you can skip the steps and omit the code for that provider. a. Pass your object models to the ``schema`` prop. - b. If configuring a synced database, pass your sync properties into the ``sync`` prop. Your - sync properties are formatted like a JSON dictionary. + b. If configuring a synced database, use the ``sync`` prop. Sync properties are defined by + a :ref:`Sync Config Object `. To sync data, you must set up a sync subscription. The example below uses an initial subscription, but you can also set up subscriptions in ``RealmProvider`` child components. c. Add other configuration object properties as props to ``RealmProvider`` as needed. -5. Nest you app components in the providers. - Once your providers have been configured, nest your app components within the +5. Nest your app components in the providers. + + Once your providers have been configured and nested as described above, nest your app components within the provider whose context it needs to access. Generally, you can nest your components within the ``RealmProvider`` to ensure they have access to all three providers' contexts. The rendering of each component is dependent on the successful -execution of its parent components' functionality. For example, if ``AppProvider`` cannot -connect to your app's App Services backend, the components it wraps will not render. +execution of its parent components' functionality. For example, while ``AppProvider`` is +connecting to your app's App Services backend, or if ``AppProvider`` is unable to connect, the +components it wraps will not render. In these cases, the provider's fallback component is +rendered instead. You *must* nest the providers as shown below to ensure each has access to its required context: .. literalinclude:: /examples/generated/react-native/ts/configure-realm-sync.test.snippet.configure-realm-sync-full.tsx :language: javascript +.. note:: Exposing more than one database using createRealmContext() + + The example above details how to configure and expose a single database using a ``RealmProvider`` + imported directly from ``@realm/react``. + For information about using ``createRealmContext()`` to configure a database or exposing more + than one database, see :ref:`Create Context with createRealmContext() + ` below. + Working with Providers using Hooks ---------------------------------- @@ -273,7 +288,7 @@ The ``useQuery()`` method subscribes to updates to any objects in the collection and rerenders the component using it on any change to the results. You can use ``.filtered()`` and ``.sorted()`` to filter and sort your query -results. You should do this in the ``query`` argument of ``useQuery`` so that +results. Do this in the ``query`` argument of ``useQuery`` so that they only run when there are changes in the dependency array. For more examples, refer to the :ref:`Read Objects ` page. @@ -389,15 +404,16 @@ The authentication method specifies how you want users to login to your app. ``u .. list-table:: :header-rows: 1 :stub-columns: 1 - :widths: 15 20 65 + :widths: 23 20 57 * - Operation - Parameter - Example * - logIn - - ``credentials``: An Atlas credential supplied by any supported Atlas authentication. - - Logs in a user with any authentication mechanism supported by Atlas. If called when a + - ``credentials``: An Atlas credential supplied by any supported Atlas App Services + authentication provider. + - Logs in a user with any authentication mechanism supported by Atlas App Services. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use the more specific login methods. @@ -439,8 +455,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithApiKey, result} = useAuth(); const performLogin = () => { - const key = getApiKey(); // user defined function - logInWithApiKey(key); + const key = getApiKey(); + // user defined function + logInWithApiKey(key); }; * - logInWithEmailPassword @@ -466,8 +483,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithJWT, result} = useAuth(); const performLogin = () => { - const token = authorizeWithCustomerProvider(); // user defined function - logInWithJWT(token); + const token = authorizeWithCustomerProvider(); + // user defined function + logInWithJWT(token); }; * - logInWithGoogle @@ -480,8 +498,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithGoogle, result} = useAuth(); const performLogin = () => { - const token = getGoogleToken(); // user defined function - logInWithGoogle({idToken: token}); + const token = getGoogleToken(); + // user defined function + logInWithGoogle({idToken: token}); }; * - logInWithApple @@ -493,8 +512,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithApple, result} = useAuth(); const performLogin = () => { - const token = getAppleToken(); // user defined function - logInWithApple(token); + const token = getAppleToken(); + // user defined function + logInWithApple(token); }; * - logInWithFacebook @@ -506,8 +526,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithFacebook, result} = useAuth(); const performLogin = () => { - const token = getFacebookToken(); // user defined function - logInWithFacebook(token); + const token = getFacebookToken(); + // user defined function + logInWithFacebook(token); }; * - logInWithFunction @@ -520,8 +541,9 @@ The authentication method specifies how you want users to login to your app. ``u const {logInWithFunction, result} = useAuth(); const performLogin = () => { - const customPayload = getAuthParams(); // user defined arguments - logInWithFunction(customPayload); + const customPayload = getAuthParams(); + // user defined arguments + logInWithFunction(customPayload); }; * - logOut @@ -571,7 +593,7 @@ Authentication Operations .. list-table:: :header-rows: 1 :stub-columns: 1 - :widths: 15 20 65 + :widths: 27 18 55 * - Operation - Parameter @@ -727,14 +749,10 @@ Create Context with createRealmContext() createRealmContext(realmConfig?): RealmContext -Most of the time, you will only use ``createRealmContext()`` if you need to -configure more than one database. Otherwise, you should import ``RealmProvider`` -and its associated Hooks directly from ``@realm/react``. - -The ``createRealmContext()`` method creates a `React Context -`__ object for a database with a given -:realm-react-sdk:`Configuration `. The -``Context`` object contains the following: +Use ``createRealmContext()`` to configure more than one database. The ``createRealmContext()`` +method creates a `React Context `__ +object for a database with a given :realm-react-sdk:`Configuration +`. The ``Context`` object contains the following: - A Context Provider component that wraps around child components and provides them with access to Hooks. @@ -743,8 +761,8 @@ The ``createRealmContext()`` method creates a `React Context To work with more than one database, you need to destructure a new provider and its associated Hooks from the result of ``createRealmContext()``. You can call this new database provider and use its associated Hooks the same way you would with the ``RealmProvider`` -imported from the ``@realm/react`` library. You should namespace providers -to avoid confusion about which provider and Hooks you're working with. +imported from the ``@realm/react`` library. Namespace your providers to avoid confusion about +which provider and Hooks you're working with. *Parameters*