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}