From 76f874916b4b4dabef3065b81315a4948a234a87 Mon Sep 17 00:00:00 2001 From: osharaf-mdb Date: Thu, 25 Jul 2024 15:43:08 -0400 Subject: [PATCH 01/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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