update the router guide
This commit is contained in:
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::*;
|
||||
|
||||
@@ -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::*;
|
||||
|
||||
@@ -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::*;
|
||||
|
||||
@@ -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::*;
|
||||
|
||||
@@ -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::*;
|
||||
|
||||
Reference in new issue
Block a user