diff --git a/examples/router/src/components/author_card.rs b/examples/router/src/components/author_card.rs index 443059918c2..caaba80e84e 100644 --- a/examples/router/src/components/author_card.rs +++ b/examples/router/src/components/author_card.rs @@ -46,7 +46,7 @@ impl Component for AuthorCard { diff --git a/examples/router/src/components/post_card.rs b/examples/router/src/components/post_card.rs index e61fa62a13d..9613664282c 100644 --- a/examples/router/src/components/post_card.rs +++ b/examples/router/src/components/post_card.rs @@ -34,10 +34,10 @@ impl Component for PostCard {
- classes={classes!("title", "is-block")} route={Route::Post { id: post.seed }}> + classes={classes!("title", "is-block")} to={Route::Post { id: post.seed }}> { &post.title } > - classes={classes!("subtitle", "is-block")} route={Route::Author { id: post.author.seed }}> + classes={classes!("subtitle", "is-block")} to={Route::Author { id: post.author.seed }}> { &post.author.name } >
diff --git a/examples/router/src/main.rs b/examples/router/src/main.rs index 2054f4f9ad4..ab4ee7b4b08 100644 --- a/examples/router/src/main.rs +++ b/examples/router/src/main.rs @@ -56,11 +56,11 @@ impl Component for Model { fn view(&self, ctx: &Context) -> Html { html! { - <> + { self.view_nav(ctx.link()) }
- render={Router::render(switch)} /> + render={Switch::render(switch)} />
- + } } } @@ -99,10 +99,10 @@ impl Model {
- classes={classes!("navbar-item")} route={Route::Home}> + classes={classes!("navbar-item")} to={Route::Home}> { "Home" } > - classes={classes!("navbar-item")} route={Route::Posts}> + classes={classes!("navbar-item")} to={Route::Posts}> { "Posts" } > @@ -112,7 +112,7 @@ impl Model {
- classes={classes!("navbar-item")} route={Route::Authors}> + classes={classes!("navbar-item")} to={Route::Authors}> { "Meet the authors" } > diff --git a/examples/router/src/pages/post.rs b/examples/router/src/pages/post.rs index 2ee0fb82b27..bf6fda9aec0 100644 --- a/examples/router/src/pages/post.rs +++ b/examples/router/src/pages/post.rs @@ -46,7 +46,7 @@ impl Component for Post {

{ "by " } - classes={classes!("has-text-weight-semibold")} route={Route::Author { id: post.meta.author.seed }}> + classes={classes!("has-text-weight-semibold")} to={Route::Author { id: post.meta.author.seed }}> { &post.meta.author.name } >

@@ -74,7 +74,7 @@ impl Post {
- classes={classes!("is-size-5")} route={Route::Author { id: quote.author.seed }}> + classes={classes!("is-size-5")} to={Route::Author { id: quote.author.seed }}> { "e.author.name } >

diff --git a/examples/router/src/pages/post_list.rs b/examples/router/src/pages/post_list.rs index 7f6b21cd001..1f52e0a94a6 100644 --- a/examples/router/src/pages/post_list.rs +++ b/examples/router/src/pages/post_list.rs @@ -2,6 +2,7 @@ use crate::components::{pagination::Pagination, post_card::PostCard}; use crate::Route; use serde::{Deserialize, Serialize}; use yew::prelude::*; +use yew_router::prelude::*; const ITEMS_PER_PAGE: u64 = 10; const TOTAL_PAGES: u64 = u64::MAX / ITEMS_PER_PAGE; @@ -25,23 +26,27 @@ impl Component for PostList { Self } - fn update(&mut self, _ctx: &Context, msg: Self::Message) -> bool { + fn update(&mut self, ctx: &Context, msg: Self::Message) -> bool { match msg { Msg::ShowPage(page) => { - yew_router::push_route_with_query(Route::Posts, PageQuery { page }).unwrap(); + ctx.link() + .history() + .unwrap() + .push_with_query(Route::Posts, PageQuery { page }) + .unwrap(); true } } } fn view(&self, ctx: &Context) -> Html { - let page = self.current_page(); + let page = self.current_page(ctx); html! {

{ "Posts" }

{ "All of our quality writing in one place" }

- { self.view_posts() } + { self.view_posts(ctx) } Html { - let start_seed = (self.current_page() - 1) * ITEMS_PER_PAGE; + fn view_posts(&self, ctx: &Context) -> Html { + let start_seed = (self.current_page(ctx) - 1) * ITEMS_PER_PAGE; let mut cards = (0..ITEMS_PER_PAGE).map(|seed_offset| { html! {
  • @@ -77,9 +82,9 @@ impl PostList { } } - fn current_page(&self) -> u64 { - yew_router::parse_query::() - .map(|it| it.page) - .unwrap_or(1) + fn current_page(&self, ctx: &Context) -> u64 { + let location = ctx.link().location().unwrap(); + + location.query::().map(|it| it.page).unwrap_or(1) } } diff --git a/packages/yew-router-macro/src/routable_derive.rs b/packages/yew-router-macro/src/routable_derive.rs index 29aa8bcc880..d0d97efcf99 100644 --- a/packages/yew-router-macro/src/routable_derive.rs +++ b/packages/yew-router-macro/src/routable_derive.rs @@ -189,23 +189,25 @@ pub fn routable_derive_impl(input: Routable) -> TokenStream { let from_path = input.build_from_path(); let to_path = input.build_to_path(); - let not_found_route = match not_found_route { + let maybe_not_found_route = match not_found_route { Some(route) => quote! { ::std::option::Option::Some(Self::#route) }, None => quote! { ::std::option::Option::None }, }; - let cache_thread_local_ident = Ident::new( - &format!("__{}_ROUTER_CURRENT_ROUTE_CACHE", ident), - ident.span(), - ); - - quote! { - ::std::thread_local! { - #[doc(hidden)] - #[allow(non_upper_case_globals)] - static #cache_thread_local_ident: ::std::cell::RefCell<::std::option::Option<#ident>> = ::std::cell::RefCell::new(::std::option::Option::None); + let maybe_default = match not_found_route { + Some(route) => { + quote! { + impl ::std::default::Default for #ident { + fn default() -> Self { + Self::#route + } + } + } } + None => TokenStream::new(), + }; + quote! { #[automatically_derived] impl ::yew_router::Routable for #ident { #from_path @@ -216,32 +218,17 @@ pub fn routable_derive_impl(input: Routable) -> TokenStream { } fn not_found_route() -> ::std::option::Option { - #not_found_route - } - - fn current_route() -> ::std::option::Option { - #cache_thread_local_ident.with(|val| ::std::clone::Clone::clone(&*val.borrow())) + #maybe_not_found_route } fn recognize(pathname: &str) -> ::std::option::Option { ::std::thread_local! { static ROUTER: ::yew_router::__macro::Router = ::yew_router::__macro::build_router::<#ident>(); } - let route = ROUTER.with(|router| ::yew_router::__macro::recognize_with_router(router, pathname)); - { - let route = ::std::clone::Clone::clone(&route); - #cache_thread_local_ident.with(move |val| { - *val.borrow_mut() = route; - }); - } - route - } - - fn cleanup() { - #cache_thread_local_ident.with(move |val| { - *val.borrow_mut() = ::std::option::Option::None; - }); + ROUTER.with(|router| ::yew_router::__macro::recognize_with_router(router, pathname)) } } + + #maybe_default } } diff --git a/packages/yew-router/Cargo.toml b/packages/yew-router/Cargo.toml index 43e1f0f23bc..4c9e24eb3fc 100644 --- a/packages/yew-router/Cargo.toml +++ b/packages/yew-router/Cargo.toml @@ -19,10 +19,12 @@ yew-router-macro = { path = "../yew-router-macro" } wasm-bindgen = "0.2" js-sys = "0.3" -gloo = "0.3" +gloo = { version = "0.3", features = ["futures"] } route-recognizer = "0.3" serde = "1" serde_urlencoded = "0.7" +serde-wasm-bindgen = "0.3.1" +thiserror = "1.0.30" [dependencies.web-sys] version = "0.3" diff --git a/packages/yew-router/src/components/link.rs b/packages/yew-router/src/components/link.rs index da318b9cff5..b2b82c6251d 100644 --- a/packages/yew-router/src/components/link.rs +++ b/packages/yew-router/src/components/link.rs @@ -1,20 +1,25 @@ -use crate::{service, Routable}; use std::marker::PhantomData; + +use wasm_bindgen::UnwrapThrowExt; use yew::prelude::*; +use crate::history::History; +use crate::scope_ext::RouterScopeExt; +use crate::Routable; + /// Props for [`Link`] #[derive(Properties, Clone, PartialEq)] -pub struct LinkProps { +pub struct LinkProps { /// CSS classes to add to the anchor element (optional). #[prop_or_default] pub classes: Classes, /// Route that will be pushed when the anchor is clicked. - pub route: R, + pub to: R, pub children: Children, } /// A wrapper around `` tag to be used with [`Router`](crate::Router) -pub struct Link { +pub struct Link { _data: PhantomData, } @@ -22,7 +27,7 @@ pub enum Msg { OnClick, } -impl Component for Link { +impl Component for Link { type Message = Msg; type Properties = LinkProps; @@ -33,7 +38,10 @@ impl Component for Link { fn update(&mut self, ctx: &Context, msg: Self::Message) -> bool { match msg { Msg::OnClick => { - service::push_route(ctx.props().route.clone()); + ctx.link() + .history() + .expect_throw("failed to read history") + .push(ctx.props().to.clone()); false } } @@ -42,7 +50,7 @@ impl Component for Link { fn view(&self, ctx: &Context) -> Html { html! { { + /// Route that will be pushed when the component is rendered. + pub to: R, +} + +/// A component that will redirect to specified route when rendered. +#[function_component(Redirect)] +pub fn redirect(props: &RedirectProps) -> Html +where + R: Routable + 'static, +{ + let history = use_history().expect_throw("failed to read history."); + + let target_route = props.to.clone(); + use_effect(move || { + history.push(target_route.clone()); + + || {} + }); + + Html::default() +} diff --git a/packages/yew-router/src/history.rs b/packages/yew-router/src/history.rs new file mode 100644 index 00000000000..e75b7bc171b --- /dev/null +++ b/packages/yew-router/src/history.rs @@ -0,0 +1,684 @@ +//! A module that provides universal session history and location information. + +use std::borrow::Cow; +use std::cell::RefCell; +use std::rc::{Rc, Weak}; + +use gloo::events::EventListener; +use serde::de::DeserializeOwned; +use serde::Serialize; +use thiserror::Error; +use wasm_bindgen::{JsValue, UnwrapThrowExt}; +use yew::callback::Callback; +use yew::utils::window; + +use crate::utils::base_url; +use crate::Routable; + +/// A History Listener to manage callbacks registered on a [`History`]. +/// +/// This Listener has the same behaviour as the [`EventListener`] from [`gloo`] +/// that the underlying callback will be unregistered when the listener is dropped. +pub struct HistoryListener { + _listener: Rc>, +} + +#[derive(Error, Debug)] +pub enum HistoryError { + #[error("failed to serialize / deserialize state.")] + State(#[from] serde_wasm_bindgen::Error), + #[error("failed to serialize query.")] + QuerySer(#[from] serde_urlencoded::ser::Error), + #[error("failed to deserialize query.")] + QueryDe(#[from] serde_urlencoded::de::Error), +} + +pub type HistoryResult = std::result::Result; + +/// A trait to provide [`History`] access. +pub trait History: Clone + PartialEq { + type Location: Location + 'static; + + /// Returns the number of elements in [`History`]. + fn len(&self) -> usize; + + /// Returns true if the current [`History`] is empty. + fn is_empty(&self) -> bool { + self.len() == 0 + } + + /// Moves back 1 page in [`History`]. + fn back(&self) { + self.go(-1); + } + + /// Moves forward 1 page in [`History`]. + fn forward(&self) { + self.go(1); + } + + /// Loads a specific page in [`History`] with a `delta` relative to current page. + /// + /// See: + fn go(&self, delta: isize); + + /// Pushes a [`Routable`] entry with [`None`] being the state. + fn push(&self, route: impl Routable); + + /// Replaces the current history entry with provided [`Routable`] and [`None`] state. + fn replace(&self, route: impl Routable); + + /// Pushes a [`Routable`] entry with state. + /// + /// The implementation of state serialization differs between [`History`] types. + /// + /// For [`BrowserHistory`], it uses [`serde_wasm_bindgen`] where as other types uses + /// [`Any`](std::any::Any). + fn push_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static; + + /// Replaces the current history entry with provided [`Routable`] and state. + /// + /// The implementation of state serialization differs between [`History`] types. + /// + /// For [`BrowserHistory`], it uses [`serde_wasm_bindgen`] where as other types uses + /// [`Any`](std::any::Any). + fn replace_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static; + + /// Same as `.push()` but affix the queries to the end of the route. + fn push_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize; + + /// Same as `.replace()` but affix the queries to the end of the route. + fn replace_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize; + + /// Same as `.push_with_state()` but affix the queries to the end of the route. + fn push_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static; + + /// Same as `.replace_with_state()` but affix the queries to the end of the route. + fn replace_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static; + + /// Creates a Listener that will be notified when current state changes. + /// + /// This method returns a [`HistoryListener`] that will automatically unregister the callback + /// when dropped. + fn listen(&self, callback: CB) -> HistoryListener + where + CB: Fn() + 'static; + + /// Returns the associated [`Location`] of the current history. + fn location(&self) -> Self::Location; + + fn into_any_history(self) -> AnyHistory; + + /// Returns the State. + /// + /// The implementation differs between [`History`] type. + /// + /// For [`BrowserHistory`], it uses [`serde_wasm_bindgen`] where as other types uses + /// `downcast_ref()` on [`Any`](std::any::Any). + fn state(&self) -> HistoryResult + where + T: DeserializeOwned + 'static; +} + +/// A [`History`] that is implemented with [`web_sys::History`] that provides native browser +/// history and state access. +#[derive(Clone)] +pub struct BrowserHistory { + inner: web_sys::History, + callbacks: Rc>>>>, +} + +impl PartialEq for BrowserHistory { + fn eq(&self, _rhs: &Self) -> bool { + // All browser histories are created equal. + true + } +} + +impl History for BrowserHistory { + type Location = BrowserLocation; + + fn len(&self) -> usize { + self.inner.length().expect_throw("failed to get length.") as usize + } + + fn go(&self, delta: isize) { + self.inner + .go_with_delta(delta as i32) + .expect_throw("failed to call go.") + } + + fn push(&self, route: impl Routable) { + let url = Self::route_to_url(route); + self.inner + .push_state_with_url(&JsValue::NULL, "", Some(&url)) + .expect("failed to push state."); + + self.notify_callbacks(); + } + + fn replace(&self, route: impl Routable) { + let url = Self::route_to_url(route); + self.inner + .replace_state_with_url(&JsValue::NULL, "", Some(&url)) + .expect("failed to replace history."); + + self.notify_callbacks(); + } + + fn push_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static, + { + let url = Self::route_to_url(route); + let state = serde_wasm_bindgen::to_value(&state)?; + self.inner + .push_state_with_url(&state, "", Some(&url)) + .expect("failed to push state."); + + self.notify_callbacks(); + Ok(()) + } + + fn replace_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static, + { + let url = Self::route_to_url(route); + let state = serde_wasm_bindgen::to_value(&state)?; + self.inner + .replace_state_with_url(&state, "", Some(&url)) + .expect("failed to replace state."); + + self.notify_callbacks(); + Ok(()) + } + + fn push_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize, + { + let url = Self::route_to_url(route); + let query = serde_urlencoded::to_string(query)?; + self.inner + .push_state_with_url(&JsValue::NULL, "", Some(&format!("{}?{}", url, query))) + .expect("failed to push history."); + + self.notify_callbacks(); + Ok(()) + } + fn replace_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize, + { + let url = Self::route_to_url(route); + let query = serde_urlencoded::to_string(query)?; + self.inner + .replace_state_with_url(&JsValue::NULL, "", Some(&format!("{}?{}", url, query))) + .expect("failed to replace history."); + + self.notify_callbacks(); + Ok(()) + } + + fn push_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static, + { + let url = Self::route_to_url(route); + let query = serde_urlencoded::to_string(query)?; + let state = serde_wasm_bindgen::to_value(&state)?; + self.inner + .push_state_with_url(&state, "", Some(&format!("{}?{}", url, query))) + .expect("failed to push history."); + + self.notify_callbacks(); + Ok(()) + } + + fn replace_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static, + { + let url = Self::route_to_url(route); + let query = serde_urlencoded::to_string(query)?; + let state = serde_wasm_bindgen::to_value(&state)?; + self.inner + .replace_state_with_url(&state, "", Some(&format!("{}?{}", url, query))) + .expect("failed to replace history."); + + self.notify_callbacks(); + Ok(()) + } + + fn listen(&self, callback: CB) -> HistoryListener + where + CB: Fn() + 'static, + { + // Callbacks do not receive a copy of [`History`] to prevent reference cycle. + let cb = Rc::new(Callback::from(move |_| callback())); + + self.callbacks.borrow_mut().push(Rc::downgrade(&cb)); + + HistoryListener { _listener: cb } + } + + fn location(&self) -> Self::Location { + BrowserLocation::new(self.clone()) + } + + fn into_any_history(self) -> AnyHistory { + AnyHistory::Browser(self) + } + + fn state(&self) -> HistoryResult + where + T: DeserializeOwned + 'static, + { + serde_wasm_bindgen::from_value(self.inner.state().expect_throw("failed to read state.")) + .map_err(|e| e.into()) + } +} + +impl Default for BrowserHistory { + fn default() -> Self { + // We create browser history only once. + thread_local! { + static BROWSER_HISTORY: RefCell> = RefCell::default(); + static LISTENER: RefCell> = RefCell::default(); + } + + BROWSER_HISTORY.with(|m| { + let mut m = m.borrow_mut(); + + let history = match *m { + Some(ref m) => m.clone(), + None => { + let window = window(); + + let inner = window + .history() + .expect_throw("Failed to create browser history. Are you using a browser?"); + let callbacks = Rc::default(); + + let history = Self { inner, callbacks }; + + let history_clone = history.clone(); + + // Listens to popstate. + LISTENER.with(move |m| { + let mut listener = m.borrow_mut(); + + *listener = Some(EventListener::new(&window, "popstate", move |_| { + history_clone.notify_callbacks(); + })); + }); + + history + } + }; + + *m = Some(history.clone()); + + history + }) + } +} + +impl BrowserHistory { + /// Creates a new [`BrowserHistory`] + pub fn new() -> Self { + Self::default() + } + + fn route_to_url(route: impl Routable) -> Cow<'static, str> { + let base = base_url(); + let url = route.to_path(); + + let path = match base { + Some(base) => { + let path = format!("{}{}", base, url); + if path.is_empty() { + Cow::from("/") + } else { + path.into() + } + } + None => url.into(), + }; + + path + } + + fn notify_callbacks(&self) { + let callables = { + let mut callbacks_ref = self.callbacks.borrow_mut(); + + // Any gone weak references are removed when called. + let (callbacks, callbacks_weak) = callbacks_ref.iter().cloned().fold( + (Vec::new(), Vec::new()), + |(mut callbacks, mut callbacks_weak), m| { + if let Some(m_strong) = m.clone().upgrade() { + callbacks.push(m_strong); + callbacks_weak.push(m); + } + + (callbacks, callbacks_weak) + }, + ); + + *callbacks_ref = callbacks_weak; + + callbacks + }; + + for callback in callables { + callback.emit(()) + } + } +} + +/// A trait to to provide [`Location`] information. +pub trait Location: Clone + PartialEq { + type History: History + 'static; + + /// Returns the `pathname` on the [`Location`] struct. + fn pathname(&self) -> String; + + /// Returns the queries of current URL in [`String`] + fn search(&self) -> String; + + /// Returns the queries of current URL parsed as `T`. + fn query(&self) -> HistoryResult + where + T: DeserializeOwned; + + /// Returns the hash fragment of current URL. + fn hash(&self) -> String; + + /// Returns current route or `None` if none matched. + fn route(&self) -> Option + where + R: Routable; +} + +/// The [`Location`] type for [`BrowserHistory`]. +/// +/// Most functionality of this type is provided by [`web_sys::Location`]. +/// +/// This type also provides additional methods that are unique to Browsers and are not available in [`Location`]. +/// +/// This types is read-only as most setters on `window.location` would cause a reload. +#[derive(Clone)] +pub struct BrowserLocation { + inner: web_sys::Location, + _history: BrowserHistory, +} + +impl PartialEq for BrowserLocation { + fn eq(&self, rhs: &Self) -> bool { + self._history == rhs._history + } +} + +impl Location for BrowserLocation { + type History = BrowserHistory; + + fn pathname(&self) -> String { + self.inner + .pathname() + .expect_throw("failed to get pathname.") + } + + fn search(&self) -> String { + self.inner.search().expect_throw("failed to get search.") + } + + fn query(&self) -> HistoryResult + where + T: DeserializeOwned, + { + let query = self.search(); + serde_urlencoded::from_str(query.strip_prefix('?').unwrap_or("")).map_err(|e| e.into()) + } + + fn hash(&self) -> String { + self.inner.hash().expect_throw("failed to get hash.") + } + + fn route(&self) -> Option + where + R: Routable, + { + R::recognize(&self.pathname()) + } +} + +impl BrowserLocation { + fn new(history: BrowserHistory) -> Self { + Self { + inner: window().location(), + _history: history, + } + } + + /// Returns the `href` of current [`Location`]. + pub fn href(&self) -> String { + self.inner.href().expect_throw("failed to get href.") + } + + /// Returns the `origin` of current [`Location`]. + pub fn origin(&self) -> String { + self.inner.origin().expect_throw("failed to get origin.") + } + + /// Returns the `protocol` property of current [`Location`]. + pub fn protocol(&self) -> String { + self.inner + .protocol() + .expect_throw("failed to get protocol.") + } + + /// Returns the `host` of current [`Location`]. + pub fn host(&self) -> String { + self.inner.host().expect_throw("failed to get host.") + } + + /// Returns the `hostname` of current [`Location`]. + pub fn hostname(&self) -> String { + self.inner + .hostname() + .expect_throw("failed to get hostname.") + } +} + +/// A [`History`] that is always available under a [`Router`](crate::Router). +#[derive(Clone, PartialEq)] +pub enum AnyHistory { + Browser(BrowserHistory), +} + +/// The [`Location`] for [`AnyHistory`] +#[derive(Clone, PartialEq)] +pub enum AnyLocation { + Browser(BrowserLocation), +} + +impl History for AnyHistory { + type Location = AnyLocation; + + fn len(&self) -> usize { + let Self::Browser(self_) = self; + self_.len() + } + + fn go(&self, delta: isize) { + let Self::Browser(self_) = self; + self_.go(delta) + } + + fn push(&self, route: impl Routable) { + let Self::Browser(self_) = self; + self_.push(route) + } + + fn replace(&self, route: impl Routable) { + let Self::Browser(self_) = self; + self_.replace(route) + } + + fn push_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static, + { + let Self::Browser(self_) = self; + self_.push_with_state(route, state) + } + + fn replace_with_state(&self, route: impl Routable, state: T) -> HistoryResult<()> + where + T: Serialize + 'static, + { + let Self::Browser(self_) = self; + self_.replace_with_state(route, state) + } + + fn push_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize, + { + let Self::Browser(self_) = self; + self_.push_with_query(route, query) + } + fn replace_with_query(&self, route: impl Routable, query: Q) -> HistoryResult<()> + where + Q: Serialize, + { + let Self::Browser(self_) = self; + self_.replace_with_query(route, query) + } + + fn push_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static, + { + let Self::Browser(self_) = self; + self_.push_with_query_and_state(route, query, state) + } + + fn replace_with_query_and_state( + &self, + route: impl Routable, + query: Q, + state: T, + ) -> HistoryResult<()> + where + Q: Serialize, + T: Serialize + 'static, + { + let Self::Browser(self_) = self; + self_.replace_with_query_and_state(route, query, state) + } + + fn listen(&self, callback: CB) -> HistoryListener + where + CB: Fn() + 'static, + { + let Self::Browser(self_) = self; + self_.listen(callback) + } + + fn location(&self) -> Self::Location { + let Self::Browser(self_) = self; + AnyLocation::Browser(self_.location()) + } + + fn into_any_history(self) -> AnyHistory { + self + } + + fn state(&self) -> HistoryResult + where + T: DeserializeOwned + 'static, + { + let Self::Browser(self_) = self; + self_.state() + } +} + +impl Location for AnyLocation { + type History = AnyHistory; + + fn pathname(&self) -> String { + let Self::Browser(self_) = self; + self_.pathname() + } + + fn search(&self) -> String { + let Self::Browser(self_) = self; + self_.search() + } + + fn query(&self) -> HistoryResult + where + T: DeserializeOwned, + { + let Self::Browser(self_) = self; + self_.query() + } + + fn hash(&self) -> String { + let Self::Browser(self_) = self; + self_.hash() + } + + fn route(&self) -> Option + where + R: Routable, + { + let Self::Browser(self_) = self; + self_.route() + } +} diff --git a/packages/yew-router/src/hooks.rs b/packages/yew-router/src/hooks.rs new file mode 100644 index 00000000000..d297f156f0d --- /dev/null +++ b/packages/yew-router/src/hooks.rs @@ -0,0 +1,32 @@ +//! Hooks to access router state and navigate between pages. + +use crate::history::*; +use crate::routable::Routable; +use crate::router::RouterState; + +use yew::prelude::*; + +/// A hook to access the [`AnyHistory`] type. +pub fn use_history() -> Option { + let history_state = use_context::()?; + + Some(history_state.history()) +} + +/// A hook to access the [`AnyLocation`] type. +pub fn use_location() -> Option { + Some(use_history()?.location()) +} + +/// A hook to access the current route. +/// +/// This hook will return [`None`] if there's no available location or none of the routes match. +/// +/// If your `Routable` has a `#[not_found]` route, you can use `.unwrap_or_default()` instead of +/// `.unwrap()` to unwrap. +pub fn use_route() -> Option +where + R: Routable + 'static, +{ + use_location()?.route::() +} diff --git a/packages/yew-router/src/lib.rs b/packages/yew-router/src/lib.rs index 80d64dac708..11e85f508bb 100644 --- a/packages/yew-router/src/lib.rs +++ b/packages/yew-router/src/lib.rs @@ -4,9 +4,9 @@ //! # Usage //! //! ```rust -//! # use yew::prelude::*; -//! # use yew::functional::*; -//! # use yew_router::prelude::*; +//! use yew::prelude::*; +//! use yew::functional::*; +//! use yew_router::prelude::*; //! //! #[derive(Debug, Clone, Copy, PartialEq, Routable)] //! enum Route { @@ -19,22 +19,33 @@ //! NotFound, //! } //! -//! # #[function_component(Main)] -//! # fn app() -> Html { -//! html! { -//! render={Router::render(switch)} /> +//! #[function_component(Secure)] +//! fn secure() -> Html { +//! let history = use_history().unwrap(); +//! +//! let onclick_callback = Callback::from(move |_| history.push(Route::Home)); +//! html! { +//!
    +//!

    { "Secure" }

    +//! +//!
    +//! } +//! } +//! +//! #[function_component(Main)] +//! fn app() -> Html { +//! html! { +//! +//! render={Switch::render(switch)} /> +//! +//! } //! } -//! # } //! //! fn switch(routes: &Route) -> Html { -//! let onclick_callback = Callback::from(|_| yew_router::push_route(Route::Home)); //! match routes { //! Route::Home => html! {

    { "Home" }

    }, //! Route::Secure => html! { -//!
    -//!

    { "Secure" }

    -//! -//!
    +//! //! }, //! Route::NotFound => html! {

    { "404" }

    }, //! } @@ -43,15 +54,13 @@ //! //! # Internals //! -//! The router keeps its own internal state which is used to store the current route and its associated data. -//! This allows the [Router] to be operated using the [service] with an API that -//! isn't cumbersome to use. +//! The router registers itself as a context provider and makes session history and location information +//! available via [`hooks`] or [`RouterScopeExt`](scope_ext::RouterScopeExt). //! //! # State //! -//! The browser history API allows users to state associated with the route. This crate does -//! not expose or make use of it. It is instead recommended that a state management library like -//! [yewdux](https://github.com/intendednull/yewdux) be used. +//! The [`history`] API has a way access / store state associated with session history. Please +//! consule [`history.state()`](history::History::state) for detailed usage. extern crate self as yew_router; @@ -59,23 +68,30 @@ extern crate self as yew_router; #[path = "macro_helpers.rs"] pub mod __macro; pub mod components; +pub mod history; +pub mod hooks; mod routable; pub mod router; -mod service; -pub(crate) mod utils; - -pub use service::*; +pub mod scope_ext; +pub mod switch; +pub mod utils; -pub use routable::Routable; -pub use router::{RenderFn, Router}; +pub use routable::{AnyRoute, Routable}; +pub use router::{BrowserRouter, Router}; +pub use switch::{RenderFn, Switch}; pub mod prelude { //! Prelude module to be imported when working with `yew-router`. //! //! This module re-exports the frequently used types from the crate. - pub use crate::components::Link; + pub use crate::components::{Link, Redirect}; + pub use crate::history::*; + pub use crate::hooks::*; + pub use crate::scope_ext::RouterScopeExt; #[doc(no_inline)] pub use crate::Routable; - pub use crate::Router; + pub use crate::{BrowserRouter, Router}; + + pub use crate::Switch; } diff --git a/packages/yew-router/src/routable.rs b/packages/yew-router/src/routable.rs index f8826c4bc36..bd3da649af9 100644 --- a/packages/yew-router/src/routable.rs +++ b/packages/yew-router/src/routable.rs @@ -13,7 +13,7 @@ pub use yew_router_macro::Routable; /// /// The functions exposed by this trait are **not** supposed to be consumed directly. Instead use /// the functions exposed at the [crate's root][crate] to perform operations with the router. -pub trait Routable: Sized + Clone { +pub trait Routable: Clone + PartialEq { /// Converts path to an instance of the routes enum. fn from_path(path: &str, params: &HashMap<&str, &str>) -> Option; @@ -26,14 +26,56 @@ pub trait Routable: Sized + Clone { /// The route to redirect to on 404 fn not_found_route() -> Option; - /// The current route - /// - /// This is the cached result of [`recognize`] - fn current_route() -> Option; - /// Match a route based on the path fn recognize(pathname: &str) -> Option; +} + +/// A special route that accepts any route. +/// +/// This can be used with [`History`](crate::History) and [`Location`](crate::Location) +/// when the type of [`Routable`] is unknown. +#[derive(Debug, Clone, PartialEq)] +pub struct AnyRoute { + path: String, +} + +impl Routable for AnyRoute { + fn from_path(path: &str, params: &HashMap<&str, &str>) -> Option { + // No params allowed. + if params.is_empty() { + Some(Self { + path: path.to_string(), + }) + } else { + None + } + } + + fn to_path(&self) -> String { + self.path.to_string() + } + + fn routes() -> Vec<&'static str> { + vec!["/*path"] + } + + fn not_found_route() -> Option { + Some(Self { + path: "/404".to_string(), + }) + } + + fn recognize(pathname: &str) -> Option { + Some(Self { + path: pathname.to_string(), + }) + } +} - /// Called when [`Router`](crate::Router) is destroyed. - fn cleanup() {} +impl AnyRoute { + pub fn new>(pathname: S) -> Self { + Self { + path: pathname.into(), + } + } } diff --git a/packages/yew-router/src/router.rs b/packages/yew-router/src/router.rs index 059171f5d29..785ad6d36b3 100644 --- a/packages/yew-router/src/router.rs +++ b/packages/yew-router/src/router.rs @@ -1,55 +1,32 @@ //! Router Component. -use crate::Routable; -use gloo::{console, events::EventListener}; -use std::marker::PhantomData; -use std::rc::Rc; +use crate::prelude::*; use yew::prelude::*; -/// Wraps `Rc` around `Fn` so it can be passed as a prop. -pub struct RenderFn(Rc Html>); - -impl RenderFn { - /// Creates a new [`RenderFn`] - /// - /// It is recommended that you use [`Router::render`] instead - pub fn new(value: impl Fn(&R) -> Html + 'static) -> Self { - Self(Rc::new(value)) - } -} - -impl Clone for RenderFn { - fn clone(&self) -> Self { - Self(Rc::clone(&self.0)) - } -} - -impl PartialEq for RenderFn { - fn eq(&self, other: &Self) -> bool { - // https://github.com/rust-lang/rust-clippy/issues/6524 - #[allow(clippy::vtable_address_comparisons)] - Rc::ptr_eq(&self.0, &other.0) - } +/// Props for [`Router`]. +#[derive(Properties, PartialEq, Clone)] +pub struct RouterProps { + pub children: Children, + pub history: AnyHistory, } -/// Props for [`Router`] -#[derive(Properties)] -pub struct RouterProps { - /// Callback which returns [`Html`] to be rendered for the current route. - pub render: RenderFn, +/// A context for [`Router`] +#[derive(Clone)] +pub(crate) struct RouterState { + history: AnyHistory, + // Counter to force update. + ctr: u32, } -impl Clone for RouterProps { - fn clone(&self) -> Self { - Self { - render: self.render.clone(), - } +impl RouterState { + pub fn history(&self) -> AnyHistory { + self.history.clone() } } -impl PartialEq for RouterProps { - fn eq(&self, other: &Self) -> bool { - self.render.eq(&other.render) +impl PartialEq for RouterState { + fn eq(&self, rhs: &Self) -> bool { + self.ctr == rhs.ctr } } @@ -58,70 +35,93 @@ pub enum Msg { ReRender, } -/// The router component. +/// The Router component. +/// +/// This provides [`History`] context to its children and switches. /// -/// When a route can't be matched, it looks for the route with `not_found` attribute. -/// If such a route is provided, it redirects to the specified route. -/// Otherwise `html! {}` is rendered and a message is logged to console -/// stating that no route can be matched. -/// See the [crate level document][crate] for more information. -pub struct Router { - #[allow(dead_code)] // only exists to drop listener on component drop - route_listener: EventListener, - _data: PhantomData, +/// You only need one `` for each application. +pub struct Router { + _listener: HistoryListener, + history: AnyHistory, + ctr: u32, } -impl Component for Router -where - R: Routable + 'static, -{ +impl Component for Router { type Message = Msg; - type Properties = RouterProps; + type Properties = RouterProps; fn create(ctx: &Context) -> Self { let link = ctx.link().clone(); - let route_listener = EventListener::new(&yew::utils::window(), "popstate", move |_| { - link.send_message(Msg::ReRender) - }); + + let listener = ctx + .props() + .history + .listen(move || link.send_message(Msg::ReRender)); Self { - route_listener, - _data: PhantomData, + _listener: listener, + history: ctx.props().history.clone(), + ctr: 0, } } fn update(&mut self, _ctx: &Context, msg: Self::Message) -> bool { match msg { - Msg::ReRender => true, + Msg::ReRender => { + self.ctr += 1; + true + } } } - fn view(&self, ctx: &Context) -> Html { - let pathname = yew::utils::window().location().pathname().unwrap(); - let route = R::recognize(&pathname); - - match route { - Some(route) => (ctx.props().render.0)(&route), - None => { - console::warn!("no route matched"); - html! {} - } + fn changed(&mut self, ctx: &Context) -> bool { + let link = ctx.link().clone(); + + if self.history != ctx.props().history { + self._listener = ctx + .props() + .history + .listen(move || link.send_message(Msg::ReRender)); + + self.history = ctx.props().history.clone(); + + true + } else { + false } } - fn destroy(&mut self, _ctx: &Context) { - R::cleanup(); + fn view(&self, ctx: &Context) -> Html { + let state = RouterState { + history: self.history.clone().into_any_history(), + ctr: self.ctr, + }; + + html! { + context={state}> + {ctx.props().children.clone()} + > + } } } -impl Router -where - R: Routable + Clone + 'static, -{ - pub fn render(func: F) -> RenderFn - where - F: Fn(&R) -> Html + 'static, - { - RenderFn::new(func) +#[derive(Properties, PartialEq, Clone)] +pub struct BrowserRouterProps { + pub children: Children, +} + +/// A [`Router`] thats provides history via [`BrowserHistory`]. +/// +/// This Router uses browser's native history to manipulate session history +/// and uses regular URL as route. +#[function_component(BrowserRouter)] +pub fn browser_router(props: &BrowserRouterProps) -> Html { + let history = use_state(BrowserHistory::new); + let children = props.children.clone(); + + html! { + + {children} + } } diff --git a/packages/yew-router/src/scope_ext.rs b/packages/yew-router/src/scope_ext.rs new file mode 100644 index 00000000000..da114cfb572 --- /dev/null +++ b/packages/yew-router/src/scope_ext.rs @@ -0,0 +1,110 @@ +use crate::history::*; +use crate::routable::Routable; +use crate::router::RouterState; + +use yew::context::ContextHandle; +use yew::prelude::*; + +/// A [`ContextHandle`] for [`add_history_listener`](RouterScopeExt::add_history_listener). +pub struct HistoryHandle { + _inner: ContextHandle, +} + +/// An extension to [`Scope`](yew::html::Scope) that provides session history information. +/// +/// You can access on `ctx.link()` +/// +/// # Example +/// +/// Below is an example of the implementation of the [`Link`](crate::components::Link) component. +/// +/// ``` +/// # use std::marker::PhantomData; +/// # use wasm_bindgen::UnwrapThrowExt; +/// # use yew::prelude::*; +/// # use yew_router::prelude::*; +/// # use yew_router::components::{LinkProps, Msg}; +/// # +/// # pub struct Link { +/// # _data: PhantomData, +/// # } +/// # +/// impl Component for Link { +/// type Message = Msg; +/// type Properties = LinkProps; +/// +/// fn create(_ctx: &Context) -> Self { +/// Self { _data: PhantomData } +/// } +/// +/// fn update(&mut self, ctx: &Context, msg: Self::Message) -> bool { +/// match msg { +/// Msg::OnClick => { +/// ctx.link() +/// .history() +/// .expect_throw("failed to read history") +/// .push(ctx.props().to.clone()); +/// false +/// } +/// } +/// } +/// +/// fn view(&self, ctx: &Context) -> Html { +/// html! { +///     +/// { ctx.props().children.clone() } +/// +/// } +/// } +/// } +/// ``` +pub trait RouterScopeExt { + /// Returns current [`History`]. + fn history(&self) -> Option; + + /// Returns current [`Location`]. + fn location(&self) -> Option; + + /// Returns current route. + fn route(&self) -> Option + where + R: Routable + 'static; + + /// Adds a listener that gets notified when history changes. + /// + /// # Note + /// + /// [`HistoryHandle`] works like a normal [`ContextHandle`] and it unregisters the callback + /// when the handle is dropped. You need to keep the handle for as long as you need the + /// callback. + fn add_history_listener(&self, cb: Callback) -> Option; +} + +impl RouterScopeExt for yew::html::Scope { + fn history(&self) -> Option { + self.context::(Callback::from(|_| {})) + .map(|(m, _)| m.history()) + } + + fn location(&self) -> Option { + self.history().map(|m| m.location()) + } + + fn route(&self) -> Option + where + R: Routable + 'static, + { + self.location()?.route() + } + + fn add_history_listener(&self, cb: Callback) -> Option { + self.context::(Callback::from(move |m: RouterState| cb.emit(m.history()))) + .map(|(_, m)| HistoryHandle { _inner: m }) + } +} diff --git a/packages/yew-router/src/service.rs b/packages/yew-router/src/service.rs deleted file mode 100644 index 1c39bf29410..00000000000 --- a/packages/yew-router/src/service.rs +++ /dev/null @@ -1,127 +0,0 @@ -use crate::utils::base_url; -use crate::Routable; -use gloo::events::EventListener; -use serde::{Deserialize, Serialize}; -use wasm_bindgen::JsValue; -use web_sys::Event; -use yew::Callback; - -/// Navigate to a specific route, pushing the new route onto the -/// user's history stack. -pub fn push_route(route: impl Routable) { - update_route_impl(route.to_path(), true) -} - -/// Navigate to a specific route, replacing the current route on the -/// user's history stack. -pub fn replace_route(route: impl Routable) { - update_route_impl(route.to_path(), false) -} - -/// Navigate to a specific route with query parameters, pushing the -/// new route onto the user's history stack. -/// -/// This should be used in cases where [`Link`](crate::prelude::Link) is insufficient. -pub fn push_route_with_query( - route: impl Routable, - query: S, -) -> Result<(), serde_urlencoded::ser::Error> -where - S: Serialize, -{ - update_route_with_query_impl(route, query, true) -} - -/// Navigate to a specific route with query parameters, replacing the -/// current route on the user's history stack. -pub fn replace_route_with_query( - route: impl Routable, - query: S, -) -> Result<(), serde_urlencoded::ser::Error> -where - S: Serialize, -{ - update_route_with_query_impl(route, query, false) -} - -fn update_route_with_query_impl( - route: impl Routable, - query: S, - push: bool, -) -> Result<(), serde_urlencoded::ser::Error> -where - S: Serialize, -{ - let mut url = route.to_path(); - let query = serde_urlencoded::to_string(query)?; - if !query.is_empty() { - url.push_str(&format!("?{}", query)); - } - - update_route_impl(url, push); - - Ok(()) -} - -fn update_route_impl(url: String, push: bool) { - let history = yew::utils::window().history().expect("no history"); - let base = base_url(); - let path = match base { - Some(base) => { - let path = format!("{}{}", base, url); - if path.is_empty() { - "/".to_string() - } else { - path - } - } - None => url, - }; - - if push { - history - .push_state_with_url(&JsValue::NULL, "", Some(&path)) - .expect("push history"); - } else { - history - .replace_state_with_url(&JsValue::NULL, "", Some(&path)) - .expect("replace history"); - } - let event = Event::new("popstate").unwrap(); - yew::utils::window() - .dispatch_event(&event) - .expect("dispatch"); -} - -pub fn parse_query() -> Result -where - T: for<'de> Deserialize<'de>, -{ - let query = yew::utils::document().location().unwrap().search().unwrap(); - serde_urlencoded::from_str(query.strip_prefix('?').unwrap_or("")) -} - -pub fn current_route() -> Option { - R::current_route() -} - -/// Handle for the router's path event listener -pub struct RouteListener { - // this exists so listener is dropped when handle is dropped - #[allow(dead_code)] - listener: EventListener, -} - -/// Adds a listener which is called when the current route is changed. -/// -/// The callback receives `Option` so it can handle the error case itself. -pub fn attach_route_listener(callback: Callback>) -> RouteListener -where - R: Routable + 'static, -{ - let listener = EventListener::new(&yew::utils::window(), "popstate", move |_| { - callback.emit(current_route()) - }); - - RouteListener { listener } -} diff --git a/packages/yew-router/src/switch.rs b/packages/yew-router/src/switch.rs new file mode 100644 index 00000000000..d11d65fe41c --- /dev/null +++ b/packages/yew-router/src/switch.rs @@ -0,0 +1,120 @@ +//! The [`Switch`] Component. + +use std::marker::PhantomData; +use std::rc::Rc; + +use gloo::console; +use wasm_bindgen::UnwrapThrowExt; +use yew::prelude::*; + +use crate::prelude::*; +use crate::scope_ext::HistoryHandle; + +/// Wraps `Rc` around `Fn` so it can be passed as a prop. +pub struct RenderFn(Rc Html>); + +impl RenderFn { + /// Creates a new [`RenderFn`] + /// + /// It is recommended that you use [`Switch::render`] instead + pub fn new(value: impl Fn(&R) -> Html + 'static) -> Self { + Self(Rc::new(value)) + } + pub fn render(&self, route: &R) -> Html { + (self.0)(route) + } +} + +impl Clone for RenderFn { + fn clone(&self) -> Self { + Self(Rc::clone(&self.0)) + } +} + +impl PartialEq for RenderFn { + fn eq(&self, other: &Self) -> bool { + // https://github.com/rust-lang/rust-clippy/issues/6524 + #[allow(clippy::vtable_address_comparisons)] + Rc::ptr_eq(&self.0, &other.0) + } +} + +/// Props for [`Switch`] +#[derive(Properties, PartialEq, Clone)] +pub struct SwitchProps +where + R: Routable, +{ + /// Callback which returns [`Html`] to be rendered for the current route. + pub render: RenderFn, +} + +#[doc(hidden)] +pub enum Msg { + ReRender, +} + +/// A Switch that dispatches route among variants of a [`Routable`]. +/// +/// When a route can't be matched, it looks for the route with `not_found` attribute. +/// If such a route is provided, it redirects to the specified route. +/// Otherwise `html! {}` is rendered and a message is logged to console +/// stating that no route can be matched. +/// See the [crate level document][crate] for more information. +pub struct Switch { + _listener: HistoryHandle, + _phantom: PhantomData, +} + +impl Component for Switch +where + R: Routable + 'static, +{ + type Message = Msg; + type Properties = SwitchProps; + + fn create(ctx: &Context) -> Self { + let link = ctx.link(); + let listener = link + .add_history_listener(link.callback(move |_| Msg::ReRender)) + .expect_throw("failed to create history handle. Do you have a router registered?"); + + Self { + _listener: listener, + _phantom: PhantomData, + } + } + + fn update(&mut self, _ctx: &Context, msg: Self::Message) -> bool { + match msg { + Msg::ReRender => true, + } + } + + fn view(&self, ctx: &Context) -> Html { + let route = ctx.link().location().and_then(|m| m.route::()); + + let children = match &route { + Some(ref route) => (ctx.props().render.0)(route), + None => { + console::warn!("no route matched"); + Html::default() + } + }; + + html! {<>{children}} + } +} + +impl Switch +where + R: Routable + Clone + 'static, +{ + /// Creates a [`RenderFn`]. + pub fn render(func: F) -> RenderFn + where + F: Fn(&R) -> Html + 'static, + { + RenderFn::new(func) + } +} diff --git a/packages/yew-router/src/utils.rs b/packages/yew-router/src/utils.rs index e6b294be5ef..e8db60032a3 100644 --- a/packages/yew-router/src/utils.rs +++ b/packages/yew-router/src/utils.rs @@ -43,11 +43,8 @@ pub fn fetch_base_url() -> Option { #[cfg(test)] mod tests { - use serde::Serialize; - use std::collections::HashMap; use wasm_bindgen_test::wasm_bindgen_test as test; use yew::utils::*; - use yew_router::parse_query; use yew_router::prelude::*; use yew_router::utils::*; @@ -81,34 +78,4 @@ mod tests { .set_inner_html(r#""#); assert_eq!(fetch_base_url(), Some("/base".to_string())); } - - #[derive(Serialize, Clone)] - struct QueryParams { - foo: String, - bar: u32, - } - - #[test] - fn test_get_query_params() { - assert_eq!( - parse_query::>().unwrap(), - HashMap::new() - ); - - let query = QueryParams { - foo: "test".to_string(), - bar: 69, - }; - - yew_router::push_route_with_query(Routes::Home, query).unwrap(); - - let params: HashMap = parse_query().unwrap(); - - assert_eq!(params, { - let mut map = HashMap::new(); - map.insert("foo".to_string(), "test".to_string()); - map.insert("bar".to_string(), "69".to_string()); - map - }); - } } diff --git a/packages/yew-router/tests/history.rs b/packages/yew-router/tests/history.rs new file mode 100644 index 00000000000..75daa2384a6 --- /dev/null +++ b/packages/yew-router/tests/history.rs @@ -0,0 +1,79 @@ +use gloo::timers::future::TimeoutFuture; +use wasm_bindgen_test::{wasm_bindgen_test as test, wasm_bindgen_test_configure}; +use yew_router::prelude::*; +use yew_router::AnyRoute; + +use serde::{Deserialize, Serialize}; + +wasm_bindgen_test_configure!(run_in_browser); + +#[derive(Debug, Serialize, Deserialize, PartialEq)] +struct Query { + a: String, + b: u64, +} + +#[derive(Debug, Serialize, Deserialize, PartialEq)] +struct State { + i: String, + ii: u64, +} + +#[test] +async fn history_works() { + let history = BrowserHistory::new(); + assert_eq!(history.location().pathname(), "/"); + + history.push(AnyRoute::new("/path-a")); + assert_eq!(history.location().pathname(), "/path-a"); + + history.replace(AnyRoute::new("/path-b")); + assert_eq!(history.location().pathname(), "/path-b"); + + history.back(); + TimeoutFuture::new(100).await; + assert_eq!(history.location().pathname(), "/"); + + history.forward(); + TimeoutFuture::new(100).await; + assert_eq!(history.location().pathname(), "/path-b"); + + history + .push_with_query( + AnyRoute::new("/path"), + Query { + a: "something".to_string(), + b: 123, + }, + ) + .unwrap(); + + assert_eq!(history.location().pathname(), "/path"); + assert_eq!(history.location().search(), "?a=something&b=123"); + assert_eq!( + history.location().query::().unwrap(), + Query { + a: "something".to_string(), + b: 123, + } + ); + + history + .push_with_state( + AnyRoute::new("/path-c"), + State { + i: "something".to_string(), + ii: 123, + }, + ) + .unwrap(); + + assert_eq!(history.location().pathname(), "/path-c"); + assert_eq!( + history.state::().unwrap(), + State { + i: "something".to_string(), + ii: 123, + } + ); +} diff --git a/packages/yew-router/tests/router.rs b/packages/yew-router/tests/router.rs index 0db3df24226..494a0aaf26c 100644 --- a/packages/yew-router/tests/router.rs +++ b/packages/yew-router/tests/router.rs @@ -33,35 +33,43 @@ struct NoProps { fn no(props: &NoProps) -> Html { let route = props.id.to_string(); + let location = use_location().unwrap(); + html! { <>
    { route }
    -
    { yew_router::parse_query::().unwrap().foo }
    +
    { location.query::().unwrap().foo }
    } } #[function_component(Comp)] fn component() -> Html { - let switch = Router::render(|routes| { - let replace_route = Callback::from(|_| { - yew_router::replace_route_with_query( - Routes::No { id: 2 }, - Query { - foo: "bar".to_string(), - }, - ) - .unwrap(); + let history = use_history().unwrap(); + + let switch = Switch::render(move |routes| { + let history_clone = history.clone(); + let replace_route = Callback::from(move |_| { + history_clone + .replace_with_query( + Routes::No { id: 2 }, + Query { + foo: "bar".to_string(), + }, + ) + .unwrap(); }); - let push_route = Callback::from(|_| { - yew_router::push_route_with_query( - Routes::No { id: 3 }, - Query { - foo: "baz".to_string(), - }, - ) - .unwrap(); + let history_clone = history.clone(); + let push_route = Callback::from(move |_| { + history_clone + .push_with_query( + Routes::No { id: 3 }, + Query { + foo: "baz".to_string(), + }, + ) + .unwrap(); }); match routes { @@ -82,8 +90,16 @@ fn component() -> Html { }); html! { - render={switch}> - > + render={switch} /> + } +} + +#[function_component(Root)] +fn root() -> Html { + html! { + + + } } @@ -97,7 +113,7 @@ fn component() -> Html { // - 404 redirects #[test] fn router_works() { - yew::start_app_in_element::(yew::utils::document().get_element_by_id("output").unwrap()); + yew::start_app_in_element::(yew::utils::document().get_element_by_id("output").unwrap()); assert_eq!("Home", obtain_result_by_id("result")); diff --git a/website/docs/concepts/router.md b/website/docs/concepts/router.md index 632ac15d850..1dd6314b834 100644 --- a/website/docs/concepts/router.md +++ b/website/docs/concepts/router.md @@ -5,21 +5,20 @@ description: "Yew's official router" [The router on crates.io](https://crates.io/crates/yew-router) -Routers in Single Page Applications (SPA) handle displaying different pages depending on what the URL is. -Instead of the default behavior of requesting a different remote resource when a link is clicked, -the router instead sets the URL locally to point to a valid route in your application. +Routers in Single Page Applications (SPA) handle displaying different pages depending on what the URL is. +Instead of the default behavior of requesting a different remote resource when a link is clicked, +the router instead sets the URL locally to point to a valid route in your application. The router then detects this change and then decides what to render. ## Usage -The Router component. It takes in a callback and renders the HTML based on the returned value of the callback. It is usually placed -at the top of the application. +You start by defining a `Route`. -Routes are defined by an `enum` which derives `Routable`. This enum must be `Clone + Sized. +Routes are defined as an `enum` which derives `Routable`. This enum must be `Clone + PartialEq`. ```rust -use yew_router::Routable; +use yew_router::prelude::*; -#[derive(Clone, Routable)] +#[derive(Clone, Routable, PartialEq)] enum Route { #[at("/")] Home, @@ -31,19 +30,16 @@ enum Route { } ``` -The `Router` component takes the `Routable` enum as its type parameter, finds the first variant whose path matches the -browser's current URL and passes it to the `render` callback. The callback then decides what to render. -In case no path is matched, the router navigates to the path with `not_found` attribute. If no route is specified, +A `Route` is paired with a `` component, which finds the first variant whose path matches the +browser's current URL and passes it to the `render` callback. The callback then decides what to render. +In case no path is matched, the router navigates to the path with `not_found` attribute. If no route is specified, nothing is rendered, and a message is logged to console stating that no route was matched. -`yew_router::current_route` is used to programmatically obtain the current route. -`yew_router::attach_route_listener` is used to attach a listener which is called every time route is changed. - ```rust -use yew_router::{Router, Routable}; -use yew::{Callback, function_component, html, Html}; +use yew_router::prelude::*;; +use yew::prelude::*; -#[derive(Clone, Routable)] +#[derive(Clone, Routable, PartialEq)] enum Route { #[at("/")] Home, @@ -54,45 +50,130 @@ enum Route { NotFound, } +#[function_component(Secure)] +fn secure() -> Html { + let history = use_history().unwrap(); + + let onclick_callback = Callback::from(move |_| history.push(Route::Home)); + html! { +
    +

    { "Secure" }

    + +
    + } +} + +fn switch(routes: &Route) -> Html { + match routes { + Route::Home => html! {

    { "Home" }

    }, + Route::Secure => html! { + + }, + Route::NotFound => html! {

    { "404" }

    }, + } +} + #[function_component(Main)] fn app() -> Html { html! { - render={Router::render(switch)} /> + render={Switch::render(switch)} /> } } +``` + +Finally, you need to register the `` component as a context. +`` provides session history information to its children. + +When using `yew-router` in browser environment, `` is +recommended. -fn switch(route: &Route) -> Html { - match route { +```rust +use yew_router::prelude::*;; +use yew::prelude::*; + +#[derive(Clone, Routable, PartialEq)] +enum Route { + #[at("/")] + Home, + #[at("/secure")] + Secure, + #[not_found] + #[at("/404")] + NotFound, +} + +#[function_component(Secure)] +fn secure() -> Html { + let history = use_history().unwrap(); + + let onclick_callback = Callback::from(move |_| history.push(Route::Home)); + html! { +
    +

    { "Secure" }

    + +
    + } +} + +fn switch(routes: &Route) -> Html { + match routes { Route::Home => html! {

    { "Home" }

    }, - Route::Secure => { - let callback = Callback::from(|_| yew_router::push_route(Route::Home)); - html! { -
    -

    { "Secure" }

    - -
    - } + Route::Secure => html! { + }, Route::NotFound => html! {

    { "404" }

    }, } } + +#[function_component(Main)] +fn app() -> Html { + html! { + + render={Switch::render(switch)} /> + + } +} ``` +### History and Location + +The router provides a universal `History` and `Location` struct which +can be used to access routing information. They can be retrieved by +hooks or convenient functions on `ctx.link()`. + +They have a couple flavours: + +#### `AnyHistory` and `AnyLocation` + +These types are available with all routers and should be used whenever possible. +They implement a subset of `window.history` and `window.location`. + +You can access them using the following hooks: + +- `use_history` +- `use_location` + +#### `BrowserHistory` and `BrowserLocation` + +These are only available when `` is used. They provide +additional functionality that is not available in `AnyHistory` and +`AnyLocation` (such as: `location.host`). + ### Navigation -To navigate between pages, use either a `Link` component (which renders a `` element), the `yew_router::push_route` function, or the `yew_router::replace_route` function, which replaces the current page in the user's browser history instead of pushing a new one onto the stack. +To navigate between pages, use either a `Link` component (which renders a `` element), the `history.push` function, or the `history.replace` function, which replaces the current page in the user's browser history instead of pushing a new one onto the stack. ### Query Parameters #### Specifying query parameters when navigating -In order to specify query parameters when navigating to a new route, use either `yew_router::push_route_with_query` or the `yew_router::replace_route_with_query` functions. +In order to specify query parameters when navigating to a new route, use either `history.push_with_query` or the `history.replace_with_query` functions. It uses `serde` to serialize the parameters into query string for the URL so any type that implements `Serialize` can be passed. In its simplest form this is just a `HashMap` containing string pairs. #### Obtaining query parameters for current route -`yew_router::parse_query` is used to obtain the query parameters. +`location.query` is used to obtain the query parameters. It uses `serde` to deserialize the parameters from query string in the URL. ## Relevant examples