-
-
Notifications
You must be signed in to change notification settings - Fork 616
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add chapter on nested reactivity and iteration (#1920)
- Loading branch information
Showing
2 changed files
with
273 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,272 @@ | ||
# Iterating over More Complex Data with `<For/>` | ||
|
||
This chapter goes into iteration over nested data structures in a bit | ||
more depth. It belongs here with the other chapter on iteration, but feel | ||
free to skip it and come back if you’d like to stick with simpler subjects | ||
for now. | ||
|
||
## The Problem | ||
|
||
I just said that the framework does not rerender any of the items in one of the | ||
rows, unless the key has changed. This probably makes sense at first, but it can | ||
easily trip you up. | ||
|
||
Let’s consider an example in which each of the items in our row is some data structure. | ||
Imagine, for example, that the items come from some JSON array of keys and values: | ||
|
||
```rust | ||
#[derive(Debug, Clone)] | ||
struct DatabaseEntry { | ||
key: String, | ||
value: i32, | ||
} | ||
``` | ||
|
||
Let’s define a simple component that will iterate over the rows and display each one: | ||
|
||
```rust | ||
#[component] | ||
pub fn App() -> impl IntoView { | ||
// start with a set of three rows | ||
let (data, set_data) = create_signal(vec![ | ||
DatabaseEntry { | ||
key: "foo".to_string(), | ||
value: 10, | ||
}, | ||
DatabaseEntry { | ||
key: "bar".to_string(), | ||
value: 20, | ||
}, | ||
DatabaseEntry { | ||
key: "baz".to_string(), | ||
value: 15, | ||
}, | ||
]); | ||
view! { | ||
// when we click, update each row, | ||
// doubling its value | ||
<button on:click=move |_| { | ||
set_data.update(|data| { | ||
for row in data { | ||
row.value *= 2; | ||
} | ||
}); | ||
// log the new value of the signal | ||
logging::log!("{:?}", data.get()); | ||
}> | ||
"Update Values" | ||
</button> | ||
// iterate over the rows and display each value | ||
<For | ||
each=data | ||
key=|state| state.key.clone() | ||
let:child | ||
> | ||
<p>{child.value}</p> | ||
</For> | ||
} | ||
} | ||
``` | ||
|
||
> Note the `let:child` syntax here. In the previous chapter we introduced `<For/>` | ||
> with a `children` prop. We can actually create this value directly in the children | ||
> of the `<For/>` component, without breaking out of the `view` macro: the `let:child` | ||
> combined with `<p>{child.value}</p>` above is the equivalent of | ||
> | ||
> ```rust | ||
> children=|child| view! { <p>{child.value}</p> } | ||
> ``` | ||
When you click the `Update Values` button... nothing happens. Or rather: | ||
the signal is updated, the new value is logged, but the `{child.value}` | ||
for each row doesn’t update. | ||
|
||
Let’s see: is that because we forgot to add a closure to make it reactive? | ||
Let’s try `{move || child.value}`. | ||
|
||
...Nope. Still nothing. | ||
|
||
Here’s the problem: as I said, each row is only rerendered when the key changes. | ||
We’ve updated the value for each row, but not the key for any of the rows, so | ||
nothing has rerendered. And if you look at the type of `child.value`, it’s a plain | ||
`i32`, not a reactive `ReadSignal<i32>` or something. This means that even if we | ||
wrap a closure around it, the value in this row will never update. | ||
|
||
We have three possible solutions: | ||
|
||
1. change the `key` so that it always updates when the data structure changes | ||
2. change the `value` so that it’s reactive | ||
3. take a reactive slice of the data structure instead of using each row directly | ||
|
||
## Option 1: Change the Key | ||
|
||
Each row is only rerendered when the key changes. Our rows above didn’t rerender, | ||
because the key didn’t change. So: why not just force the key to change? | ||
|
||
```rust | ||
<For | ||
each=data | ||
key=|state| (state.key.clone(), state.value) | ||
let:child | ||
> | ||
<p>{child.value}</p> | ||
</For> | ||
``` | ||
|
||
Now we include both the key and the value in the `key`. This means that whenever the | ||
value of a row changes, `<For/>` will treat it as if it’s an entirely new row, and | ||
replace the previous one. | ||
|
||
### Pros | ||
|
||
This is very easy. We can make it even easier by deriving `PartialEq`, `Eq`, and `Hash` | ||
on `DatabaseEntry`, in which case we could just `key=|state| state.clone()`. | ||
|
||
### Cons | ||
|
||
**This is the least efficient of the three options.** Every time the value of a row | ||
changes, it throws out the previous `<p>` element and replaces it with an entirely new | ||
one. Rather than making a fine-grained update to the text node, in other words, it really | ||
does rerender the entire row on every change, and this is expensive in proportion to how | ||
complex the UI of the row is. | ||
|
||
You’ll notice we also end up cloning the whole data structure so that `<For/>` can hold | ||
onto a copy of the key. For more complex structures, this can become a bad idea fast! | ||
|
||
## Option 2: Nested Signals | ||
|
||
If we do want that fine-grained reactivity for the value, one option is to wrap the `value` | ||
of each row in a signal. | ||
|
||
```rust | ||
#[derive(Debug, Clone)] | ||
struct DatabaseEntry { | ||
key: String, | ||
value: RwSignal<i32>, | ||
} | ||
``` | ||
|
||
`RwSignal<_>` is a “read-write signal,” which combines the getter and setter in one object. | ||
I’m using it here because it’s a little easier to store in a struct than separate getters | ||
and setters. | ||
|
||
```rust | ||
#[component] | ||
pub fn App() -> impl IntoView { | ||
// start with a set of three rows | ||
let (data, set_data) = create_signal(vec![ | ||
DatabaseEntry { | ||
key: "foo".to_string(), | ||
value: create_rw_signal(10), | ||
}, | ||
DatabaseEntry { | ||
key: "bar".to_string(), | ||
value: create_rw_signal(20), | ||
}, | ||
DatabaseEntry { | ||
key: "baz".to_string(), | ||
value: create_rw_signal(15), | ||
}, | ||
]); | ||
view! { | ||
// when we click, update each row, | ||
// doubling its value | ||
<button on:click=move |_| { | ||
data.with(|data| { | ||
for row in data { | ||
row.value.update(|value| *value *= 2); | ||
} | ||
}); | ||
// log the new value of the signal | ||
logging::log!("{:?}", data.get()); | ||
}> | ||
"Update Values" | ||
</button> | ||
// iterate over the rows and display each value | ||
<For | ||
each=data | ||
key=|state| state.key.clone() | ||
let:child | ||
> | ||
<p>{child.value}</p> | ||
</For> | ||
} | ||
} | ||
``` | ||
|
||
This version works! And if you look in the DOM inspector in your browser, you’ll | ||
see that unlike in the previous version, in this version only the individual text | ||
nodes are updated. Passing the signal directly into `{child.value}` works, as | ||
signals do keep their reactivity if you pass them into the view. | ||
|
||
Note that I changed the `set_data.update()` to a `data.with()`. `.with()` is the | ||
non-cloning way of accessing a signal’s value. In this case, we are only updating | ||
the internal values, not updating the list of values: because signals maintain their | ||
own state, we don’t actual need to update the `data` signal at all, so the immutable | ||
`.with()` is fine here. | ||
|
||
> In fact, this version doesn’t update `data`, so the `<For/>` is essentially a static | ||
> list as in the last chapter, and this could just be a plain iterator. But the `<For/>` | ||
> is useful if we want to add or remove rows in the future. | ||
### Pros | ||
|
||
This is the most efficient option, and fits directly with the rest of the mental model | ||
of the framework: values that change over time are wrapped in signals so the interface | ||
can respond to them. | ||
|
||
### Cons | ||
|
||
Nested reactivity can be cumbersome if you’re receiving data from an API or another | ||
data source you don’t control, and you don’t want to create a different struct wrapping | ||
each field in a signal. | ||
|
||
## Option 3: Memoized Slices | ||
|
||
Leptos provides a primitive called [`create_memo`](https://docs.rs/leptos/latest/leptos/fn.create_memo.html), | ||
which creates a derived computation that only triggers a reactive update when its value | ||
has changed. | ||
|
||
This allows you to create reactive values for subfields of a larger data structure, | ||
without needing to wrap the fields of that structure in signals. | ||
|
||
Most of the application can remain the same as the initial (broken) version, but the `<For/>` | ||
will be updated to this: | ||
|
||
```rust | ||
<For | ||
each=move || data().into_iter().enumerate() | ||
key=|(_, state)| state.key.clone() | ||
children=move |(index, _)| { | ||
let value = create_memo(move |_| { | ||
data.with(|data| data[index].value) | ||
}); | ||
view! { | ||
<p>{value}</p> | ||
} | ||
} | ||
/> | ||
``` | ||
|
||
You’ll notice a few differences here: | ||
|
||
- we convert the `data` signal into an enumerated iterator | ||
- we use the `children` prop explicitly, to make it easier to run some non-`view` code | ||
- we define a `value` memo and use that in the view. This `value` field doesn’t actually | ||
use the `child` being passed into each row. Instead, it uses the index and reaches back | ||
into the original `data` to get the value. | ||
|
||
Every time `data` changes, now, each memo will be recalculated. If its value has changed, | ||
it will update its text node, without rerendering the whole row. | ||
|
||
## Pros | ||
|
||
We get the same fine-grained reactivity of the signal-wrapped version, without needing to | ||
wrap the data in signals. | ||
|
||
## Cons | ||
|
||
It’s a bit more complex to set up this memo-per-row inside the `<For/>` loop rather than | ||
using nested signals. Note also that while memos memoize their reactive changes, the same | ||
calculation does need to re-run to check the value every time, so nested reactive signals | ||
will still be more efficient for pinpoint updates here. |