Skip to content

Commit 574a124

Browse files
osharaf-mdbosharaf-mdb
committed
first round of reviews
1 parent 9b15971 commit 574a124

File tree

2 files changed

+170
-51
lines changed

2 files changed

+170
-51
lines changed

‎source/frameworks/react/providers-hooks.txt‎

Lines changed: 75 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -22,76 +22,100 @@ Providers & Hooks
2222
:depth: 2
2323
:class: singlecol
2424

25+
The ``@realm/react`` offers custom React components that eliminate the boilerplate needed to
26+
develop a React app. The components leverage the Provider design pattern to manage user
27+
creation, user authentication, and data management.
2528

26-
The ``@realm/react`` library offers custom React components called Providers to simplify the app
27-
development process.
29+
- ``RealmProvider``: Work with the configured database.
2830

29-
Atlas App Services offers pathways that support user creation, user authentication, and data
30-
management. However, manually integrating these processes into your app introduces a new layer
31-
of complexity. Instead of manually integrating these features, you can use the the Providers
32-
to manage the logic needed to run your app.
31+
- ``AppProvider``: Connect to your App Client for user authentication, only necessary when
32+
using Device Sync.
3333

34-
- ``RealmProvider`` grants access to the configured realm
35-
- ``AppProvider`` grants access to the App Services App
36-
- ``UserProvider`` grants access to the logged-in user object
34+
- ``UserProvider``: Access to the logged-in user object, only necessary when using Device Sync.
3735

3836
The Providers are available to all frameworks used to build with the JavaScript SDK.
3937

40-
Components and Hooks
41-
--------------------
38+
Configure your Providers
39+
------------------------
4240

43-
Providers are specialized React components, so you can interact with them as you would any other
44-
component. As with components, you can use hooks to access states from Providers.
41+
Like all React components, you call Providers using html opening and closing tags. They take
42+
parameters called Props as input, passed into the opening tag.
4543

46-
Components
47-
~~~~~~~~~~
44+
Nesting components within each other creates a parent-child relationship between them. The
45+
props passed into the parent component help create the context inherited by the components it
46+
wraps. Thus, any component wrapped by the Providers can access their context.
4847

49-
Components are the basic building blocks of React applications and resemble JavaScript
50-
functions. They allow you to separate your app’s functionality and views into smaller chunks
51-
you can manipulate and assemble to create the complete app. You call components using html
52-
opening and closing tags, and they take parameters called Props as input.
48+
You can configure a ``RealmProvider`` in two ways:
5349

54-
You can nest components within another components tags, creating a parent-child relationship between
55-
them. The props passed into the parent component help create the context that its child
56-
components need to execute their logic. Child components can access this context using hooks.
50+
- Import ``RealmProvider`` directly from ``@realm/react``
51+
- Use ``createRealmContext()`` to configure a ``Realm
5752

58-
Hooks
59-
~~~~~
53+
This section details how to configure a ``RealmProvider`` imported directly from
54+
``@realm/react`` to expose a single realm. For information about using
55+
``createRealmContext()``, refer to :ref:`Create Context with createRealmContext()
56+
<react-native-realm-context>`. For information about using
57+
configuring more than one realm, refer to Expose More Than One Realm.
6058

61-
Hooks act as functions you can use to access states in your app. React has built-in hooks you
62-
can import and use in any component. The ``@realm/react`` library also has custom hooks for each
63-
provider you can import. You can use a Provider’s hooks within its component and any of its
64-
child components. There are two important rules to consider when working with hooks:
59+
``sentence about when you may need a synced vs non-synced realm``
6560

66-
- Hooks can only be used at the top level of a React component.
67-
- Hooks can only be called in a React component or a custom hook, not in regular JavaScript
68-
functions.
61+
.. tabs::
6962

70-
Using Providers
71-
---------------
63+
.. tab:: Configure realm with sync
64+
:tabid: configure-sync-realm
7265

73-
To make your Providers context available to your entire app, you can create an App Wrapper by
74-
nesting the Providers in each other. You can then nest any of your custom components in this wrapper.
75-
Most applications built using the ``@realm/react`` library assemble their custom components in
76-
an ``App`` component for better organization.
66+
If you are developing an app using sync, you will need to use ``RealmProvider``,
67+
``AppProvider``, and ``UserProvider``.
7768

78-
.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js
69+
By default, Realm syncs all data from the server before returning anything. If you want
70+
to sync data in the background, read Configure a Synced Realm While Offline [link].
7971

80-
You *must* nest the Providers as shown when making a wrapper to ensure each Provider can
81-
access the context it needs to function.
72+
To configure a synced realm:
8273

83-
To use a state in a component you’re creating, call the related hook at the top of your
84-
component definition and save the return value to a variable. You can then use this variable
85-
containing the state throughout your component.
74+
#. Import ``RealmProvider``, ``AppProvider``, and ``UserProvider`` from ``@realm/react``.
75+
76+
#. Configure ``AppProvider``.
8677

87-
``CODE EXAMPLE COMING``
78+
Pass your App ID string to the ``id`` prop of the ``AppProvider``.
79+
80+
#. Configure ``UserProvider`` and nest it within ``AppProvider``.
8881

89-
Props and Hooks
90-
---------------
82+
Pass a component that logs a user in into the ``fallback`` prop. The app renders this component if there is no authenticated user.
83+
84+
#. Configure ``RealmProvider`` for sync and nest it within ``UserProvider``.
9185

92-
For more detail about configuration each provider and to see the props and hooks available for
93-
each, please refer their the API references:
86+
Pass your object models to the ``schema`` prop. (link out)
9487

95-
- :ref:`react-realm-provider`
96-
- :ref:`react-user-provider`
97-
- :ref:`react-app-provider`
88+
Pass your sync properties into the ``sync`` prop. Your sync properties are formatted like a json dictionary.
89+
90+
Add other Configuration object properties as props to ``RealmProvider``.
91+
92+
Once your Providers have been configured, nest your app components within the ``RealmProvider``.
93+
94+
You *must* nest the Providers and app components as described. This ensures each Provider can
95+
access the context it needs to function and all your app components can access the App Client, authenticated user object, and opened realm.
96+
97+
[Code example here]
98+
99+
.. tab:: Configure realm without sync
100+
:tabid: configure-non-sync-realm
101+
102+
If you are developing an app without sync, you only need to configure your ``RealmProvider``.
103+
104+
To configure a non-synced realm:
105+
106+
#. Import ``RealmProvider`` from ``@realm/react``.
107+
108+
#. Pass your object models to the ``schema`` prop. (link out)
109+
110+
#. Add other Configuration object properties as props to ``RealmProvider``
111+
112+
Once your ``RealmProvider`` has been configured, nest your app components within it to
113+
give them access to the realm opened.
114+
115+
[code example - unsynced]
116+
117+
118+
Working in your Providers
119+
-------------------------
120+
121+
[insert text here lol]

‎source/frameworks/react/temp.txt‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
=================
2+
Providers & Hooks
3+
=================
4+
5+
.. meta::
6+
:description: Develop apps using the Providers and Hooks available in the @realm/react library.
7+
:keywords: Realm, Javascript SDK, React, code example
8+
9+
.. facet::
10+
:name: genre
11+
:values: reference
12+
13+
.. facet::
14+
:name: programming_language
15+
:values: javascript
16+
17+
.. contents:: On this page
18+
:local:
19+
:backlinks: none
20+
:depth: 2
21+
:class: singlecol
22+
23+
24+
The ``@realm/react`` library offers custom React components called Providers to simplify the app
25+
development process.
26+
27+
Atlas App Services offers pathways that support user creation, user authentication, and data
28+
management. However, manually integrating these processes into your app introduces a new layer
29+
of complexity. Instead of manually integrating these features, you can use the the Providers
30+
to manage the logic needed to run your app.
31+
32+
- ``RealmProvider`` grants access to the configured realm
33+
- ``AppProvider`` grants access to the App Services App
34+
- ``UserProvider`` grants access to the logged-in user object
35+
36+
The Providers are available to all frameworks used to build with the JavaScript SDK.
37+
38+
Components and Hooks
39+
--------------------
40+
41+
Providers are specialized React components, so you can interact with them as you would any other
42+
component. As with components, you can use hooks to access states from Providers.
43+
44+
Components
45+
~~~~~~~~~~
46+
47+
Components are the basic building blocks of React applications and resemble JavaScript
48+
functions. They allow you to separate your app’s functionality and views into smaller chunks
49+
you can manipulate and assemble to create the complete app. You call components using html
50+
opening and closing tags, and they take parameters called Props as input.
51+
52+
You can nest components within another components tags, creating a parent-child relationship between
53+
them. The props passed into the parent component help create the context that its child
54+
components need to execute their logic. Child components can access this context using hooks.
55+
56+
Hooks
57+
~~~~~
58+
59+
Hooks act as functions you can use to access states in your app. React has built-in hooks you
60+
can import and use in any component. The ``@realm/react`` library also has custom hooks for each
61+
provider you can import. You can use a Provider’s hooks within its component and any of its
62+
child components. There are two important rules to consider when working with hooks:
63+
64+
- Hooks can only be used at the top level of a React component.
65+
- Hooks can only be called in a React component or a custom hook, not in regular JavaScript
66+
functions.
67+
68+
Using Providers
69+
---------------
70+
71+
To make your Providers context available to your entire app, you can create an App Wrapper by
72+
nesting the Providers in each other. You can then nest any of your custom components in this wrapper.
73+
Most applications built using the ``@realm/react`` library assemble their custom components in
74+
an ``App`` component for better organization.
75+
76+
.. literalinclude:: /examples/generated/react/providers-hooks.snippet.use-providers.js
77+
78+
You *must* nest the Providers as shown when making a wrapper to ensure each Provider can
79+
access the context it needs to function.
80+
81+
To use a state in a component you’re creating, call the related hook at the top of your
82+
component definition and save the return value to a variable. You can then use this variable
83+
containing the state throughout your component.
84+
85+
``CODE EXAMPLE COMING``
86+
87+
Props and Hooks
88+
---------------
89+
90+
For more detail about configuration each provider and to see the props and hooks available for
91+
each, please refer their the API references:
92+
93+
- :ref:`react-realm-provider`
94+
- :ref:`react-user-provider`
95+
- :ref:`react-app-provider`

0 commit comments

Comments
 (0)