Fix: Remove play button from guide example (#1118)

* fix: Remove play button from guide example

* Update index.md

* update other examples
This commit is contained in:
Marc Espín authored and GitHub committed 2023-06-28 09:32:42 -05:00
1 parent 90f80e4dc2
commit 98fc153152
74 files changed
+503 -503

No files matched your search

@@ -2,13 +2,13 @@
In some cases, you may wish to create a component that acts as a container for some other content, without the component needing to know what that content is. To achieve this, create a prop of type `Element`:
```rust
```rust, no_run
{{#include ../../../examples/component_element_props.rs:Clickable}}
```
Then, when rendering the component, you can pass in the output of `cx.render(rsx!(...))`:
```rust
```rust, no_run
{{#include ../../../examples/component_element_props.rs:Clickable_usage}}
```
@@ -20,12 +20,12 @@ Then, when rendering the component, you can pass in the output of `cx.render(rsx
Rather than passing the RSX through a regular prop, you may wish to accept children similarly to how elements can have children. The "magic" `children` prop lets you achieve this:
```rust
```rust, no_run
{{#include ../../../examples/component_children.rs:Clickable}}
```
This makes using the component much simpler: simply put the RSX inside the `{}` brackets – and there is no need for a `render` call or another macro!
```rust
```rust, no_run
{{#include ../../../examples/component_children.rs:Clickable_usage}}
```
@@ -7,6 +7,7 @@ Just like you can pass arguments to a function, you can pass props to a componen
Component props are a single struct annotated with `#[derive(Props)]`. For a component to accept props, the type of its argument must be `Scope<YourPropsStruct>`. Then, you can access the value of the props using `cx.props`.
There are 2 flavors of Props structs:
- Owned props:
- Don't have an associated lifetime
- Implement `PartialEq`, allow for memoization (if the props don't change, Dioxus won't re-render the component)
@@ -14,17 +15,17 @@ There are 2 flavors of Props structs:
- [Borrow](https://doc.rust-lang.org/beta/rust-by-example/scope/borrow.html) from a parent component
- Cannot be memoized due to lifetime constraints
### Owned Props
Owned Props are very simple – they don't borrow anything. Example:
```rust
```rust, no_run
{{#include ../../../examples/component_owned_props.rs:Likes}}
```
You can then pass prop values to the component the same way you would pass attributes to an element:
```rust
```rust, no_run
{{#include ../../../examples/component_owned_props.rs:App}}
```
@@ -36,18 +37,19 @@ Owned props work well if your props are easy to copy around – like a single nu
Rust allows for something more efficient – borrowing the String as a `&str` – this is what Borrowed Props are for!
```rust
```rust, no_run
{{#include ../../../examples/component_borrowed_props.rs:TitleCard}}
```
We can then use the component like this:
```rust
```rust, no_run
{{#include ../../../examples/component_borrowed_props.rs:App}}
```
![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.
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
@@ -57,13 +59,13 @@ The `#[derive(Props)]` macro has some features that let you customize the behavi
You can create optional fields by using the `Option<…>` type for a field:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:OptionalProps}}
```
Then, you can choose to either provide them or not:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:OptionalProps_usage}}
```
@@ -71,13 +73,13 @@ Then, you can choose to either provide them or not:
If you want to explicitly require an `Option`, and not an optional prop, you can annotate it with `#[props(!optional)]`:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:ExplicitOption}}
```
Then, you have to explicitly pass either `Some("str")` or `None`:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:ExplicitOption_usage}}
```
@@ -85,13 +87,13 @@ Then, you have to explicitly pass either `Some("str")` or `None`:
You can use `#[props(default = 42)]` to make a field optional and specify its default value:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:DefaultComponent}}
```
Then, similarly to optional props, you don't have to provide it:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:DefaultComponent_usage}}
```
@@ -99,13 +101,13 @@ Then, similarly to optional props, you don't have to provide it:
It is common for Rust functions to accept `impl Into<SomeType>` rather than just `SomeType` to support a wider range of parameters. If you want similar functionality with props, you can use `#[props(into)]`. For example, you could add it on a `String` prop – and `&str` will also be automatically accepted, as it can be converted into `String`:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:IntoComponent}}
```
Then, you can use it so:
```rust
```rust, no_run
{{#include ../../../examples/component_props_options.rs:IntoComponent_usage}}
```
@@ -115,7 +117,7 @@ So far, every Component function we've seen had a corresponding ComponentProps s
`inline_props` allows you to do just that. Instead of typing the "full" version:
```rust
```rust, no_run
#[derive(Props, PartialEq)]
struct TitleCardProps {
title: String,
@@ -130,7 +132,7 @@ fn TitleCard(cx: Scope<TitleCardProps>) -> Element {
...you can define a function that accepts props as arguments. Then, just annotate it with `#[inline_props]`, and the macro will turn it into a regular Component for you:
```rust
```rust, no_run
#[inline_props]
fn TitleCard(cx: Scope, title: String) -> Element {
cx.render(rsx!{
@@ -4,7 +4,7 @@ Just like you wouldn't want to write a complex program in a single, long, `main`
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!
```rust
```rust, no_run
{{#include ../../../examples/hello_world_desktop.rs:component}}
```
@@ -12,13 +12,13 @@ A component is a Rust function, named in UpperCammelCase, that takes a `Scope` p
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:
```rust
```rust, no_run
{{#include ../../../examples/components.rs:About}}
```
Then, you can render your component in another component, similarly to how elements are rendered:
```rust
```rust, no_run
{{#include ../../../examples/components.rs:App}}
```
+35 -23
View File
@@ -1,35 +1,42 @@
# 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 the 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 of RSX syntax in the "hello world" application:
```rust
```rust, no_run
{{#include ../../../examples/hello_world_desktop.rs:component}}
```
Here, we use the `rsx!` macro to *declare* that we want a `div` element, containing the text `"Hello, world!"`. Dioxus takes the RSX and constructs a UI from it.
Here, we use the `rsx!` macro to _declare_ that we want a `div` element, containing the text `"Hello, world!"`. Dioxus takes the RSX and constructs a UI from it.
## RSX Features
RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty `div` element in RSX, as well as the resulting HTML:
```rust
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:empty}}
```
```html
<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
```rust, no_run
{{#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>
<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.
@@ -40,26 +47,27 @@ Attributes (and [listeners](../interactivity/index.md)) modify the behavior or a
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
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:custom_attributes}}
```
```html
<b customAttribute="value">
</b>
<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
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:formatting}}
```
```html
<div class="country-es" position="(42, 0)">
<div>ES</div>
<div>42</div>
<div>{}</div>
<div>ES</div>
<div>42</div>
<div>{}</div>
</div>
```
@@ -67,14 +75,15 @@ Similarly to how you can [format](https://doc.rust-lang.org/rust-by-example/hell
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
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:children}}
```
```html
<ol>
<li>First Item</li>
<li>Second Item</li>
<li>Third Item</li>
<li>First Item</li>
<li>Second Item</li>
<li>Third Item</li>
</ol>
```
@@ -82,7 +91,7 @@ To add children to an element, put them inside the `{}` brackets after all attri
You can render multiple elements at the top level of `rsx!` and they will be automatically grouped.
```rust
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:manyroots}}
```
@@ -95,9 +104,10 @@ You can render multiple elements at the top level of `rsx!` and they will be aut
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
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:expression}}
```
```html
<span>DIOXUS0123456789</span>
```
@@ -106,9 +116,10 @@ You can include arbitrary Rust expressions as children within RSX that implement
In addition to iterators you can also use for loops directly within RSX:
```rust
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:loops}}
```
```html
<div>0</div>
<div>1</div>
@@ -122,9 +133,10 @@ In addition to iterators you can also use for loops directly within RSX:
You can also use if statements without an else branch within RSX:
```rust
```rust, no_run
{{#include ../../../examples/rsx_overview.rs:ifstatements}}
```
```html
<div>true</div>
```
```
@@ -8,8 +8,7 @@ If you're working with pre-rendered assets, output from templates, or output fro
For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the [Dioxus homepage](https://dioxuslabs.com):
```rust
```rust, no_run
{{#include ../../../examples/dangerous_inner_html.rs:dangerous_inner_html}}
```
@@ -17,21 +16,21 @@ For example, shipping a markdown-to-Dioxus converter might significantly bloat y
>
> If you're handling untrusted input, make sure to sanitize your HTML before passing it into `dangerous_inner_html` – or just pass it to a Text Element to escape any HTML tags.
## Boolean Attributes
Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether they affect the output. For these attributes, a provided value of `"false"` will cause them to be removed from the target element.
So this RSX wouldn't actually render the `hidden` attribute:
```rust
```rust, no_run
{{#include ../../../examples/boolean_attribute.rs:boolean_attribute}}
```
```html
<div>hello</div>
```
Not all attributes work like this however. *Only the following attributes* have this behavior:
Not all attributes work like this however. _Only the following attributes_ have this behavior:
- `allowfullscreen`
- `allowpaymentrequest`