{"type":"doc","content":[{"type":"paragraph","content":[{"text":"The V2 frontend now uses ","type":"text"},{"text":"Redux","type":"text","marks":[{"type":"link","attrs":{"href":"https://react-redux.js.org/"}}]},{"text":" to manage global state. Redux has a pretty good guide ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://redux.js.org/tutorials/essentials/part-1-overview-concepts"}}]},{"text":" which I recommend having a read through to understand what Redux is (Part 1) and how to use it (Part 2). This page is just going to give an overview of how to use it within Freerooms.","type":"text"}]},{"type":"paragraph","content":[{"text":"At the time of writing, the separate pieces of state (","type":"text"},{"text":"slices","type":"text","marks":[{"type":"strong"}]},{"text":") currently in our Redux store are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"currentBuilding","type":"text","marks":[{"type":"code"}]},{"text":" - the Building shown on the sidebar","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"datetime","type":"text","marks":[{"type":"code"}]},{"text":" - the Date object that is used when fetching the status","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"filters","type":"text","marks":[{"type":"code"}]},{"text":" - the Filters to be used when filtering rooms and buildings","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Interacting with the Redux state centres around two hooks: ","type":"text"},{"text":"useSelector()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"useDispatch()","type":"text","marks":[{"type":"code"}]},{"text":". You can import them from ","type":"text"},{"text":"redux/hooks","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"import { useDispatch, useSelector } from \"path/to/redux/hooks\";","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Make sure you don’t use the default ","type":"text","marks":[{"type":"strong"}]},{"text":"useSelector()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text","marks":[{"type":"strong"}]},{"text":"useDispatch()","type":"text","marks":[{"type":"code"}]},{"text":" from ","type":"text","marks":[{"type":"strong"}]},{"text":"react-redux","type":"text","marks":[{"type":"code"}]},{"text":" because they aren't typed correctly.","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"useSelector()","type":"text","marks":[{"type":"code"}]},{"text":": Accessing state","type":"text"}]},{"type":"paragraph","content":[{"text":"useSelector()","type":"text","marks":[{"type":"code"}]},{"text":" takes a ","type":"text"},{"text":"selector","type":"text","marks":[{"type":"strong"}]},{"text":" function which it uses to obtain a value from the state. The state is basically one big nested object that stores all the values that make up the global state, so a selector function is used to simplify traversing through this object.","type":"text"}]},{"type":"paragraph","content":[{"text":"Each separate slice exports a selector function to obtain the value of that slice. For example, in ","type":"text"},{"text":"redux/currentBuildingSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" the selector ","type":"text"},{"text":"selectCurrentBuilding()","type":"text","marks":[{"type":"code"}]},{"text":" is exported. ","type":"text"}]},{"type":"paragraph","content":[{"text":"To access the ","type":"text"},{"text":"currentBuilding","type":"text","marks":[{"type":"code"}]},{"text":" state in a component, we import the appropriate selector and then pass that to ","type":"text"},{"text":"useSelector()","type":"text","marks":[{"type":"code"}]},{"text":". Here’s an example","type":"text"}]},{"type":"codeBlock","attrs":{"language":"jsx"},"content":[{"text":"import { selectCurrentBuilding } from \"path/to/redux/currentBuildingSlice\";\nimport { useSelector } from \"path/to/redux/hooks\";\n\nconst ExampleComponent = () => {\n const currentBuilding = useSelector(selectCurrentBuilding);\n return (\n

The current building is {currentBuilding}

\n )\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"At the time of writing, the selectors we have are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/currentBuildingSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the selector ","type":"text"},{"text":"selectCurrentBuilding()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/datetimeSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the selector ","type":"text"},{"text":"selectDatetime()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/filtersSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the selector ","type":"text"},{"text":"selectFilters()","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"useDispatch()","type":"text","marks":[{"type":"code"}]},{"text":": Updating state","type":"text"}]},{"type":"paragraph","content":[{"text":"useDispatch()","type":"text","marks":[{"type":"code"}]},{"text":" takes an ","type":"text"},{"text":"action","type":"text","marks":[{"type":"strong"}]},{"text":" and “dispatches” it to the store. Actions are an object that look something like ","type":"text"},{"text":"{type: string, payload?: any}","type":"text","marks":[{"type":"code"}]},{"text":", and describe what ","type":"text"},{"text":"type ","type":"text","marks":[{"type":"strong"}]},{"text":"of update we are performing (e.g. set currentBuilding, or clearFilters) and the ","type":"text"},{"text":"payload ","type":"text","marks":[{"type":"strong"}]},{"text":"for that action (e.g. the new currentBuilding).","type":"text"}]},{"type":"paragraph","content":[{"text":"Luckily, there’s no need to manually create actions because each slice exports ","type":"text"},{"text":"action creator","type":"text","marks":[{"type":"strong"}]},{"text":" functions for each type of update we might want to perform on the slice. For example, in ","type":"text"},{"text":"hooks/filtersSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" we export three action creators - ","type":"text"},{"text":"setFilter()","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"unsetFilter()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"clearFilters()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"To update the state, import the appropriate action creator, call it, then pass the result to ","type":"text"},{"text":"useDispatch()","type":"text","marks":[{"type":"code"}]},{"text":". For example:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"jsx"},"content":[{"text":"import { clearFilters, setFilter, unsetFilter } from \"path/to/redux/filtersSlice\";\nimport { useDispatch } from \"path/to/redux/hooks\";\n\nconst ExampleComponent = () => {\n return (\n

\n \n \n \n

\n )\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"At the time of writing, the action creators we have are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/currentBuildingSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the action creator ","type":"text"},{"text":"setBuilding()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/datetimeSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the action creator ","type":"text"},{"text":"setDatetime()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hooks/filtersSlice.ts","type":"text","marks":[{"type":"code"}]},{"text":" exports the action creators ","type":"text"},{"text":"setFilter()","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"unsetFilter()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"clearFilters()","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Adding more state","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"When adding new pieces of state to Redux, make sure that it’s actually something that needs to go there. If it’s only used in your component or children of your component, then it’s probably better to just use a ","type":"text"},{"text":"useState","type":"text","marks":[{"type":"code"}]},{"text":" hook. If it relies on backend data, then you may want to use/create an SWR data fetching hook.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"To add a new piece of state to Redux, we need to create a new slice. As an example, we’ll walk through how we created the ","type":"text"},{"text":"filtersSlice","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The first thing we want to do is ","type":"text"},{"text":"declare the type of this slice","type":"text","marks":[{"type":"strong"}]},{"text":". Generally, this should be an object containing the key “value” whose type is the type of the state we want to store (more on why we need to put it in an object later). Here is the type we created for ","type":"text"},{"text":"filtersSlice","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"interface FiltersState {\n value: Filters\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, we need to ","type":"text"},{"text":"declare the initial state of this slice","type":"text","marks":[{"type":"strong"}]},{"text":". In this case, the initial filters are nothing:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"const initialState: FiltersState = {\n value: {}\n};","type":"text"}]},{"type":"paragraph","content":[{"text":"Now we can ","type":"text"},{"text":"create a slice","type":"text","marks":[{"type":"strong"}]},{"text":". We’ll use the ","type":"text"},{"text":"createSlice()","type":"text","marks":[{"type":"code"}]},{"text":" function from Redux toolkit and give it a name (for debugging), the initial state, and an object containing our reducers (empty for now):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"import { createSlice } from \"@reduxjs/toolkit\";\n\nconst filtersSlice = createSlice({\n name: \"filters\",\n initialState,\n reducers: {}\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"Now we want to ","type":"text"},{"text":"create","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"reducers","type":"text","marks":[{"type":"strong"}]},{"text":". We create a reducer for every action (state update) we want to perform, which takes the previous state and the action’s payload and dictates how we should use the payload to update the state.","type":"text"}]},{"type":"expand","attrs":{"title":"How do reducers work?"},"content":[{"type":"paragraph","content":[{"text":"The given ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code"}]},{"text":" object is called a “draft”, and we write whatever changes we want to make to this draft. Redux then updates the state to the completed draft. ","type":"text"},{"text":"You cannot replace ","type":"text","marks":[{"type":"em"}]},{"text":"the ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code"}]},{"text":" argument (e.g. ","type":"text"},{"text":"state = newState","type":"text","marks":[{"type":"code"}]},{"text":") as this means the draft is untouched.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is the opposite of ","type":"text"},{"text":"useState()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"setState()","type":"text","marks":[{"type":"code"}]},{"text":" where each new state ","type":"text"},{"text":"must be","type":"text","marks":[{"type":"em"}]},{"text":" a distinct object. Under the hood, Redux does create new distinct objects, but it exposes this interface to make it easier to work with arrays and objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"It’s also why we wrap non-object states in an object, so that we can update the field rather than replace the value. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Our first reducer is ","type":"text"},{"text":"unsetFilter()","type":"text","marks":[{"type":"code"}]},{"text":" which takes a key and unsets the filter that they key refers to. We'll add this to our reducers object like so:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"reducers: {\n unsetFilter: (state, action: PayloadAction) => {\n if (Object.keys(state).includes(action.payload)) {\n // otherFilters contains all keys besides action.payload\n const { [action.payload]: unset, ...otherFilters } = state.value;\n state.value = otherFilters;\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Let’s create some more reducers. We can create reducers that have ","type":"text"},{"text":"no payload","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"clearFilters: (state) => {\n state.value = {};\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"We can also create reducers that take ","type":"text"},{"text":"multiple values as a payload","type":"text","marks":[{"type":"strong"}]},{"text":". We can technically only take in one argument though, so this payload should be an object:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"setFilter: (state, action: PayloadAction<{ key: keyof Filters, value: string }>) => {\n const { key, value } = action.payload;\n state.value[key] = value;\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"And now our slice is done, all that’s left is to export stuff! First we ","type":"text"},{"text":"export the action creators","type":"text","marks":[{"type":"strong"}]},{"text":", which we can obtain from the ","type":"text"},{"text":"actions","type":"text","marks":[{"type":"code"}]},{"text":" field of our slice. The keys match the reducers we created.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"export const { setFilter, unsetFilter, clearFilters } = filtersSlice.actions;","type":"text"}]},{"type":"paragraph","content":[{"text":"Next we ","type":"text"},{"text":"export the selector(s)","type":"text","marks":[{"type":"strong"}]},{"text":". We access the state object for this slice through ","type":"text"},{"text":"state.key","type":"text","marks":[{"type":"code"}]},{"text":" where ","type":"text"},{"text":"key","type":"text","marks":[{"type":"code"}]},{"text":" is the key we use in the next step to add this slice to the store. Note that this will throw type errors until we do the next step.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"export const selectFilters = (state: RootState) => state.filters.value;","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, we want to ","type":"text"},{"text":"add the slice to the store","type":"text","marks":[{"type":"strong"}]},{"text":". We first need to export the combined reducer for this slice","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"export default filtersSlice.reducer;","type":"text"}]},{"type":"paragraph","content":[{"text":"then import it in ","type":"text"},{"text":"redux/store.ts","type":"text","marks":[{"type":"code"}]},{"text":" and add it to the ","type":"text"},{"text":"reducers","type":"text","marks":[{"type":"code"}]},{"text":" field in ","type":"text"},{"text":"configureStore()","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","attrs":{"language":"typescript"},"content":[{"text":"import filtersReducer from \"./filtersSlice\";\n\nconst store = configureStore({\n reducer: {\n currentBuilding: currentBuildingReducer,\n datetime: datetimeReducer,\n filters: filtersReducer // here!\n },\n ...\n}","type":"text"}]}],"version":1}

Browser not supported