Building a Nest

Not a bird's nest! A nest of routes!

In this chapter we will begin to build the blog portion of our site which will include links, nested URLs, and URL parameters. We will also explore the use case of rendering components directly in the component calling use_router.

Our site visitors won't know all the available pages and blogs on our site so we should provide a navigation bar for them. Let's create a new NavBar component:


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

fn NavBar(cx: Scope) -> Element {
    render! {
        nav {
            ul { }
        }
    }
}
}

Our navbar will be a list of links going between our pages. We could always use an HTML anchor element but that would cause our page to reload unnecessarily. Instead we want to use the Link component provided by Dioxus Router.

The Link is similar to a regular a tag. It takes a target (for now a path, more on other targets later) and an element. Let's add our links


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

fn NavBar(cx: Scope) -> Element {
    render! {
        nav {
            ul {
                // new stuff starts here
                li { Link {
                    target: NavigationTarget::Internal(String::from("/")),
                    "Home"
                } }
                li { Link {
                        target: "/blog", // short form
                        "Blog"
                } }
                // new stuff ends here
            }
        }
    }
}
}

Using this method, the Link component only works for links within our application. To learn more about navigation targets see here.

And finally, we add the navbar component in our app component:


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;
fn Home(cx: Scope) -> Element { unimplemented!() }
fn NavBar(cx: Scope) -> Element { unimplemented!() }
fn PageNotFound(cx: Scope) -> Element { unimplemented!() }

fn App(cx: Scope) -> Element {
    use_router(
        cx,
        &|| RouterConfiguration::default(),
        &|| Segment::content(comp(Home)).fallback(comp(PageNotFound))
    );

    render! {
        NavBar { } // this is new
        Outlet { }
    }
}
}

Now you should see a list of links near the top of your page. Click on one and you should seamlessly travel between pages.

Active Link Styling

You might want to style links differently, when their page is currently open. To achieve this, we can tell the Link to give its internal a tag a class in that case.


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

fn NavBar(cx: Scope) -> Element {
    render! {
        nav {
            ul {
                li { Link {
                    target: NavigationTarget::Internal(String::from("/")),
                    active_class: "active", // this is new
                    "Home"
                } }
                li { Link {
                    target: "/blog",
                    active_class: "active", // this is new
                    "Blog"
                } }
            }
        }
    }
}
}

This will not be reflected in the full example code.

URL Parameters and Nested Routes

Many websites such as GitHub put parameters in their URL. For example, https://github.com/DioxusLabs utilizes the text after the domain to dynamically search and display content about an organization.

We want to store our blogs in a database and load them as needed. This'll help prevent our app from being bloated therefor providing faster load times. We also want our users to be able to send people a link to a specific blog post.

We could utilize a search page that loads a blog when clicked but then our users won't be able to share our blogs easily. This is where URL parameters come in.

The path to our blog will look like /blog/myBlogPage, myBlogPage being the URL parameter.

First, lets create a component that wraps around all blog content. This allows us to add a heading that tells the user they are on the blog.


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

fn Blog(cx: Scope) -> Element {
    render! {
        h1 { "Blog" }
        Outlet {}
    }
}
}

Note the Outlet { } component. For the components of a nested route to be rendered, we need an equally nested outlet. For more details, see the nested routes chapter of the features section.

Now we'll create another index component, that'll be displayed when no blog post is selected:


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

fn BlogList(cx: Scope) -> Element {
    render! {
        h2 { "Choose a post" }
        ul {
            li { Link {
                target: "/blog/1",
                "Read the first blog post"
            } }
            li { Link {
                target: "/blog/2",
                "Read the second blog post"
            } }
        }
    }
}
}

We also need to create a component that displays an actual blog post. Within this component we can use the use_route hook to gain access to our URL parameters:


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;

struct PostId;

fn BlogPost(cx: Scope) -> Element {
    let route = use_route(cx).unwrap();

    let post_id = route.parameter::<PostId>();
    let post = post_id
        .map(|id| id.to_string())
        .unwrap_or(String::from("unknown"));

    render! {
        h2 { "Blog Post: {post}"}
    }
}
}

Finally, let's tell our router about those components.


#![allow(unused)]
fn main() {
// Hidden lines (like this one) make the documentation tests work.
extern crate dioxus;
use dioxus::prelude::*;
extern crate dioxus_router;
use dioxus_router::prelude::*;
fn Blog(cx: Scope) -> Element { unimplemented!() }
fn BlogList(cx: Scope) -> Element { unimplemented!() }
struct PostId;
fn BlogPost(cx: Scope) -> Element { unimplemented!() }
fn Home(cx: Scope) -> Element { unimplemented!() }
fn NavBar(cx: Scope) -> Element { unimplemented!() }
fn PageNotFound(cx: Scope) -> Element { unimplemented!() }

fn App(cx: Scope) -> Element {
    use_router(
        cx,
        &|| RouterConfiguration::default(),
        &|| {
            Segment::content(comp(Home))
                // new stuff starts here
                .fixed("blog", Route::content(comp(Blog)).nested(
                    Segment::content(comp(BlogList))
                        .catch_all((comp(BlogPost), PostId { }))
                ))
                // new stuff ends here
            .fallback(comp(PageNotFound))
        }
    );

    render! {
        NavBar { }
        Outlet { }
    }
}
}

That's it! If you head to /blog/1 you should see our sample post.

Conclusion

In this chapter we utilized Dioxus Router's Link, URL Parameter, and use_route functionality to build the blog portion of our application. In the next chapter, we will go over how navigation targets (like the one we passed to our links) work.

Dioxus Router

Building a Nest

Site Navigation

Active Link Styling

URL Parameters and Nested Routes

Conclusion