Skip to content

Commit 950f1c6

Browse files
author
Arthur Evans
authored
Copyedits, working with lists tutorial. (#849)
1 parent 22f9b1e commit 950f1c6

File tree

8 files changed

+60
-61
lines changed

8 files changed

+60
-61
lines changed
Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
1-
This tutorial will be exploring different ways of rendering lists of items in
1+
This tutorial explores different ways of rendering lists of items in
22
Lit!
33

4-
Lit makes it easy to render any lists of items. It has built-it support for
4+
Lit makes it easy to render any list of items. It has built-it support for
55
iterables: pass an array (or other iterable) to a child expression and Lit will
66
render each item in the array. This, combined with Lit's ability to render
77
nested templates, and JavaScript patterns for transforming lists of data into
88
lists of templates, allows for very flexible list handling.
99

1010
## What you'll learn
11-
- Rendering lists with the `map()` directive
12-
- Transforming arrays into templates with array methods
13-
- Generating lists with the `range()` directive
14-
- Imperatively building arrays of items
15-
- Diffing lists of stateful elements with the `repeat()` directive
16-
- Using event listeners in a list
11+
- Rendering lists with the `map()` directive.
12+
- Transforming arrays into templates with array methods.
13+
- Generating lists with the `range()` directive.
14+
- Imperatively building arrays of items.
15+
- Diffing lists of stateful elements with the `repeat()` directive.
16+
- Using event listeners in a list.
1717

1818
## Previous knowledge
19-
It is recommended to have basic understandings of
19+
This tutorial assumes that you've completed the
20+
[Intro to Lit](/tutorials/intro-to-lit/) tutorial,
21+
or you're already familiar with some of the basics of Lit:
2022
[defining a component](/docs/components/defining/),
2123
[rendering](/docs/components/rendering/),
2224
[reactive properties](/docs/components/properties/), and
23-
[adding an event listener](/docs/components/events/#adding-event-listeners-in-the-element-template)
24-
before working on this tutorial. The [Intro to Lit](/tutorials/intro-to-lit/)
25-
tutorial is a great place to start.
25+
[adding an event listener](/docs/components/events/#adding-event-listeners-in-the-element-template).

packages/lit-dev-content/site/tutorials/content/working-with-lists/01.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@ Lit supports rendering iterables of items directly in templates, but you often
22
need to render a _template_ that uses the items, rather than the items directly.
33

44
Lit provides a built-in `map()` directive that lets you transform the items in
5-
an iterable. The `map()` directive works with any iterables such as arrays,
6-
sets, maps, and even generators. It returns an iterable containing the result of
7-
calling the provided callback function on each item.
5+
an iterable. The `map()` directive works with all kinds of iterables, including
6+
arrays, sets, maps, and even generators. It returns an iterable containing the
7+
result of calling the provided callback function on each item.
88

9-
In this example, a custom element is presented with a state property named
10-
`items` that contains a set of strings.
9+
In this example, you're given a custom element with a state property named
10+
`items`, which contains a set of strings.
1111

1212
Render each item in the set as a list item (`<li>`) containing that string.
1313
Begin by importing the `map()` directive.

packages/lit-dev-content/site/tutorials/content/working-with-lists/02.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,6 @@ results to place in the component's template.
4242

4343
{% endswitchable-sample %}
4444

45-
Using array methods is helpful when chaining like this, but does require the
45+
Using array methods is helpful when chaining like this, but it does require the
4646
original source to be an array. Consider using the `map()` directive as shown in
4747
the previous step for any iterables that are not arrays.

packages/lit-dev-content/site/tutorials/content/working-with-lists/03.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,7 @@ In this example, the component has the following state properties:
1010
Render a list item for each member but also include pets if `includePets` is
1111
`true`. The list item for the pet should include both the name and the species.
1212

13-
Populate the `listItems` array conditionally based on the boolean state
14-
like shown below.
13+
Populate the `listItems` array conditionally based on the boolean state, as shown below.
1514

1615
{% switchable-sample %}
1716

@@ -83,7 +82,7 @@ Then add the `listItems` array to your element's template.
8382

8483
Click the button to see if the conditional rendering is working properly.
8584

86-
Extra Credit: Try refactoring the code to abstract out the logic from the
85+
Extra Credit: Try refactoring the code to abstract the logic out of the
8786
`render()` method into its own private method that returns the array of
88-
templates and invoke it within the template expression where `listItems`
89-
currently is.
87+
templates. Then invoke the new method inside the template expression
88+
(replacing `listItems`).

packages/lit-dev-content/site/tutorials/content/working-with-lists/04.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ board, for instance.
44
The `range()` directive provides a simple way of creating an iterable of
55
incrementing integers which can be used with the `map()` directive to
66
programmatically render a list of templates in a convenient manner. Nesting this
7-
allows creation of multi-dimensional patterns.
7+
allows you to create multi-dimensional patterns.
88

99
The example component already has some styles defined to create an 8 by 8 board
1010
to be filled with `<div>`s whose background color will be determined by adding
@@ -28,7 +28,7 @@ import {map} from 'lit/directives/map.js';
2828

2929
{% endswitchable-sample %}
3030

31-
Use these directives to create squares of black and white colors like a chess
31+
Use these directives to create black and white squares like a chess
3232
board.
3333

3434
{% switchable-sample %}

packages/lit-dev-content/site/tutorials/content/working-with-lists/05.md

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
When using the `map()` directive or just providing an iterable within the
22
template, Lit creates a list of DOM nodes and updates them in the iteration
3-
order, efficiently reusing any previously rendered nodes. These techniques
4-
should only be used when Lit controls all of the rendered state as is commonly
5-
the case.
3+
order, efficiently reusing any previously rendered nodes. This technique
4+
should only be used when Lit controls all of the rendered state (as is commonly
5+
the case).
66

7-
However, when relying instead on the DOM nodes to maintain state that is not
8-
controlled by Lit, unexpected behavior can occur as the example below wil
7+
However, when relying instead on the DOM nodes to maintain state that **isn't**
8+
controlled by Lit, unexpected behavior can occur as the example below will
99
demonstrate. In this case, use the `repeat()` directive instead.
1010

1111
## Example
@@ -92,15 +92,14 @@ template to render for each item.
9292
{% endswitchable-sample %}
9393

9494
Confirm that this is working correctly by checking an item and changing the sort
95-
order. The check mark should now be moving to stay next to its original label.
95+
order. The check mark should now move to stay next to its original label.
9696

9797
{% aside "positive" %}
9898

9999
The key function provided must return a unique key for an item.
100100

101-
A key function that simply returns the index (or omitting the key function)
102-
would have the same behavior as using `map()`. See the [repeat
103-
documentation](/docs/templates/directives/#repeat) for more details. Also see
101+
If you omit the key function—or provide a key function that simply returns the index—`repeat()` behaves exactly like `map()`. For more information, see the [repeat
102+
documentation](/docs/templates/directives/#repeat). Also see
104103
[When to use map or repeat](/docs/templates/lists/#when-to-use-map-or-repeat)
105104
for guidance on deciding when to use one or the other.
106105

packages/lit-dev-content/site/tutorials/content/working-with-lists/06.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
1-
There are several ways of adding event listeners to list items getting rendered,
2-
but care must be taken to ensure the correct information is made available to
3-
the event handler. This step shows one way of achieving this.
1+
There are several ways of adding event listeners to list items in your template.
2+
You also need to make sure that the event handler can identify which item the event is related to. This step shows one way of achieving this.
43

5-
The example currently has an array of strings in the `things` state property
6-
that are being rendered as list items with a "Delete" button which does not do
7-
anything yet.
4+
The example currently has an array of strings in the `things` state property.
5+
Each string is rendered as a list item with a "Delete" button, but the button
6+
does not do anything yet.
87

9-
First, create a method that will be called when the button is clicked that will
10-
remove the item from the `things` array. It will take the item's index.
8+
First, create a method that will be called when the button is clicked. The method should take an item's index as a parameter, and remove that item from the `things` array.
119

1210
{% switchable-sample %}
1311

@@ -41,8 +39,8 @@ The `filter()` array method returns a new array which is assigned to
4139
`this.things`. Since the reference stored in `this.things` changes, Lit will
4240
know to update the component when `_deleteThing()` is called. If the array is
4341
mutated instead with something like the `splice()` array method, an update must
44-
be manually requested. See [Mutating objects and array
45-
properties](/docs/components/properties/#mutating-properties) for details.
42+
be manually requested. For more information, see [Mutating objects and array
43+
properties](/docs/components/properties/#mutating-properties).
4644

4745
{% endaside %}
4846

@@ -94,19 +92,18 @@ mapped.
9492
{% endswitchable-sample %}
9593

9694
Now clicking the delete button should remove the item. Note that an inline arrow
97-
function is used here to create closures such that each list item gets a
95+
function is used here to create a closure, so each list item gets a
9896
function that calls `_deleteThing` with its own index.
9997

10098
{% aside "info" %}
10199

102-
While closures will be fine for most cases, there are other ways to achieve this
100+
While closures are fine for most cases, there are other ways to achieve this
103101
behavior.
104102

105-
For instance, a property or attribute can be left on the element with the
106-
listener which can then be accessed by the event handler via `event.target`.
107-
When listening to an event that bubbles, using event delegation can be a
108-
convenient way of handling it without attaching event listeners on every item.
109-
Read more about it in [Listening to events fired from repeated
110-
templates](/docs/components/events/#listening-to-events-fired-from-repeated-templates).
103+
For instance, you can add a property or attribute to the element that dispatches
104+
the event. The event handler can then access that data using `event.target`.
105+
When listening to an event that bubbles, you can use event delegation to avoid
106+
attaching event listeners on every item. For more information, see [Listening to
107+
events fired from repeated templates](/docs/components/events/#listening-to-events-fired-from-repeated-templates).
111108

112109
{% endaside %}
Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,36 @@
1-
Congratulations on completing the **Working with Lists** tutorial!
1+
Congratulations on completing the **Working with lists** tutorial!
22

33
## Takeaways
44

55
- Lit has built-in support for rendering iterables! Just place arrays, sets,
66
maps, or generators directly into the template expression.
77
- Use the `map()` directive for a declarative way of taking an iterable and
8-
transforming each item into some renderable template. Use it when all
9-
necessary states are controlled by Lit.
10-
- For complex situations involving more logic, an array of renderables can be
11-
manually built and placed into the component template. Consider using a
8+
transforming each item into a renderable template. Use it when all
9+
necessary state is controlled by Lit.
10+
- For complex situations involving more logic, you can build an array of
11+
renderable imperatively using the `Array` methods. Consider using a
1212
separate private method to abstract the related logic out of the `render()`
1313
method.
14-
- Use the `repeat()` directive when relying on the DOM nodes for some state or
15-
otherwise needing a tight coupling between the DOM and the list item. Provide
16-
a key function that produces a unique key for each item of the iterable.
14+
- Use the `repeat()` directive when the rendered DOM nodes have state that
15+
**isn't** controlled by Lit, or when updating the DOM nodes is more expensive
16+
than moving them. Provide a key function that produces a unique key for each
17+
item of the iterable.
1718
- Consider using the `range()` directive along with `map()` to programmatically
1819
generate a list. These can be nested to produce a multi-dimensional grid as
1920
well.
2021
- Lastly, when adding event listeners to items rendered from a list, make sure
2122
the handler has access to the data it needs that's specific to each item.
2223
Using an inline arrow function is often a good way to achieve this by creating
23-
closures.
24+
a closure for each item.
2425

2526
## Further learning
2627

2728
Check out other [built-in directives](/docs/templates/directives/) besides
2829
`map()`, `repeat()`, and `range()` that are available, or learn how to make your
2930
very own [custom directive](/docs/templates/custom-directives/)!
3031

32+
To learn more about reactive properties and the reactive update cycle that drives
33+
Lit components, try the [Reactivity tutorial](/tutorials/reactivity/)
34+
3135
<!-- TODO(augustinekim) Add callout to virtualizer for handling big lists
3236
when it lands -->

0 commit comments

Comments
 (0)