update the router guide

docs/router/examples/catch_all.rs

@@ -0,0 +1,48 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+// ANCHOR: router
+#[derive(Routable, Clone)]
+enum Route {
+    #[route("/")]
+    Home {},
+    // PageNotFound is a catch all route that will match any route and placing the matched segments in the route field
+    #[route("/:...route")]
+    PageNotFound { route: Vec<String> },
+}
+// ANCHOR_END: router
+
+// ANCHOR: app
+#[inline_props]
+fn App(cx: Scope) -> Element {
+    render! {
+        Router {}
+    }
+}
+// ANCHOR_END: app
+
+// ANCHOR: home
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    render! {
+        h1 { "Welcome to the Dioxus Blog!" }
+    }
+}
+// ANCHOR_END: home
+
+// ANCHOR: fallback
+#[inline_props]
+fn PageNotFound(cx: Scope, route: Vec<String>) -> Element {
+    render! {
+        h1 { "Page not found" }
+        p { "We are terribly sorry, but the page you requested doesn't exist." }
+        pre {
+            color: "red",
+            "log:\nattemped to navigate to: {route:?}"
+        }
+    }
+}
+// ANCHOR_END: fallback
+
+fn main() {}

docs/router/examples/dynamic_route.rs

@@ -0,0 +1,115 @@
+#![allow(non_snake_case)]
+
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+fn main() {
+    #[cfg(target_arch = "wasm32")]
+    dioxus_web::launch(App);
+    #[cfg(not(target_arch = "wasm32"))]
+    dioxus_desktop::launch(App);
+}
+
+// ANCHOR: router
+#[derive(Routable, Clone)]
+#[rustfmt::skip]
+enum Route {
+    #[layout(NavBar)]
+        #[route("/")]
+        Home {},
+        #[nest("/blog")]
+            #[layout(Blog)]
+            #[route("/")]
+            BlogList {},
+            #[route("/blog/:name")]
+            BlogPost { name: String },
+            #[end_layout]
+        #[end_nest]
+    #[end_layout]
+    #[route("/:...route")]
+    PageNotFound {
+        route: Vec<String>,
+    },
+}
+// ANCHOR_END: router
+
+fn App(cx: Scope) -> Element {
+    render! {
+        Router {}
+    }
+}
+
+#[inline_props]
+fn NavBar(cx: Scope) -> Element {
+    render! {
+        nav {
+            ul {
+                li { Link { target: Route::Home {}, "Home" } }
+                li { Link { target: Route::BlogList {}, "Blog" } }
+            }
+        }
+        Outlet {}
+    }
+}
+
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    render! {
+        h1 { "Welcome to the Dioxus Blog!" }
+    }
+}
+
+// ANCHOR: blog
+#[inline_props]
+fn Blog(cx: Scope) -> Element {
+    render! {
+        h1 { "Blog" }
+        Outlet {}
+    }
+}
+// ANCHOR_END: blog
+
+// ANCHOR: blog_list
+#[inline_props]
+fn BlogList(cx: Scope) -> Element {
+    render! {
+        h2 { "Choose a post" }
+        ul {
+            li {
+                Link {
+                    target: Route::BlogPost { name: "Blog post 1".into() },
+                    "Read the first blog post"
+                }
+            }
+            li {
+                Link {
+                    target: Route::BlogPost { name: "Blog post 2".into() },
+                    "Read the second blog post"
+                }
+            }
+        }
+    }
+}
+// ANCHOR_END: blog_list
+
+// ANCHOR: blog_post
+// The name prop comes from the /:name route segment
+#[inline_props]
+fn BlogPost(cx: Scope, name: String) -> Element {
+    render! {
+        h2 { "Blog Post: {name}"}
+    }
+}
+// ANCHOR_END: blog_post
+
+#[inline_props]
+fn PageNotFound(cx: Scope, route: Vec<String>) -> Element {
+    render! {
+        h1 { "Page not found" }
+        p { "We are terribly sorry, but the page you requested doesn't exist." }
+        pre {
+            color: "red",
+            "log:\nattemped to navigate to: {route:?}"
+        }
+    }
+}

docs/router/examples/external_link.rs

@@ -0,0 +1,28 @@
+#![allow(non_snake_case, unused)]
+
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+#[derive(Routable, Clone)]
+enum Route {
+    #[route("/")]
+    Home {},
+}
+
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    todo!()
+}
+
+fn main() {}
+
+// ANCHOR: component
+fn GoToDioxus(cx: Scope) -> Element {
+    render! {
+        Link {
+            target: NavigationTarget::External("https://dioxuslabs.com".into()),
+            "ExternalTarget target"
+        }
+    }
+}
+// ANCHOR_END: component

docs/router/examples/first_route.rs

@@ -0,0 +1,35 @@
+// ANCHOR: router
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+/// An enum of all of the possible routes in the app.
+#[derive(Routable, Clone)]
+enum Route {
+    // The home page is at the / route
+    #[route("/")]
+    // If the name of the component and variant are the same you can omit the component and props name
+    // #[route("/", ComponentName, PropsName)]
+    Home {},
+}
+// ANCHOR_END: router
+
+// ANCHOR: app
+#[inline_props]
+fn App(cx: Scope) -> Element {
+    render! {
+        Router {}
+    }
+}
+// ANCHOR_END: app
+
+// ANCHOR: home
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    render! {
+        h1 { "Welcome to the Dioxus Blog!" }
+    }
+}
+// ANCHOR_END: home
+
+fn main() {}

docs/router/examples/full_example.rs

@@ -1,37 +1,49 @@
+#![allow(non_snake_case)]
+
 use dioxus::prelude::*;
 use dioxus_router::prelude::*;
 
 fn main() {
+    #[cfg(target_arch = "wasm32")]
     dioxus_web::launch(App);
+    #[cfg(not(target_arch = "wasm32"))]
+    dioxus_desktop::launch(App);
 }
 
-#[derive(Routable, Clone, Serialize, Deserialize)]
+// ANCHOR: router
+#[derive(Routable, Clone)]
 #[rustfmt::skip]
 enum Route {
-    #[route("/")]
-    Home {},
-    #[nest("/blog")]
-        #[layout(Blog)]
-            #[route("/")]
-            BlogList {},
-            #[route("/blog/:id")]
-            BlogPost { id: String },
-        #[end_layout]
+    #[layout(NavBar)]
+        #[route("/")]
+        Home {},
+        #[nest("/blog")]
+            #[layout(Blog)]
+                #[route("/")]
+                BlogList {},
+                #[route("/blog/:name")]
+                BlogPost { name: String },
+            #[end_layout]
+        #[end_nest]
+    #[end_layout]
+    #[nest("/myblog")]
+        #[redirect("/", || Route::BlogList {})]
+        #[redirect("/:name", |name: String| Route::BlogPost { name })]
     #[end_nest]
-    #[redirect("/myblog", || Route::BlogList {})]
     #[route("/:...route")]
     PageNotFound {
         route: Vec<String>,
     },
 }
+// ANCHOR_END: router
 
 fn App(cx: Scope) -> Element {
     render! {
-        NavBar {}
         Router {}
     }
 }
 
+#[inline_props]
 fn NavBar(cx: Scope) -> Element {
     render! {
         nav {
@@ -40,6 +52,7 @@ fn NavBar(cx: Scope) -> Element {
                 li { Link { target: Route::BlogList {}, "Blog" } }
             }
         }
+        Outlet {}
     }
 }
 
@@ -65,13 +78,13 @@ fn BlogList(cx: Scope) -> Element {
         ul {
             li {
                 Link {
-                    target: Route::BlogPost { id: 1 },
+                    target: Route::BlogPost { name: "Blog post 1".into() },
                     "Read the first blog post"
                 }
             }
             li {
                 Link {
-                    target: Route::BlogPost { id: 2 },
+                    target: Route::BlogPost { name: "Blog post 2".into() },
                     "Read the second blog post"
                 }
             }
@@ -80,9 +93,9 @@ fn BlogList(cx: Scope) -> Element {
 }
 
 #[inline_props]
-fn BlogPost(cx: Scope, id: usize) -> Element {
+fn BlogPost(cx: Scope, name: String) -> Element {
     render! {
-        h2 { "Blog Post: {id}"}
+        h2 { "Blog Post: {name}"}
     }
 }
 

docs/router/examples/links.rs

@@ -0,0 +1,72 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+// ANCHOR: router
+#[derive(Routable, Clone)]
+#[rustfmt::skip]
+enum Route {
+    // All routes under the NavBar layout will be rendered inside of the NavBar Outlet
+    #[layout(NavBar)]
+        #[route("/")]
+        Home {},
+    #[end_layout]
+    #[route("/:...route")]
+    PageNotFound { route: Vec<String> },
+}
+// ANCHOR_END: router
+
+// ANCHOR: nav
+#[inline_props]
+fn NavBar(cx: Scope) -> Element {
+    render! {
+        nav {
+            ul {
+                li {
+                    Link {
+                        // The Link component will navigate to the route specified
+                        // in the target prop which is checked to exist at compile time
+                        target: Route::Home {},
+                        "Home"
+                    }
+                }
+            }
+        }
+        Outlet {}
+    }
+}
+// ANCHOR_END: nav
+
+// ANCHOR: app
+#[inline_props]
+fn App(cx: Scope) -> Element {
+    render! {
+        Router {}
+    }
+}
+// ANCHOR_END: app
+
+// ANCHOR: home
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    render! {
+        h1 { "Welcome to the Dioxus Blog!" }
+    }
+}
+// ANCHOR_END: home
+
+// ANCHOR: fallback
+#[inline_props]
+fn PageNotFound(cx: Scope, route: Vec<String>) -> Element {
+    render! {
+        h1 { "Page not found" }
+        p { "We are terribly sorry, but the page you requested doesn't exist." }
+        pre {
+            color: "red",
+            "log:\nattemped to navigate to: {route:?}"
+        }
+    }
+}
+// ANCHOR_END: fallback
+
+fn main() {}

docs/router/examples/nested_routes.rs

@@ -0,0 +1,66 @@
+#![allow(non_snake_case)]
+use dioxus::prelude::*;
+use dioxus_router::prelude::*;
+
+// ANCHOR: router
+#[derive(Routable, Clone)]
+#[rustfmt::skip]
+enum Route {
+    // All routes under the NavBar layout will be rendered inside of the NavBar Outlet
+    #[layout(NavBar)]
+        #[route("/")]
+        Home {},
+    #[end_layout]
+    #[route("/:...route")]
+    PageNotFound { route: Vec<String> },
+}
+// ANCHOR_END: router
+
+// ANCHOR: nav
+#[inline_props]
+fn NavBar(cx: Scope) -> Element {
+    render! {
+        nav {
+            ul {
+                li { "links" }
+            }
+        }
+        // The Outlet component will render child routes (In this case just the Home component) inside the Outlet component
+        Outlet {}
+    }
+}
+// ANCHOR_END: nav
+
+// ANCHOR: app
+#[inline_props]
+fn App(cx: Scope) -> Element {
+    render! {
+        Router {}
+    }
+}
+// ANCHOR_END: app
+
+// ANCHOR: home
+#[inline_props]
+fn Home(cx: Scope) -> Element {
+    render! {
+        h1 { "Welcome to the Dioxus Blog!" }
+    }
+}
+// ANCHOR_END: home
+
+// ANCHOR: fallback
+#[inline_props]
+fn PageNotFound(cx: Scope, route: Vec<String>) -> Element {
+    render! {
+        h1 { "Page not found" }
+        p { "We are terribly sorry, but the page you requested doesn't exist." }
+        pre {
+            color: "red",
+            "log:\nattemped to navigate to: {route:?}"
+        }
+    }
+}
+// ANCHOR_END: fallback
+
+fn main() {}