Files
dioxus/docs/nightly/router/example/building-a-nest.html
T
2023-06-01 11:09:51 -05:00

464 lines
26 KiB
HTML

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Building a Nest - Dioxus Router</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../highlight.css">
<link rel="stylesheet" href="../tomorrow-night.css">
<link rel="stylesheet" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="../index.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">Features</li><li class="chapter-item expanded "><a href="../features/index.html"><strong aria-hidden="true">1.</strong> Adding the Router to Your Application</a></li><li class="chapter-item expanded "><a href="../features/routes/index.html"><strong aria-hidden="true">2.</strong> Defining Routes</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../features/routes/nested.html"><strong aria-hidden="true">2.1.</strong> Nested Routes</a></li><li class="chapter-item expanded "><a href="../features/routes/catch_all.html"><strong aria-hidden="true">2.2.</strong> Catch All Routes</a></li><li class="chapter-item expanded "><a href="../features/routes/matching.html"><strong aria-hidden="true">2.3.</strong> Matching Routes</a></li><li class="chapter-item expanded "><a href="../features/routes/fallback.html"><strong aria-hidden="true">2.4.</strong> Fallback Routes (404 page)</a></li><li class="chapter-item expanded "><a href="../features/routes/multiple-and-redirect.html"><strong aria-hidden="true">2.5.</strong> Multiple Components &amp; Redirects</a></li></ol></li><li class="chapter-item expanded "><a href="../features/outlets.html"><strong aria-hidden="true">3.</strong> Outlets</a></li><li class="chapter-item expanded "><a href="../features/navigation/index.html"><strong aria-hidden="true">4.</strong> Links &amp; Navigation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../features/navigation/name.html"><strong aria-hidden="true">4.1.</strong> Named Navigation</a></li><li class="chapter-item expanded "><a href="../features/navigation/external.html"><strong aria-hidden="true">4.2.</strong> External Navigation</a></li><li class="chapter-item expanded "><a href="../features/navigation/programmatic.html"><strong aria-hidden="true">4.3.</strong> Programmatic Navigation</a></li></ol></li><li class="chapter-item expanded "><a href="../features/query.html"><strong aria-hidden="true">5.</strong> Query</a></li><li class="chapter-item expanded "><a href="../features/failures/index.html"><strong aria-hidden="true">6.</strong> Navigation Failures</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../features/failures/named.html"><strong aria-hidden="true">6.1.</strong> Named Navigation Failure</a></li><li class="chapter-item expanded "><a href="../features/failures/external.html"><strong aria-hidden="true">6.2.</strong> External Navigation Failure</a></li><li class="chapter-item expanded "><a href="../features/failures/redirection-limit.html"><strong aria-hidden="true">6.3.</strong> Redirection Limit Failure</a></li></ol></li><li class="chapter-item expanded "><a href="../features/history-providers.html"><strong aria-hidden="true">7.</strong> History Providers</a></li><li class="chapter-item expanded "><a href="../features/history-buttons.html"><strong aria-hidden="true">8.</strong> History Buttons</a></li><li class="chapter-item expanded "><a href="../features/sitemap-generation.html"><strong aria-hidden="true">9.</strong> Sitemap Generation</a></li><li class="chapter-item expanded "><a href="../features/routing-update-callback.html"><strong aria-hidden="true">10.</strong> Routing Update Callback</a></li><li class="chapter-item expanded affix "><li class="part-title">Example Project</li><li class="chapter-item expanded "><a href="../example/index.html"><strong aria-hidden="true">11.</strong> Overview</a></li><li class="chapter-item expanded "><a href="../example/first-route.html"><strong aria-hidden="true">12.</strong> Creating Our First Route</a></li><li class="chapter-item expanded "><a href="../example/building-a-nest.html" class="active"><strong aria-hidden="true">13.</strong> Building a Nest</a></li><li class="chapter-item expanded "><a href="../example/navigation-targets.html"><strong aria-hidden="true">14.</strong> Navigation Targets</a></li><li class="chapter-item expanded "><a href="../example/redirection-perfection.html"><strong aria-hidden="true">15.</strong> Redirection Perfection</a></li><li class="chapter-item expanded "><a href="../example/full-code.html"><strong aria-hidden="true">16.</strong> Full Code</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Dioxus Router</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="building-a-nest"><a class="header" href="#building-a-nest">Building a Nest</a></h1>
<p>Not a bird's nest! A nest of routes!</p>
<p>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 <a href="https://docs.rs/dioxus-router/latest/dioxus_router/hooks/fn.use_router.html"><code>use_router</code></a>.</p>
<h2 id="site-navigation"><a class="header" href="#site-navigation">Site Navigation</a></h2>
<p>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 <code>NavBar</code> component:</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>fn NavBar(cx: Scope) -&gt; Element {
render! {
nav {
ul { }
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>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 <a href="https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html"><code>Link</code></a> component provided by Dioxus Router.</p>
<p>The <a href="https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html"><code>Link</code></a> is similar to a regular <code>a</code> tag. It takes a target (for now a path,
more on other targets later) and an element. Let's add our links</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>fn NavBar(cx: Scope) -&gt; Element {
render! {
nav {
ul {
// new stuff starts here
li { Link {
target: NavigationTarget::Internal(String::from(&quot;/&quot;)),
&quot;Home&quot;
} }
li { Link {
target: &quot;/blog&quot;, // short form
&quot;Blog&quot;
} }
// new stuff ends here
}
}
}
}
<span class="boring">}
</span></code></pre></pre>
<blockquote>
<p>Using this method, the <a href="https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html"><code>Link</code></a> component only works for links within our
application. To learn more about navigation targets see
<a href="./navigation-targets.html">here</a>.</p>
</blockquote>
<p>And finally, we add the navbar component in our app component:</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">fn Home(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn NavBar(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn PageNotFound(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">
</span>fn App(cx: Scope) -&gt; Element {
use_router(
cx,
&amp;|| RouterConfiguration::default(),
&amp;|| Segment::content(comp(Home)).fallback(comp(PageNotFound))
);
render! {
NavBar { } // this is new
Outlet { }
}
}
<span class="boring">}
</span></code></pre></pre>
<p>Now you should see a list of links near the top of your page. Click on one and
you should seamlessly travel between pages.</p>
<h3 id="active-link-styling"><a class="header" href="#active-link-styling">Active Link Styling</a></h3>
<p>You might want to style links differently, when their page is currently open.
To achieve this, we can tell the <a href="https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html"><code>Link</code></a> to give its internal <code>a</code> tag a class
in that case.</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>fn NavBar(cx: Scope) -&gt; Element {
render! {
nav {
ul {
li { Link {
target: NavigationTarget::Internal(String::from(&quot;/&quot;)),
active_class: &quot;active&quot;, // this is new
&quot;Home&quot;
} }
li { Link {
target: &quot;/blog&quot;,
active_class: &quot;active&quot;, // this is new
&quot;Blog&quot;
} }
}
}
}
}
<span class="boring">}
</span></code></pre></pre>
<blockquote>
<p>This will not be reflected in the <a href="./full-code.html">full example code</a>.</p>
</blockquote>
<h2 id="url-parameters-and-nested-routes"><a class="header" href="#url-parameters-and-nested-routes">URL Parameters and Nested Routes</a></h2>
<p>Many websites such as GitHub put parameters in their URL. For example,
<code>https://github.com/DioxusLabs</code> utilizes the text after the domain to
dynamically search and display content about an organization.</p>
<p>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.</p>
<p>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.</p>
<p>The path to our blog will look like <code>/blog/myBlogPage</code>, <code>myBlogPage</code> being the
URL parameter.</p>
<p>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.</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>fn Blog(cx: Scope) -&gt; Element {
render! {
h1 { &quot;Blog&quot; }
Outlet {}
}
}
<span class="boring">}
</span></code></pre></pre>
<blockquote>
<p>Note the <code>Outlet { }</code> component. For the components of a nested route to be
rendered, we need an equally nested outlet. For more details, see the
<a href="../features/routes/nested.html">nested routes</a> chapter of the features section.</p>
</blockquote>
<p>Now we'll create another index component, that'll be displayed when no blog post
is selected:</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>fn BlogList(cx: Scope) -&gt; Element {
render! {
h2 { &quot;Choose a post&quot; }
ul {
li { Link {
target: &quot;/blog/1&quot;,
&quot;Read the first blog post&quot;
} }
li { Link {
target: &quot;/blog/2&quot;,
&quot;Read the second blog post&quot;
} }
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>We also need to create a component that displays an actual blog post. Within
this component we can use the <code>use_route</code> hook to gain access to our URL
parameters:</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">
</span>struct PostId;
fn BlogPost(cx: Scope) -&gt; Element {
let route = use_route(cx).unwrap();
let post_id = route.parameter::&lt;PostId&gt;();
let post = post_id
.map(|id| id.to_string())
.unwrap_or(String::from(&quot;unknown&quot;));
render! {
h2 { &quot;Blog Post: {post}&quot;}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>Finally, let's tell our router about those components.</p>
<pre><pre class="playground"><code class="language-rust no_run edition2021">
<span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span><span class="boring">// Hidden lines (like this one) make the documentation tests work.
</span><span class="boring">extern crate dioxus;
</span><span class="boring">use dioxus::prelude::*;
</span><span class="boring">extern crate dioxus_router;
</span><span class="boring">use dioxus_router::prelude::*;
</span><span class="boring">fn Blog(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn BlogList(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">struct PostId;
</span><span class="boring">fn BlogPost(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn Home(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn NavBar(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">fn PageNotFound(cx: Scope) -&gt; Element { unimplemented!() }
</span><span class="boring">
</span>fn App(cx: Scope) -&gt; Element {
use_router(
cx,
&amp;|| RouterConfiguration::default(),
&amp;|| {
Segment::content(comp(Home))
// new stuff starts here
.fixed(&quot;blog&quot;, Route::content(comp(Blog)).nested(
Segment::content(comp(BlogList))
.catch_all((comp(BlogPost), PostId { }))
))
// new stuff ends here
.fallback(comp(PageNotFound))
}
);
render! {
NavBar { }
Outlet { }
}
}
<span class="boring">}
</span></code></pre></pre>
<p>That's it! If you head to <code>/blog/1</code> you should see our sample post.</p>
<h2 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h2>
<p>In this chapter we utilized Dioxus Router's Link, URL Parameter, and <code>use_route</code>
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.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../example/first-route.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../example/navigation-targets.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../example/first-route.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../example/navigation-targets.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="../book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>