` so we can add todos with Enter.
126 | <2> Bind the value of the text field to the task property.
127 | <3> Listen for the `change` event on the text field and call `this.updateTask`
128 | <4> Bind the button click event to `this.addTodo`
129 |
130 | Then, implement the methods on `TodoView`:
131 |
132 | .`*views/todo-view.js*`
133 | [source,javascript]
134 | ----
135 | class TodoView extends LitElement {
136 | static get properties() {...}
137 | constructor() {...}
138 | render() {...}
139 |
140 | addTodo() {
141 | if (this.task) {
142 | this.todos = [...this.todos, { <1>
143 | task: this.task,
144 | complete: false
145 | }];
146 | this.task = ''; //<2>
147 | }
148 | }
149 |
150 | shortcutListener(e) {
151 | if (e.key === 'Enter') { //<3>
152 | this.addTodo();
153 | }
154 | }
155 |
156 | updateTask(e) {
157 | this.task = e.target.value; //<4>
158 | }
159 | }
160 | ----
161 | <1> Create a new array with the new todo object
162 | <2> Clear the task property
163 | <3> If the `keyup` event originates from the `Enter` key, call `this.addTodo()`
164 | <4> Update the `task` property to the value of the text field on change events
165 |
166 | If you run the app, you should see the input layout and be able to input new tasks (although you won't see them quite yet).
167 |
168 | image::task-input.png[UI for entering new todos]
169 |
170 | === Listing todos
171 | Now that we can add todos, the next task is to display them. Loop through the `todos` array and produce a template for each todo.
172 |
173 | Under the input layout, add the following:
174 |
175 | [source,html]
176 | ----
177 |
178 | ${this.todos.map(
179 | todo => html` //<1>
180 |
181 |
183 | @change="${ e => this.updateTodoStatus(todo, e.target.checked)}"> //<3>
184 | ${todo.task}
185 |
186 |
187 | `
188 | )
189 | }
190 |
191 | ----
192 | <1> Use the `.map()` operation to map each todo object to a lit-html template
193 | <2> Bind the checked boolean attribute to the complete property on the todo object
194 | <3> Call `this.updateTodoStatus` with the todo and a boolean for status on `change` events
195 |
196 | Then, implement `updateTodoStatus`
197 |
198 | .`*views/todo-view.js*`
199 | [source,javascript]
200 | ----
201 | class TodoView extends LitElement {
202 | static get properties() {...}
203 | constructor() {...}
204 | render() {...}
205 | shortcutListener(e) {...}
206 | updateTask(e) {...}
207 | addTodo() {...}
208 |
209 | updateTodoStatus(updatedTodo, complete) {
210 | this.todos = this.todos.map(todo =>
211 | updatedTodo === todo ? { ...updatedTodo, complete } : todo
212 | );
213 | }
214 | }
215 | ----
216 |
217 | NOTE: LitElement only observes changes to objects and arrays, not changes to their contents. That's why we always create a new array of todos with the changes. Using immutable data structures also makes it easier for us to start using Redux for state management in the next part.
218 |
219 | image::add-tasks.gif[Adding and listing todos]
220 |
221 | === Filtering todos
222 | The last piece of functionality we add in this part of the tutorial is filtering and clearing todos.
223 |
224 | Add the following to the template:
225 |
226 | [source,html]
227 | ----
228 |
<1>
232 |
233 | ${Object.values(VisibilityFilters).map( <2>
234 | filter => html`
235 |
236 | ${filter}
237 | `
238 | )}
239 |
240 |
<3>
242 | Clear completed
243 |
244 | ----
245 | <1> Bind the value to the `filter` property and the `value-changed` event to the `this.filterChanged` method
246 | <2> Loop over the filter values and create a radio button for each
247 | <3> Hook up the clear button click event to `this.clearCopleted`
248 |
249 | Then add the JavaScript methods:
250 |
251 | .`*views/todo-view.js*`
252 | [source,javascript]
253 | ----
254 | class TodoView extends LitElement {
255 | static get properties() {...}
256 | constructor() {...}
257 | render() {...}
258 | shortcutListener(e) {...}
259 | updateTask(e) {...}
260 | addTodo() {...}
261 | updateTodoStatus(updatedTodo, complete) {...}
262 |
263 | filterChanged(e) { //<1>
264 | this.filter = e.target.value;
265 | }
266 |
267 | clearCompleted() { //<2>
268 | this.todos = this.todos.filter(todo => !todo.complete);
269 | }
270 |
271 | applyFilter(todos) { //<3>
272 | switch (this.filter) {
273 | case VisibilityFilters.SHOW_ACTIVE:
274 | return todos.filter(todo => !todo.complete);
275 | case VisibilityFilters.SHOW_COMPLETED:
276 | return todos.filter(todo => todo.complete);
277 | default:
278 | return todos;
279 | }
280 | }
281 | }
282 | ----
283 | <1> Update the `filter` property based on the event value.
284 | <2> Update the `todos` property to a new array only containing the non-completed todos.
285 | <3> Create a method that returns only the todos that pass the filter criteria.
286 |
287 | Finally, update the template to use the `applyFilter` method to only show the filtered todos:
288 |
289 | [source,diff]
290 | ----
291 |
292 | - ${this.todos.map(
293 | + ${this.applyFilter(this.todos).map(
294 | todo => html`
295 | ----
296 |
297 | image::filters.gif[Filtering todos]
298 |
299 | == Adding CSS styles
300 | Finally, let's add a few finishing touches with CSS. At the top of your template, add the following `
325 | ----
326 | <1> The `:host` selector refers to the `
` component itself
327 | <2> Using a CSS custom property defined in `styles.css`.
328 |
329 | NOTE: The content of our component is shielded from external CSS by a https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM[Shadow DOM^]. We can still access https://developer.mozilla.org/en-US/docs/Web/CSS/--*[CSS Custom Properties^] defined in our top-level CSS.
330 |
331 | image::styled.png[The complete, styled todo view]
332 |
333 | https://github.com/learn-vaadin/lit-element-tutorial-02-templating-properties-and-events[Browse the finished code on GitHub, role="cta"]
334 |
335 | == Next
336 | In the next part of the tutorial, we extract the state from the view component into a central Redux store.
--------------------------------------------------------------------------------
/tutorials/frontend/lit-element/03-state-management-with-redux/content.adoc:
--------------------------------------------------------------------------------
1 | = Using Redux in a LitElement app
2 | :title: Using Redux in a LitElement app
3 | :authors: marcus
4 | :type: text, video
5 | :topic: frontend
6 | :tags: LitElement, redux, state management
7 | :description: Using Redux for state management in a LitElement application
8 | :repo: https://github.com/vaadin-learning-center/lit-element-tutorial-03-state-management-with-redux
9 | :linkattrs:
10 | :imagesdir: ./images
11 |
12 | In this third tutorial, you'll learn how to use Redux for state management in a LitElement application. Check out the first two tutorials to learn how to set up a LitElement application and how to use lit-html for templating. If you aren't interested in Redux, feel free to skip over this tutorial and jump straight to the next one that covers navigation and code splitting.
13 |
14 | If you did not complete the two first tutorials in this series, you can check out the code from the previous step as a starter:
15 |
16 | https://github.com/learn-vaadin/lit-element-tutorial-02-templating-properties-and-events[Step 2 source code, role="cta"]
17 |
18 | == A brief introduction to Redux
19 | Redux is a widely used library for state management. It builds on a concept of a central _state_ that is kept in a _store_ and gets updated by _actions_. _Reducers_ define how the state is changed based on the action. You can read more about Redux on https://redux.js.org/introduction/coreconcepts[the Redux documentation page^].
20 |
21 | Redux uses an immutable data structure. Views should never update the state directly, only dispatch actions. This model works well together with LitElement, as its change detection only looks for changes of properties (like objects and arrays), not their contents.
22 |
23 | == Installing dependencies
24 | Install the following dependencies with npm:
25 |
26 | [source,terminal]
27 | ----
28 | $ npm install --save redux reselect pwa-helpers nanoid
29 | ----
30 |
31 | * `redux` is the redux library itself
32 | * `reselect` is a middleware that lets us create optimized selectors for data that are derived from the state
33 | * `pwa-helpers` is a collection of helpers for PWA that includes helpers for lazily connecting Web Components to a Redux store
34 |
35 | == Creating a reducer
36 | A reducer is the piece of code that updates the application state based on actions. This is where our application logic resides.
37 |
38 | Create a folder `*src/redux*` and inside it `*reducer.js*`.
39 |
40 | .`*src/redux/reducer.js*`
41 | [source,javascript]
42 | ----
43 | export const VisibilityFilters = { //<1>
44 | SHOW_ALL: 'All',
45 | SHOW_ACTIVE: 'Active',
46 | SHOW_COMPLETED: 'Completed'
47 | };
48 |
49 | const INITIAL_STATE = {
50 | todos: [],
51 | filter: VisibilityFilters.SHOW_ALL
52 | };
53 |
54 | export const reducer = (state = INITIAL_STATE, action) => {
55 | switch (action.type) {
56 | default:
57 | return state;
58 | }
59 | };
60 | ----
61 | <1> Move the `VisibilityFilters` from `src/views/todo-view.js` to `reducer.js`. Remember to import it in `todo-view` so the code doesn't break.
62 |
63 | The `reducer` function takes in the current state and an action and produces a new state based on the action. Here, we provide an `INITIAL_STATE` for when we start the application, and since we do not have any actions yet, we only return the state.
64 |
65 | == Setting up the store
66 | To use the reducer and access the state we need to set up a _store_. It allows our views to subscribe to state changes and dispatch actions to update the state.
67 |
68 | In the same folder, create a file `*store.js*`.
69 |
70 | To create the store, we use the `createStore` function from Redux and pass it in the reducer we created.
71 |
72 | .`*src/redux/store.js*`
73 | [source,javascript]
74 | ----
75 | import { createStore } from 'redux';
76 | import { reducer } from './reducer.js';
77 |
78 | export const store = createStore(
79 | reducer,
80 | window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__() //<1>
81 | );
82 | ----
83 | <1> Add support for the Redux DevTools extension if it's installed.
84 |
85 | TIP: The Redux DevTools extension for Chrome is helpful for inspecting and understanding the state of your application. You can download it from the https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en[Chrome Web Store]. image:redux-dev-tools.png[Redux DevTools]
86 |
87 | == Connecting todo-view to the store
88 | The next step is to make `todo-view` aware of the store and listen to updates to the state.
89 |
90 | .`*src/views/todo-view.js*`
91 | [source,diff]
92 | ----
93 | +import { connect } from 'pwa-helpers';
94 | +import { store } from '../redux/store.js';
95 | +import { VisibilityFilters } from '../redux/reducer.js';
96 |
97 | ---
98 |
99 | -class TodoView extends LitElement
100 | +class TodoView extends connect(store)(LitElement) { <1>
101 |
102 | ---
103 |
104 | - constructor() { //<2>
105 | - this.todos = [];
106 | - this.filter = VisibilityFilters.SHOW_ALL;
107 | - this.task = '';
108 | - }
109 | + stateChanged(state) { <3>
110 | + this.todos = state.todos;
111 | + this.filter = state.filter;
112 | + }
113 |
114 | ---
115 |
116 |
120 | @change="${this.updateTask}">
121 |
122 | }
123 | ----
124 | <1> Connect the component to the Redux store
125 | <2> Our state now comes from Redux, remove the constructor.
126 | <3> Add a `stateChanged` method and update the component properties based on it.
127 | <4> The `task` property is internal to our component (not in redux) and can be undefined at first, default to showing an empty string.
128 |
129 | Now, every time the app state changes, `stateChanged` gets called on the component and we can update the properties on our component.
130 |
131 | == Dispatching actions to update the state
132 | The final step in converting `todo-view` to use Redux is dispatching actions to update the state. Currently, we are still updating the todos inside the component.
133 |
134 | Actions are objects with a mandatory `type` property and any number of additional action-specific properties.
135 |
136 | .Sample action object
137 | [source,javascript]
138 | ----
139 | {
140 | type: ADD_TODO,
141 | task: 'Learn Redux'
142 | }
143 | ----
144 |
145 | There are two parts to dispatching an action:
146 |
147 | . Creating the action. We will do this in a new file `*src/redux/actions.js*`
148 | . Updating the state based on the action. We will do this in `*src/redux/reducer.js*`
149 |
150 | == Creating actions
151 |
152 | Begin by defining the actions of our application.
153 |
154 | .`*src/redux/actions.js*`
155 | [source,javascript]
156 | ----
157 | import nanoid from 'nanoid';
158 |
159 | //<1>
160 | export const ADD_TODO = 'ADD_TODO';
161 | export const UPDATE_TODO_STATUS = 'UPDATE_TODO_STATUS';
162 | export const UPDATE_FILTER = 'UPDATE_FILTER';
163 | export const CLEAR_COMPLETED = 'CLEAR_COMPLETED';
164 |
165 | export const addTodo = task => {//<2>
166 | return {
167 | type: ADD_TODO,
168 | todo: { //<3>
169 | id: nanoid(),
170 | task,
171 | complete: false
172 | }
173 | };
174 | };
175 |
176 | export const updateTodoStatus = (todo, complete) => {
177 | return {
178 | type: UPDATE_TODO_STATUS,
179 | todo,
180 | complete
181 | };
182 | };
183 |
184 | export const updateFilter = filter => {
185 | return {
186 | type: UPDATE_FILTER,
187 | filter
188 | };
189 | };
190 |
191 | export const clearCompleted = () => {
192 | return {
193 | type: CLEAR_COMPLETED
194 | };
195 | };
196 | ----
197 | <1> Define constants for the action types to avoid typos when we handle these in the reducer.
198 | <2> Action creators are functions that create the action object. They can be used to instantiate objects and to ensure that everyone dispatches the action in the same way.
199 | <3> Create a todo object based on the task. Create a unique id and set the `complete` property to false.
200 |
201 | == Updating the state with actions
202 | Before we can use the actions, we need to define how they should update the state. We do this in `*src/redux/reducer.js*`.
203 |
204 | First, import the action types:
205 |
206 | .`*src/redux/actions.js*`
207 | [source,javascript]
208 | ----
209 | import {
210 | ADD_TODO,
211 | UPDATE_FILTER,
212 | UPDATE_TODO_STATUS,
213 | CLEAR_COMPLETED
214 | } from './actions.js';
215 | ----
216 |
217 | Then update the reducer function to move the logic from `todo-view` into the reducer.
218 |
219 | .`*src/redux/actions.js*`
220 | [source,javascript]
221 | ----
222 | export const reducer = (state = INITIAL_STATE, action) => {
223 | switch (action.type) {
224 | case ADD_TODO:
225 | return {
226 | ...state,
227 | todos: [...state.todos, action.todo]
228 | };
229 | case UPDATE_TODO_STATUS:
230 | return {
231 | ...state,
232 | todos: state.todos.map(todo =>
233 | todo.id === action.todo.id //<1>
234 | ? { ...action.todo, complete: action.complete }
235 | : todo
236 | )
237 | };
238 | case UPDATE_FILTER:
239 | return {
240 | ...state,
241 | filter: action.filter
242 | };
243 | case CLEAR_COMPLETED:
244 | return {
245 | ...state,
246 | todos: state.todos.filter(todo => !todo.complete)
247 | };
248 | default:
249 | return state;
250 | }
251 | };
252 | ----
253 | <1> The only change to the logic is that we identify the todo now based on its `id` property.
254 |
255 | == Dispatching actions from todo-view
256 | Now that we have a way of creating actions and updating the state based on those actions, all that remains is to change `todo-view` to dispatch the actions instead of running the logic itself.
257 |
258 | You dispatch actions by calling `store.dispatch` with the result from an action creator (=the action object).
259 |
260 | .`*src/views/todo-view.js*`
261 | [source,javascript]
262 | ----
263 | import {
264 | addTodo,
265 | updateTodoStatus,
266 | updateFilter,
267 | clearCompleted
268 | } from '../redux/actions.js';
269 |
270 | class TodoView extends connect(store)(LitElement) {
271 | static get properties() {...}
272 | stateChanged(state) {...}
273 | render() {...}
274 | shortcutListener(e) {...}
275 | updateTask(e) {...}
276 |
277 | addTodo() {
278 | if (this.task) {
279 | store.dispatch(addTodo(this.task));
280 | this.task = '';
281 | }
282 | }
283 |
284 | updateTodoStatus(updatedTodo, complete) {
285 | store.dispatch(updateTodoStatus(updatedTodo, complete));
286 | }
287 |
288 | filterChanged(e) {
289 | store.dispatch(updateFilter(e.detail.value));
290 | }
291 |
292 | clearCompleted() {
293 | store.dispatch(clearCompleted());
294 | }
295 |
296 | applyFilter(todos) {...}
297 | }
298 | ----
299 |
300 | If you run the application, you should now again be able to use it the same way as before. Install the https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en[Redux DevTools^] to see how the state gets updated based on actions.
301 |
302 | == Optimizing todo filtering with reselect
303 | Even though our application now works the same as before and we have moved the state to a central Redux store, there is still one part that we could optimize.
304 |
305 | Currently, we filter the list of todos every time the view gets rendered, that is any time any part of the state changes. Ideally, we would only perform the filtering if the todos array changes or if the selected filter changes.
306 |
307 | To solve this, we use _reselect_, a helper that memoizes the result and only recompute it if any of the relevant inputs change.
308 |
309 | .`*src/redux/reducer.js*`
310 | [source,javascript]
311 | ----
312 | import { createSelector } from 'reselect';
313 |
314 | ...
315 |
316 | // Selectors <1>
317 | const getTodosSelector = state => state.todos;
318 | const getFilterSelector = state => state.filter;
319 |
320 | export const getVisibleTodosSelector = createSelector(
321 | getTodosSelector, getFilterSelector, <2>
322 | (todos, filter) => { <3>
323 | switch (filter) {
324 | case VisibilityFilters.SHOW_COMPLETED:
325 | return todos.filter(todo => todo.complete);
326 | case VisibilityFilters.SHOW_ACTIVE:
327 | return todos.filter(todo => !todo.complete);
328 | default:
329 | return todos;
330 | }
331 | }
332 | );
333 | ----
334 | <1> Define functions that return the parts of the state that are relevant.
335 | <2> Tell reselect that these functions should be observed for changes.
336 | <3> Define the output based on the state values.
337 |
338 | Then, update `todo-view` to use the new selector.
339 |
340 | .`*src/views/todo-view.js*`
341 | [source,diff]
342 | ----
343 | -import { VisibilityFilters } from '../redux/reducer.js';
344 | +import { VisibilityFilters, getVisibleTodosSelector } from '../redux/reducer.js';
345 |
346 | ---
347 |
348 | stateChanged(state) {
349 | - this.todos = state.todos;
350 | + this.todos = visibleTodosSelector(state);
351 | this.filter = state.filter;
352 | }
353 |
354 | ---
355 |
356 |
357 | - ${this.applyFilter(this.todos).map(
358 | + ${this.todos.map(
359 | todo => html`
360 | ----
361 |
362 | Now, we only filter the todos when needed. Reselect is a useful helper for avoiding duplication of the state.
363 |
364 | image::redux-finished-app.gif[LitElemetn Todo app converted to use Redux for state management]
365 |
366 | == The code is more complicated now. Yay?
367 | By using Redux, we arguably increased the complexity of our application quite significantly without adding any new functionality. It's reasonable to ask why you would want to do this.
368 |
369 | The advantages of Redux are more apparent when your application grows, and several components update the state. Using distinct actions to update a central state makes it easy for us to ensure that all parts of the application are in sync.
370 |
371 | Our example application is too small to show off the benefits of Redux properly. However, it is small enough to make it easy to understand the basics of using Redux.
372 |
373 | TIP: Read more about splitting up reducers and handling larger applications in the https://polymer.github.io/pwa-starter-kit/redux-and-state-management/[PWA Starter Kit^] documentation.
374 |
375 |
376 | https://github.com/learn-vaadin/lit-element-tutorial-03-state-management-with-redux[Source code for this tutorial, role="cta"]
377 |
378 | == Next
379 | In the next part of the tutorial series, we add a second view to learn how to deal with navigation. We also look at using code splitting to maintain good performance as our application grows.
--------------------------------------------------------------------------------