From 7349e0277a5b641d94a76a1fcc052d61725155e4 Mon Sep 17 00:00:00 2001 From: Vojtech Novak Date: Tue, 3 Apr 2018 00:35:28 +0200 Subject: [PATCH 1/4] first pass at key docs --- docs/navigation-key.md | 26 ++++++++++++++++++++++++++ website/i18n/en.json | 2 ++ website/sidebars.json | 3 ++- 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 docs/navigation-key.md diff --git a/docs/navigation-key.md b/docs/navigation-key.md new file mode 100644 index 00000000000..8a1eb43faaa --- /dev/null +++ b/docs/navigation-key.md @@ -0,0 +1,26 @@ +--- +id: navigation-key +title: Using the navigation key +sidebar_label: Using the navigation key +--- + +The `key` parameter comes up repeatedly across different navigation functions. Let's take a look at a summary of its use cases: + +### Idempotent navigation with the [`navigate` call](/docs/navigation-actions.html#navigate) + +`navigate` function accepts an optional `key` parameter which is used as an identifier for the route to navigate to. If you provide the identifier (as for example in `navigate({ routeName: 'someScreen', params: { someParam: 'someValue' }, key: 'someScreen' })`) and user triggers such navigation action multiple times (eg. by pushing a button that calls the navigation action quickly multiple times in a row), the navigation action will be executed only once. + +Without using the key, calling `navigate({ routeName: 'someScreen' })` twice would result in pushing the screen onto the stack two times. Providing the `key` instead results into one push only. The second call to `navigate` finds out that the screen is already present on the stack and instead of pushing a new instance of the same screen, it calls `setParams` on the existing screen. // TODO what if a screen with given key is present "earlier" in the navigation stack? Will it go back? + +### Usage with [`reset`](/docs/navigation-actions.html#reset) + +When resetting, `key` is also optional and can be a string or null. If set, the navigator with the given key will reset. If null, the root navigator will reset. +// TODO how to find navigator key? + +### Usage with [`replace`](/docs/navigation-actions.html#replace) + +With replace, key is a required parameter used for identifying the route to be replaced. + +### Usage with `goBack` + +Please refer to the [`goBack docs`](/docs/navigation-prop.html#goback-close-the-active-screen-and-move-back) for a detailed explanation. diff --git a/website/i18n/en.json b/website/i18n/en.json index 06ccb84666f..23362058462 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -71,6 +71,8 @@ "Moving between screens": "Moving between screens", "navigation-actions": "NavigationActions reference", "NavigationActions": "NavigationActions", + "navigation-key": "Using the navigation key", + "Using the navigation key": "Using the navigation key", "navigation-options": "navigation-options", "Configuring Navigation Options": "Configuring Navigation Options", "navigation-prop": "Navigation prop reference", diff --git a/website/sidebars.json b/website/sidebars.json index ac33c305823..18693d3057f 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -25,7 +25,8 @@ "deep-linking", "screen-tracking", "state-persistence", - "redux-integration" + "redux-integration", + "navigation-key" ], "Build your own Navigator": [ "custom-navigator-overview", From c010f5ad7479c466435ae74c7b6525799354404a Mon Sep 17 00:00:00 2001 From: Vojtech Novak Date: Sun, 8 Apr 2018 16:20:22 +0200 Subject: [PATCH 2/4] second pass --- docs/navigation-key.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/navigation-key.md b/docs/navigation-key.md index 8a1eb43faaa..009dea6f9cf 100644 --- a/docs/navigation-key.md +++ b/docs/navigation-key.md @@ -6,20 +6,27 @@ sidebar_label: Using the navigation key The `key` parameter comes up repeatedly across different navigation functions. Let's take a look at a summary of its use cases: -### Idempotent navigation with the [`navigate` call](/docs/navigation-actions.html#navigate) +### Usage with the [`navigate`](/docs/navigation-actions.html#navigate) call -`navigate` function accepts an optional `key` parameter which is used as an identifier for the route to navigate to. If you provide the identifier (as for example in `navigate({ routeName: 'someScreen', params: { someParam: 'someValue' }, key: 'someScreen' })`) and user triggers such navigation action multiple times (eg. by pushing a button that calls the navigation action quickly multiple times in a row), the navigation action will be executed only once. +TL;DR: The behavior of `navigate` together with `key` depends on the version of react-navigation you use. In v1, key has to be provided for navigate to behave idempotently. In v2, this is no longer needed. -Without using the key, calling `navigate({ routeName: 'someScreen' })` twice would result in pushing the screen onto the stack two times. Providing the `key` instead results into one push only. The second call to `navigate` finds out that the screen is already present on the stack and instead of pushing a new instance of the same screen, it calls `setParams` on the existing screen. // TODO what if a screen with given key is present "earlier" in the navigation stack? Will it go back? +#### v2 behavior + +In v2, if no key is provided, `StackRouter` assumes the user just wants to either jump (along with setting new params) to the route by the given name if it exists in state already or push it if not. If, however, you want to push several instances of the same route, you can do so by providing a unique `key` parameter each time you call `navigate`, or you can use the `push` action available on `StackRouter`. See the related [RFC](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md) for more background. + +#### v1 behavior + +In v1, `key` parameter is used as an identifier for the route to navigate to. If you provide the identifier (as for example in `navigate({ routeName: 'someScreen', params: { someParam: 'someValue' }, key: 'someScreen' })`) and user triggers such navigation action twice (eg. by pushing a button that calls the navigation action quickly twice in a row), the navigation action will be executed only once. The second call to `navigate` finds out that the route with the key is already present on the stack and instead of pushing a new instance of the same route, it calls `setParams` on the existing one. + +Without using the key, calling `navigate({ routeName: 'someScreen' })` twice would result in pushing the route onto the stack two times. ### Usage with [`reset`](/docs/navigation-actions.html#reset) -When resetting, `key` is also optional and can be a string or null. If set, the navigator with the given key will reset. If null, the root navigator will reset. -// TODO how to find navigator key? +When resetting, `key` is also optional and can be a string or null. If set, the navigator with the given key will reset. If null, the root navigator will reset. You can obtain a route's navigator key by calling `this.props.navigation.dangerouslyGetParent().state.key`. Reason why the function is called `dangerouslyGetParent` is to warn developers against overusing it to eg. get parent of parent. ### Usage with [`replace`](/docs/navigation-actions.html#replace) -With replace, key is a required parameter used for identifying the route to be replaced. +With the replace navigation action, key is a required parameter used for identifying the route to be replaced. If you use the helper function `this.props.navigation.replace`, we will automatically substitute the key of the current route. ### Usage with `goBack` From 7be79fc0cbc8ed45b889898c30ed3dabe0cc97cb Mon Sep 17 00:00:00 2001 From: Vojtech Novak Date: Sun, 29 Apr 2018 21:43:03 +0200 Subject: [PATCH 3/4] do not explain v1 --- docs/navigation-key.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/navigation-key.md b/docs/navigation-key.md index 009dea6f9cf..b8b92c4c069 100644 --- a/docs/navigation-key.md +++ b/docs/navigation-key.md @@ -8,25 +8,22 @@ The `key` parameter comes up repeatedly across different navigation functions. L ### Usage with the [`navigate`](/docs/navigation-actions.html#navigate) call -TL;DR: The behavior of `navigate` together with `key` depends on the version of react-navigation you use. In v1, key has to be provided for navigate to behave idempotently. In v2, this is no longer needed. +If not key is provided, `StackRouter` will behave as follows: -#### v2 behavior +* if a route with the given name already exists in the state, `StackRouter` will jump to the existing route, along with setting the new parameters. +* if no such route exists, `StackRouter` will push it onto the stack -In v2, if no key is provided, `StackRouter` assumes the user just wants to either jump (along with setting new params) to the route by the given name if it exists in state already or push it if not. If, however, you want to push several instances of the same route, you can do so by providing a unique `key` parameter each time you call `navigate`, or you can use the `push` action available on `StackRouter`. See the related [RFC](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md) for more background. +If, however, you want to push several instances of the same route, you can do so by providing a unique `key` parameter each time you call `navigate`, or you can use the `push` action available on `StackRouter`. See the related [RFC](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md) for more background. -#### v1 behavior - -In v1, `key` parameter is used as an identifier for the route to navigate to. If you provide the identifier (as for example in `navigate({ routeName: 'someScreen', params: { someParam: 'someValue' }, key: 'someScreen' })`) and user triggers such navigation action twice (eg. by pushing a button that calls the navigation action quickly twice in a row), the navigation action will be executed only once. The second call to `navigate` finds out that the route with the key is already present on the stack and instead of pushing a new instance of the same route, it calls `setParams` on the existing one. - -Without using the key, calling `navigate({ routeName: 'someScreen' })` twice would result in pushing the route onto the stack two times. +> Note: the behavior of `navigate` without a `key` is significantly different in the 1.x series of releases. Read more about it [here](https://gist.github.com/vonovak/ef72f5efe1d36742de8968ff6a708985). ### Usage with [`reset`](/docs/navigation-actions.html#reset) -When resetting, `key` is also optional and can be a string or null. If set, the navigator with the given key will reset. If null, the root navigator will reset. You can obtain a route's navigator key by calling `this.props.navigation.dangerouslyGetParent().state.key`. Reason why the function is called `dangerouslyGetParent` is to warn developers against overusing it to eg. get parent of parent. +When resetting, `key` is also optional and can be a string or `null`. If set, the navigator with the given key will reset. If `null`, the root navigator will reset. You can obtain a route's navigator key by calling `this.props.navigation.dangerouslyGetParent().state.key`. Reason why the function is called `dangerouslyGetParent` is to warn developers against overusing it to eg. get parent of parent and other hard-to-follow patterns. ### Usage with [`replace`](/docs/navigation-actions.html#replace) -With the replace navigation action, key is a required parameter used for identifying the route to be replaced. If you use the helper function `this.props.navigation.replace`, we will automatically substitute the key of the current route. +With the `replace` navigation action, `key` is a required parameter used for identifying the route to be replaced. If you use the helper function `this.props.navigation.replace`, we will automatically substitute the key of the current route. ### Usage with `goBack` From f646dc697d78f9545948101142406dbd32957e8e Mon Sep 17 00:00:00 2001 From: Vojtech Novak Date: Sun, 29 Apr 2018 21:44:09 +0200 Subject: [PATCH 4/4] fix typo --- docs/navigation-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/navigation-key.md b/docs/navigation-key.md index b8b92c4c069..2f2b227c4f4 100644 --- a/docs/navigation-key.md +++ b/docs/navigation-key.md @@ -8,7 +8,7 @@ The `key` parameter comes up repeatedly across different navigation functions. L ### Usage with the [`navigate`](/docs/navigation-actions.html#navigate) call -If not key is provided, `StackRouter` will behave as follows: +If no key is provided, `StackRouter` will behave as follows: * if a route with the given name already exists in the state, `StackRouter` will jump to the existing route, along with setting the new parameters. * if no such route exists, `StackRouter` will push it onto the stack