swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs to reflect changes in master (#670)

Browse Source 
* work on updating docs to master version

* more updates

* more polishing

* finish interactivity chapter

* finish updating core guide

* fix grammer mistakes and typos

* more grammer fixes

* add liveview guide

* remove doc build

* WIP custom renderer docs

* add axum as dev-dependancy to guide

* fix examples

* fix overview example

* use md book fork to fix compilation
This commit is contained in:
ealmloff authored and GitHub committed 2023-01-06 15:00:12 -08:00
1 parent a616a8fa9d
commit cd4474cc4f
51 files changed
+870 -549
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/guide/src/en/describing_ui/component_props.md
+3 -2
View File
@@ -9,7 +9,7 @@ Component props are a single struct annotated with `#[derive(Props)]`. For a com
There are 2 flavors of Props structs:
- Owned props:
- Don't have an associated lifetime
- Implement `PartialEq`, allowing for memoization (if the props don't change, Dioxus won't re-render the component)
- Implement `PartialEq`, allow for memoization (if the props don't change, Dioxus won't re-render the component)
- Borrowed props:
- [Borrow](https://doc.rust-lang.org/beta/rust-by-example/scope/borrow.html) from a parent component
- Cannot be memoized due to lifetime constraints
@@ -32,7 +32,7 @@ You can then pass prop values to the component the same way you would pass attri
### Borrowed Props
Owning props works well if your props are easy to copy around – like a single number. But what if we need to pass a larger data type, like a String from an `App` Component to a `TitleCard` subcomponent? A naive solution might be to [`.clone()`](https://doc.rust-lang.org/std/clone/trait.Clone.html) the String, creating a copy of it for the subcomponent – but this would be inefficient, especially for larger Strings.
Owned props work well if your props are easy to copy around – like a single number. But what if we need to pass a larger data type, like a String from an `App` Component to a `TitleCard` subcomponent? A naive solution might be to [`.clone()`](https://doc.rust-lang.org/std/clone/trait.Clone.html) the String, creating a copy of it for the subcomponent – but this would be inefficient, especially for larger Strings.
Rust allows for something more efficient – borrowing the String as a `&str` – this is what Borrowed Props are for!
@@ -47,6 +47,7 @@ We can then use the component like this:
```
![Screenshot: TitleCard component](./images/component_borrowed_props_screenshot.png)
Borrowed props can be very useful, but they do not allow for memorization so they will *always* rerun when the parent scope is rerendered. Because of this Borrowed Props should be reserved for components that are cheap to rerun or places where cloning data is an issue. Using Borrowed Props everywhere will result in large parts of your app rerunning every interaction.
## Prop Options
docs/guide/src/en/describing_ui/components.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Components
Just like you wouldn't want to write a complex program in a single, long, `main` function, you shouldn't build a complex UI in a single `App` function. Instead, it would be better to break down the functionality of an app in logical parts called components.
Just like you wouldn't want to write a complex program in a single, long, `main` function, you shouldn't build a complex UI in a single `App` function. Instead, you should break down the functionality of an app in logical parts called components.
A component is a Rust function, named in UpperCammelCase, that takes a `Scope` parameter and returns an `Element` describing the UI it wants to render. In fact, our `App` function is a component!
@@ -8,7 +8,7 @@ A component is a Rust function, named in UpperCammelCase, that takes a `Scope` p
{{#include ../../../examples/hello_world_desktop.rs:component}}
```
> You'll probably want to add `#![allow(non_snake_case)]` to the top of your crate to avoid warnings about the function name
> You'll probably want to add `#![allow(non_snake_case)]` to the top of your crate to avoid warnings about UpperCammelCase component names
A Component is responsible for some rendering task – typically, rendering an isolated part of the user interface. For example, you could have an `About` component that renders a short description of Dioxus Labs:
docs/guide/src/en/describing_ui/index.md
+76 -52
View File
@@ -1,8 +1,8 @@
# Describing the UI
Dioxus is a *declarative* framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set color to red") we simply *declare* what we want the UI to look like using RSX.
Dioxus is a *declarative* framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply *declare* what we want the UI to look like using RSX.
You have already seen a simple example or RSX syntax in the "hello world" application:
You have already seen a simple example of RSX syntax in the "hello world" application:
```rust
{{#include ../../../examples/hello_world_desktop.rs:component}}
@@ -21,9 +21,51 @@ RSX is very similar to HTML in that it describes elements with attributes and ch
<div></div>
```
### Attributes
Attributes (and [listeners](../interactivity/index.md)) modify the behavior or appearance of the element they are attached to. They are specified inside the `{}` brackets, using the `name: value` syntax. You can provide the value as a literal in the RSX:
```rust
{{#include ../../../examples/rsx_overview.rs:attributes}}
```
```html
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true" style="color: red"></a>
```
> Note: All attributes defined in `dioxus-html` follow the snake_case naming convention. They transform their `snake_case` names to HTML's `camelCase` attributes.
> Note: Styles can be used directly outside of the `style:` attribute. In the above example, `color: "red"` is turned into `style="color: red"`.
#### Custom Attributes
Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:
```rust
{{#include ../../../examples/rsx_overview.rs:custom_attributes}}
```
```html
<b customAttribute="value">
</b>
```
### Interpolation
Similarly to how you can [format](https://doc.rust-lang.org/rust-by-example/hello/print/fmt.html) Rust strings, you can also interpolate in RSX text. Use `{variable}` to Display the value of a variable in a string, or `{variable:?}` to use the Debug representation:
```rust
{{#include ../../../examples/rsx_overview.rs:formatting}}
```
```html
<div class="country-es" position="(42, 0)">
<div>ES</div>
<div>42</div>
<div>{}</div>
</div>
```
### Children
To add children to an element, put them inside the `{}` brackets. They can be either other elements, or text. For example, you could have an `ol` (ordered list) element, containing 3 `li` (list item) elements, each of which contains some text:
To add children to an element, put them inside the `{}` brackets after all attributes and listeners in the element. They can be other elements, text, or [components](components.md). For example, you could have an `ol` (ordered list) element, containing 3 `li` (list item) elements, each of which contains some text:
```rust
{{#include ../../../examples/rsx_overview.rs:children}}
@@ -38,69 +80,51 @@ To add children to an element, put them inside the `{}` brackets. They can be ei
### Fragments
You can also "group" elements by wrapping them in `Fragment {}`. This will not create any additional elements.
> Note: you can also render multiple elements at the top level of `rsx!` and they will be automatically grouped – no need for an explicit `Fragment {}` there.
You can render multiple elements at the top level of `rsx!` and they will be automatically grouped.
```rust
{{#include ../../../examples/rsx_overview.rs:fragments}}
{{#include ../../../examples/rsx_overview.rs:manyroots}}
```
```html
<p>First Item</p>
<p>Second Item</p>
<span>a group</span>
<span>of three</span>
<span>items</span>
```
### Attributes
Attributes are also specified inside the `{}` brackets, using the `name: value` syntax. You can provide the value as a literal in the RSX:
```rust
{{#include ../../../examples/rsx_overview.rs:attributes}}
```
```html
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true">Log In</a>
```
> Note: All attributes defined in `dioxus-html` follow the snake_case naming convention. They transform their `snake_case` names to HTML's `camelCase` attributes.
#### Custom Attributes
Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:
```rust
{{#include ../../../examples/rsx_overview.rs:custom_attributes}}
```
```html
<b customAttribute="value">
Rust is cool
</b>
```
### Interpolation
Similarly to how you can [format](https://doc.rust-lang.org/rust-by-example/hello/print/fmt.html) Rust strings, you can also interpolate in RSX text. Use `{variable}` to Display the value of a variable in a string, or `{variable:?}` to use the Debug representation:
```rust
{{#include ../../../examples/rsx_overview.rs:formatting}}
```
```html
<div class="country-es">Coordinates: (42, 0)
<div>ES</div>
<div>42</div>
</div>
```
### Expressions
You can include arbitrary Rust expressions within RSX, but you must escape them in `[]` brackets:
You can include arbitrary Rust expressions as children within RSX that implements [IntoDynNode](https://docs.rs/dioxus-core/0.3/dioxus_core/trait.IntoDynNode.html). This is useful for displaying data from an [iterator](https://doc.rust-lang.org/stable/book/ch13-02-iterators.html#processing-a-series-of-items-with-iterators):
```rust
{{#include ../../../examples/rsx_overview.rs:expression}}
```
```html
<span>DIOXUS</span>
<span>DIOXUS0123456789</span>
```
### Loops
In addition to iterators you can also use for loops directly within RSX:
```rust
{{#include ../../../examples/rsx_overview.rs:loops}}
```
```html
<div>0</div>
<div>1</div>
<div>2</div>
<div>0</div>
<div>1</div>
<div>2</div>
```
### If statements
You can also use if statements without an else branch within RSX:
```rust
{{#include ../../../examples/rsx_overview.rs:ifstatements}}
```
```html
<div>true</div>
```