[outdated] Consolidation Providers & Hooks #3339
Conversation
✅ Deploy Preview for device-sdk ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Great start, Omar! I think you've started laying out the framework for some info that's going to be really helpful for developers. I have some high-level suggestions, but didn't get too much into the weeds of each provider reference page. If you'd like more detailed line-level comments or IA-related comments for those pages, just let me know!
| The ``@realm/react`` library offers custom React components called Providers to simplify the app | ||
| development process. |
There was a problem hiding this comment.
I think the way we're framing this is a conceptual mismatch. It looks like the Provider pattern is a React Design Pattern - I found this Medium article that breaks it down a bit: React Design Patterns: Provider Pattern.
The phrasing here - saying that the @realm/react library offers custom React components called Providers - implies that the "Providers" is a @realm/react concept, and it's not.
We might rephrase this to talk about how @realm/react uses this common design pattern to simplify app development - i.e.
| The ``@realm/react`` library offers custom React components called Providers to simplify the app | |
| development process. | |
| The ``@realm/react`` library leverages the Provider design pattern to offer custom React | |
| components that eliminate the boilerplate needed to work with the SDK in a React app. |
That's not the most readable sentence - it's kinda long and meandering - so maybe you could use a tool like Hemingway Editor to help you get it trimmed down more.
| 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 |
There was a problem hiding this comment.
Going from the sentence above to this one seems like a surprising context switch that doesn't make sense to the user until the last sentence here. We were just talking about React Providers, and now we're talking about App Services. We could rephrase the above line and the content here to smooth this transition and make it more obvious how these two things are related:
The
@realm/reactlibrary offers custom React components that eliminate the boilerplate needed to work with the SDK in a React app. These components leverage the Provider design pattern to manage user creation, user authentication, and data flow between components.
RealmProvider: Work with the configured database.AppProvider: Connect to Atlas for user authentication, calling a Function, or using Device Sync.UserProvider: Work with the logged-in user object.
Instead of just saying that the provider "grants access," we can reframe it to focus on the types of tasks the user might need to do with that provider. This makes it easier for the user to figure out which provider they need to use for the task they're trying to do.
| Using Providers | ||
| --------------- | ||
|
|
||
| To make your Providers context available to your entire app, you can create an App Wrapper by |
There was a problem hiding this comment.
I think we could build this content out more, and then it might be easier to make more logical sense of how the elements fit together on the page and what the headers should be.
It would probably be good to show a hierarchy diagram for various tasks - i.e.
Use a Synced Database
- AppProvider
- UserProvider
- RealmProvider
- UserProvider
Use a Non-Synced Database
- RealmProvider
Authenticate a User
- AppProvider
- UserProvider
Call a Function
- AppProvider
- UserProvider
Access MongoDB Atlas (this is the "Query MongoDB page" that uses the MongoClient API)
- AppProvider
- UserProvider
When you see a bunch of the tasks listed out, it becomes more obvious how the providers fit together and which ones you need to use to perform common tasks. And then I think the requirement to nest components within the wrapper makes more sense. There are a lot of different ways you might choose to represent this information, visually and within the context of the page IA (and as it relates to the larger section IA).
| 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 |
There was a problem hiding this comment.
Maybe this would be a good place for a procedure?
|
|
||
| AppProvider(props, context?): null | ReactElement<any, any> | ||
|
|
||
| Components nested within ``AppProvider`` can access your App Services App |
There was a problem hiding this comment.
We should probably provide more information in the introduction to each of these pages about what tasks a user might want to do when they are using the Provider - i.e. in this case, accessing an App Services App. The act of accessing an App Services App isn't the developer's goal - it's an incidental implementation detail. It's something they have to do in order to accomplish a task they're trying to do. Documentation usually makes a lot more sense to users when we can frame it in terms of how the developer can use it to do the task they're trying to do instead of mentioning the implementation without that task-based framing.
| Components and Hooks | ||
| -------------------- | ||
|
|
||
| Providers are specialized React components, so you can interact with them as you would any other |
There was a problem hiding this comment.
It may be more clear if you can make the connection to React's context / provider or maybe use this as a reference on how to frame it. https://react.dev/reference/react/createContext#provider
"Wrap your components into a context provider to specify the value of this context for all components inside." is what React's docs say, adjusting it in this direction may be a good idea
I am also not sure what "interacting" with a provider means.
|
|
||
| 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 |
There was a problem hiding this comment.
not sure what destructure means but what you're creating is a RealmContext which includes a Provider and hooks. So with multiple Realms, you will need multiple Realm Contexts and then use their associated providers and hooks depending on the one you need.
As with React docs, you can think of a Provider as a component that "specifies the value of the (Realm) context for all components inside it", so when you have multiple Realms, what you do is create multiple Realm contexts and then use providers to specify what parts of your applications should get what context (in some cases they could be the same).
And in the sense, the hooks are accessing the realm/app/user from the context, not the provider.
It's quite challenging / confusing to word this even for me now but hope this helps 😄
There was a problem hiding this comment.
Redux framing for provider and hooks, may be a helpful reference with subtle wording things:
https://react-redux.js.org/api/provider
https://react-redux.js.org/api/hooks
| For details about ``createRealmContext()``, refer to "Create Context with | ||
| createRealmContext()" on this page. | ||
|
|
||
| RealmProvider Hooks |
There was a problem hiding this comment.
I understand the reasoning for wording it this way to separate different types of hooks and their needed providers but this may make more sense as Realm Hooks, the provider is an implementation detail. https://react-redux.js.org/api/hooks (our case is more complex since we have multiple providers but may be helpful...)
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
3 times, most recently
from
931d4f0 to
a3dac6d
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
from
a3dac6d to
574a124
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
from
4d29e7b to
d790543
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
5 times, most recently
from
d2938b6 to
d50c87d
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
2 times, most recently
from
ea5a9dc to
16d221e
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
from
16d221e to
c9de1e5
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
3 times, most recently
from
f1760a7 to
0f32911
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
from
0f32911 to
d3a2585
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
2 times, most recently
from
d103d6f to
8db5443
Compare
osharaf-mdb
force-pushed
the
feature-consolidated-sdk-docs
branch
from
8db5443 to
0f49482
Compare
There was a problem hiding this comment.
Nice work, Omar! I really like how this page is shaping up. I've got a handful of suggestions, a couple of technical implementation fixes we need to address, and a Q about possibly adding a little info at a higher conceptual level. But I think you've done a great job and this is really close!
|
|
||
| - ``RealmProvider``: Work with the configured database. | ||
|
|
||
| - ``AppProvider``: Connect to your App Client for user authentication, only necessary when |
There was a problem hiding this comment.
The "only necessary when using Device Sync" part isn't accurate for this line and the next line.
The App Client is used for any operation that connects to Atlas. That includes:
- Authenticating a user
- Using mongoClient to query MongoDB Atlas collections
- Calling an Atlas Function
- Working with synced databases
And the last three all require access to the logged-in User object, because we perform those operations in the context of the logged-in user.
We might want to update this section to reflect the full range of operations you can perform with AppProvider and UserProvider - maybe as bullet lists under each?
There was a problem hiding this comment.
Overall, excellent work @osharaf-mdb! Thank you for working hard on this new page! 🥳
I requested changes for a couple of reasons:
- There are some higher-level concepts that should be tweaked a bit
- Some leftovers from the original content should be generalized so that they're not specific to React Native. This is one of the not fun parts of moving content around. 😄
osharaf-mdb
changed the title
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-41470 *Staged Page* - [Providers & Hooks](https://preview-mongodbosharafmdb.gatsbyjs.io/realm/react-providers-and-hooks/frameworks/react/providers-hooks/) *Page Source* - [RealmProvider (@realm/react)](https://www.mongodb.com/docs/atlas/device-sdks/sdk/react-native/api-reference/realm-provider/) - [AppProvider (@realm/react)](https://www.mongodb.com/docs/atlas/device-sdks/sdk/react-native/api-reference/app-provider/) - [UserProvider (@realm/react)](https://www.mongodb.com/docs/atlas/device-sdks/sdk/react-native/api-reference/user-provider/) *Note* This PR is built off a previous PR, [linked here](#3339). The previous PR had feedback from the original draft and the second draft after that. The feedback from that second draft was then implemented to get what is seen here. ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [ ] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [ ] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [ ] Shared code boxes have snippets or placeholders for all 9 languages - [ ] API description sections have API details or a generic placeholder for all 9 languages - [ ] Check related pages for relevant content to include - [ ] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [ ] Shared code example boxes contain language-specific snippets or placeholders for every language - [ ] API reference details contain working API reference links or generic content - [ ] Realm naming/language has been updated - [ ] All relevant content from individual SDK pages is present on the consolidated page
Pull Request Info - SDK Docs Consolidation
Jira ticket: https://jira.mongodb.org/browse/DOCSP-41470
Staged Page
Note
This PR preceeds the Consolidation Providers and Hooks PR, linked here. This PR has feedback from the original draft and second draft. The feedback from this PR was then used to create what is seen in the other PR, which went on the be merged.
PR Author Checklist
Before requesting a review for your PR, please check these items:
feature-consolidated-sdk-docsbranch instead ofmasterNaming
.rstfiles comply with the naming guidelinesLinks and Refs
Content
Reviewer Checklist
As a reviewer, please check these items: