Improve Context API docs (#3409)

* improved context API docs, added example of struct component context producer

* forgot to commit that oops

Author: its-the-shrimp

Cargo.lock

@@ -5,6 +5,5 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-serde = { version = "1.0", features = ["derive"] }
 yew = { path = "../../packages/yew", features = ["csr"] }
 yew-agent = { path = "../../packages/yew-agent" }

examples/contexts/Cargo.toml

@@ -1,10 +1,12 @@
 mod msg_ctx;
 mod producer;
+mod struct_component_producer;
 mod struct_component_subscriber;
 mod subscriber;
 
 use msg_ctx::MessageProvider;
 use producer::Producer;
+use struct_component_producer::StructComponentProducer;
 use struct_component_subscriber::StructComponentSubscriber;
 use subscriber::Subscriber;
 use yew::prelude::*;
@@ -14,6 +16,7 @@ pub fn App() -> Html {
     html! {
         <MessageProvider>
             <Producer />
+            <StructComponentProducer />
             <Subscriber />
             <StructComponentSubscriber />
         </MessageProvider>

examples/contexts/src/main.rs

@@ -6,10 +6,8 @@ use super::msg_ctx::MessageContext;
 pub fn Producer() -> Html {
     let msg_ctx = use_context::<MessageContext>().unwrap();
 
-    let onclick = Callback::from(move |_| msg_ctx.dispatch("Message Received.".to_string()));
-
     html! {
-        <button {onclick}>
+        <button onclick={move |_| msg_ctx.dispatch("Message Received.".to_string())}>
             {"PRESS ME"}
         </button>
     }

examples/contexts/src/producer.rs

@@ -0,0 +1,27 @@
+use yew::prelude::*;
+
+use super::msg_ctx::MessageContext;
+
+pub struct StructComponentProducer;
+
+impl Component for StructComponentProducer {
+    type Message = ();
+    type Properties = ();
+
+    fn create(_ctx: &Context<Self>) -> Self {
+        Self
+    }
+
+    fn view(&self, ctx: &Context<Self>) -> Html {
+        let (msg_ctx, _) = ctx
+            .link()
+            .context::<MessageContext>(Callback::noop())
+            .expect("No Message Context Provided");
+
+        html! {
+            <button onclick={move |_| msg_ctx.dispatch("Other message received.".to_owned())}>
+                {"OR ME"}
+            </button>
+        }
+    }
+}

examples/contexts/src/struct_component_producer.rs

@@ -11,7 +11,7 @@ use crate::functional::{Hook, HookContext};
 /// is returned. A component which calls `use_context` will re-render when the data of the context
 /// changes.
 ///
-/// More information about contexts and how to define and consume them can be found on [Yew Docs](https://yew.rs).
+/// More information about contexts and how to define and consume them can be found on [Yew Docs](https://yew.rs/docs/concepts/contexts).
 ///
 /// # Example
 ///

packages/yew/src/functional/hooks/use_context.rs

@@ -96,35 +96,57 @@ A context provider is required to consume the context. `ContextProvider<T>`, whe
 The children are re-rendered when the context changes. A struct is used to define what data is to be passed. The `ContextProvider` can be used as:
 
 ```rust
-use std::rc::Rc;
 use yew::prelude::*;
 
+
+/// App theme
 #[derive(Clone, Debug, PartialEq)]
 struct Theme {
     foreground: String,
     background: String,
 }
 
+/// Main component
 #[function_component]
-fn NavButton() -> Html {
-    let theme = use_context::<Theme>();
+pub fn App() -> Html {
+    let ctx = use_state(|| Theme {
+        foreground: "#000000".to_owned(),
+        background: "#eeeeee".to_owned(),
+    });
 
     html! {
-        // use theme
+        // `ctx` is type `Rc<UseStateHandle<Theme>>` while we need `Theme`
+        // so we deref it.
+        // It derefs to `&Theme`, hence the clone
+        <ContextProvider<Theme> context={(*ctx).clone()}>
+            // Every child here and their children will have access to this context.
+            <Toolbar />
+        </ContextProvider<Theme>>
     }
 }
 
+/// The toolbar.
+/// This component has access to the context
 #[function_component]
-fn App() -> Html {
-    let theme = use_memo((), |_| Theme {
-        foreground: "yellow".to_owned(),
-        background: "pink".to_owned(),
-    });
+pub fn Toolbar() -> Html {
+    html! {
+        <div>
+            <ThemedButton />
+        </div>
+    }
+}
+
+/// Button placed in `Toolbar`.
+/// As this component is a child of `ThemeContextProvider` in the component tree, it also has access
+/// to the context.
+#[function_component]
+pub fn ThemedButton() -> Html {
+    let theme = use_context::<Theme>().expect("no ctx found");
 
     html! {
-        <ContextProvider<Rc<Theme>> context={theme}>
-            <NavButton />
-        </ContextProvider<Rc<Theme>>>
+        <button style={format!("background: {}; color: {};", theme.background, theme.foreground)}>
+            { "Click me!" }
+        </button>
     }
 }
 ```