yew_stdweb/html/component/
mod.rs

1//! Component trait and related types
2
3mod children;
4mod lifecycle;
5mod properties;
6mod scope;
7
8use super::Html;
9pub use children::*;
10pub use properties::*;
11pub(crate) use scope::Scoped;
12pub use scope::{AnyScope, Scope, SendAsMessage};
13
14/// This type indicates that component should be rendered again.
15pub type ShouldRender = bool;
16
17/// Link to component's scope for creating callbacks.
18pub type ComponentLink<COMP> = Scope<COMP>;
19
20/// Components are the basic building blocks of the UI in a Yew app. Each Component
21/// chooses how to display itself using received props and self-managed state.
22/// Components can be dynamic and interactive by declaring messages that are
23/// triggered and handled asynchronously. This async update mechanism is inspired by
24/// Elm and the actor model used in the Actix framework.
25pub trait Component: Sized + 'static {
26    /// Messages are used to make Components dynamic and interactive. Simple
27    /// Component's can declare their Message type to be `()`. Complex Component's
28    /// commonly use an enum to declare multiple Message types.
29    type Message: 'static;
30
31    /// Properties are the inputs to a Component and should not mutated within a
32    /// Component. They are passed to a Component using a JSX-style syntax.
33    /// ```
34    ///# use yew::{Html, Component, Properties, ComponentLink, html};
35    ///# struct Model;
36    ///# #[derive(Clone, Properties)]
37    ///# struct Props {
38    ///#     prop: String,
39    ///# }
40    ///# impl Component for Model {
41    ///#     type Message = ();type Properties = Props;
42    ///#     fn create(props: Self::Properties,link: ComponentLink<Self>) -> Self {unimplemented!()}
43    ///#     fn update(&mut self,msg: Self::Message) -> bool {unimplemented!()}
44    ///#     fn change(&mut self, _: Self::Properties) -> bool {unimplemented!()}
45    ///#     fn view(&self) -> Html {
46    /// html! {
47    ///     <Model prop="value" />
48    /// }
49    ///# }}
50    /// ```
51    type Properties: Properties;
52
53    /// Components are created with their properties as well as a `ComponentLink` which
54    /// can be used to send messages and create callbacks for triggering updates.
55    fn create(props: Self::Properties, link: ComponentLink<Self>) -> Self;
56
57    /// Components handle messages in their `update` method and commonly use this method
58    /// to update their state and (optionally) re-render themselves.
59    fn update(&mut self, msg: Self::Message) -> ShouldRender;
60
61    /// When the parent of a Component is re-rendered, it will either be re-created or
62    /// receive new properties in the `change` lifecycle method. Component's can choose
63    /// to re-render if the new properties are different than the previously
64    /// received properties. Most Component's will use props with a `PartialEq`
65    /// impl and will be implemented like this:
66    /// ```
67    ///# use yew::{Html, Component, ComponentLink, html, ShouldRender};
68    ///# struct Model{props: ()};
69    ///# impl Component for Model {
70    ///#     type Message = ();type Properties = ();
71    ///#     fn create(props: Self::Properties,link: ComponentLink<Self>) -> Self {unimplemented!()}
72    ///#     fn update(&mut self,msg: Self::Message) -> bool {unimplemented!()}
73    ///#     fn view(&self) -> Html {unimplemented!()}
74    /// fn change(&mut self, props: Self::Properties) -> ShouldRender {
75    ///     if self.props != props {
76    ///         self.props = props;
77    ///         true
78    ///     } else {
79    ///         false
80    ///     }
81    /// }
82    ///# }
83    /// ```
84    /// Components which don't have properties should always return false.
85    fn change(&mut self, _props: Self::Properties) -> ShouldRender;
86
87    /// Components define their visual layout using a JSX-style syntax through the use of the
88    /// `html!` procedural macro. The full guide to using the macro can be found in [Yew's
89    /// documentation](https://yew.rs/docs/concepts/html).
90    fn view(&self) -> Html;
91
92    /// The `rendered` method is called after each time a Component is rendered but
93    /// before the browser updates the page.
94    /// ## Examples
95    /// ```rust
96    ///# use yew::{Html, Component, ComponentLink, html, ShouldRender};
97    ///# struct Model{props: ()};
98    ///# impl Model { fn setup_element(&self) { } }
99    ///# impl Component for Model {
100    ///#     type Message = ();type Properties = ();
101    ///#     fn create(props: Self::Properties,link: ComponentLink<Self>) -> Self {unimplemented!()}
102    ///#     fn update(&mut self,msg: Self::Message) -> bool {unimplemented!()}
103    ///#     fn view(&self) -> Html {unimplemented!()}
104    ///#     fn change(&mut self, _props: Self::Properties) -> ShouldRender { unimplemented!() }
105    /// fn rendered(&mut self, first_render: bool) {
106    ///    if first_render {
107    ///      self.setup_element(); // Similar to 'mounted' in other frameworks
108    ///    }
109    /// }
110    ///# }
111    /// ```
112    fn rendered(&mut self, _first_render: bool) {}
113
114    /// The `destroy` method is called right before a Component is unmounted.
115    fn destroy(&mut self) {}
116}
yew_stdweb/html/component/mod.rs

yew_stdweb/html/component/
mod.rs
