wix / react-native-navigation

A complete native navigation solution for React Native
https://wix.github.io/react-native-navigation/
MIT License
13.02k stars 2.68k forks source link

Contributing to the Documentation #6103

Open guyca opened 4 years ago

guyca commented 4 years ago

Everyone is more than welcome to take part in this effort - either by contributing articles or by giving feedback and suggestions. You feedback will help us prioritise articles and improve existing articles.

Working locally on the docs

Our documentation is powered by Docusaurus2 which displays MarkDown files via GitHub pages. You don't need to be familiar with it, if you're familiar with MarkDown syntax than you're good to go.

git clone react-native-navigation
cd react-native-navigation/website
npm install
npm start # Serve the docs to http://localhost:3000

Bellow is the outline of the remaining tasks. If anyone would like to contribute articles please comment here or contact one of the admins on discord.

Open tasks

jinshin1013 commented 4 years ago

Hey! I know I've tried to get this doc done for ages but here we are: #6116 this adds React Context API and MobX integration.

lukebrandonfarrell commented 4 years ago

@guyca

Firstly, wondering if it's worth mentioning the support / community libraries built around RNN somewhere in the docs? (I'm not sure how many libraries there are) but I manage two:

https://github.com/lukebrandonfarrell/react-native-navigation-drawer-extension https://github.com/lukebrandonfarrell/react-native-navigation-search-bar

Next, I thought this would be a good place to ask a question about the external components API, instead of creating a new issue with a question, as I should be able to contribute to the documentation in more detail in a few weeks, as we are most likely using an external component for a payment page in our application with 3D secure 2.

How would one navigate from an external component to a React Navigation Component?

I'll keep in mind this issue when I'm working through the v6 upgrade for one of our client apps.

Been stuck on v2 for several months, but recently upgraded to v6, and you guys have done a fantastic job, with fixing some of the major issues, and the new docs are very straightforward, great job! 🎉

guyca commented 4 years ago

Hey @lukebrandonfarrell 👋 Glad to hear v6 is working better for you and that you like the new docs! ❤️

wondering if it's worth mentioning the support / community libraries built around RNN Of course it is! First time I'm seeing your libraries - awesome work! When we thought of the overlay api, this is exactly what we had in mind!

We've just merged @jinshin1013 's PR and added the Third party integration section to the docs. Would you like to add an article to this section for Community libraries ? Please also include https://github.com/underscopeio/react-native-navigation-hooks (the only RNN related community library I was aware of until today 😅 )

Also, I think you should submit your libraries to https://reactnative.directory/ 👍


How would one navigate from an external component to a React Navigation Component?

I really want to keep this issue focused on the docs - but to answer your question and if you have more questions I'll be happy to chat on Discord or feel free to open an issue. At the moment, interacting with the navigator not through JavaScript is not possible. What you can do is emit events (Like we do here and here) from native to js and navigate accordingly.

lukebrandonfarrell commented 4 years ago

@guyca Yes. I'll make a PR for 'Community libraries' this week.

I'll give your suggestion a try, if I can't work it out I'll jump onto discord.

Thanks!

lukebrandonfarrell commented 4 years ago

@guyca PR done.

Another thing which I believe would belong in the workflow section of the DOCS, but first would like your opinion on, is navigational flow composition in larger applications, let me explain.

So in larger applications you may need to reuse pages in various different flows, below is an example of reusing the LoginPage in two different scenarios.

Scenario 1: Initial Page → Login Page → Home Page

Scenario 2: Create Pin Page (Forgot Pin) → Login Page → Reset Pin Page

In this case the login page could have the same look and functionality, but the only thing that is different is a successful login would result in a different destination. There a few solutions to this problem, although maybe there is a solution you guys are using which I have not came across.

  1. Pass a property via the push method (e.g. flow: 'reset') then we have an if statement on LoginPage which says, if flow is 'reset' navigate here, otherwise navigate here. (this is the simplest solution, but the least flexible, if LoginPage is used in 5 - 6+ places, this solution starts to get convoluted and confusing)

  2. Use template pages, so we'd have a component called LoginTemplate and that would contain the full login page and functionality, then we'd have different registered components with React Native Navigation e.g. ResetPinLoginPage, InitialLoginPage, these would just contain LoginTemplate component, with maybe a callback for navigation onLoginSuccess (this is much more flexible, but is more verbose)

What is your take? wondering if a best practice on this would belong in the DOCS.

guyca commented 4 years ago

Hey @lukebrandonfarrell. Sorry for the delay, I was on vacation :)

That is a great suggestion!! While both suggestions seem trivial and simple, I'm sure this isn't straight forward to newcomers.

I've added a slightly similar article called "Conditional Roots" under the Advance Navigation section. Here I demonstrate how to set the correct root according to some state.

I'm thinking we should pull the "Conditional Roots" section the a dedicated page so it's more visible. WDYT?

Regarding the methods to address this problem. I think option 1 is wrong since it creates coupling between screens. It makes "Login Screen" aware of "Reset pin" flow. Option 2 is better. Passing an onSuccess callback is great as it makes the screen flow-agnostic and decoupled for other screens. This way, we don't even need ResetPinLoginPage and InitialLoginPage since the onSuccess callback is always called.

lukebrandonfarrell commented 4 years ago

@guyca No problem, hope you enjoyed your holiday!

I agree with "Conditional Roots" being its own section, there is a lot we can write about this.

Option 1 does create coupling, an onSuccess callback is a good solution. We currently have our own in-built solution called Funnels, which is an abstraction over this library which allow us to declare the full navigation flow of the application in a single file, each screen just then moves a step along in the funnel by calling Funnels.navigate(), with the option to choose which branch of the funnel to move along... but I think for 99% of use-case onSuccess is the best option.

guyca commented 4 years ago

@lukebrandonfarrell WOW that sounds very interesting! This is exactly who we envisioned RNN will be used - by creating abstraction layer which fits the developer's use cases and needs.

This actually leads me to another section which I think a lot of developers will benefit from - "Best Practices". This section should explain that RNN should not be used directly but instead interacted with through a facade, like the on you've implemented, or by another abstraction layer which is used to enhance RNN with more capabilities (add a dismiss button to modals, always show modals in a stack etc) or simply to reduce a project's coupling with RNN.

lukebrandonfarrell commented 4 years ago

@guyca I think "Best Practices" is a good section... although I'm not sure if we should shout about the abstraction stuff too much, for 90% of projects using the methods this library provides is the way forward... I'm worried that people just getting into this will start abstracting and make a complete mess of their project 😂

As for the 10% of projects which have more complicated use cases, then maybe we should add a small section about wrapping the navigation methods. Although, I think the research is still underway for the best approach.

We are going to revisit our 'Funnel' library to see if we can simplify it and possible open-source it, but we are still a few months away from that.

I agree with wrapping components like modals to add certain buttons then use those components. It's the same thing I did with the RNNDrawer, so a section on that may be useful to some people.

guyca commented 4 years ago

You have a point.. perhaps this topic is more suitable for a blog post then the documentation which should remain unopinionated.

mrousavy commented 3 years ago

Regarding bottomTabs + react-native-vector-icons: You can use Icon.getImageSourceSync to get the icons when creating the bottom tabs. There are no types for this yet, I think there's a dedicated issue for that at @oblador 's repo. Also, there is a bug which causes the function to return the same Image for different icon names. Here's the issue for that, I've created a fix for this here, which also includes a .patch file if you want to use this fix until he merges it.

I'll add info to the docs as soon as that PR is being merged.

stale[bot] commented 3 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you believe the issue is still relevant, please test on the latest version and report back. Thank you for your contributions.

stale[bot] commented 3 years ago

The issue has been closed for inactivity.

guyca commented 3 years ago

Stale bot what are you doing!!!! 🤬

lukebrandonfarrell commented 3 years ago

Damn stale bot ! He should know documentation is never finished 🥴

guyca commented 3 years ago

I'm a believer 🤷 image