update the router guide

This commit is contained in:
Evan Almloff committed 2023-06-01 13:13:59 -05:00
1 parent 67992f7da9
commit 0d3ea377ce
63 files changed
+615 -1705

No files matched your search

@@ -10,6 +10,7 @@ functionality with catch all routes.
> The parameter will be URL decoded.
## Creating a content component
We start by creating a component that uses the parameters value.
We can get the current state of the router using the [`use_route`] hook. From
@@ -23,7 +24,7 @@ will later also define on our route.
> The [`use_route`] hook can only be used in components nested within a
> component that called [`use_router`].
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
@@ -45,6 +46,7 @@ fn Greeting(cx: Scope) -> Element {
```
## Defining the routes
Now we can define our route. Unlike a fixed [`Route`], a [`ParameterRoute`]
needs two arguments to be created.
@@ -54,7 +56,7 @@ needs two arguments to be created.
> For that reason, the example below would not work in practice, but showing
> both forms (explicit and short) is more important for this example.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -83,6 +85,7 @@ fn App(cx: Scope) -> Element {
```
## Interaction with other routes
Each individual [`Segment`] can only ever have one active route. This means that
when a [`Segment`] has more than just a catch all route, the router has to
decide which is active. It does that this way:
@@ -105,11 +108,13 @@ by the path, i.e. `//`.
>
> If you absolutely need an empty parameter on the root [`Segment`], a URL like
> this _could_ work:
>
> - `https://your-site.example//` for web sites
> - `dioxus://index.html//` for desktop apps
## Full Code
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
+4 -2
View File
@@ -8,10 +8,11 @@ Fallback routes allow us to do that.
> path, like web apps running in the browser.
## A single global fallback
To catch all cases of invalid paths within our app, we can simply add a fallback
route to our root [`Segment`].
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
@@ -59,6 +60,7 @@ fn App(cx: Scope) -> Element {
```
## More specific fallback routes
In some cases we might want to show different fallback content depending on what
section of our app the user is in.
@@ -73,7 +75,7 @@ will then replace the global fallback whenever our [`Segment`] was active.
Note the `.clear_fallback(false)` part. If we didn't add this, the fallback
content would be rendered inside the `Settings` component.
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
+8 -4
View File
@@ -4,10 +4,11 @@ When creating a router we need to pass it a [`Segment`]. It tells the router
about all the routes of our app.
## Example content
To get a good understanding of how we define routes we first need to prepare
some example content, so we can see the routing in action.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
@@ -28,6 +29,7 @@ fn Other(cx: Scope) -> Element {
```
## Index routes
The easiest thing to do is to define an index route.
Index routes act very similar to `index.html` files in most web servers. They
@@ -36,7 +38,7 @@ are active, when we don't specify a route.
> Note that we wrap our `Index` component with [`comp`]. This is because of
> rust type system requirements.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -59,6 +61,7 @@ fn App(cx: Scope) -> Element {
```
## Fixed routes
It is almost as easy to define a fixed route.
Fixed routes work similar to how web servers treat files. They are active, when
@@ -66,7 +69,7 @@ specified in the path. In the example, the path must be `/other`.
> The path will be URL decoded before checking if it matches our route.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -91,7 +94,8 @@ fn App(cx: Scope) -> Element {
```
## Full Code
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
+4 -2
View File
@@ -14,10 +14,11 @@ _Matching_ routes make it easy to implement such behavior.
> unfit for all other purposes.
## Code Example
> Notice that the parameter of a _matching route_ has the same type as a
> [_catch all route_](./catch_all.md).
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -112,6 +113,7 @@ fn App(cx: Scope) -> Element {
```
## Matcher
In the example above, both _matching routes_ use a regular expression to specify
when they match. However, _matching routes_ are not limited to those. They
accept all types that implement the [`Matcher`] trait.
@@ -119,7 +121,7 @@ accept all types that implement the [`Matcher`] trait.
For example, you could (but probably shouldn't) implement a matcher, that
matches all values with an even number of characters:
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus_router;
# use dioxus_router::prelude::*;
@@ -1,11 +1,13 @@
# Multiple Components & Redirects
## Multiple Components
When creating complex apps we sometimes want to have multiple pieces of content
side by side. The router allows us to do this. For more details see the section
about [named `Outlet`s](../outlets.md#named-outlets).
## Redirects
In some cases we may want to redirect our users to another page whenever they
open a specific path. We can tell the router to do this when defining our
routes.
@@ -16,7 +18,7 @@ routes.
In the following example we will redirect everybody from `/` and `/start` to
`/home`.
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
use dioxus::prelude::*;
+9 -4
View File
@@ -22,6 +22,7 @@ We might want to map this structure to these paths and components:
Nested routes allow us to do this.
## Route Depth
With nesting routes, the router manages content on multiple levels. In our
example, when the path is `/settings`, there are two levels of content:
@@ -34,13 +35,14 @@ content of nested routes to actually be rendered, we also need nested
[`Outlet`]s.
## Defining the content components
We start by creating the components we want the router to render.
Take a look at the `Settings` component. When it gets rendered by an [`Outlet`],
it will render a second [`Outlet`]. Thus the second [`Outlet`] is nested within
the first one, and will in turn render our nested content.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -74,13 +76,14 @@ fn PrivacySettings(cx: Scope) -> Element {
```
## Defining the root [`Segment`]
Now we create the [`Segment`] that we will pass to the router.
Note that we wrap `comp(Settings)` within a [`Route`]. For this exact code that
is unnecessary, as this would be done automatically. However, in the next step
we'll use a method of [`Route`], so we might as well add this now.
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -103,6 +106,7 @@ fn App(cx: Scope) -> Element {
```
## Defining the nested [`Segment`]
In order to create nested routes we need to create a nested [`Segment`]. We then
pass it to the [`Route`] on the root segment.
@@ -110,7 +114,7 @@ pass it to the [`Route`] on the root segment.
>
> https://router.example/`root_segment`/`first_nested_segment`/`second_nested_segment`/...
```rust,no_run
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;
@@ -143,7 +147,8 @@ fn App(cx: Scope) -> Element {
```
## Full Code
```rust
```rust, no_run
# // Hidden lines (like this one) make the documentation tests work.
# extern crate dioxus;
# use dioxus::prelude::*;