diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 6c00723fe..5ef73694e 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -5,9 +5,9 @@ - [Hello, World!](hello_world.md) - [Core Topics](concepts/00-index.md) - [Intro to Elements](concepts/vnodes.md) + - [Intro to Components](concepts/components.md) - [Elements with RSX and NodeFactory](concepts/rsx.md) - [RSX in Depth](concepts/rsx_in_depth.md) - - [Components and Props](concepts/components.md) - [Memoization](concepts/memoization.md) - [Hooks and Internal State](concepts/hooks.md) - [Event handlers](concepts/event_handlers.md) diff --git a/docs/src/concepts/components.md b/docs/src/concepts/components.md index 62d0eaf81..e54cc2066 100644 --- a/docs/src/concepts/components.md +++ b/docs/src/concepts/components.md @@ -1,4 +1,17 @@ -# Components and Props +# Introduction to Components + +In the previous chapter, we learned about Elements and how they can be composed to create a basic User Interface. In this chapter, we'll learn how to group Elements together to form Components. + +## What is a component? + +In short, a component is a special function that takes an input and outputs a group of Elements. Typically, Components serve a single purpose: group functionality of a User Interface. Much like a function encapsulates some specific computation task, a Component encapsulates some specific rendering task. + +Let's take the r/rust subreddit page and see if we can identify some parts of the page that are encapsulated as a single rendering task. + + + + + Dioxus should look and feel just like writing functional React components. In Dioxus, there are no class components with lifecycles. All state management is done via hooks. This encourages logic reusability and lessens the burden on Dioxus to maintain a non-breaking lifecycle API. @@ -9,7 +22,7 @@ struct MyProps { } fn Example(cx: Context) -> DomTree { - html! {
"Hello {cx.cx.name}!"
} + html! {
"Hello {cx.props.name}!"
} } ``` diff --git a/docs/src/concepts/vnodes.md b/docs/src/concepts/vnodes.md index c80c93853..28e0c35a5 100644 --- a/docs/src/concepts/vnodes.md +++ b/docs/src/concepts/vnodes.md @@ -25,7 +25,7 @@ Produces: ## Composing Elements -Every element has a set of properties that can be rendered in different ways. In particular, each Element may contain other Elements. To achieve this, we can simply declare new Elements within the parent: +Every element has a set of properties that can be rendered in different ways. In particular, each Element may contain other Elements. To achieve this, we can simply declare new Elements contained within the parent's curly braces: ```rust #use dioxus::prelude::*; @@ -37,17 +37,27 @@ rsx!( } ) ``` +As you might expect, the generated HTML for this structure would look like: +```html +
+

+

+

+
+``` + With the default configuration, any Element defined within the `dioxus-html` crate can be declared in this way. To create your own new elements, see the `Custom Elements` Advanced Guide. ## Text Elements -Dioxus also supports a special type of Element: Text. Text Elements do not accept children, but rather just text denoted with double quotes. +Dioxus also supports a special type of Element: Text. Text Elements do not accept children, but rather just string literals denoted with double quotes. ```rust rsx! ( "hello world" ) ``` + Text Elements can be composed within other Elements: ```rust rsx! ( @@ -57,7 +67,8 @@ rsx! ( } ) ``` -Text can also be formatted with any value that implements `Display`. We use f-string formatting - a "coming soon" feature for stable Rust that is familiar for Python and JavaScript users: + +Text can also be formatted with any value that implements `Display`. We use [f-string formatting](https://docs.rs/fstrings/0.2.3/fstrings/) - a "coming soon" feature for stable Rust that is familiar for Python and JavaScript users: ```rust let name = "Bob"; @@ -81,6 +92,7 @@ rsx!( ``` Each field is defined as a method on the element in the `dioxus-html` crate. This prevents you from misspelling a field name and lets us provide inline documentation. When you need to use a field not defined as a method, you have two options: + 1) file an issue if the attribute _should_ be enabled 2) add a custom attribute on-the-fly @@ -89,11 +101,36 @@ To use custom attributes, simply put the attribute name in quotes followed by a ```rust rsx!( div { - "custom_attr": "important data here" + "customAttr": "important data here" } ) ``` +Note: the name of the custom attribute must match exactly what you want the renderer to output. All attributes defined as methods in `dioxus-html` follow the snake_case naming convention. However, they internally translate their snake_case convention to HTML's camelCase convention. + ## Listeners -## Arbitrary Tokens +Listeners are a special type of Attribute that only accept functions. Listeners let us attach functionality to our Elements by running a provided closure whenever the specified Listener is triggered. + +We'll cover listeners in more depth in the Listeners chapter, but for now, just know that every listener must start with the `on` keyword and can accept either a closure or an expression wrapped in curly braces. + +```rust +rsx!( + div { + onclick: move |_| {} + onmouseover: {handler}, + } +) +``` + +## Moving On + +This chapter just scratches the surface on how Elements can be defined. + +We learned: +- Elements are the basic building blocks of User Interfaces +- Elements can contain other elements +- Elements can either be a named container or text +- Some Elements have properties that the renderer can use to draw the UI to the screen + +Next, we'll compose Elements together to form components. diff --git a/docs/src/images/reddit.png b/docs/src/images/reddit.png new file mode 100644 index 000000000..2277db264 Binary files /dev/null and b/docs/src/images/reddit.png differ diff --git a/packages/core/examples/syntax.rs b/packages/core/examples/syntax.rs index a54a3c218..39453c0cc 100644 --- a/packages/core/examples/syntax.rs +++ b/packages/core/examples/syntax.rs @@ -8,9 +8,12 @@ use dioxus_html as dioxus_elements; fn main() {} fn html_usage() { + let mo = move |_| {}; let r = rsx! { div { onclick: move |_| {} + onmouseover: {mo} + "type": "bar", "hello world" } };