Mark's Dev Blog

Practical Redux, Part 11: Nested Data and Trees

Mon, 01 Jan 2018 16:46:44 -0500

Intro

Last time in Part 10, we built modal dialog and context menu systems that were driven by Redux. This time, we're going to add creation of new entities, implement loading of nested relational data, and display that nested data in a tree component.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #14: Practical Redux Part 11 WIP, and the final "clean" commits can be seen in in PR #15: Practical Redux Part 11 Final.

I'll be linking to each "final" commit as I go through the post, as well as specific files in those commits. I won't paste every changed file in here or show every single changed line, to save space, but rather try to show the most relevant changes for each commit as appropriate.

Library Updates

It's been a few months since the last post, and both React and Semantic-UI-React have been updated. At the time of this writing, the latest versions are React 16.2 and Semantic-UI-React 0.77.

Right now, this project is on React 15.6. Since our code currently compiles and runs with no warnings, we should be able to safely upgrade to React 16 just by updating our package versions. The main concern would be making sure that our other libraries are also compatible with React 16. Since we previously updated libraries that depended on PropTypes, that's not much of an issue here. The only other issue is our use of Portals for context menus. There's a newer version of the react-portal library that supports both React 15 and React 16's differing Portal APIs, so we'll update that as well.

yarn upgrade react@16.2 react-dom@16.2 react-portal@4.1.2

Commit 415fc95: Upgrade to React 16.2

There's one small code tweak we need to make, which is changing Portal to be a named import instead of a default import.

Commit 11b7ef4: Update React-Portal usage to match version 4.x

We'll also upgrade Semantic-UI-React.

yarn upgrade semantic-ui-react@0.77

Commit 6e1be79: Update Semantic-UI-React

As a side note, I actually experienced some issues with Yarn's offline mirror feature doing these upgrades. When I upgraded React, the older package tarballs were correctly removed from the ./offline-mirror feature, but the new tarballs weren't added. Even more oddly, the SUI-React tarball showed up correctly. I eventually resolved this by running yarn cache clean, then re-attempting the package updates.

Adding New Pilots

So far, we have focused on interacting with the list of pilots. Project Mini-Mek currently has the ability to show a list of pilots, update pilot entries, and delete pilots. However, we're still missing a key capability: actually creating new pilot entries (the 'C' in "CRUD").

We'll tackle that shortly, but first we'll do a bit of code cleanup related to the pilots feature.

Pilots Code Cleanup

The <PilotDetails> form has some inputs that are in separate rows, but each only takes up a part of the row, leaving some empty space. We can consolidate those into a couple combined rows.

Commit 51377a7: Rearrange PilotDetails form to be more compact

features/pilots/PilotDetails/PilotDetails.jsx

+               <Form.Group>
                    <Form.Field
                        name="rank"
                        label="Rank"
-                       width={16}
+                       width={10}
                   </Form.Field
// omit other input values and fields
+               </Form.Group>
+              <Form.Group widths="equal">
                   <Form.Field
                        name="gunnery"
                        label="Gunnery"
                   </Form.Field>
+              </Form.Group>

This looks a bit nicer:

Also, the current list of pilot ranks is hardcoded in the format that SUI-React's Dropdown wants. We can turn that into a simple constants array, and then derive the display data as needed.

Commit 02bd796: Simplify pilot rank constant definition

features/pilots/pilotsConstants.js

export const PILOT_EDIT_STOP = "PILOT_EDIT_STOP";

+export const PILOT_RANKS = [
+   "Private",
+   "Corporal",
+   "Sergeant",
+   "Lieutenant",
+   "Captain",
+   "Major",
+   "Colonel",
+];

features/pilots/PilotDetails/PilotDetails.jsx

import {selectCurrentPilot, selectIsEditingPilot} from "../pilotsSelectors";
+import {PILOT_RANKS} from "../pilotsConstants";

-const RANKS = [
-   {value: "Private", text : "Private"},
-   {value: "Corporal", text : "Corporal"},
-   {value: "Sergeant", text : "Sergeant"},
-   {value: "Lieutenant", text : "Lieutenant"},
-   {value: "Captain", text : "Captain"},
-   {value: "Major", text : "Major"},
-   {value: "Colonel", text : "Colonel"},
-];
+const RANKS = PILOT_RANKS.map(rank => ({value : rank, text : rank}));

Creating New Entities

We currently have the ability to edit items, and our editing feature has generic actions and reducers for updating the contents of Redux-ORM entities with new values. However, our editing feature is built around the assumption that there are existing items in the state.entities "current values" slice, and that editing an item should copy that item from state.entities to the state.editingEntities "work-in-progress" slice. That assumption no longer holds true for adding and editing new items - we can't copy them because they don't yet exist in the entities slice.

We need some additional support for creating new entities directly into the editingEntities slice so that our edit actions can work on them. In addition, our "save edits" logic also assumes that an item with that type and ID already exists in entities, and tries to look up that Model instance to apply the updates from the edited model. We need to update the save logic to handle this case as well.

Commit 1c8e64b: Add ability to edit a new entity

features/editing/editingReducer.js

import {
    EDIT_ITEM_EXISTING,
+   EDIT_ITEM_NEW,
    EDIT_ITEM_UPDATE,
    EDIT_ITEM_APPLY,
    EDIT_ITEM_STOP,
    EDIT_ITEM_RESET,
} from "./editingConstants";

export function updateEditedEntity(sourceEntities, destinationEntities, payload) {
    // Start by reading our "work-in-progress" data
    const readSession = orm.session(sourceEntities);

    const {itemType, itemID} = payload;

    // Look up the model instance for the requested item
    const model = getModelByType(readSession, itemType, itemID);


    // We of course will be updating our "current" relational data
    let writeSession = orm.session(destinationEntities);

    const ModelClass = writeSession[itemType];

    if(ModelClass.hasId(itemID)) {
        // Look up the original Model instance for the top item
        const existingItem = ModelClass.withId(itemID);

        if(existingItem.updateFrom) {
            // Each model class should know how to properly update itself and its
            // relations from another model of the same type.  Ask the original model to
            // update itself based on the "work-in-progress" model. Redux-ORM will apply
            // those changes as we go, and update `session.state` immutably.
            existingItem.updateFrom(model);
        }
    }
+    else {
+        const itemContents = model.toJSON();
+        ModelClass.parse(itemContents);
+    }

    // Return the updated "current" relational data.
    return writeSession.state;
}

+export function editItemNew(state, payload) {
+   const editingEntities = selectEditingEntities(state);
+
+   const updatedEditingEntities = createEntity(editingEntities, payload);
+   return updateEditingEntitiesState(state, updatedEditingEntities);
+}

const editingFeatureReducer = createReducer({}, {
    [EDIT_ITEM_EXISTING] : editItemExisting,
+   [EDIT_ITEM_NEW] : editItemNew,
    [EDIT_ITEM_UPDATE] : editItemUpdate,
    [EDIT_ITEM_APPLY] : editItemApply,
    [EDIT_ITEM_STOP] : editItemStop,
    [EDIT_ITEM_RESET] : editItemReset,
});

export default editingFeatureReducer;

The EDIT_ITEM_NEW action payload will contain {itemType, itemID, newItemAttributes}. Because we've been consistent about naming those fields in our other action types, the case reducer can reuse our existing helper methods for basic entity CRUD, which makes this easy to implement.

Also, we already have the ability to parse in plain JSON representations of our model classes, and are using that as the transfer mechanism to copy values from entities to editedEntities. We can easily add that logic in here so that saving new items creates them in entities.

Generating New Pilot Entries

The next step is to actually generate a new Pilot entry and dispatch EDIT_ITEM_NEW with the plain JSON representation of that pilot entry. This brings up several things we need to think about.

First, we need to have unique IDs for each Pilot entry. Thus far we've simply used hardcoded integers in our sample data, but we're going to need to generate IDs ourselves here for a couple reasons. Redux-ORM does have support for auto-incrementing numerical IDs based on the max ID value in a "table", but that won't work with our editing approach - the editingEntities.Pilots table would have no existing items, so it would likely give us a 0 or a 1 as the ID every time. We could calculate the numerical ID based on the contents of state.entities, but really, relying on the existing entries is not a great approach. It's better if we actually generate unique IDs.

However, this also has some problems. Generating unique IDs involves use of random numbers. While there's nothing preventing you from generating random numbers in a Redux reducer, doing so makes that reducer "impure", and it will return inconsistent output. A Redux reducer should never contain randomness - it should always be handled outside the reducer.

For our purposes, we can handle this by generating new pilot IDs in our action creator. If we needed to actually generate random numbers, there's a couple approaches you can use. I won't cover those here, but see the posts Roll the Dice: Random Numbers in Redux and Random in Redux for solutions and examples.

Another big question is where the logic for default model attribute values should live, and how to override those defaults when a new model instance is created. I've chosen to define a plain object of attributes in the same file as the model class, add a static generate() function to the model class, and merge together the default attributes and any attributes provided by the caller.

Finally, we're running into an issue with an optimization we applied earlier. We have a memoized getEntitiesSession selector that ensures we only create a single Redux-ORM Session instance for each update to the state.entities slice, just so we aren't creating separate Session instances every time a connected component's mapState function re-runs. If we were to use that selector and get that "shared" Session instance, then use that to generate a new Pilot instance, the shared Session would swap out its session.state field with the updated data. That could potentially cause problems, so we really want to avoid reusing that Session in this process. My solution is to create a getUnsharedEntitiesSession selector that just creates a new Session, which can then be safely used for manipulating data instead of just reading values.

Commit 0af9785: Implement logic to add and edit a new pilot

features/entities/entitySelectors.js

+export const getUnsharedEntitiesSession = (state) => {
+   const entities = selectEntities(state);
+   return orm.session(entities);
+}

features/pilots/Pilot.js

+const defaultAttributes = {
+   name : "New Pilot",
+   rank : "Private",
+   gunnery : 4,
+   piloting : 5,
+   age : 25,
+};

export default class Pilot extends Model {
+   static generate(newAttributes = {}) {
+       const combinedAttributes = {
+           ...defaultAttributes,
+           ...newAttributes,
+       };
+
+       return this.create(combinedAttributes);
+   }
}

features/pilots/pilotsActions.js

+import cuid from "cuid";

import {
    editExistingItem,
+    editNewItem,
    applyItemEdits,
    stopEditingItem
} from "features/editing/editingActions";

import {selectCurrentPilot, selectIsEditingPilot} from "./pilotsSelectors";
+import {getUnsharedEntitiesSession} from "features/entities/entitySelectors";

+export function addNewPilot() {
+   return (dispatch, getState) => {
+       const session = getUnsharedEntitiesSession(getState());
+       const {Pilot} = session;
+
+       const id = cuid();
+
+       const newPilot = Pilot.generate({id});
+
+       const pilotContents = newPilot.toJSON();
+
+       dispatch(editNewItem("Pilot", id, pilotContents));
+       dispatch(selectPilot(id));
+       dispatch({type : PILOT_EDIT_START});
+   }
=}

Way back at the start of the series, we added the cuid module for generating IDs. We can finally make use of that here.

Our addNewPilot() thunk first creates a Session instance we can use for modifying data. We generate a new ID value, then pass the ID as a field to Pilot.generate(), which returns a Pilot instance. We can serialize that to a plain JS object, and dispatch the actions to edit the item, mark it as selected, and update our state to reflect that we're currently editing a pilot.

Pilot Form Updates

With the logic in place, we need to actually add some UI to call addNewPilot(). We'll add a new section below the <PilotDetails> form with a button that lets us add and start editing a new pilot.

Commit 179cc52: Add an "Add New Pilot" button

features/pilots/PilotDetails/PilotCommands.jsx

import React from "react";
import {connect} from "react-redux";
import {Button} from "semantic-ui-react";

import {selectIsEditingPilot} from "../pilotsSelectors";
import {addNewPilot} from "../pilotsActions";

const mapState = (state) => {
    const isEditingPilot = selectIsEditingPilot(state);

    return {isEditingPilot};
}

const buttonWidth = 140;

const actions = {addNewPilot};

const PilotCommands = (props) => (
    <Button
        primary
        disabled={props.isEditingPilot}
        type="button"
        onClick={props.addNewPilot}
        style={{width : buttonWidth, marginRight : 10}}
    >
        Add New Pilot
    </Button>
);

export default connect(mapState, actions)(PilotCommands);

features/pilots/Pilots/Pilots.jsx

import PilotsList from "../PilotsList";
import PilotDetails from "../PilotDetails";
+import PilotCommands from "../PilotDetails/PilotCommands";


export default class Pilots extends Component {
    render() {
    // skip other rendering code
                         <Segment >
                            <PilotDetails />
                        </Segment>
+                       <Segment>
+                           <PilotCommands />
+                       </Segment>
                    </Grid.Column>
                </Grid>
            </Segment>
    }

And now we can hit "Add New Pilot", edit the details, save the edits, and see the pilot added to the list:

Fixing Pilot Selection Logic

There's one issue left from the current code. If we click "Add New Pilot" and then click "Cancel Edits", the "Start Editing" button is still enabled. This is because we still have state.pilots.selectedPilot set to the ID of the generated pilot and that isn't getting cleared out when we hit Cancel, so it thinks a valid pilot is still selected. We really need to clear the selection if we're canceling the edit.

There's probably a few ways we could handle this. For now, we'll implement the behavior on the action creation side, by checking to see if it's a new pilot when we stop editing.

In addition, the logic for the stopEditingPilot() and cancelEditingPilot() thunks is looking pretty similar. We can consolidate that logic into a single function with a flag that indicates whether we should apply the edits or not.

Commit 8ceeece: Extract common "stop editing pilot" logic

features/pilots/pilotsActions.js


import {selectCurrentPilot, selectIsEditingPilot} from "./pilotsSelectors";
-import {getUnsharedEntitiesSession} from "features/entities/entitySelectors";
import {getEntitiesSession, getUnsharedEntitiesSession} from "features/entities/entitySelectors";

+export function handleStopEditingPilot(applyEdits = true) {
+   return (dispatch, getState) => {
+       const currentPilot = selectCurrentPilot(getState());
+
+       // Determine if it's a new pilot based on the "current" slice contents
+       const session = getEntitiesSession(getState());
+       const {Pilot} = session;
+
+       const isNewPilot = !Pilot.hasId(currentPilot);
+
+       dispatch({type : PILOT_EDIT_STOP});
+
+       if(applyEdits) {
+           dispatch(applyItemEdits("Pilot", currentPilot));
+       }
+
+       dispatch(stopEditingItem("Pilot", currentPilot));
+
+       if(isNewPilot) {
+           dispatch({type : PILOT_SELECT, payload : {currentPilot : null}});
+       }
+   }
+}


export function stopEditingPilot() {
    return (dispatch, getState) => {
-       const currentPilot = selectCurrentPilot(getState());
-
-       dispatch({type : PILOT_EDIT_STOP});
-       dispatch(applyItemEdits("Pilot", currentPilot));
-       dispatch(stopEditingItem("Pilot", currentPilot));
+       dispatch(handleStopEditingPilot(true));
    }
}

export function cancelEditingPilot() {
    return (dispatch, getState) => {
-       const currentPilot = selectCurrentPilot(getState());
-
-        dispatch({type : PILOT_EDIT_STOP});
-        dispatch(stopEditingItem("Pilot", currentPilot));
+        dispatch(handleStopEditingPilot(false));
    }
}

We can determine if it's a new pilot by seeing whether the currentPilot ID value actually exists in the "current" Pilot table. From there, we clear out the "editing pilot" flag, save the edits if appropriate, clear out the entry from the "editing" slice, and clear the selection if necessary.

Reorganizing the Unit Info Display

Most of our work so far has focused on the "Pilots" tab, although we've worked some on the "Unit Info" and "Mechs" tabs. Meanwhile, the "Unit Organization" tab has been left alone since we put together the initial layout. In preparation for our next major chunk of feature work, we're going to consolidate things by moving the tree from the "Unit Organization" tab into our main "Unit Info" tab.

We'll start by extracting a separate <UnitInfoForm> component from the existing <UnitInfo> panel.

Commit d2ac9f6: Extract a separate UnitInfoForm component

features/unitInfo/UnitInfo/UnitInfo.jsx

import React, {Component} from "react";
import {
    Segment
} from "semantic-ui-react";

import UnitInfoForm from "./UnitInfoForm";

class UnitInfo extends Component {

    render() {
        return (
            <Segment attached="bottom">
                <UnitInfoForm />
            </Segment>
        );
    }
}

export default UnitInfo;

Code-wise, this was really more like renaming UnitInfo.jsx to UnitInfoForm.jsx, removing a couple of components from its render method, and then creating a new UnitInfo.jsx file to replace it.

Commit 0ec6f08: Move UnitOrganization under UnitInfo and remove unused tab

app/layout/App.js

import UnitInfo from "features/unitInfo/UnitInfo";
import Pilots from "features/pilots/Pilots";
import Mechs from "features/mechs/Mechs";
-import UnitOrganization from "features/unitOrganization/UnitOrganization";
import Tools from "features/tools/Tools";
import ModalManager from "features/modals/ModalManager";

class App extends Component {
    render() {
        const tabs = [
            {name : "unitInfo", label : "Unit Info", component : UnitInfo,},
            {name : "pilots", label : "Pilots", component : Pilots,},
            {name : "mechs", label : "Mechs", component : Mechs,},
-           {name : "unitOrganization", label : "Unit Organization", component : UnitOrganization},
            {name : "tools", label : "Tools", component : Tools},
        ];

Next, we remove the <UnitOrganization> component so it's no longer rendered as a separate tab, and move its file inside features/unitInfo.

Then, we can show <UnitOrganization> inside of the revamped <UnitInfo> panel:

Commit d18161b: Add UnitOrganization component to UnitInfo panel

import React, {Component} from "react";
import {
    Segment,
    Grid,
    Header,
} from "semantic-ui-react";

import UnitOrganization from "../UnitOrganization";
import UnitInfoForm from "./UnitInfoForm";

class UnitInfo extends Component {
    render() {
        return (
            <Segment>
                <Grid>
                    <Grid.Column width={10}>
                        <Header as="h3">Unit Table of Organization</Header>
                        <Segment>
                            <UnitOrganization />
                        </Segment>
                    </Grid.Column>
                    <Grid.Column width={6}>
                        <Header as="h3">Edit Unit</Header>
                        <Segment>
                            <UnitInfoForm />
                        </Segment>
                    </Grid.Column>
                </Grid>
            </Segment>
        );
    }
}

export default UnitInfo;

We'll consolidate the <UnitInfoForm> "Affiliation" and "Color" fields into one row, similar to what we did with the <PilotDetailsForm> earlier.

Commit 3c1be29: Improve UnitInfoForm layout

And finally, we'll rename <UnitOrganization> to <UnitOrganizationTree>.

Commit 361a1aa: Rename UnitOrganization to UnitOrganizationTree

Note that since we've started this project, <UnitInfo> has gone from being unconnected, to connected, and is now unconnected again. This is one of the reasons why I dislike specifically splitting code into containers and components folders, or having separate SomeComponent and SomeComponentContainer files - it's very possible that a component's usage could change over time. Now, I will say that there's a difference between "app-specific" components and truly generic components. We do have a common/components folder in this project, and it's very reasonable to put completely generic components in there. But, for anything that's actually related to app concepts, I'd rather put it in an appropriate feature folder and just keep it there, regardless of whether it's connected or not. (I have a saved Reactiflux chat log where I discuss my thoughts on Redux "container" components and structuring.)

Loading Nested Unit Data

Our data schema so far has been pretty simple. The sampleData.js file currently looks like this:

const sampleData = {
    unit : {
        name : "Black Widow Company",
        affiliation : "wd",
        color : "black"
    },
    pilots : [
        {
            id : 1,
            name : "Natasha Kerensky",
            rank : "Captain",
            gunnery : 2,
            piloting : 2,
            age : 52,
            mech : 1,
        },
   ],
   designs : [
        {
            id : "STG-3R",
            name : "Stinger",
            weight : 20,
        },
   ],
   mechs : [
        {
            id : 1,
            type : "WHM-6R",
            pilot : 1,
        },
   ]
}

We've got flat arrays for pilots, designs, and mechs, and we only have a single unit defined. The arrays themselves already reference each other by foreign key IDs, so there's not much processing needed.

It's time to start adding some additional depth to this schema. As mentioned in Part 0 and Part 3, in the Battletech game universe mechs are normally organized into "Lances" of 4 mechs, and "Companies" of 3 lances. We're going to apply that organizational pattern to our current sample data.

Long-term, it would make sense to support loading multiple units, and possibly having the pilots and mechs defined in a nested data tree that matches the organizational structure. We're not going to go quite that far yet. For now, we're going to start treating the unit as another model type in our database, and store the pilots and mechs arrays inside of the unit definition. We'll also add a lances array that stores which pilots belong to which lances. The designs array will stay outside the unit field in the data, because mech designs are universal across factions and not specific to a unit.

This also means that we're going to need to make our "parsing" logic a bit more complex, because it will need to handle the now-nested data correctly.

Parsing Unit Entries

The first step is to create our Unit model.

Commit 87a5f9e: Add a Unit model class

features/unitInfo/Unit.js

import {Model, many, attr} from "redux-orm";

export default class Unit extends Model {
    static modelName = "Unit";

    static fields = {
        id : attr(),
        name : attr(),
        affiliation : attr(),
        color : attr(),
        pilots : many("Pilot"),
        mechs : many("Mech")
    };

    static parse(unitData) {
        const {Pilot, Mech} = this.session;

        const parsedData = {
            ...unitData,
            pilots : unitData.pilots.map(pilotEntry => Pilot.parse(pilotEntry)),
            mechs : unitData.mechs.map(mechEntry => Mech.parse(mechEntry)),
        };

        return this.upsert(parsedData);
    }
}

There's a few things to note in this file.

First, for other model classes so far, I've tended to write the fields definition as static get fields() {}, and usually defined the modelName field separately, like Pilot.modelName = "Pilot";. This is somewhat for historical reasons - I first began using Redux-ORM before I had the Class Properties syntax available in my project, so I used getters and plain assignments instead. In theory, all three of these should be equivalent:

// 1) Field declarations added to the class later
class Pilot extends Model {}
Pilot.fields = {
  id : attr()
};

// 2) Static getters
class Pilot extends Model {
    static get fields() {
        return {
            id : attr()
        };
    }
}

// 3) The Stage 3 Class Properties syntax
class Pilot extends Model {
    static fields = {
        id : attr()
    };
}

Going forward, I'll stick with the Class Properties syntax, and define fields and modelName inside the class body.

Next, for the first time we're using Redux-ORM's many() relation. This will set up "through tables" that map together the related IDs from both tables. In this case, we'll have auto-generated model types called UnitPilots and UnitMechs, and a sample UnitPilots entry might look like {id : 2, fromUnitId : 1, toPilotId : 3}. If we have an instance of a Unit, the unitModel.pilots field will be a Redux-ORM QuerySet that can be turned into an array of Pilot models or plain JS objects.

Finally, notice that the Unit.parse() method is more complicated than the others we've seen thus far. Since our other classes haven't had to deal with any nesting, our other parse() methods have just looked like return this.create(data) or return this.upsert(data). Now, we need to continue recursing down through the nested data to parse any Pilot or Mech entries.

Our data loading reducer already runs pilots.map(pilotEntry => Pilot.parse(pilotEntry)), and the same for mechs. We can do that here instead, but there's a bit of a trick involved. Redux-ORM creates custom subclasses of your model classes every time you instantiate a Session. Those subclasses are attached to the Session instance, and any operations involving those subclasses are applied to that specific Session. So, we can't just do import Pilot from "features/pilots/Pilot" here - we need to get a reference to the specific Pilot subclass on the current Session instance related to where Unit.parse() is being called.

Fortunately, the actual solution is pretty easy. When this code runs, this inside the static method will refer to the Session-specific subclass of Unit, and Redux-ORM makes the Session available as this.session. So, in the same way that we did const {Pilot} = session over in the reducer, we can do const {Pilot} = this.session here inside the static class method.

From there, we call Pilot.parse() and Mech.parse() as we map over the arrays. Those create the proper entries inside the Session, and then passing those newly-created model entries into this.upsert() instead of the original plain objects will tell Redux-ORM to set up the associations between the Unit and those related models.

With that done, we can restructure the sample data to match:

Commit 58b9115: Restructure sample data to include pilots/mechs inside unit definition

And then we need to update the data loading reducer to call Unit.parse() instead of parsing the individual pilots and mechs directly:

Commit c8cabf2: Update data loading reducer to parse nested unit definition

app/reducers/entitiesReducer.js

export function loadData(state, payload) {
    // Create a Redux-ORM session from our entities "tables"
    const session = orm.session(state);
    // Get a reference to the correct version of model classes for this Session
-   const {Pilot, MechDesign, Mech} = session;
+   const {Unit, Pilot, Mech, MechDesign} = session;

-   const {pilots, designs, mechs} = payload;
+   const {unit, designs} = payload;

    // Clear out any existing models from state so that we can avoid
    // conflicts from the new data coming in if data is reloaded
-   [Pilot, Mech, MechDesign].forEach(modelType => {
+   [Unit, Pilot, Mech, MechDesign].forEach(modelType => {
        modelType.all().toModelArray().forEach(model => model.delete());
    });

    // Immutably update the session state as we insert items
+    Unit.parse(unit);
-    pilots.forEach(pilot => Pilot.parse(pilot));

    designs.forEach(design => MechDesign.parse(design));
-    mechs.forEach(mech => Mech.parse(mech));

    // Return the new "tables" object containing the updates
    return session.state;
}

Extracting Factions

The list of factions in the "Affiliation" dropdown is currently hardcoded, and also in a format specific to the SUI-React <Dropdown> component. We can turn those into a Faction model and extract those from the <UnitInfoForm> component.

First, we'll create the model class and the sample data, then update the data loading reducer to parse in the Faction entries.

Commit 29eb97b: Add a Faction model class

features/unitInfo/Faction.js

import {Model, attr} from "redux-orm";

export default class Faction extends Model {
    static modelName = "Faction";

    static fields = {
        id : attr(),
        name : attr(),
    };

    static parse(factionData) {
        return this.upsert(factionData);
    }
}

Commit da9dcbf: Add factions to sample data and parse them

data/sampleData.js

    designs : [
        // ommitted
    ],
+   factions : [
+       {id : "cc", name : "Capellan Confederation"},
+       {id : "dc", name : "Draconis Combine"},
+       {id : "elh", name : "Eridani Light Horse"},
+       {id : "fs", name : "Federated Suns"},
+       {id : "fwl", name : "Free Worlds League"},
+       {id : "hr", name : "Hansen's Roughriders"},
+       {id : "lc", name : "Lyran Commonwealth"},
+       {id : "wd", name : "Wolf's Dragoons"},
+   ]
};

app/reducers/entitiesReducer.js

export function loadData(state, payload) {
    // Create a Redux-ORM session from our entities "tables"
    const session = orm.session(state);
    // Get a reference to the correct version of model classes for this Session
-   const {Unit, Pilot, Mech, MechDesign} = session;
+   const {Unit, Faction, Pilot, Mech, MechDesign} = session;

-   const {unit, designs} = payload;
+   const {unit, factions, designs} = payload;

    // Clear out any existing models from state so that we can avoid
    // conflicts from the new data coming in if data is reloaded
-   [Unit, Faction, Pilot, Mech, MechDesign].forEach(modelType => {
+   [Unit, Faction, Pilot, Mech, MechDesign].forEach(modelType => {
        modelType.all().toModelArray().forEach(model => model.delete());
    });

    // Immutably update the session state as we insert items
    Unit.parse(unit);

+    factions.forEach(faction => Faction.parse(faction));
    designs.forEach(design => MechDesign.parse(design));

    // Return the new "tables" object containing the updates
    return session.state;
}

Next, now that factions are also a model type, our Unit.affiliation field needs to change from a simple attribute to a foreign key reference to the Faction table.

Commit 740e602: Update Unit affiliation to point to Factions

features/unitInfo/Unit.js

-import {Model, many, attr} from "redux-orm";
+import {Model, many, fk, attr} from "redux-orm";


export default class Unit extends Model {
    static modelName = "Unit";

    static fields = {
        id : attr(),
        name : attr(),
-       affiliation : attr(),
+       affiliation : fk("Faction"),
        color : attr(),
        pilots : many("Pilot"),
        mechs : many("Mech")
    };

Now we can update the <UnitInfoForm> component to read the list of factions from Redux and display them.

Commit 50aaf10: Use faction entries to populate affiliation dropdown

features/unitInfo/UnitInfo/UnitInfoForm.jsx

-const FACTIONS = [
-   {value : "cc", text : "Capellan Confederation"},
-   {value : "dc", text : "Draconis Combine"},
-   {value : "elh", text : "Eridani Light Horse"},
-   {value : "fs", text : "Federated Suns"},
-   {value : "fwl", text : "Free Worlds League"},
-   {value : "hr", text : "Hansen's Roughriders"},
-   {value : "lc", text : "Lyran Commonwealth"},
-   {value : "wd", text : "Wolf's Dragoons"},
-];

-const mapState = (state) => ({
-    unitInfo : selectUnitInfo(state),
-});

+import {getEntitiesSession} from "features/entities/entitySelectors";

+const mapState = (state) => {
+    const session = getEntitiesSession(state);
+    const {Faction} = session;
+
+    const factions = Faction.all().toRefArray();
+
+    const unitInfo = selectUnitInfo(state);
+
+    return {factions,unitInfo};
+};

class UnitInfoForm extends Component {
    render() {
-       const {unitInfo, updateUnitInfo} = this.props;
+       const {unitInfo, updateUnitInfo, factions} = this.props;
        const {name, affiliation, color} = unitInfo;

+       const displayFactions = factions.map(faction => {
+           return {
+               value : faction.id,
+               text : faction.name
+           };
+       });

Connecting the Unit Model

The <UnitInfoForm> is now in an awkward situation. It's still showing data from state.unitInfo, and state.unitInfo in turn contains the entire unit section from the sample data. If you inspect the current state tree, you'd see that we actually have all of the data arrays nested in there, like state.unitInfo.pilots.

In addition, the inputs are also hooked up to apply updates to the state.unitInfo section. We really need to change that so that the form displays the values from the Unit model we've loaded in via Redux-ORM, and the updates are applied there as well.

For now, we'll assume that we only have a single Unit model in memory. (Hopefully someday we'll get far enough that we can load multiple units at once, in which case that assumption will change, but it'll work for now.)

We'll start by changing the form to read the current Unit entry and display its values instead of from state.unitInfo.

Commit b08a248: Update unit info form to display current Unit details

features/unitInfo/unitInfoSelectors.js

import {createSelector} from "reselect";
import {getEntitiesSession} from "features/entities/entitySelectors";

export const selectUnitInfo = state => state.unitInfo;

export const selectCurrentUnitInfo = createSelector(
    getEntitiesSession,
    (session) => {
        const {Unit} = session;
        const currentUnitModel = Unit.all().first();

        let currentUnitInfo = null;

        if(currentUnitModel) {
            currentUnitInfo = currentUnitModel.ref;
        }

        return currentUnitInfo;
    }
)

We'll add a selector that knows how to read the plain JS object for the current Unit. Since we assume that there's only one unit at a time, Unit.all().first() should return us the model instance for that one unit, or undefined if it doesn't exist. Assuming the unit instance does exist, we can grab the underlying plain JS object reference from the model instance.

features/unitInfo/UnitInfo/UnitInfoForm.jsx

import {getEntitiesSession} from "features/entities/entitySelectors";

-import {selectUnitInfo} from "../unitInfoSelectors";
+import {selectCurrentUnitInfo} from "../unitInfoSelectors";
import {updateUnitInfo, setUnitColor} from "../unitInfoActions";


const mapState = (state) => {
    const session = getEntitiesSession(state);
    const {Faction} = session;

    const factions = Faction.all().toRefArray();
    
-   const unitInfo = selectUnitInfo(state);
+   const unitInfo = selectCurrentUnitInfo(state);

    return { factions, unitInfo };
};

class UnitInfoForm extends Component {
    render() {
        const {unitInfo, factions} = this.props;
+       const isDisplayingUnit = Boolean(unitInfo);
+       let name = "", affiliation = null, color = null;
+
+       if(isDisplayingUnit) {
+           ({name, affiliation, color} = unitInfo);
+       }

        // omit other rendering code
                        <input
                            placeholder="Name"
                            name="name"
+                           disabled={!isDisplayingUnit}
                        />

Within the <UnitInfoForm>, we switch up which selector we're using to retrieve the unit info values. Note that we could have used the same selector name and switched the way it was retrieving data, instead. This is an example of keeping the changing data storage abstracted from the component itself.

Inside the component, we're adding some additional logic to properly disable the input fields if there's no unit loaded into memory. If you look inside the if clause, there's a neat little trick you can use to do destructuring assignment to variables that have already been declared using let or var - put parentheses around the entire statement. We could also have possibly handled the isDisplayingUnit check by doing const {unitInfo = {}} = this.props, and checking to see if it actually had any fields inside.

Now things get a bit interesting. Currently, our unitInfoReducer is a slice reducer that handles updates to state.unitInfo. What we need instead is a feature reducer that handles updates to the Unit entry that's stored in state.entities.Unit. Fortunately, the rewrite isn't overly complicated, thanks to the other reducer utility functions we already have available.

Commit 2a6592b: Rewrite unit info reducer to update current Unit model

features/unitInfo/unitInfoReducer.js

-import {createConditionalSliceReducer} from "common/utils/reducerUtils";
-import {DATA_LOADED} from "features/tools/toolConstants";
+import orm from "app/schema";
+import {createConditionalSliceReducer} from "common/utils/reducerUtils";

import {
    UNIT_INFO_UPDATE,
    UNIT_INFO_SET_COLOR,
} from "./unitInfoConstants";

-const initialState = {
-   name : "N/A",
-   affiliation : "",
-   color : "blue"
-};

-function dataLoaded(state, payload) {
-   const {unit} = payload;
-   return unit;
-}

function updateUnitInfo(state, payload) {
-   return {
-       ...state,
-       ...payload,
-   };
+   const session = orm.session(state);
+   const {Unit} = session;
+
+   const currentUnit = Unit.all().first();
+
+   if(currentUnit) {
+       currentUnit.update(payload);
+   }
+
+   return session.state;
}

function setUnitColor(state, payload) {
    const {color} = payload;
    
-   return {
-       ...state,
-       color
-   };
+   const session = orm.session(state);
+   const {Unit} = session;
+
+   const currentUnit = Unit.all().first();
+
+   if(currentUnit) {
+       currentUnit.color = color;
+   }

+   return session.state;
}

-export default createReducer(initialState, {
-   [DATA_LOADED] : dataLoaded,
+export default createConditionalSliceReducer("entities", {
    [UNIT_INFO_UPDATE] : updateUnitInfo,
    [UNIT_INFO_SET_COLOR] : setUnitColor,
});

The diff might be a bit difficult to read, so here's what we did:

We removed the DATA_LOADED constant and case reducer that just copied over the unit section from the sample data
Both updateUnitInfo() and setUnitColor() case reducers now expect that state is actually the entire state.entities slice. They create a Session instance, look up the Unit model, and update the appropriate fields before returning the updated state.entities data.
The exported reducer now uses createConditionalSliceReducer() so that our case reducers only see the state.entities slice, and only if it's one of the action types this reducer knows how to handle.

app/reducers/rootReducer.js

const combinedReducer = combineReducers({
    entities : entitiesReducer,
    editingEntities : editingEntitiesReducer,
-   unitInfo : unitInfoReducer,
    pilots : pilotsReducer,
    mechs : mechsReducer,
    tabs : tabReducer,
    modals : modalsReducer,
    contextMenu : contextMenuReducer
});

const rootReducer = reduceReducers(
    combinedReducer,
    entityCrudReducer,
    editingFeatureReducer,
+   unitInfoReducer,
);

With the unitInfoReducer rewritten, we just need to update our root reducer so that we now longer have a state.unitInfo slice, and instead have the unitInfoReducer added to the sequential top-level "feature reducers" list.

At this point you might be thinking: "Hey, don't we already have a bunch of logic for updating models in the store?" Indeed, we do. However, as mentioned earlier, those assume that the model has been copied to state.editingEntities first. We'll probably tackle that in the not-too-distant future, but for now it's simpler to let this be a special case where the edits are applied directly to the data that's in state.entities.

Displaying Unit Data as a Tree

We're now ready to do something interesting and useful with the "Unit Table of Organization" tree. We're going to connect the tree so that it displays the lances in the unit and the pilots in each lance, based on the actual data in the Redux store, and we're going to load that data as a nested structure from our sample data.

Loading Lance Data

Again, our first step is to add a Lance model.

Commit 5485b10: Add Lance model

features/unitInfo/Lance.js

import {Model, many, attr} from "redux-orm";

export default class Lance extends Model {
    static modelName = "Lance";

    static fields = {
        id : attr(),
        name : attr(),
        pilots : many("Pilot")
    };

    static parse(lanceData) {
        return this.upsert(lanceData);
    }
}

Then we'll update the sample data to include info on the lance names and which pilots they contain, and parse that in as part of Unit.

Commit 14cd310: Add lance data and parse lances when loading a Unit

data/sampleData.js

const sampleData = {
    unit : {
        id : 1,
        name : "Black Widow Company",
        affiliation : "wd",
        color : "black",
-       lances : [],
+       lances : [
+           {
+               id : 1,
+               name : "Command Lance",
+               pilots : [
+                   1, 2, 3, 4
+               ]
+           },
+           {
+               id : 2,
+               name : "Fire Lance",
+               pilots : [
+                   5, 6, 7, 8
+               ]
+           },
+           {
+               id : 3,
+               name : "Recon Lance",
+               pilots : [
+                   9, 10, 11, 12
+               ]
+           }
+       ],

features/unitInfo/Unit.js

export default class Unit extends Model {
    static modelName = "Unit";

    static fields = {
        id : attr(),
        name : attr(),
        affiliation : fk("Faction"),
        color : attr(),
+       lances : many("Lance"),
        pilots : many("Pilot"),
        mechs : many("Mech")
    };

    static parse(unitData) {
-       const {Pilot, Mech} = this.session;
+       const {Pilot, Mech, Lance} = this.session;

        const parsedData = {
            ...unitData,
+           lances : unitData.lances.map(lanceEntry => Lance.parse(lanceEntry)),
            pilots : unitData.pilots.map(pilotEntry => Pilot.parse(pilotEntry)),
            mechs : unitData.mechs.map(mechEntry => Mech.parse(mechEntry)),
        };

        return this.upsert(parsedData);
    }
}

Connecting the Unit Organization Tree

We already moved UnitOrganization.jsx from features/unitOrganization to features/unitInfo. Now we'll move it into its own folder, because we're going to start extracting more components out of its current contents.

Commit 54fa32fb: Move UnitOrganizationTree into its own folder

Looking at the contents of the <UnitOrganizationTree> component, we can see a lot of repetition in the structure. A good place to start would be extracting a separate component that displays a single pilot entry.

Commit 7385be9: Add a LancePilot component

features/unitInfo/UnitOrganizationTree/LancePilot.jsx

import React from "react";
import {connect} from "react-redux";

import {
    List,
} from "semantic-ui-react";

import {getEntitiesSession} from "features/entities/entitySelectors";

const mapState = (state, ownProps) => {
    const session = getEntitiesSession(state);
    const {Pilot} = session;

    let pilot, mech;

    if(Pilot.hasId(ownProps.pilotID)) {
        const pilotModel = Pilot.withId(ownProps.pilotID);

        pilot = pilotModel.ref;

        if(pilotModel.mech) {
            mech = pilotModel.mech.type.ref;
        }
    }

    return {pilot, mech};
};

const UNKNOWN_PILOT =  {name : "Unknown", rank : ""}
const UNKNOWN_MECH = {id : "N/A", name : ""};

const LancePilot = ({pilot = UNKNOWN_PILOT, mech = UNKNOWN_MECH}) => {
    const {name, rank} = pilot;
    const {id : mechModel, name : mechName} = mech;

    return (
        <List.Item>
            <List.Icon name="user" />
            <List.Content>
                <List.Header>{rank} {name} - {mechModel} {mechName}</List.Header>
            </List.Content>
        </List.Item>
    )
};

export default connect(mapState)(LancePilot);

We connect this component in the same way that we connected the <PilotsListRow> component previously. The connected component will receive a pilotID prop, and use that to look up the appropriate Pilot model from the store. Assuming that a pilot by that ID exists, it will also look up the related Mech entry so that we can display both the name of the pilot and the type of mech assigned to that pilot.

Since we have a fixed list of pilot entries right now, we can rewrite <UnitOrganizationTree> to render individual <LancePilot> components with fixed pilot IDs:

Commit 01e506b: Show hardcoded lance members by ID in the Unit TOE tree

features/unitInfo/UnitOrganizationTree/UnitOrganizationTree.jsx

       <List.Content>
            <List.Header>Command Lance</List.Header>
            <List.List>
-               <List.Item>
-                   <List.Icon name="user" />
-                   <List.Content>
-                       <List.Header>Cpt. Natasha Kerensky - WHM-6R Warhammer</List.Header>
-                   </List.Content>
-               </List.Item>
+               <LancePilot pilotID={1} />
                // etc

If we refresh the page, we'll see 12 rows of Unknown - N/A lines inside of the tree until we load the pilot data. That's sort of good, because we know that the connected components are rendering and safely handling the case where the data doesn't exist.

The next step is to do the same thing for the lance entries. We'll extract the UI layout into a <Lance> component, and have that component render a list of <LancePilot> components based on the associated pilot IDs for that Lance.

Commit b2cba10: Add a Lance component

features/unitInfo/UnitOrganizationTree/Lance.jsx

import React from "react";
import {connect} from "react-redux";

import {
    List,
} from "semantic-ui-react";

import {getEntitiesSession} from "features/entities/entitySelectors";

import LancePilot from "./LancePilot";

const mapState = (state, ownProps) => {
    const session = getEntitiesSession(state);
    const {Lance} = session;

    let lance, pilots;

    if(Lance.hasId(ownProps.lanceID)) {
        const lanceModel = Lance.withId(ownProps.lanceID);

        lance = lanceModel.ref;
        pilots = lanceModel.pilots.toRefArray().map(pilot => pilot.id);
    }

    return {lance, pilots};
};

const UNKNOWN_LANCE =  {name : "Unknown"}

const Lance = ({lance = UNKNOWN_LANCE, pilots = []}) => {
    const {name} = lance;

    const lancePilots = pilots.map(pilotID => <LancePilot key={pilotID} pilotID={pilotID} />);

    return (
        <List.Item>
            <List.Icon name="cube" />
            <List.Content>
                <List.Header>{name}</List.Header>
                <List.List>
                    {lancePilots}
                </List.List>
            </List.Content>
        </List.Item>
    )
};

export default connect(mapState)(Lance);

Pretty similar to the <LancePilot> component, except that we now look up the list of pilots associated to the lance and extract an array of their IDs as a separate prop.

With that component created, we can simplify <UnitOrganizationTree> further.

Commit d1d5a75: Show hardcoded lances by ID in the Unit TOE tree

features/unitInfo/UnitOrganizationTree/UnitOrganizationTree.jsx

    <List.Content>
        <List.Header>Black Widow Company</List.Header>
        <List.List>
-           <List.Item>
-               <List.Icon name="cube" />
-               <List.Content>
-                   <List.Header>Command Lance</List.Header>
-                   <List.List>
-                       <LancePilot pilotID={1} />
-                       <LancePilot pilotID={2} />
-                       <LancePilot pilotID={3} />
-                       <LancePilot pilotID={4} />
-                   </List.List>
-               </List.Content>
-           </List.Item>
+           <Lance lanceID={1} />

Again, a refresh of the page will show three "Unknown" entries in the tree, with no pilot children this time. Once we load the sample data, the entire tree should populate.

We're still showing a hardcoded list of lances, and that should really be driven based on the lances that are actually in the store.

Commit eca8838: Show lances in the Unit TOE tree based on current Unit entry contents

features/unitInfo/UnitOrganization/UnitOrganizationTree.jsx

import React from "react";
+import {connect} from "react-redux";

import {
    List,
} from "semantic-ui-react";

+import {getEntitiesSession} from "features/entities/entitySelectors";

import Lance from "./Lance";

+const mapState = (state) => {
+   const session = getEntitiesSession(state);
+   const {Unit} = session;
+
+   let lances;
+
+   const unitModel = Unit.all().first();
+
+   if(unitModel) {
+       lances = unitModel.lances.toRefArray().map(lance => lance.id);
+   }
+
+   return {lances};
+}

-const UnitOrganizationTree = () => {
+const UnitOrganizationTree = ({lances = []}) => {
+    const lanceEntries = lances.map(lanceID => <Lance key={lanceID} lanceID={lanceID} />);

    return (
        <List size="large">
            <List.Item>
                <List.Icon name="cubes" />
                <List.Content>
                    <List.Header>Black Widow Company</List.Header>
                    <List.List>
-                       <Lance lanceID={1} />
-                       <Lance lanceID={2} />
-                       <Lance lanceID={3} />
+                       {lanceEntries}
                    </List.List>
                </List.Content>
            </List.Item>
        </List>
    )
}

export default connect(mapState)(UnitOrganizationTree);

Now when we refresh the page, the tree is empty except for the parent tree list item with the title "Black Widow Company". Loading the sample data will fill out the entire tree.

There's one final update to make here. Let's have that parent tree node render the current name of the unit, and show the affiliation color and values as well, so that we can see them update as we edit them in the <UnitInfoForm>.

Commit cf8e19c: Show current unit detail values in the Unit TOE tree

features/unitInfo/UnitOrganizationTree/UnitOrganizationTree.jsx

const mapState = (state) => {
    const session = getEntitiesSession(state);
    const {Unit} = session;

-   let lances;
+   let unit, faction, lances;

    const unitModel = Unit.all().first();

    if(unitModel) {
+        unit = unitModel.ref;
+        faction = unitModel.affiliation.ref;
        lances = unitModel.lances.toRefArray().map(lance => lance.id);
    }

-   return {lances};
+   return {unit, faction, lances};
}

+const UNKNOWN_UNIT = {name : "Unknown"};

-const UnitOrganizationTree = ({lances = []}) => {
+const UnitOrganizationTree = ({unit = UNKNOWN_UNIT, faction = {}, lances = []}) => {
+   const {name, color} = unit;
+   const {name : factionName} = faction;

+   const colorBlock = <div
+       style={{
+           marginLeft : 10,
+           backgroundColor : color,
+           border : "1px solid black",
+           height : 20,
+           width : 40,
+       }}
+   />;

+   const displayText = factionName ? `${name} / ${factionName}` : name;

    const lanceEntries = lances.map(lanceID => <Lance key={lanceID} lanceID={lanceID} />);

    return (
        <List size="large">
            <List.Item>
                <List.Icon name="cubes" />
                <List.Content>
-                   <List.Header>Black Widow Company</List.Header>
+                   <List.Header style={{display : "flex"}}>{displayText} {colorBlock}</List.Header>
                    <List.List>
                        {lanceEntries}
                    </List.List>
                </List.Content>
            </List.Item>
        </List>
    )
}

Notice that our tree component structure works the same way as our connected list: connected parent components using lists of IDs to render child components, and connected child components reading their own data from the store using the ID.

This tree is relatively simple, and has a fixed size, but the general pattern could be applied to a truly recursive tree as well. In fact, there's already a treeview example in the Redux repo. For background, see the PR from Dan Abramov adding the treeview example. (It's also interesting to read the discussion on that PR, as that's where the official guidance and collective wisdom really transitioned from "connect one component at the top of the component tree" to "connect many components deeper for better performance".)

Let's take a final look at the updated Unit Organization Tree:

Final Thoughts

I'm really excited to be continuing with this series. We're slowly starting to increase the level of complexity and difficulty in these examples, and I've got plenty more topics I want to cover. In the next couple parts, I hope to show how to edit complex nested/relational data, and then finally cover asynchronous logic and side effects.

As always, comments, feedback, and suggestions are greatly appreciated!

Further Information

Upgrading to React 16
Random Numbers in Redux
- Roll the Dice: Random Numbers in Redux
- Random in Redux
Project Structuring and Containers
- Reactiflux chat log: thoughts on Redux container/presentational structuring
- React/Redux Links: Project Structure
Redux Treeviews
- Redux examples: Tree View
- Redux PR #1269: Add a tree view example

Practical Redux course now available on Educative.io!

Tue, 28 Nov 2017 10:00:00 -0500

I'm very excited to announce that my "Practical Redux" tutorial series is now an interactive course on Educative.io!

Ever since I started writing this series, I've had people suggest that I ought to turn it into a book, course, or something along that line. While I don't have any real interest in writing a book, Educative's platform for building interactive courses sounded like it would be a great fit for the material in Practical Redux. In particular, the ability to create fully runnable in-course versions of an application is a great way to demonstrate what the app looks like as it's built.

For the last several months, I've been working on turning the Practical Redux blog posts into an Educative course. While the course has the same core content as the posts, I didn't want it to just be a complete copy-paste duplicate of the posts. I've taken this as a chance to clean up, reorganize, and improve several sections of the content, and rebuilt the Project Mini-Mek sample application as well.

Here's some of the changes in the course compared to the posts:

I've rearranged the content so that the project setup process is first. That section now includes the info on using Yarn's "offline mirror" feature for package management.
The Redux-ORM section has been heavily reworked. It now comes in between the project setup and data loading sections, which is when you actually need to learn about it. I've also updated all the info on Redux-ORM to cover the v0.9 API, which simplifies several aspects of using it.
I've added an extensive summary of the info contained in the lessons, and a set of suggestions for further resources and learning.
Lots of small tweaks and improvements to descriptions and wording.
I rebuilt the Project Mini-Mek sample app from the first commit. As with the written content, the code is largely the same, but I've cleaned up some of the inconconsistencies that came from being developed over time.
And, multiple runnable and editable examples of the application to show its implementation and progression throughout the course.

Here's the course link:

Practical Redux course on Educative.io

You'll need a free account on Educative in order to purchase the course.

I'd like to thank everyone who's read the "Practical Redux" series thus far, and especially those who have left encouraging comments or said thanks elsewhere. I've really enjoyed writing these posts, and I've got many more topics I want to cover in this series. No specific timeline yet for the next post, but I'm hoping to find time to resume writing the post series in the near future.

Practical Redux, Part 10: Managing Modals and Context Menus

Tue, 25 Jul 2017 10:00:00 -0400

Intro

Last time in Part 9, we upgraded Redux-ORM to 0.9 and discussed the migration, updated all other app dependencies, and used Yarn's "offline mirror" feature to cache package tarballs for offline repo installation. This time, we're going to set up modal dialogs that are driven by Redux, look at ways to get "return values" from dialogs while still following the principles of Redux, and implement a context menu system as well.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #12: Practical Redux Part 10 WIP, and the final "clean" commits can be seen in in PR #13: Practical Redux Part 10 Final.

As I've mentioned, this series is not really meant to result in a fully-working meaningful application. It's primarily intended to give me reasons to show off specific useful React and Redux techniques. That means that there's a number of things that are going to be obvious over-engineering. Like, say, modal dialogs. This app doesn't need modal dialogs, but guess what: we're going to add modal dialogs to Project Mini-Mek anyway :)

The basic concepts of handling modals in React and driving them from Redux have been described many times elsewhere, in excellent detail. My links list has many articles on the topic, but here's a selected reading list:

Dave Ceddia's post on Modal Dialogs in React demonstrates the basic approach for rendering and control a modal.
Dan Abramov's Stack Overflow answer on how to control modal dialogs using Redux shows how to write reducers that contain descriptions of a modal, and a central React component to render it.
David Gilbertson's post Modals in React, which discusses the tradeoffs of different approaches for putting modals on top of the rest of the app
Mike Vercoelen's article Scalable Modals with React and Redux, which shows Dan's technique for Redux-driven modals in practice
And finally, my own prior blog post on handling return values from generic "picker" modals

We're going to put these concepts into action, and even expand on them in some ways.

Driving React Modals from Redux

Let's start by putting together the pieces needed to show a single modal dialog. We're going to need a few things:

A ModalManager component that takes a description of what modal component to show, and what props the modal should receive, plus a lookup table of available modal components, and renders the right modal component from that description
Actions and reducers that store and clear the description for the current modal
An actual modal component to show

Commit 21777d7: Add basic handling for a single modal dialog

features/modals/modalsReducer.js

import {
    MODAL_CLOSE,
    MODAL_OPEN
} from "./modalConstants";

import {createReducer} from "common/utils/reducerUtils";

const initialState = null;

export function openModal(state, payload) {
    const {modalType, modalProps} = payload;
    return {modalType, modalProps};
}

export function closeModal(state, payload) {
    return null;
}

export default createReducer(initialState,  {
    [MODAL_OPEN] : openModal,
    [MODAL_CLOSE] : closeModal
});

The reducer logic is trivial. We're simply going to store an object that contains the name of the modal type and the props it should receive, and either set the value or clear it out.

features/modals/TestModal.jsx

import React, {Component} from "react";
import {connect} from "react-redux";
import {
    Modal,
} from "semantic-ui-react";

import {closeModal} from "features/modals/modalActions";

const actions = {closeModal};

export class TestModal extends Component {
    render() {
        return (
            <Modal
                closeIcon="close"
                open={true}
                onClose={this.props.closeModal}
            >
                <Modal.Header>Modal #1</Modal.Header>
                <Modal.Content image>
                    <Modal.Description>
                        <p>This is a modal dialog.  Pretty neat, huh?</p>
                    </Modal.Description>
                </Modal.Content>
                <Modal.Actions>
                </Modal.Actions>
            </Modal>
        )
    }
}

export default connect(null, actions)(TestModal);

Semantic-UI-React conveniently has a Modal class already, which allows you to render headers, content, and action buttons. Since the focus of this article is on how to manipulate modals via React and Redux, and not specifically how to build them from scratch, we'll use the SUI-React Modal class rather than trying to build our own.

Note that we pass an open={true} prop to <Modal>. That's because the SUI-React Modal can be either opened or closed, and in our case, whenever we show a <TestModal>, we want the inner <Modal> to be displayed.

features/modals/ModalManager.jsx

import React, {Component} from "react";
import {connect} from "react-redux";

import TestModal from "./TestModal";

const modalComponentLookupTable = {
    TestModal
};

const mapState = (state) => ({currentModal : state.modals});

export class ModalManager extends Component {
    render() {
        const {currentModal} = this.props;

        let renderedModal;

        if(currentModal) {
            const {modalType, modalProps = {}} = currentModal;
            const ModalComponent = modalComponentLookupTable[modalType];

            renderedModal = <ModalComponent {...modalProps} />;
        }

        return <span>{renderedModal}</span>
    }
}

export default connect(mapState)(ModalManager);

Now we get to the heart of the basic modal setup. Let's take a step back first, though, and consider the theory behind this.

In a typical object-oriented GUI toolkit, you might do something like const myModal = new MyModal(); myModal.show(), and the modal class would be responsible for displaying itself somehow. This is also true with things like jQuery-based UI plugins as well. At that point, you have some "implicit state" in your application. Your app is "showing a modal", but there's no real way to track that this is happening beyond the fact that there's an instance of MyModal that's been created, or - if this is a web app - the fact that there's extra elements appended to the page. The "are we showing a modal?" state is implicitly true, but not actually being tracked anywhere.

With React (and even more so with Redux), you are encouraged to make as much of your state explicit as possible. That's why you frequently see apps that store a value like requesting : true, because you can now specifically base UI behavior on the fact that there's an AJAX request in progress (like showing a loading spinner). In our case, we want to explicitly track the fact that we're showing a modal, and even more than that, a description of what the current modal is.

Our <ModalManager> component will live near the top of the app's component tree. It reads the current modal description from Redux. If there's a description object, we need to actually show a modal.

We create a lookup table where the keys are some string identifier, and the values are modal components. In this case, we're just using the variable name as the key (via ES6 object literal shorthand syntax), so if modalType is "TestModal", that's the component class we'll retrieve. Once we have the right modal component class in a variable, we can use normal JSX syntax to render that component. We can also take whatever props object was included in the description, and pass that to the modal.

Here's what the result looks like:

A modal! With a backdrop! Isn't this exciting? :)

Code-wise, that's really all there is to this idea. Use some descriptive value to decide when you should show a modal, and if so, which one, then render it and pass in whatever props it's supposed to have. But, we can expand on this idea in a lot of useful ways.

Making Modals Stackable

Most of the time, you probably only need one modal open at once. But, what if you actually do need multiple modals open, stacked on top of each other? Fortunately, now that we've got the basic modal framework in place, this is pretty simple to add. All we really need to do have our reducer store an array of modal descriptions instead of just one, and have the ModalManager component render multiple modals in response.

While we're at it, we can update our TestModal component to actually make use of the new functionality.

Commit 3cd4fd2: Implement stackable modals

features/modals/modalReducer.js

-const initialState = null;
+const initialState = [];

export function openModal(state, payload) {
    const {modalType, modalProps} = payload;
-   return {modalType, modalProps};
+   // Always pushing a new modal onto the stack
+   return state.concat({modalType, modalProps});
}

export function closeModal(state, payload) {
-   return null;
+   // Always popping the last modal off the stack
+   const newState = state.slice();
+   newState.pop();
+   return newState;
}

features/modals/ModalManager.jsx

const mapState = (state) => ({currentModals : state.modals});

export class ModalManager extends Component {
    render() {
        const {currentModals} = this.props;

        const renderedModals = currentModals.map( (modalDescription, index) => {
            const {modalType, modalProps = {}} = modalDescription;
            const ModalComponent = modalComponentLookupTable[modalType];

            return <ModalComponent {...modalProps}  key={modalType + index}/>;
        });

        return <span>{renderedModals}</span>
    }
}

Our modalReducer cases switch to tracking a stack of modal descriptions in an array, and the ModalManager component changes to loop over that array and render an array of modal components.

features/modals/TestModal.jsx

import {connect} from "react-redux";
import {
    Modal,
+   Button,
} from "semantic-ui-react";

-import {closeModal} from "features/modals/modalActions";
+import {openModal, closeModal} from "features/modals/modalActions";

-const actions = {closeModal};
+const actions = {openModal, closeModal};

export class TestModal extends Component {
+   onNextModalClick = () => {
+       const {counter} = this.props;
+       this.props.openModal("TestModal", {counter : counter + 1});
+   }

    render() {
+       const {counter, closeModal} = this.props;

        return (
            <Modal
                closeIcon="close"
                open={true}
-               onClose={this.props.closeModal}
+               onClose={closeModal}
            >
-               <Modal.Header>Modal #1</Modal.Header>
+               <Modal.Header>Modal #{counter}</Modal.Header>
                <Modal.Content image>
                    <Modal.Description>
-                       <p>This is a modal dialog.  Pretty neat, huh?</p>
+                       <h4>
+                           Value from props:
+                       </h4>
+                       <div>
+                           counter = {counter}
+                       </div>
+                       <div>
+                           <Button onClick={this.onNextModalClick}>Add Another Modal</Button>
+                       </div>
                    </Modal.Description>
                </Modal.Content>
                <Modal.Actions>

Our TestModal gets changed in two ways. First, we'll take the props.counter value and display it as part of the header and the descriptive text. Then, we'll add a button and handle clicks on it by dispatching an action to show another modal on top of the current one. To illustrate that we're stacking them, we increase the counter value and pass it as a prop for the next modal in the stack.

Let's try it out! If we click the "Show Test Modal" button in the Tools menu, and then click "Add Another Modal" a few times, here's what we get (I temporarily added dimmer={false} to TestModal to keep the entire page from being blacked out):

Looks neat, and we've proven that we can show modals on the screen. Now, let's move on to building something useful.

Building a Reusable Color Picker Dialog

Military units usually have some kind of a logo or way to visually identify themselves. Right now, our fictional Battletech units only store a name and a faction affiliation. Let's add a field for a color as well.

If we're going to have a color field, we need some way to actually let the user pick the color. And obviously, if we're going to have a color picker, it should go in a modal dialog! :) (See previous comments about deliberate over-engineering.)

We'll need to build an input to show what the current color is and trigger the color picker dialog, as well as the dialog itself.

Creating the ColorPickerDialog

We've already got the ability to show a modal, so we only need to create a new modal component class that renders some kind of color picker component. We'll use the React-Color library, which provides a variety of color pickers in various styles.

Commit 9c6166e: Add React-Color library

The ColorPickerDialog itself will be very simple. We just need to track some kind of color value in its state, pass that to the color picker component when we render, and update the state when the user selects a different color. We'll also want to accept a callback prop that we can pass the new color to when the modal is closed successfully.

Commit a035b81: Add an initial ColorPickerDialog

common/components/ColorPickerDialog.jsx

import React, {Component} from "react";
import {connect} from "react-redux";
import {
    Modal,
    Button,
} from "semantic-ui-react";

import {SketchPicker} from "react-color";

import {closeModal} from "features/modals/modalActions";
import {noop} from "common/utils/clientUtils";

const actions = {closeModal};

export class ColorPickerDialog extends Component {
    constructor(props) {
        super();
        this.state = {
            color : props.color
        }
    }

    onSelectClicked = () => {
        this.props.colorSelected(this.state.color);

        this.props.closeModal();
    }

    onSelectedColorChanged = (colorEvent) => {
        this.setState({color : colorEvent.hex});
    }

    render() {
        const {closeModal} = this.props;

        return (
            <Modal
                closeIcon="close"
                open={true}
                onClose={closeModal}
                size="small"
            >
                <Modal.Header>Select Color</Modal.Header>
                <Modal.Content>
                    <SketchPicker
                        color={this.state.color}
                        onChangeComplete={this.onSelectedColorChanged}
                    />
                </Modal.Content>
                <Modal.Actions>
                    <Button positive onClick={this.onSelectClicked}>Select</Button>
                    <Button secondary onClick={closeModal}>Cancel</Button>
                </Modal.Actions>
            </Modal>
        )
    }
}

ColorPickerDialog.defaultProps = {
    color : "red",
    colorSelected : noop
};

export default connect(null, actions)(ColorPickerDialog);

Pretty straightforward. We copy the initial color value from props to state in the constructor, and have all future changes apply to the component state. (We also added the ColorPickerDialog to the lookup table in ModalManager as well.)

Here's what it looks like if we show it:

(Yes, the fact that the modal is so much bigger than the color picker component annoys me, but the Semantic-UI modal layouts don't seem to have much flexibility in size, and I don't feel like messing with this.)

Now that we have a dialog, we also need an input to show the current color:

Commit ee3c027: Add a simple ColorPickerButton

common/components/ColorPickerButton.jsx

import React from "react";

import {Button} from "semantic-ui-react";

const ColorPickerButton = ({value, onClick, disabled=false}) => {
    return (
        <Button
            type="button"
            style={{padding: "4px", margin: 0}}
            disabled={disabled}
            onClick={onClick}
        >
            <div
                style={{
                    width : 30,
                    height : 15,
                    backgroundColor : value
                }}
            />
        </Button>
    )
}

export default ColorPickerButton;

We take a standard SUI-React Button, and put a <div> in the middle to show the current color value.

We also need to actually add a color value to our store, and can use the ColorPickerButton to show that:

Commit 07ead5b: Add color field to unit info sample data and reducer

features/unitInfo/unitInfoReducer.js

const initialState = {
    name : "N/A",
    affiliation : "",
+   color : "blue"
};

features/unitInfo/UnitInfo/UnitInfo.jsx

import FormEditWrapper from "common/components/FormEditWrapper";
+import ColorPickerButton from "common/components/ColorPickerButton";

// skip ahead

    render() {
        const {unitInfo, updateUnitInfo} = this.props;
-       const {name, affiliation} = unitInfo;
+       const {name, affiliation, color} = unitInfo;

        return (
            <Segment attached="bottom">

// skip ahead
+                   <Form.Field name="color">
+                       <label>Color</label>
+                       <ColorPickerButton value={color} />
+                   </Form.Field>
                </Form>
            </Segment>

We should now see our ColorPickerButton onscreen:

And finally, we need to hook up the ColorPickerDialog so that it is shown when we click the ColorPickerButton. While we're at it, let's move the two color components into a separate subfolder so that we also have a place to put some Redux-related files:

Commit ede7d5c: Move ColorPicker components into a separate folder

Commit 8ad59aa: Connect UnitInfo color button to show the ColorPickerDialog

common/components/ColorPicker/colorPickerActions.js

import {
    openModal
} from "features/modals/modalActions";

export function showColorPicker(initialColor) {
    return openModal("ColorPickerDialog", {color : initialColor});
}

features/unitInfo/UnitInfo/UnitInfo.jsx

import {updateUnitInfo} from "../unitInfoActions";
+import {showColorPicker} from "common/components/ColorPicker/colorPickerActions";
import {getValueFromEvent} from "common/utils/clientUtils";

const actions = {
    updateUnitInfo,
+   showColorPicker,
};

// skip ahead

+   onColorClicked = () => {
+       this.props.showColorPicker(this.props.unitInfo.color);
+   }

    render() {
        const {unitInfo, updateUnitInfo} = this.props;

// skip ahead

                    <Form.Field name="color">
                        <label>Color</label>
-                       <ColorPickerButton value={color} />
+                       <ColorPickerButton
+                           value={color}
+                           onClick={this.onColorClicked}
+                       />
                    </Form.Field>

And with that, clicking on the color button in the Unit Info tab should now show our color picker with the current color that's in the store. Progress!

Using the Dialog Result Value

Unfortunately, now we have a problem. We can forward the current color value to the ColorPickerDialog as part of the "description" that we're storing in state, and use that as the initial color value in the dialog. However, we need some way to not only retrieve the final color value when the user clicks the "Select" button, but also actually use it to update the right field in the unit info reducer.

The obvious solution is to simply pass a callback function as another prop to the dialog, but that means we'd be storing the callback function in the Redux store. Per the Redux FAQ, putting non-serializable values in the store should be avoided. Now, at the technical level, doing this would work, but it would likely cause issues with time-travel debugging. It's also not the "right" way to do things with Redux. So, what can we do instead?

Earlier, I linked a previous post I'd written on handling return values from generic "picker" modals. The basic idea is to have the code that requested the modal also include a pre-built action object as a prop for the dialog. When the dialog succeeds, it dispatches that pre-built action, with its "return value" attached. It is a level of indirection, but it allows us to continue following the Redux principles.

Commit 2bfcd6e: Allow ColorPicker to dispatch pre-built actions after selection

common/components/ColorPicker/colorPickerActions.js

import _ from "lodash";

import { openModal } from "features/modals/modalActions";

export function showColorPicker(initialColor, onColorPickedAction) {
    // Define props that we want to "pass" to the ColorPicker dialog,
    // including the body of the action that should be dispatched when
    // the dialog is actually used to select a color.
    const colorPickerProps = {
        color : initialColor,
        onColorPicked : onColorPickedAction
    };
    return openModal("ColorPickerDialog", colorPickerProps);
}

export function colorSelected(color, actionToDispatch) {
    return (dispatch) => {
        if(actionToDispatch) {
            const newAction = _.cloneDeep(actionToDispatch);
            newAction.payload.color = color;

            dispatch(newAction);
        }
    }
}

We update the showColorPicker() action creator to take a second argument - the action that the caller wants dispatched upon success. We also add a thunk that the dialog can call to handle dispatching that arbitrary action. In the process, we also clone the entire action object just to be really sure that we're not accidentally mutating whatever payload is. (It's probably not necessary given how this is likely to be called, but it won't hurt to clone the action here.)

common/components/ColorPicker/ColorPickerDialog.jsx

import {closeModal} from "features/modals/modalActions";
-import {noop} from "common/utils/clientUtils";
+import {colorSelected} from "./colorPickerActions";

-const actions = {closeModal};
+const actions = {closeModal, colorSelected};

export class ColorPickerDialog extends Component {

// skip ahead
    onSelectClicked = () => {
-       this.props.colorSelected(this.state.color);
+       this.props.colorSelected(this.state.color, this.props.onColorPicked);
        this.props.closeModal();
    }

We update the click handler to call props.colorSelected() with both the new color value and the previously-supplied action object.

Now, all we need to do is have the UserInfo component pass along an appropriate action when we click the color button, and have a reducer case to handle that action.

Commit c0baa2f: Implement logic to set the unit color from a ColorPicker

features/unitInfo/unitInfoActions.js

-import {UNIT_INFO_UPDATE} from "./unitInfoConstants";
+import {
+   UNIT_INFO_UPDATE,
+   UNIT_INFO_SET_COLOR,
+} from "./unitInfoConstants";

export function updateUnitInfo(values) {
    return {
        type : UNIT_INFO_UPDATE,
        payload : values,
    };
}

+export function setUnitColor(color) {
+   return {
+       type : UNIT_INFO_SET_COLOR,
+       payload : {color}
+   };
+}

I've mostly skipped showing action creators to save space in the posts, but we'll show the setUnitColor() action creator just to emphasize that it's a simple action creator, nothing special at all.

features/unitInfo/unitInfoReducer.js

-function setUnitColor(state, payload) {
+   const {color} = payload;
+
+   return {
+       ...state,
+       color
+   };
+}

export default createReducer(initialState, {
    [DATA_LOADED] : dataLoaded,
    [UNIT_INFO_UPDATE] : updateUnitInfo,
+   [UNIT_INFO_SET_COLOR] : setUnitColor,
});

The new case reducer is also very simple - we extract the new color variable and apply that to our unit info state.

features/unitInfo/UnitInfo/UnitInfo.jsx

import {selectUnitInfo} from "../unitInfoSelectors";
-import {updateUnitInfo} from "../unitInfoActions";
+import {updateUnitInfo, setUnitColor} from "../unitInfoActions";
import {showColorPicker} from "common/components/ColorPicker/colorPickerActions";
import {getValueFromEvent} from "common/utils/clientUtils";

// skip ahead

    onColorClicked = () => {
-       this.props.showColorPicker(this.props.unitInfo.color);
+       const onColorPickedAction = setUnitColor();
+
+       this.props.showColorPicker(this.props.unitInfo.color, onColorPickedAction);
    }

And finally, we update the click handler for the color button. We create our "pre-built" action using the setUnitColor() action creator, but instead of dispatching it, we pass it to showColorPicker() so it can be included as a prop to the ColorPickerDialog.

Let's try it out. The color field in our sample data is "blue", while the default color prop to the ColorPickerDialog is "red". Let's try changing the color to something green, and confirm that it shows up in the color picker button in the unit info form:

Success! We were able to have the UnitInfo component request that the dialog be shown, pass along its own pre-built action, have the ColorPickerDialog dispatch, and update the unit info state with the result value from the dialog.

An Alternative Approach to Dialog Results

The Redux ecosystem includes libraries for almost every use case, and that includes modals. There's a variety of existing libraries for Redux-connected modals available. One particularly interesting library is redux-promising-modals. I haven't yet used it myself, but reading the docs, it appears to offer another valid solution to the question of handling return values from dialogs without breaking Redux principles.

redux-promising-modals offers actions and a reducer for tracking open modals, very similar to what we just implemented (but does not include any components). However, it also includes a middleware. Whenever you dispatch a PUSH_MODAL_WINDOW action, the middleware returns a promise, and tracks what modal that promise belongs to. You can then use that promise in the code that called dispatch(), and chain off of it. When that modal is closed, the middleware extracts results from the action, and resolves the original promise, thus supplying the "return values" from the dialog.

Here's an (untested) example of what using redux-promising-modals might look like:

import {pushModal} from "redux-promising-modals"

function showColorPickerForUnitInfo(initialColor) {
    return (dispatch) => {}
        dispatch(pushModal("ColorPickerDialog", {color : initialColor}))
            .then( (resultColor) => {
                dispatch(setUnitInfoColor(resultColor));
            });
    }
}

To me, this looks like an excellent use of the Redux middleware pipeline for intercepting actions, and is a nicely pre-built solution to the problem of tracking open modals and handling modal return values.

Now that we've seen how to build a modal dialog system, we can apply the same principles to context menus. A context menu is really just another modal that's probably absolutely positioned on screen, doesn't have a dimmer overlay behind it, and contains just a menu instead of a titlebar, content area, and action buttons.

This might be a good time to go back and review a couple of the concepts around how modals in React can actually get shown on screen.

React Portals

We start our React applications by calling ReactDOM.render(<App />, rootElement). All of the nested HTML elements created by our React components are appended inside of that root element, in a single render tree. However, this can make showing modals a little bit awkward. especially if a very deeply nested child component wants to show a modal. That nested component can render a <Modal open={true} />, but now the HTML generated by the Modal component is going to be appended inside of the nested component. That means it probably won't show up correctly on top of the rest of the UI.

Now, sure, we can do some funky CSS stuff and make those elements pop out somehow, but there's a specific technique that's commonly used to make modals in React show up overlaid on the page contents. That technique is called a "portal". A "portal" is when a React component uses its lifecycle methods to start a second React render tree, usually appended to the page body. That way a nested component can render a <Modal>, but the modal content pops out on top of the page. React actually supports this with a semi-official method called ReactDOM.unstable_renderSubtreeIntoContainer. (Note that in React 16, this method will be replaced with a newer version called unstable_createPortal). The react-portal library wraps up that API to make it easier to use, and Semantic-UI-React's Modal component also uses that method.

Digging around the Semantic-UI-React docs and source, it looks like they do have that functionality broken out into a separate Portal component, so we could use that. But, for the sake of illustration, we'll use the react-portal library instead to help implement our context menu system.

Looking back at our description of what a "context menu" is, we said that it needs to be absolutely positioned on the screen. We can put together a generic component to help render something at an absolute position.

Commit e7c1cb3: Add an AbsolutePosition component

common/components/AbsolutePosition.jsx

import React from "react";
import PropTypes from "prop-types";

const AbsolutePosition = (props) => {
    const {children, nodeRef} = props;
    const style = {
        position: 'absolute',
        top: props.top,
        bottom : props.bottom,
        left: props.left,
        right : props.right,
        width: props.width,
    };

    return (
        <div style={style} className={props.className} ref={nodeRef}>
            {children}
        </div>
    );
}

AbsolutePosition.propTypes = {
    top: PropTypes.number,
    bottom : PropTypes.number,
    left: PropTypes.number,
    width: PropTypes.number,
    nodeRef : PropTypes.func,
};

export default AbsolutePosition;

All we really do here is set a div's style to position : "absolute", apply the provided positions, and insert the children inside the div. The only slightly unusual thing here is that we're taking a prop called nodeRef, and passing it down as a callback ref to the div. We'll see why that matters in a minute.

Now for the actual context menu behavior. First, we'll add the react-portal library to our app:

Commit 18de585: Add the React-Portal library

Then, we'll implement the core of our context menu functionality, very similar to how we built the ModalManager component and reducer logic earlier.

Commit 4fc3f4d: Implement core context menu handling logic

features/contextMenus/contextMenuReducer.js

import {createReducer} from "common/utils/reducerUtils";

import {
    CONTEXT_MENU_SHOW,
    CONTEXT_MENU_HIDE,
} from "./contextMenuConstants";

const contextMenuInitialState = {
    show : false,
    location : {
        x : null,
        y : null,
    },
    type : null,
    menuArgs : undefined,
}

function showContextMenu(state, payload) {
    return {
        ...state,
        show : true,
        ...payload
    };
}

function hideContextMenu(state, payload) {
    return {
        ...contextMenuInitialState
    }
};

export default createReducer(contextMenuInitialState, {
    [CONTEXT_MENU_SHOW] : showContextMenu,
    [CONTEXT_MENU_HIDE] : hideContextMenu
});

Our contextMenuReducer is fairly similar to the first iteration of the modal reducer. I probably could have done almost the same thing, where null represents no context menu and a valid object represents actually showing a menu, but wound up implementing this a bit differently in a couple ways. (Not entirely sure why, either, but I did :) )

We're going to track a show flag that indicates whether we're showing a menu, and type and menuArgs represent the same concepts as with our modals. We also need to track the location on screen where the menu should be positioned.

features/contextMenus/ContextMenu.jsx

import React, {Component} from "react";
import {connect} from "react-redux";

import AbsolutePosition from "common/components/AbsolutePosition";

import {hideContextMenu} from "./contextMenuActions";

const actions = {hideContextMenu};

export class ContextMenu extends Component {
    componentDidMount() {
        document.addEventListener('click', this.handleClickOutside, true);
    }

    componentWillUnmount() {
        document.removeEventListener('click', this.handleClickOutside, true);
    }

    handleClickOutside = (e) => {
        if (!this.node || !this.node.contains(e.target) ) {
            this.props.hideContextMenu();
        }
    }

    render() {
        const {location} = this.props;

        return (
            <AbsolutePosition
                left={location.x + 2}
                top={location.y}
                className="contextMenu"
                nodeRef={node => this.node = node}
            >
                {this.props.children}
            </AbsolutePosition>
        )
    }
}

export default connect(null, actions)(ContextMenu);

Next up we have a generic wrapper component for context menus. This component takes care of listening for clicks outside the menu and calling a close function, as well as using an <AbsolutePosition> component to put the menu in the right spot. Note that we offset the x coordinate by a couple pixels just to have the menu appear slightly offset from underneath the cursor. Finally, note that we use the nodeRef prop for AbsolutePosition. That's because we need to do some DOM checks to see if a click on the document is inside or outside the menu. Since the ContextMenu component doesn't render any actual HTML itself, it needs to have the AbsolutePosition component "forward a ref" on down. This is a useful technique, and Dan Abramov wrote an example of the "forwarded refs" pattern a while back.

features/contextMenus/ContextMenuManager.jsx

import React, {Component} from "react";
import {connect} from "react-redux";
import Portal from 'react-portal';

import ContextMenu from "./ContextMenu";

import {selectContextMenu} from "./contextMenuSelectors";

const menuTypes = {
};

export function contextMenuManagerMapState(state) {
    return {
        contextMenu : selectContextMenu(state)
    };
}

export class ContextMenuManager extends Component {
    render() {
        const {contextMenu} = this.props;
        const {show, location, type, menuArgs = {}} = contextMenu;

        let menu = null;

        if(show) {
            let MenuComponent = menuTypes[type];

            if(MenuComponent) {
                menu = (
                    <Portal isOpened={true}>
                        <ContextMenu location={location}>
                            <MenuComponent {...menuArgs} />
                        </ContextMenu>
                    </Portal>
                )
            }
        }

        return menu;
    }
}

export default connect(contextMenuManagerMapState)(ContextMenuManager);

Similar to our ModalManager component, the ContextMenuManager uses the description in Redux to look up the right menu component if appropriate, and renders it. In this case, we also surround the menu component with our <ContextMenu> component to put it in the right position and handle clicks outside of it, and surround that with a <Portal> to ensure that it floats over the UI.

Next up, we add the contextMenuReducer and the ContextMenuManager to our root reducer and the core application layout:

Commit f38f38b: Add the context menu reducer and component to the app

And we can now throw together a quick test menu component to verify that this is working (including adding it to the context menu lookup table):

Commit 958a2c3: Add an initial test context menu component and hook it up

features/contextMenus/TestContextMenu.jsx

import React, { Component } from 'react'
import { Menu } from 'semantic-ui-react'

export default class TestContextMenu extends Component {
    render() {
        return (
            <Menu vertical>
                <Menu.Item>
                    <Menu.Header>Menu Header: {this.props.text} </Menu.Header>
                    <Menu.Menu>
                        <Menu.Item>First Menu Item</Menu.Item>
                        <Menu.Item>Second Menu Item</Menu.Item>
                    </Menu.Menu>
                </Menu.Item>
            </Menu>
        )
    }
}

If we click our "Show Test Context Menu" button, here's what we should see:

Yay, a menu! That does nothing useful!

The majority of Project Mini-Mek's functionality thus far has involved the "Pilots" tab, so we'll work with that. We've already added the ability to select a current pilot from the list, and delete a pilot, so let's add a context menu that offers that capability as well.

Commit 70208ea: Implement a context menu for pilots list items

features/pilots/PilotsList/PilotsListItemMenu.jsx

import React, { Component } from 'react'
import {connect} from "react-redux";
import { Menu } from 'semantic-ui-react'

import {selectPilot} from "../pilotsActions";
import {deleteEntity} from "features/entities/entityActions";
import {hideContextMenu} from "features/contextMenus/contextMenuActions";

const actions = {
    selectPilot,
    deleteEntity,
    hideContextMenu,
}

export class PilotsListItemMenu extends Component {
    onSelectClicked = () => {
        this.props.selectPilot(this.props.pilotId);
        this.props.hideContextMenu();
    }

    onDeleteClicked = () => {
        this.props.deleteEntity("Pilot", this.props.pilotId);
        this.props.hideContextMenu();
    }

    render() {
        return (
            <Menu vertical>
                <Menu.Item>
                    <Menu.Header>Pilot: {this.props.text} </Menu.Header>
                    <Menu.Menu>
                        <Menu.Item onClick={this.onSelectClicked}>Select Pilot</Menu.Item>
                        <Menu.Item onClick={this.onDeleteClicked}>Delete Pilot</Menu.Item>
                    </Menu.Menu>
                </Menu.Item>
            </Menu>
        )
    }
}

export default connect(null, actions)(PilotsListItemMenu);

Our pilots menu will take two props: the ID of a pilot, and some text that will be the name of the pilot that was clicked on. We show the pilot name in the header, and use props.pilotId to tell the action creators what pilot to select or delete.

features/pilots/PilotsList/PilotsListRow.jsx

import {getEntitiesSession} from "features/entities/entitySelectors";
+import {deleteEntity} from "features/entities/entityActions";
import {showContextMenu} from "features/contextMenus/contextMenuActions";

const actions = {
    deleteEntity,
+   showContextMenu,
};


-const PilotsListRow = ({pilot={}, onPilotClicked=_.noop, selected, deleteEntity}) => {
+const PilotsListRow = ({pilot={}, onPilotClicked=_.noop, selected, deleteEntity, showContextMenu}) => {
    const {
        id = null,
        name = "",


// skip ahead

+   const onRowRightClicked = (e) => {
+       e.preventDefault();
+       e.stopPropagation();
+
+       const {pageX, pageY} = e;
+       showContextMenu(pageX, pageY, "PilotsListItemMenu", {text: pilot.name, pilotId : id});
+   }

    return (
-       <Table.Row onClick={onRowClicked} active={selected}>
+       <Table.Row onClick={onRowClicked} onContextMenu={onRowRightClicked}  active={selected}>
            <Table.Cell>
                {name}
            </Table.Cell>

Over in the PilotsListRow component, we'll add a right-click handler on the entire row, and use the click coordinates in the page as the x/y location values for showing the menu. We also pass along the pilot name and ID values to the menu.

It's worth noting that the PilotsListRow component is a functional component that now has a lot going on inside of it. Frankly, it probably ought to be converted to a class component at this point, but I haven't yet gotten around to doing that. We may try to do that next time.

With that menu implemented, let's try it out:

Fixing Some Existing Bugs

In the process of adding this menu, I did actually find a couple bugs in the pilots list behavior (gasp!). We'd better go ahead and fix those now.

Both of these bugs occur when you take certain steps while there is a pilot selected. You can reproduce the first bug with these steps:

Select a pilot and make some edits
While still editing, select another pilot (either by left-clicking the row, or right-clicking the row and choosing "Select Pilot" from our new context menu).

You'll see that when a different pilot is selected, the work-in-progress edits are actually applied to the pilot, which isn't what we want. Selecting another pilot should canceL the edits entirely, not apply them.

The second bug can be reproduced by:

Start editing a pilot
Delete that pilot
Observe that the "Start Editing" button is still active, even though there's no longer a pilot visibly selected
Click "Start Editing"

You'll see our shiny new error overlay pop up with an error saying that Error: Pilot instance with id 6 not found.

Let's go ahead and fix both of those.

Commit 08af948: Fix a pair of bugs with pilot selection and editing

features/pilots/pilotsActions.js

export function selectPilot(pilotID) {
    return (dispatch, getState) => {
        const state = getState();
        const isEditing = selectIsEditingPilot(state);

        if(isEditing) {
-           dispatch(stopEditingPilot());
+           dispatch(cancelEditingPilot())
        }

        dispatch({
            type : PILOT_SELECT,
            payload : {currentPilot : pilotID},
        });
    }
}

The first bug is really silly and stupid. In the case where we select a pilot while already editing, I was dispatching stopEditingPilot(), which is the action creator that applies our edits. We actually need to dispatch cancelEditingPilot() instead.

features/pilots/pilotsReducer.js

export function stopEditingIfDeleted(state, payload) {
    const {itemType, itemID} = payload;
    const {isEditing, currentPilot} = state;

-   if(isEditing && itemType === "Pilot" && itemID === currentPilot) {
-       return stopEditingPilot(state, payload);
+   if(itemType === "Pilot" && itemID === currentPilot) {
+       return {
+           ...state,
+           isEditing : false,
+           currentPilot : null
+       }
    }

    return state;
}

The bug with the currentPilot field not clearing out is simply a logic error in our pilotsReducer. We were attempting to handle the case of a pilot being deleted while already being edited, by listening for the ENTITY_DELETE action and checking to see if the entity was of type "Pilot" and matched the selected pilot ID. But, we were only checking that pilot ID if we were editing, We really need to handle any time the currently selected pilot is deleted, and do so by clearing out both the currentPilot and isEditing fields.

Final Thoughts

Hopefully those examples have shown you how to implement your own modal handling using React and Redux. Those same techniques can be applied to drive other parts of your UI as well. For example, it's very straightforward to implement popup toast notifications using this approach.

Be sure to tune in next time, when we'll... ah... actually, I'm not sure what I'll tackle for the next part :) I have several more ideas for things I want to cover in this series, but I haven't yet decided what topic I'm going to cover next. If you've got any preferences for which topic I should write about next, please let me know in the comments or on Twitter!

Further Information

React Modals and Portals
Dan Abramov explains the "Forwarded Refs" pattern
React and Redux Modal Tools

Practical Redux, Part 9: Upgrading Redux-ORM and Updating Dependencies

Tue, 11 Jul 2017 10:00:00 -0400

Intro

Greetings, and welcome back to the Practical Redux series! It's been a few months since the last post, but as promised, I still have a lot of topics I want to cover for this series.

Picking up where we left off: in Part 8, we added the ability to delete Pilot entries, used our generic entity reducer logic to implement "draft data" handling for the Pilot editing form, and added the ability to cancel and reset form edits. This time around, we have some housekeeping to do: we'll update Redux-ORM to 0.9 and discuss the migration and API changes, update our other dependencies to the latest versions, and look at ways to cache NPM dependencies for consistent project installation even if you're offline.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #10: Practical Redux Part 9 WIP, and the final "clean" commits can be seen in in PR #11: Practical Redux Part 9 Final.

Using Redux-ORM 0.9

When I started the series, the current version of Redux-ORM was 0.8.1. Since then, there have been some noticeable changes. Author Tommi Kaikkonen built and released version 0.9, which includes a number of breaking changes to the API and the library's behavior. Sadly, he also no longer has time to maintain the library by himself, but a call for new maintainers resulted in a couple people being given full ownership of the library, and several others (including myself) were given commit rights. So, Redux-ORM is definitely alive and well.

Let's take a look at the major changes in Redux-ORM 0.9, then tackle upgrading Project Mini-Mek to use it.

Redux-ORM 0.9 Changes

One of the nice things about the Redux-ORM library is its documentation. Too many JS libraries have nothing more than a few example snippets in their README, but Redux-ORM has had a couple pretty good intro tutorials and decent API docs since the beginning.

The Redux-ORM 0.9 changes included a helpful migration guide for using 0.9. Since that document is pretty good as-is, I won't try to restate everything, but I will highlight the biggest changes:

The 0.8 Schema class has been renamed to ORM, due to conceptual changes in how it works internally. Some of the Schema methods have been replaced:
- schema.from(state) is now orm.from(state)
- schema.withMutations(state) is now orm.mutableSession(state)
- schema.getDefaultState() is now orm.getEmptyState()
Session instances now apply changes immediately, instead of queueing up changes to be applied when you called session.reduce(). That means that after any change, like myModel.someField = 123, the session.state object will have been correctly immutably updated to reflect the current values (so session.state.MyModel.byId[id].someField would now be 123 right away). This simplifies complex reducer logic considerably, since you no longer have to worry about what updates are currently pending inside the session's queue and which have been applied. This also means that the session.state = session.reduce() trick I showed previously can be dropped, as the session basically does that for you automatically.
The prior APIs for creating an entities reducer and selectors from a schema have been moved into separate functions. I haven't yet used any of those myself, in either this series or elsewhere.
The QuerySet "flag" properties for someQuerySet.withModels and someQuerySet.withRefs have been removed, and you should now use toModelArray() or toRefArray() instead.
QuerySets are now lazy, so you can chain them together and only execute when needed
Model classes now can take declarations of expected field names. In 0.8, Model instances dynamically created ES5 properties for values that were in the underlying plain data object and for relational fields, each time an instance was built. In 0.9, you can add field declarations to your model class, and Redux-ORM can more efficiently handle those. (The field declarations are still optional if you prefer not to use them.)

In addition, 0.9.1 added a Model.upsert() method. As mentioned in Part 2, Redux-ORM didn't merge or de-duplicate items with the same ID the way Normalizr does. I had opened up an issue to discuss possible fixes, and the new upsert() method was added as a result. So, calling upsert() instead of create() takes care of things nicely.

Upgrading Project Mini-Mek to Redux-ORM 0.9

With those changes in mind, let's go ahead and migrate Project Mini-Mek to use the latest version of Redux-ORM. At the time of writing, that's 0.9.4. For this step, we'll update this version explicitly. I played around with both yarn add and yarn upgrade a bit. Both work, but yarn upgrade seemed to lock the entry in package.json to the given version even if I added the ^ in front of it. So, we'll do it with add:

yarn add redux-orm@0.9.4

That updates the contents of node_modules/redux-orm and modifies our package.json and yarn.lock files, so let's commit those:

Commit 2dd6024: Update Redux-ORM to 0.9.4

Now we can move on to actually modifying the application code to match. Fortunately, the changes aren't overly complicated, and mostly break down into a few edits repeated several times.

Commit 3c19945: Update Redux-ORM usage to work with 0.9.x

Let's go through examples of each change:

First, we need to replace creating a Schema with an ORM instead:

app/schema/schema.js

-import {Schema} from "redux-orm";
+import {ORM } from "redux-orm";

import Pilot from "features/pilots/Pilot";
import MechDesign from "features/mechs/MechDesign";
import Mech from "features/mechs/Mech";

-const schema = new Schema();
-schema.register(Pilot, MechDesign, Mech);
+const orm = new ORM();
+orm.register(Pilot, MechDesign, Mech);

Second, we need to use orm.getEmptyState(), our reducers that use a Session should stop using session.state = session.reduce(), and we should use toModelArray() instead of withModels:

app/reducers/entitiesReducer.js

import {DATA_LOADED} from "features/tools/toolConstants";

-import schema from "app/schema"
+import orm from "app/schema"

-const initialState = schema.getDefaultState();
+const initialState = orm.getEmptyState();

export function loadData(state, payload) {
    // Create a Redux-ORM session from our entities "tables"
-   const session = schema.from(state);
+   const session = orm.session(state);
    // Get a reference to the correct version of model classes for this Session
    const {Pilot, MechDesign, Mech} = session;

// skip ahead

    // Clear out any existing models from state so that we can avoid
    // conflicts from the new data coming in if data is reloaded
    [Pilot, Mech, MechDesign].forEach(modelType => {
-       modelType.all().withModels.forEach(model => model.delete());
-       session.state = session.reduce();
+       modelType.all().toModelArray().forEach(model => model.delete());
    });

-   // Queue up creation commands for each entry
+   // Immutably update the session state as we insert items
    pilots.forEach(pilot => Pilot.parse(pilot));

    designs.forEach(design => MechDesign.parse(design));
    mechs.forEach(mech => Mech.parse(mech));

-   // Apply the queued updates and return the updated "tables"
-   return session.reduce();
+   // Return the new "tables" object containing the updates
+   return session.state;
}

Third, our Model classes should be updated to add declarations for the fields they contain, and we can replace uses of create() with upsert():

features/pilots/Pilot.js

-import {Model, fk} from "redux-orm";
+import {Model, fk, attr} from "redux-orm";

export default class Pilot extends Model {
    static get fields() {
        return {
+           id : attr(),
+           name : attr(),
+           rank : attr(),
+           gunnery : attr(),
+           piloting : attr(),
+           age : attr(),
            mech : fk("Mech"),
        };
    }

    static parse(pilotData) {
        // We could do useful stuff in here with relations,
        // but since we have no relations yet, all we need
        // to do is pass the pilot data on to create() or upsert()

        // Note that in a static class method, `this` is the
        // class itself, not an instance
-       return this.create(pilotData)
+       return this.upsert(pilotData);
    }

Once we apply those edits consistently across the rest of the codebase, our application should now run correctly with no errors.

I haven't yet played with upsert() all that much, but at the moment I don't see any real downside to using it pretty much anywhere in place of create(). Note that because we're now using it, you could actually copy and paste the pilots.forEach(pilot => Pilot.parse(pilot)); line in loadData(), and those Pilot entries would load okay. You could also load a Pilot entry with an existing ID but a couple different values, and it should be merged in correctly (only overwriting the changed values).

Updating Dependencies

The React world has continued to move forward over the last few months as well. React is up to 15.6, Create-React-App hit the big 1.0 and is now at 1.0.10, and many other libs have been updated. Since we're updating things, tt would be good to get everything else up to date too.

Updating React-Scripts

As mentioned in Part 5, Create-React-App is really just the CLI tool that sets up your initial project. All the build system magic is taken care of inside the react-scripts package, and we only need to update that one dependency to take advantage of the latest improvements.

yarn add --dev react-scripts@latest

Commit c6621b3: Update react-scripts to 1.0.10

Updating Other Dependencies

We've got several other dependencies that need to be updated as well. We could list them all in a single yarn add or yarn upgrade command, but maybe we don't want to actually just automatically bump them all to the latest versions. Yarn includes a upgrade-interactive command that shows us the latest versions of each one, and lets us pick and choose which ones to update:

project-minimek> yarn upgrade-interactive
yarn upgrade-interactive
? Choose which packages to update. (Press <space> to select, <a> to toggle all, <i> to inverse selection)
 dependencies
 ( ) lodash                    4.16.6        ?  4.17.4
 ( ) react                     15.3.2        ?  15.6.1
 ( ) react-dom                 15.3.2        ?  15.6.1
 ( ) react-redux               5.0.0-beta.3  ?  5.0.5
 ( ) react-toggle-display      2.1.1         ?  2.2.0
 ( ) redbox-react              1.3.3         ?  1.4.3
 ( ) redux                     3.6.0         ?  3.7.1
 ( ) redux-devtools-extension  1.0.0         ?  2.13.2
 ( ) redux-thunk               2.1.0         ?  2.2.0
 ( ) reselect                  2.5.4         ?  3.0.1
 ( ) semantic-ui-css           2.2.4         ?  2.2.10
 ( ) semantic-ui-react         0.61.1        ?  0.71.0

Having said that, we might as well go ahead and bump all of them to the latest versions after all.

Commit e179c95: Update app dependencies to current versions

Removing the Custom Error Overlay

When I first set up the support for Hot Module Replacement in Part 3, I used a library called Redbox-React to show error messages. I'll temporarily throw an error inside a component's render method to show what it looks like:

That helps, but it could be better.

Since that time, Create-React-App has added a powerful and informative built-in error overlay. All we need to do to make use of it is remove our own error handling code from src/index.js. While we're at it, we'll also remove the dependency on redbox-react:

yarn remove redbox-react

Commit 9782e30: Remove custom error overlay in favor of CRA's built-in overlay

src/index.js

if(module.hot) {
-   // Support hot reloading of components
-   // and display an overlay for runtime errors
-   const renderApp = render;
-   const renderError = (error) => {
-       const RedBox = require("redbox-react").default;
-       ReactDOM.render(
-           <RedBox error={error} />,
-           rootEl,
-       );
-   };
-
-   // In development, we wrap the rendering function to catch errors,
-   // and if something breaks, log the error and render it to the screen
-   render = () => {
-       try {
-           renderApp();
-       }
-       catch(error) {
-           console.error(error);
-           renderError(error);
-       }
-   };
-
+   // Support hot reloading of components.
    // Whenever the App component file or one of its dependencies
    // is changed, re-import the updated component and re-render it
    module.hot.accept("./app/layout/App", () => {

Now if we throw the same error, the overlay looks like this:

Ahhh... much more readable, informative, and soothing. (Now all we need is a towel, and an electronic book with the words "Don't Panic" written on the front.)

Fixing PropTypes

If we restart our dev server and re-run the page, Create-React-App prints out a warning:

Compiled with warnings.

./src/common/components/FormEditWrapper.jsx
  Line 1:  React.PropTypes is deprecated since React 15.5.0, use the npm module prop-types instead  react/no-deprecated

Search for the keywords to learn more about each warning.
To ignore, add // eslint-disable-next-line to the line before.

As part of the preparation for React 16, the React team is working on splitting several capabilities out into separate packages. This includes React.createClass() and the PropTypes API. React 15.5 started showing warnings any time you try to use those out of the "react" package, Most of the major libraries in the React ecosystem have now been updated, but we need to do the same. Fortunately, this is an easy change:

Commit 8573ed7: Use prop-types lib instead of React.PropTypes

common/components/FormEditWrapper.jsx

-import React, {Component, PropTypes} from "react";
+import React, {Component} from "react";
+import PropTypes from "prop-types"

If we restart the server one more time, the warning should be gone.

Managing Dependency Packages for Offline Installation

Package managers are powerful tools. With just a config file and a command, we can download all the dependencies our application needs. Unfortunately, this also introduces many weaknesses and concerns. What happens if the latest version of a package breaks something for me? How can I know that I'm getting the same package contents every time? What if something happens to a package server, or I need to be able to install these packages offline?

The infamous left-pad incident and various Github outages have shown that these are very real questions. While the use of hashes and locked URLs can ensure that a package manager like NPM is actually seeing the same file each time, that doesn't help if the network is down.

There's been a few approaches suggested for handling NPM dependencies without needing a network connection. Using NPM or Yarn's local per-machine cache works, but only if you've downloaded the necessary packages on that machine before. A number of people have suggested that you check in your entire node_modules folder, but that's a very bad idea for a variety of reasons. That's potentially tens or hundreds of thousands of files taking up hundreds of megs on disk, AND that can include platform-specific binaries built post-install (like node-sass's inclusion of libsass). If you check in your node_modules on a Mac, there's a good chance that it won't work on Windows or Linux (and vice versa).

The most ideal solution is to actually check in the downloaded archives for each package. Since platform-specific artifacts like libsass are built after installation, you can safely clone a repo on any machine, install the packages from that per-repo cache, and have things built properly for that machine.

Yarn includes an "offline mirror" feature built in. As far as I know, NPM has not had this built in as a specific capability, but there's a third-party tool called Shrinkpack that can use an NPM "shrinkwrap" file file as the basis for caching package tarballs in the repo. Based on a recent Twitter conversation, it seems that this is also a future planned feature for a future NPM5 release, and that it's possible to sorta-kinda mimic that with a .npmrc file and the --prefer-offline flag for NPM right now.

So, let's set up a package cache for Yarn to work with. First, we need to create a .yarnrc file in the repo:

Commit 326f253: Add Yarn config file for an offline cache

.yarnrc

yarn-offline-mirror "./offline-mirror"
yarn-offline-mirror-pruning true

We'll set two values. yarn-offline-mirror is the folder where we want Yarn to save the package tarballs. By default, if you update package versions, Yarn will only add new files to that folder, but not remove outdated ones. If we set yarn-offline-mirror-prune to true, it will also remove old package tarballs to match what's currently installed.

Next, we need to actually force Yarn to reinstall everything. The simplest way is to rename the node_modules folder to something like node_modules.bak, then run yarn again. Now, if you look inside the offline-mirror older, you should see around 1000 archives, like react-15.6.1.tgz. We can git add the entire folder, and check them all in:

Commit XYZ: Commit dependency packages

And with that, anyone else who is using Yarn along with this project should be able to use exactly the same packages that I have right now, even if you try to install them while you're offline. In theory, anyway. For full disclosure, this is a feature that I've only partly played with myself, and I've actually spent the last couple days fighting Yarn trying to get a variation of this to cooperate in my project at work, without success. (Nitty-gritty details at yarn#3910.) So, seems really useful, but YMMV in practice.

Final Thoughts

This post was probably a lot less exciting than the last few parts, but in today's world, updating dependencies is a pretty important topic. I'm still learning a lot of these intricacies myself (and in some cases, actively struggling with the tools), so please don't take the steps I showed as absolute gospel.

The good news is that we can now get back to writing code, adding features, and demonstrating useful techniques. Next time, we'll look at how to implement Redux-driven modal dialogs and context menus.

Further Information

Redux-ORM 0.9
Create-React-App 1.0
- What's New in Create-React-App
- Create-React-App 1.0 release notes
Offline Package Caching

Practical Redux, Part 8: Form Draft Data Management

Thu, 26 Jan 2017 23:00:00 -0500

Intro

In Part 7, we used a custom FormEditWrapper component to buffer form change events, wrote custom reducer logic for the "editing" feature, and added basic editing for Pilot entries. This time, we'll add the ability to delete Pilots, use generic entity reducer logic to implement "draft data" handling for forms, and implement form resetting and cancelation..

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #8: Practical Redux Part 8 WIP, and the final "clean" commits can be seen in in PR #9: Practical Redux Part 8 Final.

Deleting Pilot Entries

Thus far, we can load a list of Pilots from our fake API, display them in the UI, and edit the details of an individual pilot. That covers two of the four capabilities in the term "CRUD" ("Create", "Retrieve", "Update", and "Delete"). Let's go ahead and implement the ability to delete Pilot entries from our state.

Creating a Redux-ORM Session Selector

Before we implement the actual deletion capability, we'll do a bit of cleanup first, which will also give us a minor performance improvement. As mentioned in in Part 6, many of our connected components create Redux-ORM Session instances in their mapState functions. Creating these Session instances probably isn't too expensive, but there really isn't a good reason to keep creating many Session instances every time the store updates and then throw them all away. This is especially true because a Session instance wraps up a specific state "tables" object, and since all of our components will be doing reads and not writes, they could easily all do reads from the same Session instance with no problems.

In addition, our mapState functions are currently accessing state.entities to pass that slice to the schema. Explicitly accessing slices of state isn't wrong, but it's good practice to use selector functions to encapsulate those lookups.

We can fix both of these issues at the same time, by creating a memoized selector function that will always return the same Session instance for a given version of the entities state slice. (As a reminder, "memoization" means caching inputs and outputs, so that if you see the same inputs, you can skip the work and return the previously calculated output.) The Reselect library provides a function called createSelector that will create the memoized selectors we need. That way, we only create one Session instance per update to our Model data. Again, our application is small enough that we probably wouldn't even see a difference in performance benchmarks, but it's a useful step in the right direction.

Commit 42693a3: Use a selector to have only a single Session instance per state update

features/entities/entitySelectors.js

import {createSelector} from "reselect";

import schema from "app/schema";

export const selectEntities = state => state.entities;

export const getEntitiesSession = createSelector(
    selectEntities,
    entities => schema.from(entities)
);

The selector creation is simple. We create an "input" selector that returns the state.entities slice, and pass that as the first argument to the createSelector function from Reselect. The "output" selector takes the returned entities slice, and calls schema.from(entities) to create the Session instance. That output selector will only run when the entities object changes.

From there, we update all the connected components to use that selector:

features/pilots/PilotDetails/PilotDetails.jsx

import {connect} from "react-redux";
import {Form, Dropdown, Grid, Button} from "semantic-ui-react";

-import schema from "app/schema";
+import {getEntitiesSession} from "features/entities/entitySelectors";

const mapState = (state) => {
    let pilot;
    
    const currentPilot = selectCurrentPilot(state);
    
-   const session = schema.from(state.entities);    
+   const session = getEntitiesSession(state);
    const {Pilot} = session;

After updating all the components to use getEntitiesSession(), we should only be creating a single Session instance per entities update.

Adding Entity Creation and Deletion Reducers

In Part 7, we created a "feature reducer" to handle generic actions that apply to our entities slice. At the time, we only created a single case reducer, which responds to the ENTITY_UPDATE action. That allowed us to make updates to the Pilot entry that's being edited.

We're going to add two more case reducers to that section, one for creating new entities and one for deleting them. We need the deletion reducer now so that we can delete our Pilot entries, and the creation reducer will come into play a bit later.

Commit 75cc30a: Add generic entity creation and deletion handling

features/entities/entityReducer.js

-import {ENTITY_UPDATE} from "./entityConstants";
+import {
+   ENTITY_UPDATE,
+   ENTITY_DELETE,
+   ENTITY_CREATE,
+} from "./entityConstants";

export function updateEntity(state, payload) {
    const {itemType, itemID, newItemAttributes} = payload;

    const session = schema.from(state);
    const ModelClass = session[itemType];

    let newState = state;

    if(ModelClass.hasId(itemID)) {
        const modelInstance = ModelClass.withId(itemID);

        modelInstance.update(newItemAttributes);

        newState = session.reduce();
    }

    return newState;
}

+export function deleteEntity(state, payload) {
+   const {itemID, itemType} = payload;
+
+   const session = schema.from(state);
+   const ModelClass = session[itemType];
+
+   let newState = state;
+
+   if(ModelClass.hasId(itemID)) {
+       const modelInstance = ModelClass.withId(itemID);
+
+       modelInstance.delete();
+
+       // Immutably apply updates and return the new entities structure
+       newState = session.reduce();
+   }
+
+   return newState;
+}
+
+export function createEntity(state, payload) {
+   const {itemType, newItemAttributes} = payload;
+
+   const session = schema.from(state);
+   const ModelClass = session[itemType];
+
+   ModelClass.parse(newItemAttributes);
+
+   const newState = session.reduce();
+   return newState;
+}
+

const entityHandlers = {
    [ENTITY_UPDATE] : updateEntity,
+   [ENTITY_CREATE] : createEntity,
+   [ENTITY_DELETE] : deleteEntity,
};

const entityCrudFeatureReducer = createConditionalSliceReducer("entities", entityHandlers);

All of these reducers follow the same basic pattern: create a Redux-ORM session from the current state, look up a session-bound Model class by name, queue the appropriate update commands in Redux-ORM, then apply the updates immutably and return the updated state. (Yes, it would probably be possible to write some kind of wrapper function that de-duplicates some of the common behavior in these functions, but they're short enough it's not worth the effort.)

Note that the createEntity() reducer expects that each Model class will have a static parse() method. Per Part 5, that's not something that's built in to Redux-ORM, but rather a convention that we're following by writing those functions in all our Model classes.

Implementing Pilot Deletion

We should now be able to dispatch an ENTITY_DELETE action to delete a given Pilot entry from the store. All we need to do now is add delete buttons to our PilotsListRow components, and hook them up to dispatch the action.

We'll add another column to the Pilots list, and show a red circular X button for each row. Clicking the button will delete the item.

Commit 35e48d5: Add the ability to delete individual Pilot entries

features/pilots/PilotsList/PilotsListHeader.jsx

-           <Table.HeaderCell width={4}>
+           <Table.HeaderCell width={3}>
                Mech
            </Table.HeaderCell>
+           <Table.HeaderCell width={1} />

features/pilots/PilotsList/PilotsListRow.jsx

-import {Table} from "semantic-ui-react";
+import {
+    Table,
+    Button,
+    Icon,
+} from "semantic-ui-react";


import {getEntitiesSession} from "features/entities/entitySelectors";
+import {deleteEntity} from "features/entities/entityActions";


+const actions = {
+    deleteEntity,
+};

-const PilotsListRow = ({pilot={}, onPilotClicked=_.noop, selected}) => {
+const PilotsListRow = ({pilot={}, onPilotClicked=_.noop, selected, deleteEntity}) => {

// Omit prop extraction

+   const onDeleteClicked = () => deleteEntity("Pilot", id);

// Omit row cell rendering
            <Table.Cell>
                {mechType}
            </Table.Cell>

+           <Table.Cell>
+               <Button
+                   compact
+                   basic
+                   circular
+                   size="tiny"
+                   color="red"
+                   icon={<Icon  name="delete" />}
+                   onClick={onDeleteClicked}
+               >
+               </Button>
+           </Table.Cell>
        </Table.Row>

That should give us a column of delete buttons for all our Pilot entries:

Clicking any of the delete buttons should remove the corresponding Pilot entry from the store, and that will result in the row being removed. If you play around with things a bit, you'll see there's also some interesting behavior around trying to delete any Pilot entry while a Pilot is being edited, whether it's the same Pilot or a different Pilot. Let's take a look at what's going on there.

Improving the Pilot Deletion Logic

Right now, any click on the pilots list will dispatch the PILOT_SELECT action, which also stops any active editing. Let's update the logic so that it only stops editing if the current pilot is deleted. There's probably a few different ways we could handle this. We're going to do it with two distinct changes.

First, we'll update the click handling in <PilotsListRow>. In the current code, a click on the delete button triggers the click handler for the button, but also triggers the click handler for the entire table row. We'll have the button click handler cancel the event, so that the row handler doesn't get run afterwards.

Second, we're going to have the pilots reducer listen for the ENTITY_DELETE action type. If the deleted item is a Pilot, and we're in the middle of editing that pilot, we'll go ahead and stop editing.

Commit d5da05b: Only stop editing if the current pilot is deleted

features/pilots/PilotsList/PilotsListRow.jsx

-   const onDeleteClicked = () => deleteEntity("Pilot", id);
+   const onDeleteClicked = (e) => {
+       e.stopPropagation();
+       e.preventDefault();
+       deleteEntity("Pilot", id);
+   }

+   const onRowClicked = () => onPilotClicked(id);


    return (
-       <Table.Row onClick={() => onPilotClicked(id)} active={selected}>
+       <Table.Row onClick={onRowClicked} active={selected}>

features/pilots/pilotsReducer.js

+import {
+   ENTITY_DELETE,
+} from "features/entities/entityConstants";

+export function stopEditingIfDeleted(state, payload) {
+   const {itemType, itemID} = payload;
+   const {isEditing, currentPilot} = state;
+
+   if(isEditing && itemType === "Pilot" && itemID === currentPilot) {
+       return stopEditingPilot(state, payload);
+   }
+
+   return state;
+}

export default createReducer(initialState, {
    [PILOT_SELECT] : selectPilot,
    [PILOT_EDIT_START] : startEditingPilot,
    [PILOT_EDIT_STOP] : stopEditingPilot,
+   [ENTITY_DELETE] : stopEditingIfDeleted,
});

Notice that our stopEditingIfDeleted function actually reuses the existing stopEditingPilot function to do the work. Also, this is another example of multiple reducers in different slices responding to the same action.

Now if we edit one Pilot, and delete another, we'll stay in editing mode for the current pilot. Selecting a different pilot will still cancel editing.

Managing Draft Data for Forms

As mentioned in Part 7, our current Pilot editing logic updates the actual data object for that Pilot in the store. Because both the list row and the edit form are referencing the same object, all edits in the form are immediately reflected in the list row. That looks kinda cool when you first see it, but it's not really a desired behavior. What if we wanted the user to be able to cancel the edits, or confirm they actually wanted to save the new values, or even reset the changes?

I faced this issue when working on my own application. It took me a while to figure out the approach I now use, although in hindsight, the idea sure feels obvious, and I'm kinda kicking myself for not working it out sooner. (In my defense, it was still early on in my first actual usage of Redux.) I also have to give a big shout-out and thanks to Tommi Kaikkonen, author of Redux-ORM, who took the time to listen to my use case, answer my questions, and help me work out the idea.

I summarized the basic idea in the Structuring Reducers - Normalizing State Shape section of the Redux docs. I'll quote the relevant section here:

An application that does a lot of editing of entities might want to keep two sets of "tables" in the state, one for the "current" item values and one for the "work-in-progress/draft" item values. When an item is edited, its values could be copied into the "work-in-progress" section, and any actions that update it would be applied to the "work-in-progress" copy, allowing the editing form to be controlled by that set of data while another part of the UI still refers to the original version. "Resetting" the edit form would simply require removing the item from the "work-in-progress" section and re-copying the original data from "current" to "work-in-progress", while "applying" the edits would involve copying the values from the "work-in-progress" section to the "current" section.

This really goes back to one of the core concepts of both React and Redux: whenever possible, represent your application's behavior through state. In this case, we want to have two different representations of the same item. So, copy it, leave the original alone, and modify the copy. (This also applies to non-relational form data as well.)

Generic Reducer Logic for Editing Entities

Implementing this "draft slice" capability will require a noticeable amount of work. We need to add this new "draft" state slice to our store, then write the reducer logic to actually copy items from our current entities slice into the "draft" slice.

Adding the Draft State Slice

The good news is that this first part is pretty easy. We've already got a small reducer in our core app folder that defines the entities slice. We just need to copy that reducer's initial state handling so that the "tables" are created for us, and add it in to the root reducer.

Commit 925d077: Add an "editingEntities" state slice to store draft data

app/reducers/editingEntitiesReducer.js

import {createReducer} from "common/utils/reducerUtils";

import schema from "app/schema";
const defaultEditingEntities = schema.getDefaultState();

export default createReducer(defaultEditingEntities, {
});

This reducer will only define the initial shape of the state. We won't add any actual update logic here - all that goes elsewhere.

app/reducers/rootReducer.js

 import entitiesReducer from "./entitiesReducer";
+import editingEntitiesReducer from "./editingEntitiesReducer";
 import tabReducer from "features/tabs/tabReducer";
 
const combinedReducer = combineReducers({
    entities : entitiesReducer,
+   editingEntities : editingEntitiesReducer,
    unitInfo : unitInfoReducer,
    pilots : pilotsReducer,
    mechs : mechsReducer,
    tabs : tabReducer,
});

We'll add editingEntities as another top-level slice in our state tree.

We'll also throw in a small utility function to simplify looking up a Model instance from a Session:

Commit dc83aeb: Add a utility function to look up a model by type and ID

common/utils/modelUtils.js

export function getModelByType(session, itemType, itemID) {
    const modelClass = session[itemType];
    const model = modelClass.withId(itemID);
    return model;
}

Finally, we'll create our initial empty "editing feature" reducer. Similar to how we defined the "generic entity CRUD" reducer, we'll add it to the end of the list of "top-level" reducers in our root reducer:

Commit fbcad74: Create an empty editing feature reducer

features/editing/editingReducer.js

import {createReducer} from "common/utils/reducerUtils";

const editingFeatureReducer = createReducer({}, {
});

export default editingFeatureReducer;

app/reducers/rootReducer.js

import entityCrudReducer from "features/entities/entityReducer";
+import editingFeatureReducer from "features/editing/editingReducer";

const rootReducer = reduceReducers(
    combinedReducer,
    entityCrudReducer,
+   editingFeatureReducer,
);

Before we create the actual core reducer logic, we'll add some utility functions to encapsulate behavior. We'll have a small function to update state.entities, and another to update state.editingEntities. We'll also create a small function to access a given Redux-ORM Model instance, and ask it to copy its entire contents into a plain JS object:

Commit 57b924c: Add editing utility functions

features/editing/editingUtilities.js

import schema from "app/schema";
import {getModelByType} from "common/utils/modelUtils";

export function updateEditingEntitiesState(state, updatedEditingEntities) {
    return {
        ...state,
        editingEntities : updatedEditingEntities,
    };
}

export function updateEntitiesState(state, updatedEntities) {
    return {
        ...state,
        entities : updatedEntities,
    };
}

export function readEntityData(entities, itemType, itemID) {
    const readSession = schema.from(entities);

    // Look up the model instance for the requested item
    const model = getModelByType(readSession, itemType, itemID);
    const data = model.toJSON();

    return data;
}

(Yes, those two "update" functions are trivial, and not really needed here, but it's a small bit of encapsulation.)

As we saw earlier with code that used parse(), here we're expecting that all our Model instances will have a toJSON() method. Again, that's something we're writing ourselves as a common convention, not anything that's built in to Redux-ORM.

On that note, let's go ahead and write those toJSON() methods for our current model classes. Since the model classes are very simple, the methods will be trivial:

Commit 6376ebd: Add toJSON() methods for Redux-ORM model classes

features/pilots/Pilot.js

    static parse(mechData) {
        return this.create(mechData);
    }

+   toJSON() {
+       return {...this.ref};
+   }
}

For now, all we're going to do is make a shallow copy of the actual plain JS object that's in the store. Once our data starts using more complex relations, this would be the place to recurse through all of the 1:1 and 1:many relations, and call toJSON() on them as well. Since we don't have any classes like that right now, here's a quick example of what this might look like:

class SomeHypotheticalModelWithRelations extends Model {
    toJSON() {}
        return {
            ...this.ref,
            someSingleRelation : this.someSingleRelation.toJSON(),
            someMultipleRelation : this.someMultipleRelation.withModels.map(item => item.toJSON())
        };
    }
}

Nothing fancy - just translate the relational fields back into a nested plain JS object as appropriate.

With all that in place, it's time to figure out what our editing reducer actually needs to do.

Writing the Core Editing Reducer Logic

To start with, we need our editing reducer to handle three basic tasks:

When we start editing an item, we need to copy it from the "current data" entities slice to the "draft data" editingEntities slice
We need to be able to update the item in editingEntities with new values
When we're done editing the item, we need to delete the copy from editingEntities, since it's not being used any more

We're going to define three initial actions for those tasks: EDIT_ITEM_EXISTING, EDIT_ITEM_UPDATE, and EDIT_ITEM_STOP.

Remember that our editing reducer is a "top-level" reducer, and receives the entire state tree as its state argument. That means it has access to both state.entities and state.editingEntities.

Looking back at our "generic entity CRUD" reducer, we can see that we already have individual case reducer functions that know how to create, update, and delete an entity in a slice of state. They're currently being used together to handle updates to the state.entities slice as a whole, but we can import and reuse those individual case reducer functions as part of the editing reducer logic.

I'll link the commit that implements the reducers for these three cases, and explain each piece in turn:

Commit 018c552: Add generic reducer logic for editing an entity

features/editing/editingReducer.js

import {createReducer} from "common/utils/reducerUtils";

import {
    createEntity,
    updateEntity,
    deleteEntity
} from "features/entities/entityReducer";

import {
    EDIT_ITEM_EXISTING,
    EDIT_ITEM_UPDATE,
    EDIT_ITEM_STOP
} from "./editingConstants";

import {selectEntities} from "features/entities/entitySelectors";
import {selectEditingEntities} from "./editingSelectors";
import {
    readEntityData,
    updateEditingEntitiesState,
} from "./editingUtils";

export function copyEntity(sourceEntities, destinationEntities, payload) {
    const {itemID, itemType} = payload;

    const newItemAttributes = readEntityData(sourceEntities, itemType, itemID);
    const creationPayload = {itemType, itemID, newItemAttributes}

    const updatedEntities = createEntity(destinationEntities, creationPayload);
    return updatedEntities;
}

export function editItemExisting(state, payload) {
    const entities = selectEntities(state);
    const editingEntities = selectEditingEntities(state);

    const updatedEditingEntities = copyEntity(entities, editingEntities, payload);
    return updateEditingEntitiesState(state, updatedEditingEntities);
}

export function editItemUpdate(state, payload) {
    const editingEntities = selectEditingEntities(state);

    const updatedEditingEntities = updateEntity(editingEntities, payload);
    return updateEditingEntitiesState(state, updatedEditingEntities);
}

export function editItemStop(state, payload) {
    const editingEntities = selectEditingEntities(state);

    const updatedEditingEntities = deleteEntity(editingEntities, payload);
    return updateEditingEntitiesState(state, updatedEditingEntities);
}

const editingFeatureReducer = createReducer({}, {
    [EDIT_ITEM_EXISTING] : editItemExisting,
    [EDIT_ITEM_UPDATE] : editItemUpdate,
    [EDIT_ITEM_STOP] : editItemStop,
});

export default editingFeatureReducer;

First, copyEntity() is an internal helper function, which isn't assigned to handle any specific cases. It's called with two different state slices, one as a source and the other as a destination, and the payload from an action. It uses the readEntityData() utility method we wrote to look up a Model instance and copy its entire contents to a plain JS object. Then, it uses the existing createEntity() case reducer to parse that object and create a copy of the destination slice with the new item "inserted into the tables".

I want to pause and re-emphasize that idea: we're copying items by "serializing" the Models to plain objects, and then re-parsing them to create the duplicate Model instances. The "parsing" concept is the same function we're calling when we load the data from our fake API - we're reusing that here as our means of insertion.

The editItemExisting() case reducer is used to start the editing process for an item that already exists in the "current data" state.entities slice. We use small selectors to retrieve the state.entities and state.editingEntities slices, then pass them to copyEntity(). That returns us the newly updated editingEntities slice, but we need to return that as part of the overall top-level state. We use the updateEditingEntitiesState() utility we wrote to do that.

Similarly, the editItemUpdate() case reducer reads the editingEntities slice, passes that to the existing updateEntity reducer, and returns the new top-level state with the updated editingEntities slice.

Finally, editItemStop() deletes the item out of the editingEntities slice, using the existing deleteEntity() case reducer to do the work.

Again, the idea here is that we already have a set of "primitive", low-level reducer functions for manipulating entities in state, so we can reuse them as building blocks to create higher-level logic. Because hey, it's all just functions!

Using Draft Data for Editing Pilots

With those building blocks set, we can now begin updating our <PilotDetails> form to work with the new editing logic and data.

Displaying the Copied Pilot Entry

Since we're copying edited items from entities to editingEntities, our <PilotDetails> form will need to be able to switch which slice of state it's reading the pilot data from. We'll add some additional logic to the mapState function so that it can determine what slice it should use to load the data. We also need to update the action creators to actually dispatch the EDIT_ITEM_EXISTING and EDIT_ITEM_STOP actions at the same time as we dispatch the PILOT_EDIT_START and PILOT_EDIT_STOP actions.

Commit 3cb01fc: Add ability to display pilot entry from "draft" editingEntities slice

features/editing/editingSelectors.js

import {createSelector} from "reselect";

import schema from "app/schema";

export const selectEditingEntities = state => state.editingEntities;

export const getEditingEntitiesSession = createSelector(
    selectEditingEntities,
    editingEntities => schema.from(editingEntities)
);

As with our entities slice, we'll create a memoized selector that ensures we only have a single Redux-ORM Session instance per update to the editingEntities slice.

features/pilots/pilotsActions.js

+import {
+   editExistingItem,
+   stopEditingItem
+} from "features/editing/editingActions";


-export function startEditingPilot() {
-   return {
-       type : PILOT_EDIT_START,
-   };
-}
+export function startEditingPilot(pilotID) {
+   return (dispatch, getState) => {
+       dispatch(editExistingItem("Pilot", pilotID));
+       dispatch({type : PILOT_EDIT_START});
+   }
+}

-export function stopEditingPilot() {
-   return {
-       type : PILOT_EDIT_STOP,
-   };
-}
+export function stopEditingPilot(pilotID) {
+   return (dispatch, getState) => {
+       dispatch({type : PILOT_EDIT_STOP});
+       dispatch(stopEditingItem("Pilot", pilotID));
+   }
+}

We need to dispatch two different actions each time the "Start Editing" and "Stop Editing" buttons are clicked. We'll change the existing plain action creators into thunks, pass in the pilot IDs as arguments, and dispatch both the pilot-related action and the editing-related action in each thunk.

features/pilots/PilotDetails/PilotDetails.jsx

import {getEntitiesSession} from "features/entities/entitySelectors";
+import {getEditingEntitiesSession} from "features/editing/editingSelectors";

// Skip to mapState

    const currentPilot = selectCurrentPilot(state);

+   const pilotIsSelected = Boolean(currentPilot);
+   const isEditingPilot = selectIsEditingPilot(state);
+
+   if(pilotIsSelected) {
+       const session = isEditingPilot ?
+           getEditingEntitiesSession(state) :
+           getEntitiesSession(state);

        const {Pilot} = session;

        if(Pilot.hasId(currentPilot)) {
            pilot = Pilot.withId(currentPilot).ref;
        }
+    }

export class PilotDetails  extends Component {
+   onStartEditingClicked = () => {
+       const {id} = this.props.pilot;
+       this.props.startEditingPilot(id);
+   }

+   onStopEditingClicked = () => {
+       const {id} = this.props.pilot;
+       this.props.stopEditingPilot(id);
=   }

// Omit rendering code
                    <Button
                        primary
                        disabled={!canStartEditing}
                        type="button"
-                       onClick={actions.startEditingPilot}                        
+                       onClick={this.onStartEditingClicked}
                    >
                        Start Editing
                    </Button>
                    <Button
                        secondary
                        disabled={!canStopEditing}
                        type="button"
-                       onClick={actions.stopEditingPilot}
+                       onClick={this.onStopEditingClicked}
                    >
                        Stop Editing
                    </Button>

We rework the mapState function to determine whether we're currently editing a pilot or just displaying it. Based on that, we retrieve either the editing Session or the "current data" Session, and read the Pilot out of there.

The <PilotDetails> component gets a couple new click handlers, which extract the pilot ID from props, and call the appropriate action creator.

features/editing/editingReducer.js

    const newItemAttributes = readEntityData(sourceEntities, itemType, itemID);
+   if(newItemAttributes.name) {
+       newItemAttributes.name += " (copied)";
+   }
    const creationPayload = {itemType, itemID, newItemAttributes}

As a visual indicator that we really are displaying the edited item, we'll temporarily modify our copyEntity() function to append the text " (copied)" to the end of the name field.

If we select a pilot and start editing it, we should now see:

Progress! We now have two different versions of the same pilot being displayed: the "current" entry in the list, and the "draft" entry in the form.

Updating the Edited Entry

If you try typing in the "Name" field, you'll notice some very strange behavior. As soon as you type anything, the list item for the pilot will update as well. That's because we're still dispatching ENTITY_UPDATE, instead of EDIT_ITEM_UPDATE. We need to modify <PilotDetails> to actually update the "draft" version. While we're at it, we'll remove the little "(copied)" modification we made to the reducer.

Commit d466044: Update pilot editing logic to apply to draft entry

features/pilots/PilotDetails/PilotDetails.jsx

-import {updateEntity} from "features/entities/entityActions";
+import {editItemAttributes} from "features/editing/editingActions";

const actions = {
    startEditingPilot,
    stopEditingPilot,
-   updateEntity,
+   editItemAttributes,
}


   onInputChanged = (e) => {
        const newValues = getValueFromEvent(e);
        const {id} = this.props.pilot;
        
-       this.props.updateEntity("Pilot", id, newValues);
+       this.props.editItemAttributes("Pilot", id, newValues);
    }

    onDropdownChanged = (e, result) => {
        const {name, value} = result;
        const newValues = { [name] : value};
        const {id} = this.props.pilot;
        
-       this.props.updateEntity("Pilot", id, newValues);
+       this.props.editItemAttributes("Pilot", id, newValues);
    }

Now, if you edit the pilot in the form, only that form should update. The corresponding entry in the list should stay as it was.

Saving Form Edits

We can now edit a draft item, but when we click "Stop Editing", the original item is still unchanged. We need to overwrite the values in the original entry with the updated values in the draft entry.

Updating Existing Models

Earlier, we wrote a function called copyEntity, which serializes the requested model (and its relations) to plain JS objects, and recreates them in the draft slice. We now need to reverse the process, but this gets a bit tricker. We already have an entry in the entities slice, so we can't just call createEntity() on that slice. If we tried deleting it and immediately recreating it with the new values, Redux-ORM would also clear out all the relational fields that reference that same item, which would break things. What we really need is a way to update the existing model "in-place".

This is the other part that Tommi Kaikkonen helped me figure out. We can write custom updateFrom() methods on our Model classes, which take another model of the same type, and recursively update themselves and all their relations. It's basically the inverse operation of the sample toJSON() function I showed earlier.

Commit df88219: Add updateFrom() methods to models

features/pilots/Pilot.js

    toJSON() {
        return {...this.ref};
    }

+   updateFrom(otherPilot) {
+       this.update(otherPilot.ref);
+   }
}

Again, our current model classes don't have any complex relations, so the implementation is really simple. We just call the built-in update() method, and pass it the plain JS object that the other model wraps around (which, in our case, is stored in the other slice of state).

(The process of updating a 1:many collection gets considerably more complicated, as you have to take into account adds, updates, and deletions. In my real app, I wound up writing a reusable helper function to encapsulate the somewhat complex logic. I plan to show that off later in the series, when we start dealing with more complex relations.)

Applying Changes to Entities

We're going to write another core logic function that can load a model from a "source" slice, load its equivalent from the "destination" slice, and tell the destination entry to update itself with the source entry. Then we'll write a case reducer that uses that function with editingEntities as the source and entities as the destination.

Commit 4bd028d: Add logic to apply item edits to the "current data" slice

features/editing/editingReducer.js

import {createReducer} from "common/utils/reducerUtils";

+import schema from "app/schema";

import {
    EDIT_ITEM_EXISTING,
    EDIT_ITEM_UPDATE,
+   EDIT_ITEM_APPLY,
    EDIT_ITEM_STOP,
} from "./editingConstants";

+import {getModelByType} from "common/utils/modelUtils";

import {
    readEntityData,
+    updateEntitiesState,
    updateEditingEntitiesState,
} from "./editingUtils";


+export function updateEditedEntity(sourceEntities, destinationEntities, payload) {
+   // Start by reading our "work-in-progress" data
+   const readSession = schema.from(sourceEntities);
+
+   const {itemType, itemID} = payload;
+
+   // Look up the model instance for the requested item
+   const model = getModelByType(readSession, itemType, itemID);
+
+   // We of course will be updating our "current" relational data
+   let writeSession = schema.from(destinationEntities);
+
+   const ModelClass = writeSession[itemType];
+
+   if(ModelClass.hasId(itemID)) {
+       // Look up the original Model instance for the top item
+       const existingItem = ModelClass.withId(itemID);
+
+       if(existingItem.updateFrom) {
+           // Each model class should know how to properly update itself and its
+           // relations from another model of the same type.  Ask the original model to
+           // update itself based on the "work-in-progress" model, which queues up a
+           // series of immutable add/update/delete actions internally
+           existingItem.updateFrom(model);
+       }
+   }
+
+   // Immutably apply the changes and generate our new "current" relational data
+   const updatedEntities = writeSession.reduce();
+   return updatedEntities;
+}
+
+

+export function editItemApply(state, payload) {
+   const entities = selectEntities(state);
+   const editingEntities = selectEditingEntities(state);

+   const updatedEntities = updateEditedEntity(editingEntities, entities, payload);
+   return updateEntitiesState(state, updatedEntities);
+}

const editingFeatureReducer = createReducer({}, {
    [EDIT_ITEM_EXISTING] : editItemExisting,
    [EDIT_ITEM_UPDATE] : editItemUpdate,
+   [EDIT_ITEM_APPLY] : editItemApply,
    [EDIT_ITEM_STOP] : editItemStop,
});

The logic is fairly straightforward. For updateEditedEntity(), we create two separate Redux-ORM sessions, retrieve the models from each, call existingItem.updateFrom(model), and return the immutably updated state as normal. The editItemApply() case reducer just selects the two state slices, calls updateEditedEntity(), and returns the updated root state.

Updating Pilot Save Logic

Our pilots reducer currently responds to the PILOT_SELECT action by resetting isEditing : false. That was fine when we were just showing and editing the existing entry, but now we have some additional steps going on. We really need to make sure that our editing data is cleaned up when another pilot is selected.

We're going to update the selectPilot() action creator to explicitly dispatch the "stop editing pilot" logic before it actually dispatches PILOT_SELECT. In the process, since we know that you can only ever edit the current Pilot, we can rework the thunks to retrieve the current pilot from state instead of passing it in as a parameter. (There's a very good discussion to be had about which approach is better, but we'll go ahead and make the changes for sake of illustrating the idea.)

Commit 4851049: Rework pilot logic to explicitly stop editing on selection

features/pilots/pilotsReducer.js

        currentPilot : isSamePilot ? null : newSelectedPilot,
-       // Any time we select a different pilot, we stop editing
-       isEditing : false,

features/pilots/pilotsActions.js

+import {selectCurrentPilot, selectIsEditingPilot} from "./pilotsSelectors";

export function selectPilot(pilotID) {
-   return {
-       type : PILOT_SELECT,
-       payload : {currentPilot : pilotID},
-   };
+   return (dispatch, getState) => {
+       const state = getState();
+       const isEditing = selectIsEditingPilot(state);
+
+       if(isEditing) {
+           dispatch(stopEditingPilot())
+       }
+
+       dispatch({
+           type : PILOT_SELECT,
+           payload : {currentPilot : pilotID},
+       });
+   }
}

-export function startEditingPilot(pilotID) {
+export function startEditingPilot() {
    return (dispatch, getState) => {
+       const currentPilot = selectCurrentPilot(getState());

-       dispatch(editExistingItem("Pilot", pilotID));
+       dispatch(editExistingItem("Pilot", currentPilot));
        dispatch({type : PILOT_EDIT_START});
    }
}

-export function stopEditingPilot(pilotID) {
+export function stopEditingPilot() {
    return (dispatch, getState) => {
+       const currentPilot = selectCurrentPilot(getState());

        dispatch({type : PILOT_EDIT_STOP});
-       dispatch(stopEditingItem("Pilot", pilotID));
+       dispatch(stopEditingItem("Pilot", currentPilot));
    }
}

From there, we can simply add in the "apply edits" action as part of the "stop editing" thunk:

Commit f6608d0: Save changes to pilot entries when editing is stopped

features/pilots/pilotsActions.js

import {
    editExistingItem,
+   applyItemEdits,
    stopEditingItem
} from "features/editing/editingActions";

export function stopEditingPilot() {
    return (dispatch, getState) => {
        const currentPilot = selectCurrentPilot(getState());

        dispatch({type : PILOT_EDIT_STOP});
+       dispatch(applyItemEdits("Pilot", currentPilot));
        dispatch(stopEditingItem("Pilot", currentPilot));
    }
}

And finally, whenever we hit the "Stop Editing" button, our changes are saved, and the list entry should be updated with whatever changes we made in the form.

Resetting and Canceling Form Edits

Our last couple tasks will be to add the ability to reset our form contents back to the original values, and to add the ability to cancel a form edit entirely.

Resetting Entity Edits

Happily, this is another feature we can implement very easily, by reusing existing code. All we have to do is delete the relevant item out of the editingEntities slice, and immediately copy the original item back over to editingEntities.

Commit 09c5236: Add logic to reset a currently edited item

features/editing/editingReducer.js

import {
    EDIT_ITEM_EXISTING,
    EDIT_ITEM_UPDATE,
    EDIT_ITEM_APPLY,
    EDIT_ITEM_STOP,
+   EDIT_ITEM_RESET,
} from "./editingConstants";


+export function editItemReset(state, payload) {
+   const stateWithoutItem = editItemStop(state, payload);
+   const stateWithCurrentItem = editItemExisting(stateWithoutItem, payload);
+
+   return stateWithCurrentItem;
+}

const editingFeatureReducer = createReducer({}, {
    [EDIT_ITEM_EXISTING] : editItemExisting,
    [EDIT_ITEM_UPDATE] : editItemUpdate,
    [EDIT_ITEM_APPLY] : editItemApply,
    [EDIT_ITEM_STOP] : editItemStop,
+   [EDIT_ITEM_RESET] : editItemReset,
});

Adding "Reset" and "Cancel" Buttons

The other neat thing is that we don't even need to create a "cancel" action. We can do that by simply calling the same "stop editing" actions, and skip applying the item edits.

We'll add a couple more buttons to our <PilotDetails> component, tweak the button layout a bit, and that'll be all:

Commit a4c2ce7: Add the ability to reset and cancel editing a pilot

features/pilots/pilotsActions.js

+export function cancelEditingPilot() {
+   return (dispatch, getState) => {
+       const currentPilot = selectCurrentPilot(getState());
+
+       dispatch({type : PILOT_EDIT_STOP});
+       dispatch(stopEditingItem("Pilot", currentPilot));
+   }
+}

features/pilots/PilotDetails/PilotDetails.jsx

import {
    startEditingPilot,
    stopEditingPilot,
+   cancelEditingPilot,
} from "../pilotsActions";

+import {
+   resetEditedItem,
+} from "features/editing/editingActions";


const actions = {
    startEditingPilot,
    stopEditingPilot,
    editItemAttributes,
+   resetEditedItem,
+   cancelEditingPilot,
}


export class PilotDetails  extends Component {

+   onResetClicked = () => {
+       const {id} = this.props.pilot;
+       this.props.resetEditedItem("Pilot", id);
+   }

// Omit rendering code

+               <Grid.Row width={16}>
+                   <Button
+                       disabled={!canStopEditing}
+                       type="button"
+                       onClick={this.onResetClicked}
+                   >
+                       Reset Values
+                   </Button>
+                   <Button
+                       negative
+                       disabled={!canStopEditing}
+                       type="button"
+                       onClick={this.props.cancelEditingPilot}
+                   >
+                       Cancel Edits
+                   </Button>
+               </Grid.Row>

We can now start editing an item; save the item and stop editing; reset the draft item to its original values; and cancel an edit without actually saving the changes. Yay!

Let's take one last look at the current UI appearance:

You can see that we're in the middle of editing a Pilot. We've edited several values, and they're different from what's being displayed in the list. We also have our "Stop", "Reset", and "Cancel" buttons active, while "Start" is disabled. Looks good!

Final Thoughts

We've come a long way from the start of the project. We've built up a UI, added data loading, displayed our data, discussed performance concerns, and implemented some fairly sophisticated logic for handling normalized entities and working with forms.

This is a good place to pause the Practical Redux series for a while. I'm absolutely not done with the series, but I have a couple other blog posts that I want to write on other topics, and some non-blogging things I want to work on soon. Rest assured, I have many more topics that I want to cover in this series! (In fact, if you're interested in my writing plans, I have a gist listing the blog post topics I want to write about in the future.)

I'd definitely like to thank everyone who has read these posts so far, and say how much I appreciate both the interest and the positive feedback you've given me! It's extremely encouraging to know that people are actually interested in what I've written, and are finding the information helpful.

Be sure to keep an eye on this blog for other posts coming soon, and I'll continue to tweet updates about what I'm working on next.

Until next time: keep on Redux-ing! :)

Further Information

Practical Redux, Part 7: Form Change Handling, Data Editing, and Feature Reducers

Thu, 12 Jan 2017 23:00:00 -0500

Intro

In Part 6, we connected our lists directly to Redux, set up basic editing for the UnitInfo form, and added the ability to toggle "editing" mode for a selected Pilot. This time, we'll look at some advanced techniques for managing form change events, implement editing for model entries, and use a custom reducer structure to handle feature logic.

The code for this project is on Github at github.com/markerikson/project-minimek. Since this post was split off from Part 6, the original WIP commits I made for this post can be seen in PR #6: Practical Redux Part 6 WIP, and the final "clean" commits can be seen in in PR #7: Practical Redux Part 7 Final.

Cleaning Up Some Code

Before we dive in to the real work for this section, we've got a few bits of cleanup that will help us later.

Handling Data Reloads

There's a problem with the current entitiesReducer logic. If we click the "Load Unit Info" button twice in a session, the reducer will try to load the same sample data again, and will throw errors because data with those IDs already exists in state. We can fix this by having the case reducer delete any existing entries before it loads in the new data.

Commit 36324ea: Clear out existing models on load to avoid conflicts when reloading data

app/reducers/entitiesReducer.js

    const {pilots, designs, mechs} = payload;

+   // Clear out any existing models from state so that we can avoid
+   // conflicts from the new data coming in if data is reloaded
+   [Pilot, Mech, MechDesign].forEach(modelType => {
+       modelType.all().withModels.forEach(model => model.delete());
+       session.state = session.reduce();
+   });

Note that we use the session.state = session.reduce() trick mentioned in Part 2 to create an intermediate updated version of the state after queueing up the delete commands for each model class.

Cleaning Up the PilotDetails Component

Since we're going to eventually add callback functions to handle the inputs in <PilotDetails>, now is a good time to convert it from a functional component to a class component.

Commit e1325ac: Convert PilotDetails to a class component

We're also going to rework the <PilotDetails> form a bit. The "gunnery" and "piloting" fields are going to have a limited range of values, so we might as well make them dropdowns. Also, while working on this part, I found out that the Semantic-UI-React <Form.Field> component supports some useful shorthand syntax. You can pass a label string and a component type as a prop, and it will render them. It will also forward any unknown props onwards to the input component it's rendering. here's an example:

-<Form.Field name="rank" width={16}>
-   <label>Rank</label>
-   <Dropdown
-       fluid
-       selection
-       options={RANKS}
-       value={rank}
-       disabled={!canStopEditing}
-   />
-</Form.Field>
+<Form.Field
+   name="rank"
+   label="Rank"
+   width={16}
+   control={Dropdown}
+   fluid
+   selection
+   options={RANKS}
+   value={rank}
+   disabled={!canStopEditing}
+/>

The name, label, and width props are handled by the <Form.Field> component. It renders an instance of <Dropdown>, and passes it the remaining props. (Order doesn't matter here, I just wrote them with the Field's props first and the Dropdown's props last.)

I suppose it's a tossup which formatting you prefer. I can see arguments both ways. But, given that I already did the work, we'll go with the latter approach :)

Commit dcdc0ec: Rework PilotDetails form layout for consistency

Investigating Form Actions

With that cleanup done, back to work on our input forms. In Part 6, I mentioned that "there's one problem with our text input that we need to address", and promised we'd come back to that later. Later is now :)

Let's type the letters "test" into the end of the "Unit Name" field, and look at the DevTools actions log:

We can see four different UNIT_INFO_UPDATE actions in that list from typing "test" into the name input. If we look at the next-to-last action, we can see that after typing the 's', the dispatched name was "Black Widow Companytes".

Right now, every single time we type a keystroke into the name input, we dispatch another Redux action. Every time we dispatch an action, every connected component gets notified, and has its mapState function run. As an example, that means that for every keystroke, all the <PilotsListRow> components are busy looking up their Pilot entries. But... all we really wanted to do was update the name input! None of the Pilots data is going to change from us typing here, so all that is wasted effort. The dispatched actions are also kind of cluttering up the actions log.

As mentioned previously, Project Mini-Mek really isn't a performance-critical application, and especially not at this stage of development. Still, it would be nice if we could cut down on the number of actual Redux actions dispatched.

Buffering Form Changes and Dispatches

I noted some of the issues with dispatching actions from form inputs while working on early prototypes for my own application. I needed a solution that could do several things for me:

Handle onChange events from input components
Respond to those change events by immediately passing the updated values back down to the input, for fast UI response
If several changes happened close together, only dispatch a single Redux action after they were all done, with the final values
Be generic enough that I could reuse it in a variety of different places.

I started playing around with some ideas, and eventually came up with a component I dubbed the "FormEditWrapper". (As you may have noticed, nothing is more permanent in programming than a temporary name. We'll call it FEW for short.)

My FormEditWrapper is a reusable, generic component that can buffer input changes in its own component state, combine those changes with incoming props, and debounce changes to minimize the number of dispatched Redux actions.. Let's look at the source, and I'll explain how it works.

Commit c321c35: Add FormEditWrapper component

common/components/FormEditWrapper.jsx

import React, {Component, PropTypes} from "react";
import {noop, debounce, defaults, values} from "lodash";

import {getValueFromEvent} from "common/utils/clientUtils";

class FormEditWrapper extends Component {
    static propTypes = {
        value : PropTypes.object.isRequired,
        isEditing : PropTypes.bool,
        onChange : PropTypes.func,
        valuePropName : PropTypes.string,
        onChangePropName : PropTypes.string,
        singleValue : PropTypes.bool,
        passIsEditing : PropTypes.bool,
        dispatchDelay : PropTypes.number,
    }
    
    static defaultProps = {
        isEditing : true,
        onChange : noop,
        valuePropName : "value",
        onChangePropName : "onChange",
        singleValue : false,
        passIsEditing : true,
        dispatchDelay : 250,
    }

    constructor(props) {
        super(props);
        const boundDispatchAttributes = this.dispatchAttributeChange.bind(this);
        this.dispatchAttributeChange = debounce(boundDispatchAttributes, props.dispatchDelay);

        this.state = {
            value : {},
        };
    }

    componentWillReceiveProps() {
        // Reset any component-local changes  Note that the incoming props
        // SHOULD match the changes we just had in local state.
        this.setState({value : {}});
    }

    onChildChange = (e) => {
        const {isEditing} = this.props;

        if(isEditing) {
            const newValues = getValueFromEvent(e);

            if(newValues) {
                const change = {
                    ...this.state.value,
                    ...newValues
                };

                // Update our component-local state with these changes, so that the child components
                // will re-render with the new values right away
                this.setState({value : change});

                // Because this is debounced, we will only call the passed-in props.onChange
                // once there is a pause in changes (like letting go of a held-down key)
                this.dispatchAttributeChange(change);
            }
        }
    }

    dispatchAttributeChange(change) {
        this.props.onChange(change);
    }

    render() {
        const {value : propsValue, children} = this.props;
        const {isEditing, passIsEditing, valuePropName, onChangePropName, singleValue} = this.props;
        const {value : stateValue = {}} = this.state;

        // Use incoming values from props IF there is no corresponding value
        // in local component state.  This allows local changes to win out.
        const currentValues = defaults({}, stateValue, propsValue);

        let valueToPassDown = currentValues;

        if(singleValue) {
            valueToPassDown = values(currentValues)[0];
        }

        const editingValue = passIsEditing ? {isEditing} : {};

        // Force the child form to re-render itself with these values
        const child = React.Children.only(children);

        const updatedChild = React.cloneElement(child, {
            [valuePropName] : valueToPassDown,
            [onChangePropName] : this.onChildChange,
            ...editingValue
        });

        return updatedChild;
    }
}

export default FormEditWrapper;

There's a lot of stuff going on in there. Let's break it down:

Passing Down Props to Children

First, FEW expects a prop named value, which should be an object. It also uses the React.Children API to ensure that it only has a single child. The most basic usage would look like:

<FormEditWrapper value={someObject}>
    <SomeChildComponent />
</FormEditWrapper>

FEW also uses another of React's top-level APIs: React.cloneElement(). Since the output of a React render function is just an object, and React exposes the render output of child components as props.children, it's possible for a component to return different children than what it was given. In this case, FEW is going to make a copy of the child render output it was given, and pass down a couple new or different props. One prop is the data value object, and the other prop is an onChange callback. So, in that minimal example, it's as if we had written SomeChildComponent value={someObject} onChange={someOnChangeCallback} />.

The second thing to note is that FEW supplies its own onChildChanged method as the onChange prop for its child. Whenever onChildChanged is called, FEW will update its internal state with the values passed up by the child, merging them with whatever values are already buffered in the state. Calling this.setState() always forces a re-render, and that leads into the next really interesting part.

Let's use the <PilotDetails> form as an example. That form has two main text inputs (name and age). Assume we have this setup:

const name = "Original Name";
const age = "42";

<FormEditWrapper value={ {name, age} }>
    <PilotDetails />
</FormEditWrapper>

If we type "newname" at the end of the name field, FEW's internal state would look like { value : { name : "Original Namenewname"}}. Meanwhile it's still being given the original value={ {name, age} } prop. We need to combine these two so that the name value we just typed overrides the name value coming in as a prop. The key is this line here:

// Use incoming values from props IF there is no corresponding value
// in local component state.  This allows local changes to win out.
const currentValues = defaults({}, stateValue, propsValue);

If we were to inspect currentValues after that line, we would see {name : "Original Namenewname", age : 42}. Since we didn't have an age prop in FEW's state, we copy that over. Since we do have a name field in state, we don't copy over the name field we were given as a prop. This means that any values from the child component will override the equivalent values from props, and the resulting object is passed back down to the child component, allowing it to re-render itself with the correct data.

Finally, when FEW receives new props, it clears out its internal state buffer. The assumption is that the new props will now be a "saved" version of the changes it's keeping inside, so it can clear those out and go back to just passing down the data it's getting as a prop.

Flexibility and Customization

Perhaps the child input or form component is different than most others. Maybe it needs its value as a prop named data (or in the case of <PilotDetails>, as a prop named pilot). Maybe it needs the callback prop to be named something other than onChange. FEW accepts some props that tell it to change its default behavior: valuePropName and onChangePropName. Going back to our earlier example, we could do:

<FormEditWrapper value={ {name, age} }  valuePropName="pilot">
    <PilotDetails />
</FormEditWrapper>

And now <PilotDetails> will be given props.pilot instead of props.value.

Another customization issue is that actual <input> components only want a specific value like a string, instead of an object. In that case, passing the singleValue={true} flag to FEW will tell it to assume there's only one field it needs to pass down, and to pass that down directly instead of the entire value object.

In my own application, a number of components also need to be given an isEditing flag. Originally I passed that through all the time, but when I added the singleValue option, I realized that inputs wouldn't need that prop, so I added a passIsEditing prop to control whether that gets passed down or not.

Buffering Dispatches

FEW's onChildChanged method will immediately call this.setState() with the new values from the child, and that queues up a re-render. That method also calls this.dispatchAttributeChanged(), which in turn calls this.props.onChange(). However, in the constructor, we create a debounced version of dispatchAttributeChanged, which will only actually run if enough time has elapsed since the last time it was called (by default, 250ms). That means that if the user quickly types several characters into a text input, dispatchAttributeChanged will be called repeatedly, but won't actually run for real until after the user is done typing. As a result, when it does run, it will call this.props.onChange() with the final value. So, instead of seeing "n", "ne", "new", and so on, you'd see a single "newname" value passed back up. The onChange prop doesn't have to be a Redux action creator, but it usually will be. That means that most of the time, only a single Redux action will be dispatched for a series of keystrokes.

`FormEditWrapper` in Action

With all that in mind, let's use FEW to buffer the "name" input in our <UnitInfo> component.

Commit 76e48af: Use FormEditWrapper with UnitInfo name input

features/unitInfo/UnitInfo/UnitInfo.jsx

+import FormEditWrapper from "common/components/FormEditWrapper";

// Omit irrelevant code
    render() {
-       const {unitInfo} = this.props;
+       const {unitInfo, updateUnitInfo} = this.props;
        const {name, affiliation} = unitInfo;

// Omit rendering code
                    <Form.Field name="name" width={6}>
                        <label>Unit Name</label>
+                       <FormEditWrapper
+                           singleValue={true}
+                           value={ {name} }
+                           onChange={updateUnitInfo}
+                           passIsEditing={false}
+                       >
                            <input
                                placeholder="Name"
                                name="name"
-                           value={name}
-                           onChange={this.onNameChanged}
                            />
+                       </FormEditWrapper>
                    <Form.Field name="affiliation" width={6}>

So now, if we type "test" at the end of the name input and look in the DevTools, we should see this:

Success! Four keystrokes, the input updated immediately as we typed, and only a single Redux action was dispatched.

Structuring Reducer Logic for Features

As mentioned in Part 4, we're using a "feature-first" folder structure. There's tradeoffs with both "file-type-first" and "feature-first" approaches.

With "file-type-first", you know where to look for a certain type of code, and it's really easy to pull together all the slice reducers into a root reducer file. However, each feature gets split across several folders, and if multiple features need to interact with a specific slice of state, the files or folders for that slice of reducer logic will start to get awfully crowded.

With "feature-first", you know exactly where all the files for a given feature are, but the process of combining the reducer logic together can be a bit tricker, especially if you're using the standard approach of combineReducers. In particular, what happens when multiple features need to interact with the same slice of state?

In our case, we've created an entities slice containing the "tables" for our relational data entries. Because this is a central data location for our application, several different features are going to need to make updates to the entities slice. We could put all the reducer logic from the different features together into one giant entitiesReducer, but that would get ugly rather quickly. What we really need is a way for each individual feature to separately apply updates to the entities slice.

Looking Beyond `combineReducers`

I'll paraphrase some of the key concepts from the Structuring Reducers section of the Redux docs:

It's important to understand that your entire application really only has one single reducer function: the function that you've passed into createStore as the first argument. It's good programming practice to take pieces of code that are very long or do many different things, and break them into smaller pieces that are easier to understand. Since a Redux reducer is just a function, the same concept applies. You can split some of your reducer logic out into another function, and call that new function from the parent function.

In Redux it is very common to structure reducer logic by delegating to other functions based on slice of state. Redux refers to this concept as "reducer composition", and it is by far the most widely-used approach to structuring reducer logic. In fact, it's so common that Redux includes a utility function called combineReducers(), which specifically abstracts the process of delegating work to other reducer functions based on slices of state. However, it's important to note that it is not the only pattern that can be used.

Once you go past the core use case for combineReducers, it's time to use more "custom" reducer logic, whether it be specific logic for a one-off use case, or a reusable function that could be widely shared. There's third-party reducer utilities that are available, or if none of the published utilities solve your use case, you can always write a function yourself that does just exactly what you need.

It's time to put some of these ideas into practice.

Using `reduceReducers`

If you happened to look at the reducerUtils.js file previously, you may have noted a function in there I haven't talked about yet: reduceReducers(). Here it is:

export function reduceReducers(...reducers) {
    return (previous, current) =>
        reducers.reduce(
            (p, r) => r(p, current),
            previous
        );
}

This was actually originally written by Andrew Clark, and is available as a package at https://github.com/acdlite/reduce-reducers . I swiped it and pasted it into reducerUtils.js to skip taking on another dependency.

reduceReducers is a nifty little utility. It lets us supply multiple reducer functions as arguments and effectively forms a pipeline out of those functions, then returns a new reducer function. If we call that new reducer with the top-level state, it will call the first input reducer with the state, pass the output of that to the second input reducer, and so on. (If I were more Functional-Programming-minded, I'd guess that there's probably a lot of similarities with compose(), but this is about as far as my mind goes in that direction. I'm sure someone will be happy to correct me or clarify things in the comments.)

Let's rework our root reducer to make use of reduceReducers:

Commit 9d6b443: Update root reducer to wrap around combined reducer

app/reducers/rootReducer.js

import {reduceReducers} from "common/utils/reducerUtils";

const combinedReducer = combineReducers({
    entities : entitiesReducer,
    unitInfo : unitInfoReducer,
    pilots : pilotsReducer,
    mechs : mechsReducer,
    tabs : tabReducer,
});


const rootReducer = reduceReducers(
    combinedReducer,
);

export default rootReducer;

Our old "root reducer" is now the combinedReducer, and we pass that into reduceReducers to get the new root reducer.

It's important to note that the combined reducer should be first in the pipeline, because that defines the shape of the state. (See the Initializing State section of the Redux docs for more info on why and how the combined reducer defines the state shape.)

Writing a Higher Order Reducer

A "higher order reducer" is any function that takes a reducer as an argument, and returns a new reducer. That includes combineReducers and reduceReducers. Now, we're going to write one of our own.

If all the reducer functions given to reduceReducers are called with the top-level state object, but a given feature only needs to apply updates to one piece of the state, we're going to have a lot of repetitive logic as each feature reducer tries to apply its updates. In addition, reduceReducers will be calling these feature reducers will be called on every dispatched action, so it would be nice to ensure the feature reducers only respond if the action is something they care about.

Putting these ideas together, we can build a higher order reducer function called createConditionalSliceReducer:

Commit 3b5b2bf: Add createConditionalSliceReducer utility

common/utils/reducerUtils.js


export function createConditionalSliceReducer(sliceName, fnMap) {
    // Create a reducer that knows how to handle one slice of state, with these action types
    const sliceReducer = createReducer({}, fnMap);

    // Create a new wrapping reducer
    return (state, action) => {
        // Check to see if this slice reducer knows how to handle this action
        if(fnMap[action.type]) {
            // If it does, pass the slice to the slice reducer, and update the slice
            return {
                ...state,
                [sliceName] : sliceReducer(state[sliceName], action),
            };
        }

        // Otherwise, return the existing state unchanged
        return state;
    }
}

We've already seen that our createReducer utility takes a lookup table mapping action types to case handler reducer functions. Now, createConditionalSliceReducer takes the same lookup table, plus the name of a state slice to update. It uses createReducer to create a reducer that can handle a single slice, and returns a new reducer that checks incoming actions and only responds if any of the given case reducers know how to handle that action type.

Creating a Generic Entity Update Reducer

Looking at our Redux-ORM models, we can see that the basic process for updating a given model's values will be identical no matter what type of model it is. We need to create a Session instance, retrieve the right Model class for the item, look up the specific Model instance by ID, and then tell it to queue an update for the given fields. We can write a generic reducer to update any model instance by its type and ID.

We're going to create a new feature folder, features/entities/, and add the reducer logic there. We then need to create a top-level "feature reducer" function to execute that logic, and add the feature reducer to our root reducer.

Commit 1d5ccae6: Add a "entity feature reducer" and a generic "entity update reducer"

features/entities/entityReducer

import {ENTITY_UPDATE} from "./entityConstants";

import {createConditionalSliceReducer} from "common/utils/reducerUtils";

import schema from "app/schema";

export function updateEntity(state, payload) {
    const {itemType, itemID, newItemAttributes} = payload;

    const session = schema.from(state);
    const ModelClass = session[itemType];

    let newState = state;

    if(ModelClass.hasId(itemID)) {
        const modelInstance = ModelClass.withId(itemID);

        modelInstance.update(newItemAttributes);

        newState = session.reduce();
    }

    return newState;
}

const entityHandlers = {
    [ENTITY_UPDATE] : updateEntity,
};

const entityCrudFeatureReducer = createConditionalSliceReducer("entities", entityHandlers);

export default entityCrudFeatureReducer;

The basic updateEntity() function should be straightforward. We extract the itemType, itemID, and newItemAttributes fields from the action payload. The state parameter in this case should be just the entities slice of our root state. We create a Redux-ORM Session instance from our "tables", retrieve the right Model class by name, look up the specific Model instance by ID, and create a new state object with the updates applied.

From there, we create a lookup table for the action types this module knows how to handle, and use the createConditionalSliceReducer utility to generate a new reducer that will only respond to the actions in the lookup table, and ensure that only the entities slice is updated.

app/reducers/rootReducer.js

import mechsReducer from "features/mechs/mechsReducer";

+import entityCrudReducer from "features/entities/entityReducer";

// Omit combined reducer

const rootReducer = reduceReducers(
    combinedReducer,
+   entityCrudReducer,
);

We then add the top-level entity "feature reducer" as another argument to reduceReducers, and make sure that it's after the combined reducer. Now, we should be able to dispatch actions to update the contents of any one specific model instance in our state.

Editing Pilot Entries

Now that we have our generic entity update reducer in place, we can implement the ability to edit Pilot entries. We already set up the "start/stop editing" toggle last time, so we just need to hook up the event handlers and dispatch the right actions.

Hooking Up Pilot Inputs

We'll start with the Pilot's name field:

Commit 762a820: Hook up editing of pilot name field

features/pilots/PilotDetails/PilotDetails.jsx


+import {updateEntity} from "features/entities/entityActions";
+import {getValueFromEvent} from "common/utils/clientUtils";

const actions = {
    startEditingPilot,
    stopEditingPilot,
+   updateEntity,
}

export class PilotDetails  extends Component {
+   onNameChanged = (e) => {
+       const newValues = getValueFromEvent(e);
+       const {id} = this.props.pilot;
+
+       this.props.updateEntity("Pilot", id, newValues);
+   }

// Omit most rendering code

                <Form.Field
                    name="name"
                    label="Name"
                    width={16}
                    placeholder="Name"
                    value={name}
                    disabled={!canStopEditing}
+                   onChange={this.onNameChanged}
                    control="input"
                />

We import the updateEntity action creator we just wrote, and add it to the actions that will be bound up to auto-dispatch when called. We then add an onNameChanged handler, extract the new values from the change event, and dispatch updateEntity() by passing in the type of item ("Pilot") and the pilot's ID.

Let's try this out by editing one of the pilots. If we select the pilot named "Miklos Delius", click "Start Editing", and type "test" at the end of his name, we should see some actions dispatched:

And there we go! The dispatched action reached our entities feature reducer, and the updateEntity() reducer applied the updates to the right data object in the state. If we look at the screen, we should now see:

Because both the form and the list item are displaying the values from the same item in state, both of them have been updated. It's important to note that we are directly editing the values for this Pilot entry in our state. Much of the time, that behavior is not something we want. It's very likely that some parts of the application would still need to display the original data, at the same time that we are making edits to an item. We'll look at one way to handle the "draft/editing data" concept in the next post.

Next up is the "Rank" dropdown:

Commit af7e46e: Hook up Pilot "rank" dropdown

features/pilots/PilotDetails/PilotDetails.jsx


+   onRankChanged = (e, result) => {
+       const newValues = {rank : result.value};
+       const {id} = this.props.pilot;
+
+       this.props.updateEntity("Pilot", id, newValues);
+   }

// Omit rendering code

                <Form.Field
                    name="rank"
                    label="Rank"
                    width={16}
                    control={Dropdown}
                    fluid
                    selection
                    options={RANKS}
                    value={rank}
+                   onChange={this.onRankChanged}
                    disabled={!canStopEditing}
                />

Easy enough, and now we can promote Corporal Delius to be a Sergeant instead.

Using Generic Change Handlers

We've got three more fields that still need to be hooked up (we'll leave the "Mech" field alone for now). The "Age" field is another text input, and the "Gunnery" and "Piloting" fields are dropdowns. We could write three more individual change handlers for those three fields, but looking at the two we have already, things are pretty simple. In fact, onNameChanged doesn't actually refer to "name" anywhere specifically, and onRankChanged just references "rank" once as a key. We could turn those into a generic "text input" handler and a generic "SUI-React Dropdown" handler, and reuse them for all five inputs:

Commit dad0aa7: Use more generic onChange handlers for PilotDetails dropdowns and inputs

features/pilots/PilotDetails/PilotDetails.jsx

export class PilotDetails  extends Component {
-   onNameChanged = (e) => {
+   onInputChanged = (e) => {
        const newValues = getValueFromEvent(e);
        const {id} = this.props.pilot;

        this.props.updateEntity("Pilot", id, newValues);
    }

-   onRankChanged = (e, result) => {
-       const newValues = {rank : result.value};
+    onDropdownChanged = (e, result) => {
+       const {name, value} = result;
+       const newValues = { [name] : value};
        const {id} = this.props.pilot;

        this.props.updateEntity("Pilot", id, newValues);
    }

We then pass the appropriate change handler to each input field, and bam! All the inputs should now be editable:

Buffering Pilot Inputs

We've got one last improvement to make. The "Name" and "Age" fields are currently unbuffered, and dispatching an ENTITY_UPDATE action every time we type a key. We can use our <FormEditWrapper> component to buffer both of those inputs:

Commit bee1c96: Use FormEditWrapper to buffer changes from Pilot inputs

features/pilots/PilotDetails/PilotDetails.jsx

+import FormEditWrapper from "common/components/FormEditWrapper";

// Omit component and rendering code

+               <FormEditWrapper
+                   singleValue={true}
+                   value={ {name} }
+                   onChange={this.onInputChanged}
+                   passIsEditing={false}
+               >
                    <Form.Field
                        name="name"
                        label="Name"
                        width={16}
                        placeholder="Name"
-                    value={name}
                        disabled={!canStopEditing}
-                    onChange={this.onInputChanged}
                        control="input"
                    />
+               </FormEditWrapper>

+               <FormEditWrapper
+                   singleValue={true}
+                   value={ {age} }
+                   onChange={this.onInputChanged}
+                   passIsEditing={false}
+               >
                    <Form.Field
                        name="age"
                        width={6}
                        label="Age"
                        placeholder="Age"
                        control="input"
-                   value={age}
-                   onChange={this.onInputChanged}
                        disabled={!canStopEditing}
                    />
+                </FormEditWrapper>

Now, if we edit the name, we should only see a single ENTITY_UPDATE action get dispatched.

Final Thoughts

We're now making some significant progress. The application is starting to become usable, and we've used some fairly advanced capabilities and concepts in the process.

Next time, we'll deal with the issue of "draft/editing data" for forms, and see how to display the "current" values for an item at the same time that we edit the "work-in-progress" values for that same item.

Further Information

Practical Redux, Part 6: Connected Lists, Forms, and Performance

Tue, 10 Jan 2017 23:00:00 -0500

Intro

In Part 5, we added sourcemap support, used Redux-ORM to define and load data, and added some basic item selection tracking. This time, we'll connect lists and forms directly to Redux, discuss performance considerations, implement basic editing capabilities, and add conditional UI state handling.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #6: Practical Redux Part 6 WIP, and the final "clean" commits can be seen in in PR #5: Practical Redux Part 6 Final.

Connecting Additional Components

Picking up where we left off, we can see that each of our main "panel" components are connected to Redux, as well as the TabBar component. However, none of the components within those panels are directly connected. Instead, we're passing data and action creators down as props from each panel to its children. It's perfectly fine to only have a few connected components, but as an app grows, this can become a pain point.

The Redux FAQ covers this topic in the question "Should I only connect my top component, or can I connect multiple components in my tree?". Quoting the answer:

The current suggested best practice is to categorize your components as “presentational” or “container” components, and extract a connected container component wherever it makes sense:

Emphasizing “one container component at the top” in Redux examples was a mistake. Don't take this as a maxim. Try to keep your presentation components separate. Create container components by connecting them when it's convenient. Whenever you feel like you're duplicating code in parent components to provide data for same kinds of children, time to extract a container. Generally as soon as you feel a parent knows too much about “personal” data or actions of its children, time to extract a container.

In fact, benchmarks have shown that more connected components generally leads to better performance than fewer connected components.

In general, try to find a balance between understandable data flow and areas of responsibility with your components.

Following this idea, our next step will be to connect more individual components at a finer-grained level of detail.

Connecting the PilotDetails Component

We'll start with the <PilotDetails> component. Right now, the <Pilots> component is retrieving a list of all Pilot objects in its mapState function, plus the currentPilot ID value. Then, when it renders, it does a lookup to find which Pilot entry matches the selected ID, and passes that object to <PilotDetails>. We can connect <PilotDetails> directly, and remove that logic from <Pilots>.

This is a straightforward transformation. We'll add a mapState function to <PilotDetails>, look up the right Pilot object by ID if available, and return that entry. While we're at it, we'll also tweak the input components to be disabled, so that the user knows they can't actually interact with them.

Commit 7663759: Update PilotDetails to be connected

features/pilots/PilotDetails/PilotDetails.jsx

import React from "react";
+import {connect} from "react-redux";
import {Form, Dropdown} from "semantic-ui-react";

+import schema from "app/schema";
+import {selectCurrentPilot} from "../pilotsSelectors";

+const mapState = (state) => {
+    let pilot;
+    
+    const currentPilot = selectCurrentPilot(state);
+    
+    const session = schema.from(state.entities);
+    const {Pilot} = session;
+    
+    if(Pilot.hasId(currentPilot)) {
+        pilot = Pilot.withId(currentPilot).ref;
+    }
+    
+    return {pilot}
+}

// Omit component code for space

-export default PilotDetails;
+export default connect(mapState)(PilotDetails);

features/pilots/Pilots/Pilots.jsx

    render() {
        const {pilots = [], selectPilot, currentPilot} = this.props;

-       const currentPilotEntry = pilots.find(pilot => pilot.id === currentPilot) || {}

// Omit irrelevant rendering code
-                           <PilotDetails pilot={currentPilotEntry} />
+                           <PilotDetails />

The mapState connection replaces the logic we had in <Pilots>.

Connecting the PilotsList Component

Next up is the <PilotsList> component. The <Pilots> component currently extracts the actual Pilot objects from the store, passes them as an array to <PilotsList>, and then each individual plain Pilot object is passed as a prop to the "presentational" list items. We could just move the current mapState logic from <Pilots> to <PilotsList> and leave it at that, but instead, we're going to implement one of the most useful Redux techniques: a connected list that passes item IDs to connected list items. Let's look at the implementation, then discuss some of the details of the specific approach we're using.

The mapState for <PilotsList> will need to return an array of IDs for all Pilot entries. <PilotsList> will then render its list of <PilotsListRow> components, and pass the appropriate pilot ID into each list item. Either the list or the list item will need to determine if that list item is currently selected. There's valid arguments either way, but since we're already passing a selected flag into each list item, we'll leave that in place.

Commit dc2c6ab: Update PilotsList to be connected

features/pilots/PilotsList/PilotsList.jsx

+import {selectPilot} from "../pilotsActions";
+import {selectCurrentPilot} from "../pilotsSelectors";
+
+
+const mapState = (state) => {
+    const session = schema.from(state.entities);
+    const {Pilot} = session;
+
+    // Extract a list of IDs for each Pilot entry
+    const pilots = Pilot.all().withModels.map(pilotModel => pilotModel.getId());
+
+    const currentPilot = selectCurrentPilot(state);
+
+    // Return the list of pilot IDs and the current pilot ID as props
+    return {pilots, currentPilot};
+}
+
+// Make an object full of action creators that can be passed to connect
+// and bound up, instead of writing a separate mapDispatch function
+const actions = {
+    selectPilot,
+};
+

export class PilotsList extends Component {
    render() {
-      const {pilots, onPilotClicked, currentPilot} = this.props;
+       const {pilots = [], selectPilot, currentPilot} = this.props;

-       const pilotRows = pilots.map(pilot => (
+       const pilotRows = pilots.map(pilotID => (
            <PilotsListRow
-               pilot={pilot}
-               key={pilot.name}
-               onPilotClicked={onPilotClicked}
-               selected={pilot.id === currentPilot}
+               pilotID={pilotID}
+               key={pilotID}
+               onPilotClicked={selectPilot}
+               selected={pilotID === currentPilot}
            />
        ));

The Model.getId() method is useful if you don't happen to know the exact name of the ID field for a model type. Maybe it's actually name, or guid, or something else. We can declare the ID field name as part of the model declaration, and the getId() method will use that to look up the right field when asked.

There's a few other ways we could come up with the list of Pilot IDs. Since we do know the ID field name in the plain Pilot objects, we could do Pilots.all().map(pilot => pilot.id). Another approach involves digging into Redux-ORM's internals just a bit. The QuerySet class keeps an array of IDs for the entries it's encapsulating, as a field named idArr. So, we could in theory do const pilotIDs = Pilot.all().idArr, and return that. Finally, if we wanted to bypass using Redux-ORM's API, we could directly access the state.entities.Pilot.items array, where Redux-ORM keeps a list of all Pilot IDs in the state.

pilots/PilotsList/PilotsListRow.jsx

+const mapState = (state, ownProps) => {
+    const session = schema.from(state.entities);
+    const {Pilot} = session;
+
+    let pilot;
+
+    if(Pilot.hasId(ownProps.pilotID)) {
+        const pilotModel = Pilot.withId(ownProps.pilotID);
+
+        // Access the underlying plain JS object using the "ref" field,
+        // and make a shallow copy of it
+        pilot = {
+            ...pilotModel.ref
+        };
+
+        // We want to look up pilotModel.mech.mechType.  Just in case the
+        // relational fields are null, we'll do a couple safety checks as we go.
+
+        // Look up the associated Mech instance using the foreign-key
+        // field that we defined in the Pilot Model class
+        const {mech} = pilotModel;
+
+        // If there actually is an associated mech, include the
+        // mech type's ID as a field in the data passed to the component
+        if(mech && mech.type) {
+            pilot.mechType = mech.type.id;
+        }
+    }
+
+    return {pilot};
+}

For <PilotsListRow>, we just copy over the lookup logic we had in <Pilots>, except that now we're only looking up one entry instead of all of them. Also, we're using the pilotID prop that the <PilotsList> parent component is passing down. The connected wrapper component for <PilotsListRow> makes all passed-in props available to mapState if we declare that mapState takes two arguments. By convention, the second argument is referred to as ownProps.

Note that when mapState is declared to take two arguments, it will be called more often. This is in case a change of passed-in props would result in a change to the values returned from mapState.

features/pilots/Pilots/Pilots.jsx

- // Delete the existing mapState function entirely

-export class Pilots extends Component {
+export default class Pilots extends Component {
    render() {
-        const {pilots = [], selectPilot, currentPilot} = this.props;

        return (
            <Segment>
                <Grid>
                    <Grid.Column width={10}>
                        <Header as="h3">Pilot List</Header>
-                       <PilotsList
-                           pilots={pilots}
-                           onPilotClicked={selectPilot}
-                           currentPilot={currentPilot}
-                       />
+                       <PilotsList />
                    </Grid.Column>

// Omit other rendering logic


-export default connect(mapState, actions)(Pilots);

With those changes in place, the <Pilots> component is no longer connected, and is actually now back to being entirely presentational. It renders several layout-related components, and two connected containers: <PilotsList> and <PilotDetails>.

Connected Components and Performance

The changes to <PilotsList> bring up a key topic: performance. There's several things that are valuable to understand here.

Basic Performance Considerations

By default, whenever a React component re-renders, React will re-render all of its descendents. That means if the root component were to call this.setState(), the entire component tree will re-render. It's very likely that the majority of components in the tree would receive the exact same data as before and render the same output. React still has to diff the virtual DOM tree to determine if anything changed, so any render output that didn't change is effectively "wasted" effort. (React's shouldComponentUpdate method can be used to skip rendering for a component and its descendents, usually by doing comparisons to see if its props have really changed.)

Redux helps with this by limiting the sub-trees that actually need to re-render. connect generates wrapper components that manage subscriptions to the store, and each individual connected component instance is a separate subscriber. After each dispatch, every connected component will re-run its mapState function, and do shallow equality checks on the result to see if the returned values have changed since the last time. If the values returned by mapState are different, then the wrapper component will re-render the "real" component.

Note: "shallow equality" means doing === reference comparisons on each individual field within the object returned from mapState. The return object itself will always be different - what matters is if currentResult.someField === lastResult.someField, and so on for each field in the object.

Keys to Good Redux Performance

This has some important implications:

First, mapState functions should run as fast as possible. This means that a mapState function should minimize the amount of work it has to do, and do that work quickly. Avoid doing very expensive work in mapState unless absolutely necessary! This includes complex filtering and transformations. Memoized selector functions, such as the ones created by reselect, can ensure that expensive work is only done when something actually changed.

There's one very specific performance anti-pattern that involves use of Immutable.js. According to its author, Lee Byron, calling toJS() is extremely expensive, and should therefore NOT be done in mapState!. (There's several other performance concerns to take into consideration with Immutable.js - see the list of links at the end of this post for more information.)

Second, returning the same variable references as part of the mapState result is necessary to eliminate wasted re-renders. That means that if you're returning the same types of data at the same keys from mapState, but the keys point to different variable references each time, connect will think things have changed and re-render your component. One of the most common examples of this is using Array.map() inside of mapState. Every time you use map(), you create a new array reference. Again, memoized selectors can help with this by ensuring that the same values are returned.

Third, overall performance is a balance between the overhead of more mapState calls, and time spent by React re-rendering. Redux subscriptions are O(n) - every additional subscriber means a bit more work every time an action is dispatched. Fortunately, per the earlier quote from the FAQ, benchmarks have shown that the cost of more connected components is generally less than the cost of more wasted re-rendering.

Connected Performance Example

The classic example for examining Redux performance would be a list of 10,000 Todo items. The basic setup would have only the parent component connected, and directly passing a Todo object to each child. In this case, editing the text of one Todo will cause the list to re-render, and thus all 10,000 children to re-render as well.

However, if the list component only passes IDs to each child, and each child is connected and looks up its own Todo item by ID, then most of the time that Todo item will be the same and the list item component won't need to re-render. This is one of several reasons why normalized data is so useful in Redux, because normalized data makes it easy to look up a specific item by its type and ID.

There's an excellent slideshow called High Performance Redux that discusses this concept in detail, with demos of varying approaches and their performance.

Performance Concerns with Project Mini-Mek

Based on all that information, let's do a quick review of our implementation of a connected <PilotsList>.

The good news is that we are using the "connected list passing IDs to connected chilren" pattern. The bad news is there's several aspects that are not fully optimized yet:

The mapState for <PilotsList> is using Array.map() to create a list of all Pilot IDs. That list will be a different array reference every time, causing <PilotsList> to re-render.
Meanwhile, the mapState for <PilotsListRow> is creating a new object for the pilot prop each time as well, so <PilotsListRow> will also keep re-rendering
Neither <PilotsList> nor <PilotsListRow> are using any memoized selector functions at all
We're also creating a new Redux-ORM Session instance every time mapState is run, for each connected component.

Fortunately, given the size and scope of Project Mini-Mek, performance isn't actually a real concern right now. Because of that, we'll skip performance optimizations for now, and investigate those at a later time. For now, we've at least examined some of the major performance concerns to be aware of, and know where to look when it's time to actually implement optimizations.

Connecting the Mechs Components

We'll wrap up this section by applying the same sets of changes to the various components in the "Mechs" panel as well.

Commit 60c3f29: Update MechDetails to be connected

Commit bba6aa9: Update MechsList to be connected

Connecting Form Components

Thus far, our application has been non-interactive. We can currently click on Pilot and Mech list items to select them, but there's no way to modify anything. It's time to start implementing some interactivity.

Creating the Form Update Logic

Our first task is to hook up the <UnitInfo> form so that we can edit the current unit's name and change what Battletech House or mercenary group they're affiliated with. We'll need to add an action type and a case reducer to handle those updates, then modify <UnitInfo> so that it dispatches the action in response to onChange callbacks from the inputs.

Commit 7352c4f: Implement initial unit info update logic

The action/reducer changes are simple. New action type, a matching action creator, and a case reducer:

features/unitInfo/unitInfoReducer.js

import {DATA_LOADED} from "features/tools/toolConstants";
+import {UNIT_INFO_UPDATE} from "./unitInfoConstants";

+function updateUnitInfo(state, payload) {
+   return {
+       ...state,
+       ...payload,
+   };
+}

export default createReducer(initialState, {
    [DATA_LOADED] : dataLoaded,
+   [UNIT_INFO_UPDATE] : updateUnitInfo,
});

We could create entirely separate action types and reducers for updating the "Name" field and the "Affiliation" field, but that would be a waste of effort. Defining action payloads and reducer logic involves tradeoffs, and it's up to you to decide when actions should be more specific or more general. I usually avoid reducers that just blindly copy whatever the action contains, but in this case it's easy enough to just copy over the payload, and let the dispatching code ensure that the payload is formatted correctly.

Connecting a Controlled Input

One of the most important concepts to understand when learning React is the idea of "controlled inputs". If you're not familiar with controlled inputs, go read Gosha Arinich's article Controlled and uncontrolled form inputs in React don't have to be complicated, or the additional articles on forms in React linked at the end of the post.

As a quick summary, a controlled input is an input with a value prop and an onChange handler. That means that the input is being told what its value is at all times, instead of the application asking the input for its value when it's time to submit the form. Managing controlled inputs does take additional work, but ultimately makes the application much easier to think about, since all the form data is already being stored by the application.

Values for controlled inputs can be stored by a React component, or passed all the way back to a Redux store. Since the <UnitInfo> component is already connected, we just need to pass in the action creator, add an onChange handler for the "Affiliation" dropdown, and dispatch the action appropriately:

Commit dc4d179: Implement initial change handling for UnitInfo

features/unitInfo/UnitInfo/UnitInfo.jsx

+import {updateUnitInfo} from "../unitInfoActions";

+const actions = {
+   updateUnitInfo,
+};

class UnitInfo extends Component {
+   onAffiliationChanged = (e, result) => {
+       const {name, value} = result;
+
+       const newValues = { [name] : value};
+       this.props.updateUnitInfo(newValues);
+   }

// Omit unrelated rendering 

                        <Dropdown
+                           name="affiliation"
                            selection
                            options={FACTIONS}
                            value={affiliation}
+                           onChange={this.onAffiliationChanged}
                        />

// Omit rest of component

-export default connect(mapState)(UnitInfo);
+export default connect(mapState, actions)(UnitInfo);

A few things to note about the onAffiliationChanged handler:

First, we're using the stage 2 Class Properties syntax to define an auto-bound method using an arrow function, so that this inside the callback correctly refers to the component instance.

Second, while Semantic-UI-React's component props documentation is excellent, they don't seem to formally document the signature for the <Dropdown>'s onChange callback. After checking some issues such as SUI-React #581, I've confirmed that the <Dropdown> passes two arguments to its onChange callback: some event object, and a result object that contains the name of the component and its new value (like {name : "affiliation", value : "wd"}). We want to reshape that into something like {affiliation : "wd"}, so we use the ES6 object computed properties syntax to create the new object.

Finally, since we used the object shorthand syntax for binding up action creators with connect(), calling this.props.updateUnitInfo(newValues) immediately dispatches the action.

Now, if we go to the Unit Info tab and select "Draconis Combine" from the dropdown, we should see the dispatched action in our DevTools:

And the dropdown should now read "Draconis Combine":

From there, we can enable editing the "Name" field with just another change handler:

Commit 2cca3ea: Hook up unit info name input

features/unitInfo/UnitInfo/UnitInfo.jsx

+   onNameChanged = (e) => {
+       const {name, value} = e.target;
+
+       const newValues = { [name] : value};
+       this.props.updateUnitInfo(newValues);
+   }
    
// Omit other rendering

                    <Form.Field name="name" width={6}>
                        <label>Unit Name</label>
-                       <input placeholder="Name" name="name" value={name}/>
+                       <input
+                           placeholder="Name"
+                           name="name"
+                           value={name}
+                           onChange={this.onNameChanged}
+                       />
                    </Form.Field>

And now we can happily type some gibberish into the "Unit Name" field, and see it show up:

So, this is great progress! We can edit the name and affiliation of our combat unit.

Retrieving Values from Input Events

Right now we're manually extracting the name and value fields from the text input's onChange event. There's some differences in how HTML inputs structure their events. Checkboxes in particular use a different field name ( checked instead of value). We can write a small utility function to extract the name and value from events, and do the object formatting for us.

Commit 745eda8: Add a utility function to extract values from input events

common/utils/clientUtils.js

import {isObject} from "lodash";

export function getValueFromEvent(e) {
    const {target} = e;

    let newValues;

    if(target) {
        const value = (target.type === "checkbox") ? target.checked : target.value;
        newValues = {
            [target.name] : value,
        };
    }
    else if(isObject(e)) {
        newValues = e;
    }

    return newValues;
}

And that simplifies our code in <UnitInfo> a bit:

features/unitInfo/UnitInfo/UnitInfo.jsx

+import {getValueFromEvent} from "common/utils/clientUtils";


    onNameChanged = (e) => {
-       const {name, value} = e.target;
-
-       const newValues = { [name] : value};
+       const newValues = getValueFromEvent(e);
        this.props.updateUnitInfo(newValues);
    }

Type in the input, we get back a name/value object as needed, and we dispatch it. Looks great.

There is one problem with our text input that we need to address, but we'll deal with that next time.

Pilot Form UI State

Now that we can edit the basic attributes for our combat unit, it's time to move on to the Pilots panel. We want to add the ability to edit the attributes for our individual Pilot entries. As part of that, it would be nice if we actually could toggle whether we're in "edit mode" or not. For now, let's implement logic to track "editing mode" for pilots, and hold off on actually connecting the inputs until next time.

We already have logic for tracking which pilot is selected. To add to that, we should only be able to start editing if a pilot is selected. If we're editing one pilot, and click to select another, editing mode should be turned off.

Tracking Editing State for the UI

Let's start by adding some logic to track whether we're editing a pilot or not. We'll create a couple new action types (PILOT_EDIT_START and PILOT_EDIT_STOP), and update our pilots reducer with a new flag and the logic to update it appropriately:

Commit 09fda20: Add logic to track if a pilot is being edited

features/pilots/pilotsReducer.js

import {
    PILOT_SELECT,
+   PILOT_EDIT_START,
+   PILOT_EDIT_STOP,
} from "./pilotsConstants";

const initialState = {
    currentPilot : null,
+   isEditing : false,
};

export function selectPilot(state, payload) {
    const prevSelectedPilot = state.currentPilot;
    const newSelectedPilot = payload.currentPilot;

    const isSamePilot = prevSelectedPilot === newSelectedPilot;
    
    return {
        ...state,
        // Deselect entirely if it's a second click on the same pilot,
        // otherwise go ahead and select the one that was clicked
        currentPilot : isSamePilot ? null : newSelectedPilot,
+       // Any time we select a different pilot, we stop editing
+       isEditing : false,
    };
}

+export function startEditingPilot(state, payload) {
+   return {
+       ...state,
+       isEditing : true,
+   };
+}

+export function stopEditingPilot(state, payload) {
+   return {
+       ...state,
+       isEditing : false,
+   };
+}


export default createReducer(initialState, {
    [PILOT_SELECT] : selectPilot,
+   [PILOT_EDIT_START] : startEditingPilot,
+   [PILOT_EDIT_STOP] : stopEditingPilot,
});

The reducer logic is straightforward. We respond to "start" and "stop" by setting the isEditing flag appropriately, and also reset it to false whenever a pilots list entry is clicked.

Adding Edit Mode Toggles

Our next step is adding a pair of "Start / Stop Editing" buttons to the <PilotDetails> form, and hooking them up. We also want to add some conditional logic so that they're only enabled if appropriate.

Commit ab6f27e: Add "Start/Stop Editing" buttons to PilotDetails

features/pilots/PilotDetails/PilotDetails.jsx

-import {selectCurrentPilot} from "../pilotsSelectors";
+import {selectCurrentPilot, selectIsEditingPilot} from "../pilotsSelectors";

+import {
+   startEditingPilot,
+   stopEditingPilot,
+} from "../pilotsActions";


const mapState = (state) => {
    // Omit Pilot object lookup code
 
+   const pilotIsSelected = Boolean(currentPilot);
+   const isEditingPilot = selectIsEditingPilot(state);

-   return {pilot}
+   return {pilot, pilotIsSelected, isEditingPilot}
}

+const actions = {
+    startEditingPilot,
+    stopEditingPilot,
+}


-const PilotDetails = ({pilot={}}) =>{
+const PilotDetails = ({pilot={}, pilotIsSelected = false, isEditingPilot = false, ...actions }) =>{
// Omit attribute lookups

+    const canStartEditing = pilotIsSelected && !isEditingPilot;
+    const canStopEditing = pilotIsSelected && isEditingPilot;

    return (
        <Form size="large">
            <Form.Field name="name" width={16}>
                <label>Name</label>
                <input
                    placeholder="Name"
                    value={name}
-                   disabled={true}
+                   disabled={!canStopEditing}
                />
            </Form.Field>
// Omit other fields
+           <Grid.Row width={16}>
+               <Button
+                   primary
+                   disabled={!canStartEditing}
+                   type="button"
+                   onClick={actions.startEditingPilot}
+               >
+                   Start Editing
+               </Button>
+               <Button
+                   secondary
+                   disabled={!canStopEditing}
+                   type="button"
+                   onClick={actions.stopEditingPilot}
+               >
+                   Stop Editing
+               </Button>
+           </Grid.Row>

In our mapState function, we look at the currentPilot flag to determine if a pilot is selected or not, and pass that as a prop. In the component, we look at isEditing and pilotIsSelected, and derive two new flags to determine if the "Start" and "Stop" buttons should be enabled. We also use those to appropriately enable and disable the inputs.

One other useful note: by default, clicking an HTML <button> inside of a <form> will auto-submit the form. To avoid that, you have to give the button a type="button" attribute. Real pain in the neck, but now you know :)

Let's check out how the form looks now. If we have data loaded, select a pilot, and click "Start Editing", we should now see this:

That's probably a good place to wrap up the work for this post.

Final Thoughts

It took the first few posts to lay a foundation, but we're now seeing some progress. We've got a good pattern for connecting list components and list items. We've looked at some important performance considerations, and know where we can make performance improvements in the future. We can now do our first data editing, and we've added the ability to toggle the status of some UI components.

I had to split this post into two parts due to its size, so Part 7 should follow within the next few days. Part 7 will dig into some advanced techniques for managing form inputs and structuring reducer logic, so be sure to check that out soon!

Further Information

Practical Redux, Part 5: Loading and Displaying Data

Mon, 12 Dec 2016 23:00:00 -0500

Intro

Last time, we built up a hardcoded initial UI layout for Project Mini-Mek using Semantic-UI-React, added a tab bar component controlled by Redux, and started using a "feature-first"-style folder structure for our code. This time, we'll improve debugging support with sourcemaps, define data models with Redux-ORM, use those models to load data into the store and display it, and add the ability to track which items are selected.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #3: Practical Redux Part 5 WIP, and the final "clean" commits can be seen in in PR #4: Practical Redux Part 5 Final.

I'll be linking to each "final" commit as I go through the post, as well as specific files in those commits. I won't paste every changed file in here, to save space, but rather try to show the most relevant changes for each commit as appropriate.

Adding Sourcemap Support for Better Debugging

Before we can start working on the code for this set of improvements, we need to make some library updates that will help improve our development experience, by fixing up a weakness with the debugging process.

Tools like Webpack and Babel compile our input source code, transform it in various ways, and output a bundle containing all the transformed code in one file. This is great for production use, since users will load a site faster thanks to smaller files and fewer requests. However, trying to debug code that's been compiled, minified, and bundled is just about impossible. Fortunately, this can be solved with sourcemaps, which contain information the debugger can use to show the original code instead of the transformed code.

Webpack has many different options for creating sourcemaps, with varying tradeoffs for speed, details, and contents. Up through Create-React-App 0.7.0, CRA configured Webpack to use the eval sourcemaps option. That option shows you individual files in the debugger, but shows the code after it's been compiled by Babel. Looking at that in the debugger is better than trying to read minified/bundled code, but it's not exactly the prettiest, as seen in this screenshot:

The devtool: "eval" option was chosen because sourcemap support in both browsers and tools hasn't always worked right, and this option was known to at least produce usable results.

After a lot of discussion, in Create-React-App 0.8.0, the sourcemaps option was switched to one that should actually show the original code. I was extremely excited about this, but soon ran into a problem - while I could see the code as expected, I couldn't set any breakpoints. Fortunately, after some further investigation by the CRA and Webpack teams, fixes were made, and Create-React-App 0.8.2 was released with working sourcemap+breakpoints support. This made me very happy :). A couple other bug fix releases were put out while I was working on this post, so at the time of writing the latest version is Create-React-App 0.8.4.

Technically, create-react-app is just the CLI tool that's used to create a new project. The real magic happens in the react-scripts package, which includes all the build tool configuration. So, after running yarn add --dev react-scripts@0.8.4 and restarting the development server, the same debugger view should now look like this:

Notice that we now see the original source code (even the JSX), the DevTools debugger will let us set breakpoints on most of the lines in the file, and we've even added a breakpoint and stopped there during a re-render. This will make the development experience much easier as we go along! Definitely time to save that change.

Commit 01c62c6: Upgrade react-scripts to 0.8.4

With that upgrade in place, we can now turn our attention back to the code. We'll start by completing the file reorganization we worked on last time.

Making File Structure Consistent

As described in Part 4, we're using a "feature-first" folder structure. However, not all the code qualifies as a "feature". There's really three main divisions: common code that's generic and reused throughout the application, code that's specific to a feature, and the application-level code that ties those features together.

We'll do some more file shuffling to reflect those concepts:

Commit 611cb6f: Move core project files to /app for consistency

After the move, the project file structure now looks like this:

- src
  - app
    - layout
      - App.js, App.css
    - reducers
      - rootReducer.js
    - store
      - configureStore.js
  - common
    - components
    - utils
  - features
    - mechs
    - pilots
    - tabs
    - unitInfo
    - unitOrganization
  - index.js

Extracting Components in Features

The original UI layout we made in Part 4 has a single component for each of the tab panels. It also has fake data hardcoded right into the UI layout itself. That's not going to work well when we start dealing with actual data. So, before we can work with data, we should extract some components from those panels.

Looking at our <Pilots> component, it really consists of two main parts: the list of pilots, and the form showing the details of a single pilot. It makes sense to extract separate components for each of those, so we'll split out a <PilotsList> component and a <PilotDetails> component.

In addition, the pilots list has a couple different parts. The header section is static and won't change. We could leave that as part of, the render method in <PilotsList>, but we might as well split it out as a PilotsListHeader> while we're at it. At the same time, we definitely need to be able to render an individual row for each pilot entry, so we'll create a <PilotsListRow> component that we can use while rendering the list.

Since we're transitioning from hardcoded text in the UI, we should start making use of some kind of sample data. For the moment, the simplest approach is to treat <Pilots> as a "container" component, store an array with one item in its state, and pass that down to the list and details components.

Commit c404584: Extract components from Pilots panel, and add initial test data

The main part of our <Pilots> component now looks like this (skipping library imports):

features/pilots/Pilots/Pilots.jsx

import PilotsList from "../PilotsList";
import PilotDetails from "../PilotDetails";

const pilots = [
    {
        name : "Natasha Kerensky",
        rank : "Captain",
        age : 52,
        gunnery : 2,
        piloting : 3,
        mechType : "WHM-6R",
    }
];

export class Pilots extends Component {
    state = {
        pilots : pilots,
    }

    render() {
        const {pilots} = this.state;

        // Use the first pilot as the "current" one for display, if available.
        const currentPilot = pilots[0] || {};

        return (
            <Segment>
                <Grid>
                    <Grid.Column width={10}>
                        <Header as="h3">Pilot List</Header>
                        <PilotsList pilots={pilots} />
                    </Grid.Column>
                    <Grid.Column width={6}>
                        <Header as="h3">Pilot Details</Header>
                        <Segment >
                            <PilotDetails pilot={currentPilot} />
                        </Segment>
                    </Grid.Column>
                </Grid>
            </Segment>
        );
    }
}

Since our Mechs list is effectively identical so far, we'll do the same set of transformations on that as well.

Commit 6b51219: Extract components from Mechs panel, and add initial test data

There's one new and useful tidbit to show out of this commit. In Battletech, a Battlemech can weigh anywhere from 20 to 100 tons, in 5-ton increments. Mechs are frequently described and grouped based on their "weight class". Mechs from 20-35 tons are "Lights", 40-55 tons are "Mediums", 60-75 tons are "Heavies", and a Mech weighing 80-100 tons is an "Assault". This is a description that can be derived based on the known weight of a Mech type. So, we can write a small selector function that takes in a weight value, and returns a description of the weight class:

features/mechs/mechSelectors.js

const WEIGHT_CLASSES = [
    {name : "Light", weights : [20, 25, 30, 35]},
    {name : "Medium", weights : [40, 45, 50, 55]},
    {name : "Heavy", weights : [60, 65, 70, 75]},
    {name : "Assault", weights : [80, 85, 90, 95, 100]},
];

export function getWeightClass(weight) {
    const weightClass = WEIGHT_CLASSES.find(wc => wc.weights.includes(weight)) || {name : "Unknown"};
    return weightClass.name;
}

Nothing too fancy here. We define an array with one entry per weight class, and use the Array.find() method to return the first entry that matches a filter function. Our filter function uses the Array.includes() method to see if the given weight value is in the list of weights for that weight class. If we don't find a valid weight class, we provide a default result so that we can always return weightClass.name. This selector can then be used in <MechsListRow> and <MechDetails> to provide a display value for the given Mech instance.

Adding a Mock API for Sample Data

We're at a point where we need to start working with some data. In a bigger application or more realistic example, that would probably mean standing up a separate backend server to send back responses, or at least using some kind of "mock API" tool.

In order to keep this tutorial application as focused as possible, we're going to follow the classic advice of "Do The Simplest Thing That Could Possibly Work" / "You Ain't Gonna Need It". In this case, that means writing a file to contain our sample data, directly importing it into the source code, and writing a mock API query function that just returns that data in a promise.

We'll need a bit of UI to actually let us call that mock API function. Since we've already got our tabs bar set up, the simplest way to add some UI is to just create a new panel with a button that fetches the data, and add that as another tab. We'll label it the "Tools" panel for now. It might also make a good place to add "Import" and "Export" buttons down the road.

Commit db596954: Add a Tools panel and mock API for loading sample data

The only really interesting bits of out of here are the initial sample data, the mock API function, and our thunk action creator:

data/sampleData.js

const sampleData = {
    unit : {
        name : "Black Widow Company",
        affiliation : "wd",
    },
};

export default sampleData;

data/mockAPI.js

import sampleData from "./sampleData";

export function fetchData() {
    return Promise.resolve(sampleData);
}

features/tools/toolActions.js

import {fetchData} from "data/mockAPI";

import {DATA_LOADED} from "./toolConstants";

export function loadUnitData() {
    return (dispatch, getState) => {
        fetchData()
            .then(data => {
                dispatch({
                    type : DATA_LOADED,
                    payload : data
                })
            });
    }
}

After adding the panel, the UI looks like this:

Feel the excitement! :)

Connecting the Unit Info Tab

It's time to start hooking up some of our UI to the store. We'll start with the simplest part: the Unit Info tab. First, a bit of background info - it would be helpful to know what a "unit" is.

A Battletech "unit" is a military group, which could be part of the official armed forces of one of the various "star nations" in the Battletech universe, or an independent combat group like a mercenary unit. The five Great Houses in the Battletech universe all maintain vast armies, while hundreds of mercenary units large and small try to make a living through combat. Some examples of units from the game universe include:

Great House army units:
- 24th Dieron Regulars from the Draconis Combine
- 2nd Free Worlds Guards from the Free Worlds League
- 11th Avalon Hussars from the Federated Suns
Mercenaries:
- Wolf's Dragoons
- 21st Centauri Lancers
- Hansen's Roughriders

For now, we're just going to track two attributes for a unit: their name, and what larger group they are affiliated with.

We'll start by creating a simple reducer that stores the "Name" and "Affiliation" values, add that to our root reducer, and connect the <UnitInfo> component to use the data:

Commit bce3a2d: Add initial unit info reducer and connection

features/unitInfo/unitInfoReducer.js

import {createReducer} from "common/utils/reducerUtils";

const initialState = {
    name : "Black Widow Company",
    affiliation : "wd",
};

export default createReducer(initialState, {
});

features/unitInfo/unitInfoSelectors.js

export const selectUnitInfo = state => state.unitInfo;

app/reducers/rootReducer.js

import {combineReducers} from "redux";

import tabReducer from "features/tabs/tabReducer";
import unitInfoReducer from "features/unitInfo/unitInfoReducer";

const rootReducer = combineReducers({
    unitInfo : unitInfoReducer,
    tabs : tabReducer,
});

export default rootReducer;

features/unitInfo/UnitInfo/UnitInfo.jsx

const mapState = (state) => ({
    unitInfo : selectUnitInfo(state),
});

class UnitInfo extends Component {
    render() {
        const {unitInfo} = this.props;
        const {name, affiliation} = unitInfo;

        return (
            <Segment attached="bottom">
                <Form size="large">
                    <Form.Field name="name" width={6}>
                        <label>Unit Name</label>
                        <input placeholder="Name" value={name}/>
                    </Form.Field>
                    <Form.Field name="affiliation" width={6}>
                        <label>Affiliation</label>
                        <Dropdown
                            selection
                            options={FACTIONS}
                            value={affiliation}
                        />
                    </Form.Field>
                </Form>
            </Segment>
        );
    }
}

export default connect(mapState)(UnitInfo);

(Side note: remember how I said I'm still trying to figure out my own best practices for folder structure? After that last code sample, I definitely have to admit that having the word "unitInfo" show up three times in a path is kinda silly. Oh well, I'll deal with it for now.)

Now that the <UnitInfo> component is being driven by data from the store, we can do something with that sample data from the mock API. Let's update the unit info reducer to respond to the DATA_LOADED action and see what happens:

Commit 3ccddf1: Load unit details from sample data

features/unitInfo/unitInfoReducer.js

import {createReducer} from "common/utils/reducerUtils";

import {DATA_LOADED} from "features/tools/toolConstants";

const initialState = {
    name : "N/A",
    affiliation : "",
};

function dataLoaded(state, payload) {
    const {unit} = payload;

    return unit;
}

export default createReducer(initialState, {
    [DATA_LOADED] : dataLoaded,
});

The reducer's very simple for now. We start with some empty data in our initial state, listen for DATA_LOADED, and return the unit data from the action payload.

If we load the page, we should see "Name: N/A". If we then click the "Reload Unit Data" button in the Tools tab, we should see it change to "Name: Black Widow Company". No point in showing a screenshot here, because the UI should still look exactly the same as it has up until now.

Adding a Redux-ORM Schema and Model

Okay, so loading two fields was pretty easy. It's time to start actually working out what the application's data model will look like.

As described back in Part 0 and Part 3, the goal of this sample application is to build a miniature version of the Battletech MekHQ game tool. We want to be able to track Battlemech Pilots assigned to a combat unit, which specific Battlemech each Pilot is assigned to, and ultimately organize Battlemechs and their Pilots into groups called "Lances" and "Companies".

We're going to use the Redux-ORM library to help define what our data types are and how they relate to each other. Those Model types can then be used to help us load data into our store, and query and update that data. (See Part 1: Redux-ORM Basics and Part 2: Redux-ORM Concepts and Techniques for details on how the library works.)

The first thing we'll do is create a Redux-ORM Schema instance, and a parent reducer for all of our entity data. Since this code isn't specific to a single feature, we'll add it underneath the app folder.

Commit 1e48ca2: Create a Redux-ORM Schema and the initial entities reducer

app/schema/schema.js

import {Schema} from "redux-orm";

const schema = new Schema();

export default schema;

app/reducers/entitiesReducer.js

import {createReducer} from "common/utils/reducerUtils";

import schema from "app/schema"

const initialState = schema.getDefaultState();

export default createReducer(initialState, {
});

app/reducers/rootReducer.js

import {combineReducers} from "redux";

+import entitiesReducer from "./entitiesReducer";
import tabReducer from "features/tabs/tabReducer";
import unitInfoReducer from "features/unitInfo/unitInfoReducer";

const rootReducer = combineReducers({
+   entities : entitiesReducer,
    unitInfo : unitInfoReducer,
    tabs : tabReducer,
});

If we look at our overall app state now using the Redux DevTools, we'll see entities: {}. That's because we haven't added any Model types to the Schema instance.

The first Model type we should add is for pilots. We'll keep it really simple - just a Pilot class, with no relations, and add that to our Schema. There's no specific rule for where Model classes should be defined, so for the moment we're going to define them inside the relevant feature folders.

Commit 4ca88bd: Create Pilot model and add to schema

features/pilots/Pilot.js

import {Model} from "redux-orm";

export default class Pilot extends Model {
}

Pilot.modelName = "Pilot";

app/schema/schema.js

import {Schema} from "redux-orm";

+import Pilot from "features/pilots/Pilot";

const schema = new Schema();
+schema.register(Pilot);

export default schema;

Now that we have the Pilot model class registered with the Schema instance, we can go back to the Redux DevTools and see that the generated initial state for our entities slice reducer now includes an empty "table" for the Pilot type:

Loading Pilot Data with Redux-ORM

With the Pilot model hooked up to the Schema, we can start using it for something useful. We already have a sample data file and a DATA_LOADED action being dispatched containing that data. Let's add some pilot entries to that list, and load them into memory.

For sample entries, we're going to use the characters from the legendary Black Widow Company of the Wolf's Dragoons mercenary unit, as they existed in the 3025 game era. This group was led by the notorious Black Widow herself, Natasha Kerensky.

We'll define several attributes for each pilot: an ID, their name, rank, age, in-game Gunnery and Piloting skills (lower is better), and a short description of what type of Battlemech they pilot. An example looks like:

{
    pilots: [
        {
            id : 1,
            name : "Natasha Kerensky",
            rank : "Captain",
            gunnery : 2,
            piloting : 2,
            age : 52,
            mechType : "WHM-6R",
        },
        {
            id : 2,
            name : "Colin Maclaren",
            rank : "Sergeant",
            gunnery : 3,
            piloting : 4,
            age : 43,
            mechType : "MAD-3R",
        },
    ]
}

Once those entries have been added to the sample data, they wil be included in the DATA_LOADED action we've been dispatching. So, we should update our entitiesReducer to respond to that action.

Redux-ORM provides methods on Model instances to query, update, and delete instances. It also provides a create static method on the class itself to create new instances. I like to write parse methods on my Model classes that encapsulate the logic for handling all the relations that might be involved in nested JSON data. Since this is our first Model type, there's actually nothing special we need to do:

Commit 04a6785: Add Pilot parsing, and load Pilots from sample data

features/pilots/Pilot.js

import {Model} from "redux-orm";

export default class Pilot extends Model {
    static parse(pilotData) {
        // We could do useful stuff in here with relations,
        // but since we have no relations yet, all we need
        // to do is pass the pilot data on to create()

        // Note that in a static class method, `this` is the
        // class itself, not an instance
        return this.create(pilotData);
    }
}

Pilot.modelName = "Pilot";

app/reducers/entitiesReducer.js

export function loadData(state, payload) {
    // Create a Redux-ORM session from our entities "tables"
    const session = schema.from(state);
    // Get a reference to the correct version of the Pilots class for this Session
    const {Pilot} = session;

    const {pilots} = payload;
    // Queue up creation commands for each pilot entry
    pilots.forEach(pilot => Pilot.parse(pilot));

    // Apply the queued updates and return the updated "tables"
    return session.reduce();
}

export default createReducer(initialState, {
    [DATA_LOADED] : loadData,
});

Notice that we actually have two different slice reducers responding to the same action! Both our unitInfoReducer and our entitiesReducer are responding to the DATA_LOADED action. This is a key concept for Redux usage, which is often misunderstood or ignored. It doesn't happen by accident, or completely automatically - the combineReducers function we're using in our rootReducer is specifically calling both slice reducers, and giving them a chance to respond to that action by updating their own slice of data. We could implement the same behavior ourselves, but combineReducers does it for us. (We could also choose not to use combineReducers if we wanted to, and maybe handle things a different way if it made sense.)

If we hit the "Reload Unit Data" button in our "Tools" tab and check out the results in the DevTools, our entities slice should now contain entries for each of the pilot entries in our sample data:

Also notice that Redux-ORM automatically stored all the pilots in "normalized" form, by creating an items array for the Pilot type that stores a list of all item IDs, and an itemsById lookup table that stores the actual objects keyed by their IDs

Displaying a List of Pilots

Now that we have pilots added to the store, we can update our <Pilots> and <PilotsList> components to display them. Since we already had <Pilots> acting as a container component, all we really need to do is connect it to the store, return an array of plain JS pilot objects as a prop, and switch from using the sample entry we had stored in its state to the array from props.

To do this, we're going to import the singleton Redux-ORM Schema instance we created. In our mapState function, we'll create a Session instance from the current set of "tables" in our state, and use the Pilot class we defined to query those tables. We'll retrieve a list of the actual JS objects, and return those as a prop.

Commit 5e2b5d5: Connect the Pilots component to render a list of pilots from the store

features/pilots/Pilots/Pilots.jsx

// Omit imports not relevant to this commit
import schema from "app/schema";

const mapState = (state) => {
    // Create a Redux-ORM Session from our "entities" slice, which
    // contains the "tables" for each model type
    const session = schema.from(state.entities);

    // Retrieve the model class that we need.  Each Session
    // specifically "binds" model classes to itself, so that
    // updates to model instances are applied to that session.
    // These "bound classes" are available as fields in the sesssion.
    const {Pilot} = session;

    // Query the session for all Pilot instances.
    // The QuerySet that is returned from all() can be used to
    // retrieve instances of the Pilot class, or retrieve the
    // plain JS objects that are actually in the store.
    // The toRefArray() method will give us an array of the
    // plain JS objects for each item in the QuerySet.
    const pilots = Pilot.all().toRefArray();

    // Now that we have an array of all pilot objects, return it as a prop
    return {pilots};
}

export class Pilots extends Component {
    render() {
        const {pilots = []} = this.props;

        // Use the first pilot as the "current" one for display, if available.
        const currentPilot = pilots[0] || {};
        
        // Omit rendering code, which didn't change
    }
}
       
export default connect(mapState)(Pilots);

And with that, we finally have something useful and interesting displayed on screen!

Defining Models with Relations

Redux-ORM allows you to define relations between various model types, using standard database concepts. This is done by adding a fields entry on a Model class type itself, and using the relation operators provided by Redux-ORM. Also, as described in Part 2, when a Model instance is created Redux-ORM will generate getter properties for all fields in the actual data object, as well as all of the relational fields.

With those ideas in mind, we're almost ready to define our next couple Model types, but first we need to review a bit more information about the ideas we're trying to represent. In Battletech, there are many different Battlemech designs. Each design has different statistics: weight, speed, armor, weapons, and so on. There may also be different variations on the same design, which would share the same basic characteristics (usually weight and speed), but maybe have some differences in weapons and armor. There can be many different individual mechs of the same design. Here's some examples of different Battlemech design variants to give you the idea:

Stinger STG-3R: 20 tons; 6/9/6 movement points (walk/run/jump); 48 armor points; 1 Medium Laser and 2 Machine Guns
Stinger STG-3G: 20 tons; 6/9/6 movement points; 69 armor points; 2 Medium Lasers
Warhammer WHM-6R: 70 tons; 4/6 movement points; 160 armor points; 2 PPCs, 2 Medium Lasers, 2 Small Lasers, 1 SRM-6 launcher
Warhammer WHM-6D: 70 tons; 4/6 movement points; 217 armor points; 2 PPCs, 2 Medium Lasers, 2 Small Lasers

As a real-life comparison, the F-15 Eagle has several variants: the F-15C is made for air-to-air combat, the F-15D is a training version, the F-15E is intended for ground attacks, and hundreds of individual F-15s have been manufactured.

For our data modeling, we're going to create two more Model classes. We're going to need to store information on different Battlemech designs, and we also need to track individual mechs. Rather than copy all the attributes of a design into each individual Mech entry, we can just store the design once, and add a relation between the individual Mech and its design entry. Meanwhile, since Pilots are going to be assigned to Mechs, we would also want to be able to relate Pilots and Mechs to each other.

Based on that, we're going to create separate models for MechDesigns and Mechs. The Mech class will use "foreign key" relations to point to a MechDesign instance and a Pilot instance. For now, we'll also add an FK relation from Pilot to Mech so that we can look up the Mech instance that a given Pilot is assigned to. We'll also go ahead and create parse() methods on them so that we can load them from data. Finally, we'll add the Mech and MechDesign classes to our Schema instance, the same way we did with Pilot.

Commit f28fee9: Define Mech and MechDesign model classes, and add them to the schema

features/mechs/MechDesign.js

import {Model} from "redux-orm";

export default class MechDesign extends Model {
    static parse(designData) {
        return this.create(designData);
    }
}

MechDesign.modelName = "MechDesign";

features/mechs/Mech.js

import {Model, fk} from "redux-orm";


export default class Mech extends Model {
    static get fields() {
        return {
            type : fk("MechDesign"),
            pilot : fk("Pilot"),
        };
    }
    
    static parse(mechData) {
        return this.create(mechData);
    }
}

Mech.modelName = "Mech";

(The fields option could have been defined as Mech.fields = {...} as well, I've just been doing it this way since I started using Redux-ORM. No practical difference as far as I know.)

After making those changes, we're also going to be making several other related changes in a follow-up commit. First, we need to add entries for MechDesigns and Mechs to our sample data. Second, we need to update the existing Pilot data so that they refer to a specific individual mech's ID, rather than the ID of a mech type. Those data changes look roughly like this (for one of the entries):

Commit 3b25f24:Load Mechs and MechDesigns from sample data, and use in display

features/data/sampleData.js

pilots : [
    {
        id : 1,
        name : "Natasha Kerensky",
        rank : "Captain",
        gunnery : 2,
        piloting : 2,
        age : 52,
-       mech : "WHM-6R",
+       mech : 1,
    },
],
+designs : [
+   {
+       id : "WHM-6R",
+       name : "Warhammer",
+       weight : 70,
+   },
+],
+mechs : [
+   {
+       id : 1,
+       type : "WHM-6R",
+       pilot : 1,
+   },
+]

Third, we need to update our entities reducer to also load the Mech and Design entries into state:

app/reducers/entitiesReducer

export function loadData(state, payload) {
    // Create a Redux-ORM session from our entities "tables"
    const session = schema.from(state);
    // Get a reference to the correct version of model classes for this Session
    const {Pilot, MechDesign, Mech} = session;

    const {pilots, designs, mechs} = payload;

    // Queue up creation commands for each entry
    pilots.forEach(pilot => Pilot.parse(pilot));
    designs.forEach(design => MechDesign.parse(design));
    mechs.forEach(mech => Mech.parse(mech));

    // Apply the queued updates and return the updated "tables"
    return session.reduce();
}

The final change we need to make here is how we prepare the data in the mapState function for <Pilots>. Previously, we just returned the plain JS objects directly. Now, though, we need to follow the relations from Pilot to Mech to MechDesign in order to display what type of mech this Pilot uses. The revised mapState function now looks like this:

features/pilots/Pilots/Pilots.jsx

const mapState = (state) => {
    // Create a Redux-ORM Session from our "entities" slice, which
    // contains the "tables" for each model type
    const session = schema.from(state.entities);

    // Retrieve the model class that we need.  Each Session
    // specifically "binds" model classes to itself, so that
    // updates to model instances are applied to that session.
    // These "bound classes" are available as fields in the sesssion.
    const {Pilot} = session;

    // Query the session for all Pilot instances.
    // The QuerySet that is returned from all() can be used to
    // retrieve instances of the Pilot class, or retrieve the
    // plain JS objects that are actually in the store.

    // The withModels modifier will let us map over Model instances
    // for each entry, rather than the plain JS objects.
    const pilots = Pilot.all().withModels.map(pilotModel => {
        // Access the underlying plain JS object using the "ref" field,
        // and make a shallow copy of it
        const pilot = {
            ...pilotModel.ref
        };
        
        // We want to look up pilotModel.mech.mechType.  Just in case the
        // relational fields are null, we'll do a couple safety checks as we go.

        // Look up the associated Mech instance using the foreign-key
        // field that we defined in the Pilot Model class
        const {mech} = pilotModel;

        // If there actually is an associated mech, include the
        // mech type's ID as a field in the data passed to the component
        if(mech && mech.type) {
            pilot.mechType = mech.type.id;
        }

        return pilot;
    });

    // Now that we have an array of all pilot objects, return it as a prop
    return {pilots};
}

With these changes in place, the <PilotsList> should render exactly the same, but with the data for the last column now coming from the MechDesign "table" instead of being directly in each pilot entry.

Displaying a List of Mechs

We can now connect our <Mechs> component the same way we did <Pilots>. This is pretty straightforward, and the only really interesting part is the mapState method:

Commit 7a5b756: Connect the Mechs component to display a list of mechs from the store

features/mechs/Mechs/Mechs.jsx

// Omit imports

const mapState = (state) => {
    const session = schema.from(state.entities);
    const {Mech} = session;

    const mechs = Mech.all().withModels.map(mechModel => {
        const mech = {
            // Copy the data from the plain JS object
            ...mechModel.ref,
            // Provide a default empty object for the relation
            mechType : {},
        };

        if(mechModel.type) {
            // Replace the default object with a copy of the relation's data
            mech.mechType = {...mechModel.type.ref};
        }

        return mech;
    });

    return {mechs}
}

// Omit component

And that gives us this update to our UI:

Handling Selection Logic

We're almost done with this set of changes. The last thing to add for now is the ability for the user to click on either of the lists and select the item that was clicked on. Right now, we're just defaulting to using the first item in an array as the "current" item for display in the Details sections.

We'll start with the Pilots list. We don't have a reducer for anything pilot-related yet, so we'll create one. Going along with the idea of "normalization", all we need to store is the ID of the currently selected pilot. We'll actually get a bit fancy with the reducer logic, and handle de-selecting the current item entirely if the user clicks on it again:

Commit c42c5bd: Add logic for tracking the currently selected pilot

features/pilots/pilotsReducer.js

import {createReducer} from "common/utils/reducerUtils";

import {PILOT_SELECT} from "./pilotsConstants";

const initialState = {
    currentPilot : null
};

export function selectPilot(state, payload) {
    const prevSelectedPilot = state.currentPilot;
    const newSelectedPilot = payload.currentPilot;

    const isSamePilot = prevSelectedPilot === newSelectedPilot;
    
    return {
        // Deselect entirely if it's a second click on the same pilot,
        // otherwise go ahead and select the one that was clicked
        currentPilot : isSamePilot ? null : newSelectedPilot,
    };
}

export default createReducer(initialState, {
    [PILOT_SELECT] : selectPilot,
});

That gives us some data handling, but we need to hook that up to the UI. We need to pull the currentPilot ID value into <Pilots>, and use that in a couple places. We should pass the actual entry for the current pilot into <PilotDetails>, and it would also be nice to highlight the row for that pilot in the list. We also need to call the selectPilot action creator with the ID of the pilot whose row was just clicked on. Let's look at the relevant changes:

Commit 19c3c3a: Implement selection handling for pilots

features/pilots/Pilots/Pilots.jsx

// Omit initial imports

+import {selectPilot} from "../pilotsActions";
+import {selectCurrentPilot} from "../pilotsSelectors";

const mapState = (state) => {}
    // Omit pilot objects lookup
    
+   const currentPilot = selectCurrentPilot(state);

    // Now that we have an array of all pilot objects, return it as a prop
-   return {pilots};
+   return {pilots, currentPilot};
}


+// Make an object full of action creators that can be passed to connect
+// and bound up, instead of writing a separate mapDispatch function
+const actions = {
+    selectPilot,
+};

export class Pilots extends Component { 
    render() {
-       const {pilots = []} = this.props;
+       const {pilots = [], selectPilot, currentPilot} = this.props;

-       const currentPilot = pilots[0] || {};
+       const currentPilotEntry = pilots.find(pilot => pilot.id === currentPilot) || {}

        // Omit irrelevant layout component rendering for space
        return (
            <Segment>
-               <PilotsList pilots={pilots} />
+               <PilotsList
+                   pilots={pilots}
+                   onPilotClicked={selectPilot}
+                   currentPilot={currentPilot}
+               />
-               <PilotDetails pilot={currentPilot} />
+               <PilotDetails pilot={currentPilotEntry} />
            </Segment>
        );
    }
}

-export default connect(mapState)(Pilots);
+export default connect(mapState, actions)(Pilots);

features/pilots/PilotsList/PilotsList.jsx

export default class PilotsList extends Component {
    render() {
-       const {pilots} = this.props;
+       const {pilots, onPilotClicked, currentPilot} = this.props;

        const pilotRows = pilots.map(pilot => (
-           <PilotsListRow pilot={pilot} key={pilot.name}/>
+           <PilotsListRow
+               pilot={pilot}
+               key={pilot.name}
+               onPilotClicked={onPilotClicked}
+               selected={pilot.id === currentPilot}
+           />
        ));

        // Omit layout rendering for space
    }

features/pilots/PilotsList/PilotsListRow.jsx

+import _ from "lodash";

-const PilotsListRow = ({pilot={}}) => {
+const PilotsListRow = ({pilot={}, onPilotClicked=_.noop, selected}) => {
    const {
+        id = null,
        // Omit other fields
    } = pilot;
    
    return (
-       <Table.Row>
+       <Table.Row onClick={() => onPilotClicked(id)} active={selected}>

And voila! If we click on an entry in the pilots list, we should now see that row highlighted, and the entry also shown in the <PilotDetails> form:

And finally, after WAYYYY too long of a blog post, the last thing we'll do is implement the same behavior for the mechs list as well:

Commit 54794ac: Add logic for tracking the currently selected mech

Commit b461cb3: Implement selection handling for mechs

And we see the same nicely highlighted selection for the mechs list:

Final Thoughts

For those of you who actually got this far, congratulations! That was a lot of words, code, screenshots, and links. But, Project Mini-Mek is now starting to look vaguely useful. We've got some realistic-looking data being loaded up, our first data models are defined, we're displaying that data in the UI, and we can actually interact with the lists a bit. It's taken some time to get here, but we've laid a pretty good foundation for the application. After this, we should be able to start implementing some interesting and useful features with specific techniques.

Be sure to tune in next time, when we might just finally get around to doing some of that form editing work I've been promising for the last couple posts! :)

Further Information

Practical Redux, Part 4: UI Layout and Project Structure

Tue, 22 Nov 2016 19:30:36 -0500

Intro

Last time, we sketched out a feature list and some UI mockups for Project Mini-Mek, created a new project using Create-React-App, added a basic Redux configuration, and enabled the use of Hot Module Reloading so that we could see changes in our UI without having to reload the entire page. In this part, we'll set up the initial application layout to match our UI mockups, talk about folder structures, and look at an example of managing UI state with Redux.

Before starting this series, I posted a poll on Twitter asking whether people would rather see "clean" commits, all WIP commits, or both. The responses showed a preference for seeing "clean" commits, but I'm actually going to include a way for people to see both.

The code for this project is on Github at github.com/markerikson/project-minimek. The original WIP commits I made for this post can be seen in PR #1: Practical Redux Part 4 WIP, and the final "clean" commits can be seen in in PR #2: Practical Redux Part 4 Final.

Choosing a UI Toolkit

There's a seemingly infinite number of web UI toolkits and CSS frameworks out there, of which Bootstrap and its variations are probably the most popular. I've been using Semantic-UI in another project, and been very happy with it. It has a nice appearance out of the box, uses very readable markup, and allows considerable customization for theming, including several built-in theme options for various parts such as buttons.

Semantic-UI consists of two main aspects: CSS-only content for styling, and logic for smarter widgets (such as AJAX fetching capabilities for the Dropdown component). The original framework uses jQuery to implement its smart widgets.

There are numerous React libraries that provide React components which render Semantic-UI markup. However, many of them also try to wrap up the jQuery-based smart components as well. In my own current app, I've been trying to avoid dragging in jQuery as a dependency, so I spent some time looking for a React wrapper for Semantic-UI that avoided the jQuery parts. I eventually found React-Semantic-UI-Kit, which initially fit the bill. However, since I started using it, there have been few updates to the wrappers, and there's some lingering pain points with the library (such as inability to override styles).

One of the other React/Semantic-UI libraries I looked at was called "Stardust". It looked comprehensive and well written, but also wrapped up the jQuery components. (There was some useful discussion about their approach in a Reddit thread about Stardust.) Since then, the situation has changed. "Stardust" has been turned into the official Semantic-UI-React library, and now includes completely new React implementations for all of Semantic-UI's smart components, with no jQuery needed at all. So, we'll be using Semantic-UI-React for the UI layout and styling.

It's important to note that Semantic-UI-React is only about generating the correct markup and adding additional logic on top. In order for that markup to change any appearances, we need to include Semantic-UI's CSS. Semantic-UI has its own build system that can be used to generate a customized theme, but to simplify things, we're just going to use the semantic-ui-css package, which provides a prebuilt version of the full Semantic-UI CSS output.

Setting Up Semantic-UI

Our first step is to add semantic-ui-react and semantic-ui-css to our project;

yarn add semantic-ui-react semantic-ui-css

Then, we need to import the main Semantic-UI CSS file into our code so it gets included in the bundle. We should also render a single Semantic-UI <Header> component to make sure that's working as intended. While we're at it, let's yank out the sample component we set up, since we won't be needing it any more, and also do some cleanup on the original CSS and HTML that generated when the project was created (such as removing the spinning logo, and shrinking the size of the header bar).

Commit 059c2a7: Use Semantic-UI and clean up unused code

index.js

import {Provider} from "react-redux";

-import './index.css';
+import "semantic-ui-css/semantic.css";

App.js

import React, { Component } from 'react';
import {
    Header,
} from "semantic-ui-react";


import './App.css';

class App extends Component {
    render() {
        return (
            <div className="App">
                <div className="App-header">
                    <Header inverted as="h1">Project Mini-Mek</Header>
                </div>
            </div>
        );
    }
}

export default App;

With the sample code cleaned up, our initial empty UI now looks like:

Yay - a black bar with some white text! Isn't this exciting? :) Don't worry, we'll start adding a lot more from here.

Initial UI Layout

Let's review the original mockup for Project Mini-Mek's UI:

The main part of our layout is a tab bar with tabs for the four main panels. Semantic-UI's <Menu> component can be configured to display in a tabbed form, so we can go ahead and render an initial hardcoded version of our tabs:

Commit 9bfab80: Render initial hardcoded tab bar

App.js

import {
    Header,
+   Container,
+   Menu,
} from "semantic-ui-react";


class App extends Component {
    render() {
        return (
            <div className="App">
                <div className="App-header">
                    <Header inverted as="h1">Project Mini-Mek</Header>
                </div>
+               <Container>
+                   <Menu tabular size="massive">
+                       <Menu.Item name="unitInfo" active={true}>Unit Info</Menu.Item>
+                       <Menu.Item name="pilots" active={false}>Pilots</Menu.Item>
+                       <Menu.Item name="mechs" active={false}>Mechs</Menu.Item>
+                       <Menu.Item name="unitOrganization" active={false}>Unit Organization</Menu.Item>
+                   </Menu>
+               </Container>
            </div>
        );
    }
}

That gives us the following result:

Still not very exciting, but now we can start filling this out.

Building a TabBar Component

We're going to need to track which tab is active, change that on click, and re-render the tab list. We also will eventually need to swap which content panel is visible as well. I added a <TabBar> component that takes an array of tab names and labels and renders the tabs. Now, we could have the <TabBar> store the value of which tab is currently selected, but it's a good practice in React to write "container components" which store the state, and keep other components that are "presentational" and just display things based on the props they're given. So, we'll create a <TabBarContainer> component to track which tab is currently selected:

Commit c5600b7: Create a TabBar component to render a list of tabs

features/tabs/Tab.jsx

import React from "react";
import {Menu} from "semantic-ui-react";

const Tab = ({name, label, onClick, active}) => (
    <Menu.Item
        name={name}
        content={label}
        active={active}
        onClick={() => onClick(name)}
    />
);

export default Tab;

features/tabs/TabBar.jsx

import React from "react";
import {Menu} from "semantic-ui-react";

import Tab from "./Tab";

const TabBar = (props) => {
    const {tabs, currentTab, onTabClick, ...otherProps} = props;

    const tabItems = tabs.map(tabInfo => {
        const {name, label} = tabInfo;

        return (
            <Tab
                key={name}
                name={name}
                label={label}
                active={currentTab === name}
                onClick={onTabClick}
            />
        );
    });

    return (
        <div>
            <Menu tabular attached="top" {...otherProps}>
                {tabItems}
            </Menu>
        </div>
    )
}

export default TabBar;

features/tabs/TabBarContainer.jsx

import React, {Component} from "react";

import TabBar from "./TabBar";

export default class TabBarContainer extends Component {
    constructor(props) {
        super(props);

        const {tabs = [{name : null}]} = props;

        const firstTab = tabs[0];

        this.state = {
            currentTab : firstTab.name
        } ;
    }

    onTabClick = (name) => {
        this.setState({currentTab : name});
    }

    render() {
        const {tabs, ...otherProps} = this.props;
        const {currentTab} = this.state;
        
        return (
            <TabBar
                {...otherProps}
                currentTab={currentTab}
                onTabClick={this.onTabClick}
                tabs={tabs}
            />
        )
    }
}

With that in place, we can then use it to render our main set of tabs:

Commit 47154d0: Render the list of tabs using TabBarContainer

App.js

class App extends Component {
    render() {
        const tabs = [
            {name : "unitInfo", label : "Unit Info"},
            {name : "pilots", label : "Pilots"},
            {name : "mechs", label : "Mechs"},
            {name : "unitOrganization", label : "Unit Organization"}
        ];

        return (
            <div className="App">
                <div className="App-header">
                    <Header inverted as="h1">Project Mini-Mek</Header>
                </div>
                <Container>
                    <TabBarContainer tabs={tabs} size="massive" />
                </Container>
            </div>
        );
    }
}

No major visual changes from this, but we can now click on each tab and see the "active" tab get highlighted.

Rendering Tab Panels

Right now the tab bar only shows the tabs themselves, but no content. We really need to show a different component as the content for each tab, and swap which component is visible as the active tab changes.

One way to do this would be to actually change which component is being rendered for the content panel each time the currentTab prop changes. Another would be to always render all the tabs, but toggle the visibility instead of un-rendering them. We're going to go with toggling visibility, just because I feel like it.

It's not too hard to write the logic for toggling the display style on a given component, but I don't feel like writing that myself at the moment. There's a nice little utility component I've found called React-Toggle-Display that just renders a span with your content, and toggles the visibility of the span based on a condition or flag prop.

After adding that to the project, we need to update TabBar to look for components in the tab definitions, and render those wrapped in a <ToggleDisplay>. We also need to add some initial dummy components to our existing tab definitions:

Commit 21393ed: Add ability to swap visible tab component based on active tab

features/tabs/TabBar.jsx

import {Menu} from "semantic-ui-react";
+import ToggleDisplay from 'react-toggle-display';


const TabBar = (props) => {
    const {tabs, currentTab, onTabClick, ...otherProps} = props;

    const tabItems = tabs.map(tabInfo => { /*.....*/ });

+   const tabPanels = tabs.map(tabInfo => {
+       const {name, component : TabComponent} = tabInfo;

+       return (
+           <ToggleDisplay show={name === currentTab} key={name}>
+               <TabComponent />
+           </ToggleDisplay>
+       )
+   });

    return (
        <div>
            <Menu tabular attached="top" {...otherProps}>
                {tabItems}
            </Menu>
+
+            {tabPanels}
        </div>
    );
}

App.jsx


+const UnitInfo = () => <div>Unit Info content</div>;

+const Pilots = () => <div>Pilots content</div>;

+const Mechs = () => <div>Mechs content</div>;

+const UnitOrganization = () => <div>Unit Organization content</div>;

 class App extends Component {
     render() {
         const tabs = [
+           {name : "unitInfo", label : "Unit Info", component : UnitInfo,},
+           {name : "pilots", label : "Pilots", component : Pilots,},
+           {name : "mechs", label : "Mechs", component : Mechs,},
+           {name : "unitOrganization", label : "Unit Organization", component : UnitOrganization}
         ];
         
         // ....
     }
}

Now, as we click between tabs, we can see the visible panel change:

Now that we've got the tabs working, it's about time to start filling out the content for those tabs, and that means new components and new files. But, we're going to take a detour first. Creating new files means deciding where to put where to put them, and that's a topic in and of itself.

Thoughts on Folder Structure

There's been lots of discussion over what constitutes a good folder structure for a Redux application. The typical approaches generally fall into two categories: "file-type-first" (folders like /reducers, /components, etc), and "feature-first", also sometimes referred to as "pods" or "domain-based" (folders that each have all the file types for a given feature).

The original Redux examples use a "file-type-first" approach, but a lot of the recent articles and discussion have shown some convergence on the "feature-first" approach. There's tradeoffs either way - "file-type-first" makes it really easy to do something like pulling together all the reducers, but the code for a given feature can be scattered around, and vice versa for "feature-first".

My own current approach is mostly a "feature-first"-style approach. It's got some similarities to the approach described by Max Stoiber in his article How to Scale React Applications. The main differences are:

I prefer to give my files full unique names, rather than having files named "actions.js" and "reducer.js" in every folder. This is mostly for ease of finding files and reading file names in editor tabs. I also would rather give component files unique names, rather than naming them SomeComponent/index.js.
I've been using index.js files to re-export functions and components upwards as a sort of "public API" for nested folders.
I put these folders grouped under a folder named features, rather than containers
I personally tend to use thunks pretty heavily, only using sagas for some specific chunks of async logic.
I also prefer to use "absolute imports", such as from "features/someFeature/SomeComponent", rather than multi-level relative imports.

All that said, I'm honestly not 100% happy with my current approach. In particular, in a larger app I've noticed that the time needed to hot-reload changes has gone up considerably, and I'm not sure how much is due to just having more code, and how much is due to a more entangled dependency tree causing more files to be affected. The proliferation of index.js files and re-exports is also annoying. So, I'll freely admit that I'm still trying to figure things out myself.

So, with those caveats, we're at a point where we should start extracting files to a more maintainable structure, but there's a couple tweaks we have to make first.

Enabling Absolute Imports

As I mentioned, I prefer to consistently use import paths that start from the src folder. Among other things, that makes it easier to move files around, as compared to relative import paths.

Normally, I'd enable that by changing some path resolution options in my Webpack config, but since Create-React-App keeps all the configuration hidden, that's not an option unless we eject the project. I did some digging around, and it turns out that, at least for now, there's a semi-undocumented way to enable this in a CRA app without having to eject. If the NODE_PATH environment variable is set, CRA/Webpack will use that in the resolution process. Also, if a .env file exists in the project root, those environment variables will be loaded up. So, we can enable absolute imports by putting those two together. However, the default .gitignore file generated by CRA ignores .env, so we'll need to fix that:

Commit 922292f: Enable absolute import paths (such as "features/a/SomeComponent")

.env

NODE_PATH=src

.gitignore

-.env

With that, we can extract the dummy tab panel components into separate feature folders, and import them into App.js:

Commit 07a9c68: Extract tab panels into separate feature folders

App.js

import TabBarContainer from "./components/TabBar";
+import UnitInfo from "features/unitInfo/UnitInfo";
+import Pilots from "features/pilots/Pilots";
+import Mechs from "features/mechs/Mechs";
+import UnitOrganization from "features/unitOrganization/UnitOrganization";

import './App.css';

-const UnitInfo = () => <div>Unit Info content</div>;
-const Pilots = () => <div>Pilots content</div>;
-const Mechs = () => <div>Mechs content</div>;
-const UnitOrganization = () => <div>Unit Organization content</div>;

Building The First Content Components

Unit Info Tab

The first major piece of our UI will allow displaying and editing the details for whatever fictional Battletech combat group we've created. That includes things like what the name of the group is, what faction they work for, and so on.

Per the mockup shown earlier, the Unit Info tab is just a basic form with a few fields. We'll just add the "Name" and "Affiliation" fields for now, and deal with the other fields another time.

Filling out the <UnitInfo> component is pretty straightforward:

Commit 7bcde03: Add initial form layout for UnitInfo

features/unitInfo/UnitInfo/UnitInfo.jsx

import React from "react";
import {
    Form,
    Dropdown,
    Segment
} from "semantic-ui-react";

const FACTIONS = [
    // skip other entries
    {value : "lc", text : "Lyran Commonwealth"},
    {value : "wd", text : "Wolf's Dragoons"},
];

const UnitInfo = () => {

    return (
        <Segment attached="bottom">
            <Form size="large">
                <Form.Field name="name" width={6} >
                    <label>Unit Name</label>
                    <input placeholder="Name" value="Black Widow Company"/>
                </Form.Field>
                <Form.Field name="affiliation" width={6}>
                    <label>Affiliation</label>
                    <Dropdown
                       selection
                       options={FACTIONS}
                       value="wd"
                    />
                </Form.Field>
            </Form>
        </Segment>
    );
}

export default UnitInfo;

And now we finally have something slightly more visible to show off:

Pilots Tab

The second major part of the UI is a list of all the pilots that are part of our unit, and a section that will let us view and edit the details of the currently selected pilot. I'll skip pasting in the entire Pilots tab component to save space, but here's the commit and the resulting UI:

Commit 4f871f1: Add initial Pilots tab layout with hardcoded content

Handling Tab State with Redux

While working on the Pilots tab, a problem becomes noticeable: because the "current tab" value is stored as state in the <TabBarContainer> component, reloading the component tree resets the selected tab when the component instance gets wiped out. This is where Redux can help us, by moving our state outside the component tree. Fortunately, because we kept the tab state in the <TabBarContainer> component, we can replace the local component state version with one that pulls the value from Redux instead. The feature folder will contain the standard action constants, action creators, and reducers, as well as the selector functions to encapsulate looking up this piece of state. For simplicity, we'll just look at the reducer and the new version of <TabBarContainer>:

Commit e2312e2: Rewrite tabs handling to be driven by Redux

features/tabs/tabReducer.js

import {createReducer} from "common/utils/reducerUtils";

import {TAB_SELECTED} from "./tabConstants";

const initialState = {
    currentTab : "unitInfo",
};

export function selectTab(state, payload) {
    return {
        currentTab : payload.tabName,
    };
}

export default createReducer(initialState, {
    [TAB_SELECTED] : selectTab,
});

features/tabs/TabBarContainer.jsx

import React, {Component} from "react";
import {connect} from "react-redux";

import TabBar from "common/components/TabBar";

import {selectCurrentTab} from "./tabSelectors";
import {selectTab} from "./tabActions";

const mapState = (state) => {
    const currentTab = selectCurrentTab(state);

    return {currentTab};
}

const actions = {onTabClick : selectTab};

export default connect(mapState, actions)(TabBar);

A couple things to note here. We're using one of the umpteen million createReducer utility functions out there, which lets you define separate reducer functions and a a lookup table instead of switch statements. We're also using the object shorthand syntax that connect supports for the mapDispatch argument, allowing you to pass in an object full of action creator functions to be bound up, instead of writing an actual mapDispatch function yourself.

Filling Out the Other Tabs

Mechs Tab

With the tab state persisted, we can turn our attention back to laying out the other tabs. The third major part of the UI is the Mechs tab. This will basically be identical to the Pilots tab, in that it's a list of what Battlemechs our force owns, and some form of ability to view and edit details for a selected Battlemech.

Again, the layout code is long enough that it's not worth pasting here in full, but here's what the resulting UI looks like:

Commit f8f6fc4: Add initial Mechs tab layout with hardcoded content

Unit Organization Tab

The last major part of the UI is the Unit Table of Organization tab. In Battletech fiction, Pilots and Mechs are grouped together into Lances of four Mechs apiece. Three Lances are then grouped together to form a Company. We're going to need some kind of treeview that will show the hierarchy of Company > Lance > Pilot+Mech, and eventually will need to be able to rearrange which Pilots are in which Lances. For now, we'll just hardcode a tree-like display into the UI, and leave things alone until it's time to build the real thing:

Commit e5f5258: Add initial Unit Organization tab layout with hardcoded content

Final Thoughts

That was a pretty good chunk of work. We've got all of our main UI laid out to match the mockups, started using a folder structure that should help the code stay maintainable as we move forward, and added some initial UI logic using Redux. From here, we can start implementing some actual functionality, and that will give us a chance to look at some specific useful Redux techniques in the process.

Next time, we'll look at some approaches for working with forms in Redux, and maybe actually get around to doing some data modeling as well.

Further Information

Project Mini-Mek repo
- PR #1: Practical Redux Part 4 - WIP branch
- PR #2: Practical Redux Part 4 - Final branch
Semantic-UI
React-Toggle-Display
Container/Presentational Components
- Dan Abramov: Presentational and Container Components
- React/Redux Links: React Component Patterns
Folder Structures
Absolute imports in Create-React-App
Selector Functions
- Querying a Redux Store
- React/Redux Links: Redux Reducers and Selectors

Practical Redux, Part 3: Project Planning and Setup

Thu, 10 Nov 2016 23:00:00 -0400

Planning The Sample Application

As I mentioned in the series introduction, I've got a number of specific techniques and concepts that I'd like to talk about. I've had several requests to show some actual working examples of these techniques, so I've decided to try to build a small example application to demonstrate these ideas in a meaningful context.

I'm a big fan of the Battletech game universe, a game about big stompy robots with weapons that are used to fight wars a thousand years in the future. The game universe includes miniatures tabletop games, computer games, roleplaying games, fiction, and more.

There's a number of fan-built projects based in the Battletech universe. One of the most popular is Megamek, a cross-platform computer implementation of the Classic Battletech tabletop game. In addition, the Megamek authors have built a tool called MekHQ, a tool for managing an ongoing campaign for a fictional combat organization, such as a mercenary unit.

For this blog series, I'm planning to build a miniature version of the MekHQ application. I definitely do not intend to seriously rebuild all of MekHQ's functionality, but it should serve as a useful inspiration and justification for most of the techniques I want to show off.

On a related note: I'm absolutely making this up as I go along :) I've got some definite ideas for what I want to show off, but I'll be developing this sample app as I work on each post. That means I'll probably make some mistakes, need to change things, and iterate on the code. This will be a learning experience for everyone involved :)

Every project needs a good name. I haven't come up with a good name yet, so we'll call this "Project Mini-Mek" for now. (If anyone comes up with a better name, I'm listening!)

Project Features

MekHQ is a very complex and in-depth application. The "About" page describes it this way:

MekHQ is a Java program that allow users to manage units in-between actual games of MegaMek. It implements most of the rules in the "Maintenance, Repair, and Salvage" section of Strategic Operations, many of the rules and options from the Mercenary Field Manual, and various options that allow users to customize a mercenary, house, or clan campaign to their liking . Some of the features include:

Track XP and improve pilot skills and abilities

Integration with MegaMek and MegaMekLab

Planetary map and the plotting of jumpship travel

Organize a TO&E

Create and resolve missions and scenarios

Repair and salvage units

Equipment tracking

Financial tracking

For Project Mini-Mek, we're only going to deal with a couple of these, and at a very simple level. Here's a tentative list of features:

Load JSON data describing the pilots and Battlemechs in a combat force
For both pilots and Battlemechs:
- Show a list of all items
- Allow selection of an item in the list, and show details of the selected item
Edit the details for a pilot
Organize the pilots and their mechs into "lances" of four mechs, and the "lances" into a "company" of three lances.
Add and remove pilots and mechs from the force
Save the force back out to JSON

So, basically Yet Another CRUD APP, with some specific themes :) For now, I'm not planning to deal with a backend or any AJAX handling. I figure I'll start with static JSON being directly imported, and then maybe add file import/export later on.

UI Mockups

MekHQ: Pilot Listing

Let's start by looking at some screenshots of the original MekHQ UI. First, here's the screen that shows the list of pilots, and the details for the currently selected pilot:

MekHQ: Unit Table of Organization Tree

Next, the "Unit Table of Organization" section, showing the various sub-units in a tree structure, and again with a details section on the right:

This gives us a general idea of the UI layout we want: a tab bar across the top, with most of the tab panes containing a list of some kind on the left, and a details box for the currently selected item on the right.

Here's some rough mockups of what our UI might look like:

Project Mini-Mek: Unit Info

Project Mini-Mek: Pilot Listing

Project Mini-Mek: Mech Listing

Project Mini-Mek: Unit Table of Organization Tree

Project Setup and Configuration

We're going to set up the project using the excellent Create-React-App tool. I'm also going to be using the new Yarn package manager, partly because it's supposed to be faster, and partly because this gives me a chance to try it out. Also, as an FYI, I'm writing all this on Windows, but I don't expect any meaningful OS/platform issues to pop up as we go. Finally, I don't necessarily intend to show every last command I've typed or bit of code I've written as we go on - the real focus is intended to be on using Redux itself, not using Git or an editor.

The project is available on Github, at https://github.com/markerikson/project-minimek. I plan on updating it as I publish each post, and hope to show both some of the nitty-gritty "WIP" commits as well as cleaner "final result" commits. Also, when I show code snippets or refer to source files in the repo, I'll usually try to link to that file on Github at the specific version where the changes were made.

All right, let's do this!

Creating the Project

Follow the instructions for installing the create-react-app and yarn tools on your system. Once that's done, we can create our project:

create-react-app project-minimek

This is a good time to initialize a Git repo for the initial sample files and project config files. After the project is created, we want to set up a Yarn lockfile to nail down the specific dependency versions we're using. create-react-app already installed everything it needs (using NPM, although Yarn support is planned), but we need to run yarn to make sure we're ready for adding more dependencies:

cd project-minimek
yarn

There's a bunch more file work done as Yarn figures out what dependencies you have, and prepares its lockfile, yarn.lock. That should be committed to Git as well.

Dependencies

Time to pull in our initial list of dependencies. Here's what we're going to add:

Redux: because without it, this would be a really short blog series
React-Redux: ditto
Redux-Thunk: the most common and simple addon for side effects and complex dispatching logic
Reselect: needed for memoized "selector" functions when retrieving data from our state
Redux-ORM: a handy abstraction layer for managing relational data in our state
Lodash: every useful function you can think of, and a bunch more you didn't even know existed
cuid: We'll probably be generating IDs at some point, so this will fill that need

We can add them all in at once:

yarn add redux react-redux redux-thunk reselect redux-orm lodash cuid

And then commit our package.json and yarn.lock again.

Initial Redux Configuration

We need to set up the initial Redux store and reducers, make the store available to our component tree, and make sure that it's being used. Here's what my initial Redux configuration looks like:

store/configureStore.js

import {createStore, applyMiddleware, compose} from "redux";

import thunk from "redux-thunk";

import rootReducer from "../reducers/rootReducer";

export default function configureStore(preloadedState) {
    const middlewares = [thunk];
    const middlewareEnhancer = applyMiddleware(...middlewares);

    const storeEnhancers = [middlewareEnhancer];
    
    const composedEnhancer = compose(...storeEnhancers);

    const store = createStore(
        rootReducer,
        preloadedState,
        composedEnhancer
    );

    return store;
}

I like to keep my store setup logic in a configureStore function that can be further improved as time goes on. I also try to keep the setup for each piece of the configuration process separate, so it's easy to follow what's going on.

reducers/testReducer.js

const initialState = {
    data : 42
};

export default function testReducer(state = initialState, action) {
    return state;
}

reducers/rootReducer.js

import {combineReducers} from "redux";

import testReducer from "./testReducer";

const rootReducer = combineReducers({
    test : testReducer,
});

export default rootReducer;

Our initial reducers just pass along some test data so we can verify things are working.

We then create a store instance and use it in the rendering process:

index.js

import React from 'react';
import ReactDOM from 'react-dom';
import {Provider} from "react-redux";

import App from './App';
import './index.css';

import configureStore from "./store/configureStore";
const store = configureStore();

ReactDOM.render(
    <Provider store={store}>
        <App />
    </Provider>,
    document.getElementById('root')
);

Finally, we add a simple test component, connect it to Redux, and render it in our App component to verify that everything's hooked up properly:

SampleComponent.jsx

import React, {Component} from "react";
import {connect} from "react-redux";

const mapState = state => ({
    data : state.test.data
});

class SampleComponent extends Component {
    render() {
        const {data} = this.props;
        
        return (
            <div>
                Data from Redux: {data}
            </div>
        );
    }
}

export default connect(mapState)(SampleComponent);

App.js

import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';

import SampleComponent from "./SampleComponent";

class App extends Component {
    render() {
        return (
            <div className="App">
                <div className="App-header">
                    <img src={logo} className="App-logo" alt="logo"/>
                    <h2>Project Mini-Mek</h2>
                </div>
                <SampleComponent />
            </div>
        );
    }
}

export default App;

We should now see the text "Data from Redux: 42" in our page, right below the header bar.

Adding the Redux DevTools Extension

One of the original reasons for Redux's creation was the goal of "time-travel debugging": the ability to see the list of dispatched actions, view the contents of an action, see what parts of the state were changed after the action was dispatched, view the overall application state after that dispatch, and step back and forth between dispatched actions. Dan Abramov wrote the original Redux DevTools toolset, which showed that information with the UI as a component within the page.

Since then, Mihail Diordiev has built the Redux DevTools Extension, a browser extension that bundles together the core Redux DevTools logic and several community-built data visualizers as a browser extension, and adds a bunch of useful functionality on top of that. Connecting the DevTools Extension to your store requires a few extra checks, so there's now a package available that encapsulates the process needed to hook up the DevTools Extension to your store.

We'll add the helper package with yarn add redux-devtools-extension, then make a couple small changes to the store setup logic:

store/configureStore.js

- import {createStore, applyMiddleware, compose} from "redux";
+ import {createStore, applyMiddleware} from "redux";
+ import { composeWithDevTools } from 'redux-devtools-extension/developmentOnly';


- const composedEnhancer = compose(...storeEnhancers);
+ const composedEnhancer = composeWithDevTools(...storeEnhancers);

This should add the DevTools enhancer to our store, but only when we're in development mode. With that installed, the Redux DevTools browser extension can now view the contents of our store and the history of the dispatched actions.

Component Hot Reloading

Out of the box, create-react-app will watch your files on disk, and whenever you save changes, it will recompile the application and reload the entire page. That's nice, but we can actually set up some improvements on that. In particular, the Webpack build tool used by create-react-app supports a feature known as Hot Module Replacement, or HMR, which can hot-swap the newly compiled versions of files into your already-open application. That lets us see our changes faster. This works great with a React app, and even better in combination with Redux, since we can reload our component tree but still keep the same application state as before.

We'll also want to add the redbox-react package, which we can use to render an error message and a stack trace if something goes wrong. Once that's installed, we need to update index.js to rework the top-level rendering logic:

index.js

import React from 'react';
import ReactDOM from 'react-dom';
import {Provider} from "react-redux";

import './index.css';

import configureStore from "./store/configureStore";
const store = configureStore();

// Save a reference to the root element for reuse
const rootEl = document.getElementById("root");

// Create a reusable render method that we can call more than once
let render = () => {
    // Dynamically import our main App component, and render it
    const App = require("./App").default;
    
    ReactDOM.render(
        <Provider store={store}>
            <App />
        </Provider>,
        rootEl
    );
};

if(module.hot) {
    // Support hot reloading of components
    // and display an overlay for runtime errors
    const renderApp = render;
    const renderError = (error) => {
        const RedBox = require("redbox-react").default;
        ReactDOM.render(
            <RedBox error={error} />,
            rootEl,
        );
    };

    // In development, we wrap the rendering function to catch errors,
    // and if something breaks, log the error and render it to the screen
    render = () => {
        try {
            renderApp();
        }
        catch(error) {
            console.error(error);
            renderError(error);
        }
    };

    // Whenever the App component file or one of its dependencies
    // is changed, re-import the updated component and re-render it
    module.hot.accept("./App", () => {
        setTimeout(render);
    });
}

render();

With this in place, editing one of our components (such as changing the text in SampleComponent.jsx) should now just reload the component tree, rather than reloading the entire page. If there's an error, we should see it displayed on the screen and logged in the console. (To try it out, you can add throw new Error("Oops!") to SampleComponent.render() and see what happens.)

Reducer Hot Reloading

Finally, we can also configure our project to hot-reload our reducers as well. Right now, if we edit the initial state in our testReducer.js from data : 42 to data : 123, we'll see the whole page reload, just like it did for component edits before we added the hot reloading. We need to listen for updates to the root reducer file, re-import it, and then replace the old reducer in the store with the new one. The updated configureStore.js looks like this:

store/configureStore.js

import {createStore, applyMiddleware} from "redux";
import { composeWithDevTools } from 'redux-devtools-extension/developmentOnly';

import thunk from "redux-thunk";

import rootReducer from "../reducers/rootReducer";

export default function configureStore(preloadedState) {
    const middlewares = [thunk];
    const middlewareEnhancer = applyMiddleware(...middlewares);

    const storeEnhancers = [middlewareEnhancer];
    
    const composedEnhancer = composeWithDevTools(...storeEnhancers);

    const store = createStore(
        rootReducer,
        preloadedState,
        composedEnhancer
    );

    if(process.env.NODE_ENV !== "production") {
        if(module.hot) {
            module.hot.accept("../reducers/rootReducer", () =>{
                const newRootReducer = require("../reducers/rootReducer").default;
                store.replaceReducer(newRootReducer)
            });
        }
    }

    return store;
}

Final Thoughts

At this point, we know what kind of app we want to build, and have a decent idea what it should do and what it should look like (or at least enough of an idea to get us started). We also have an initial project set up with our basic dependencies, and some nice tweaks to the development workflow.

Next time, we'll at setting up some initial UI layout, and possibly tackle some of the initial data modeling as well.

If you've got questions, comments, or suggestions, please let me know! Leave me a comment here, file an issue in the repo, or ping me on Twitter or Reactiflux.

Further Information

Practical Redux, Part 2: Redux-ORM Concepts and Techniques

Mon, 31 Oct 2016 23:30:00 -0400

Intro

Continuing on from the previous post about what Redux-ORM is and why you might want to use it, let's look at the core concepts of Redux-ORM, and how I actually use it in my own application.

Note: The code examples in this post are intended to demonstrate the general concepts and workflow, and probably won't entirely run as-is. See the series introduction for info on the example scenarios and plans for demonstrating these ideas in a working example application later.

Note: These two posts cover use of Redux-ORM 0.8, but version 0.9 has since been released with several breaking API changes. The basic usage is still the same, but some aspects of behavior are different. See Practical Redux, Part 9: Upgrading Redux-ORM for details on the differences.

Redux-ORM Core Concepts

Redux-ORM serves as an extremely useful abstraction layer over the normalized data in your Redux store. There's a number of key concepts to understand when using it:

Sessions

The Session class is used to interact with an underlying set of data. If you use the reducer generated by schema.reducer(), Redux-ORM will create a Session instance internally. Otherwise, you can create Session instances by calling schema.from(entities) (which creates a Session that will apply updates immutably), or schema.withMutations(entities) (which creates a Session that will directly mutate the provided data).

When a Session instance is created from source data, Redux-ORM creates temporary subclasses of the Model types available in the Schema, "binds" them to that session, and exposes the subclasses as fields on the Session instance. This means it's important that you always extract the Model classes you want to use from the Session instance and interact with those, rather than using the versions you might have directly imported at the module level. If you're writing your reducers as part of your Model classes, Redux-ORM passes the bound version of the current class in as the third argument, and the current Session instance as the fourth argument.

Models

The Model instances returned by a Session really just act as facades over the plain Javascript objects inside the store. When a Model instance is requested, Redux-ORM generates property fields on the Model instances based on the keys in the underlying object, as well as the declared relations. These property fields define getters and setters that encapsulate the real behavior. Depending on what that field is, the getters will return the plain value from the underlying object, a new Model instance for a single relation, or a QuerySet instance for a collection relation. The underlying object can be accessed directly using someModelInstance.ref.

The use of properties and getters also means that relations are not denormalized until you actually access those properties. So, even an entity has a lot of relations, there shouldn't be any additional expense to just retrieving a Model instance for that entity.

Updates

Internally, Redux-ORM uses a queue of actions, and applies those actions kind of like a mini-Redux (where each action is used to update its internal state reducer-style). For example, running const pilot = Pilot.create(attributes); pilot.name = "Jaime Wolf"; would queue up a CREATE action and an UPDATE action. Neither of those actions is applied until you call one of the appropriate methods on the session or model, such as session.reduce(). There is one exception to this: if the session was created using schema.withMutations(entities), it will directly apply all updates to the affected object right away. Otherwise, all updates are queued up, then applied immutably in sequence to produce the final result.

Managing Relations

Redux-ORM relies on a "QuerySet" class as an abstraction for managing collections. A QuerySet knows what Model type it relates to, and contains a list of IDs. Operations such as filter() return a new QuerySet instance with a different internal list of IDs. QuerySets have an internal flag indicating whether they should dereference just the plain objects, or corresponding Model instances. This is used by chaining the properties withModels or withRefs into the lookup process, such as this.mechs.withModels.map(mechModel => mechModel.name).

For many-type relations, Redux-ORM will auto-generate "through model" classes, which store the IDs for both items in the relation. For example, a Lance with a field pilots : many("Pilot") would result in a LancePilot class and table. There's a PR currently open to allow customization of those through models, to better enable situations like ordering of items in that relation.

Synchronization

It's also important to understand that Redux-ORM does not include any capabilities for synchronizing data with a server (such as the methods included with Backbone.Model or Ember Data). It is only about managing relations stored locally as plain JS data. (In fact, despite the name, it doesn't even depend on Redux at all.) You are responsible for handling data syncing yourself.

Typical Usage

I primarily use Redux-ORM as a specialized "super-selector" and "super-immutable-update" tool. This means that I work with it in my selector functions, thunks, reducers, and mapState functions. Here's some of the practices I've come up with.

Entity Selection

Because I consistently use the Schema singleton instance across my application, I've created a selector that encapsulates extracting the current entities slice and returning a Session instance initialized with that data:

import {createSelector} from "reselect";
import schema from "./schema";

export const selectEntities = state => state.entities;

export const getEntitiesSession = createSelector(
    selectEntities,
    entities => schema.from(entities),
);

Using that selector, I can retrieve a Session instance inside of a mapState function, and look up pieces of data as needed by that component.

This has a couple benefits. In particular, because many different mapState functions might be trying to do data lookups right in a row, only one Session instance should be created per store update, so this should be something of a performance optimization. Redux-ORM does offer a schema.createSelector() function that is supposed to create optimized selectors that track which models were accessed, but I haven't yet gotten around to actually trying that. I may look into it later when I do some perf/optimization passes on my own application.

Overall, I make it a point to keep all my components unaware of Redux-ORM's existence, and only pass plain data as props to my components.

Writing Entity-Based Reducers

Most of my entity-related reducers are based more around a specific action case rather than a certain Model class. Because of this, some of my reducers are fairly generic, and take an item type and an item ID as parameters in the action payload. As an example, here's a generic reducer for updating the attributes of any arbitrary Model instance:

export function updateEntity(state, payload) {
    const {itemType, itemID, newItemAttributes} = payload;

    const session = schema.from(state);
    const ModelClass = session[itemType];

    let newState = state;

    if(ModelClass.hasId(itemID)) {
        const modelInstance = ModelClass.withId(itemID);

        modelInstance.update(newItemAttributes);

        newState = session.reduce();
    }

    return newState;
}

Not all my reducers are this generic - some of them do end up specifically referencing certain model types in specific ways. In some cases, I can build up higher-level functionality by reusing these generic building block reducers.

My reducers generally follow the same pattern: extract parameters from payload, create Session instance, queue updates, apply updates using session.reduce(), and return the new state. There's admittedly some verbosity there, which I could probably abstract out a bit more if I wanted to, but the overall consistency and the simplification of the actual update logic is a big win in my book.

I've also written a couple small utilities that aid with the process of looking up a given model by its type and ID:

export function getModelByType(session, itemType, itemID) {
    const modelClass = session[itemType];
    const model = modelClass.withId(itemID);
    return model;
}

export function getModelIdentifiers(model) {
    return {
        itemID : model.getId(),
        itemType : model.getClass().modelName,
    };
}

Many of my actions contain itemType and itemID pairs in their payloads. Part of that is that I personally lean towards keeping my actions fairly minimal, with more work in the thunks and the reducers as necessary, and don't like blindly merging data from an action straight into my state.

Handling Iterative Updates

I've found that I frequently need to apply updates in a multi-step fashion. However, because the Model instances are facades over the plain data, this doesn't always work well. If I've queued up some update (such as someModel.someField = 123), that change isn't really "visible" to the Model instances until it's been applied. Since updates are applied immutably, this situation can get complicated.

One way to handle this might be to create an initial Session instance with the starting data, then create a second Session instance with the updated data:

const firstSession = schema.from(entities);
const {Pilot} = firstSession;

const pilot = Pilot.withId(pilotId);
// Attribute update queued up here
pilot.name = "Natasha Kerensky";

const updatedEntities = firstSession.reduce();

const secondSession = schema.from(updatedEntities);
const {Pilot : Pilot2} = secondSession;

// do something with the classes from the second session, which
// are now acting as facades over the updated data object

I'm not a fan of that approach, though. It's kind of ugly, and there could be confusion over which Session and Model classes I need to use at any moment.

I did some digging through the Redux-ORM source, and noted that a Session instance ultimately is a wrapper around the object stored as this.state internally. Since that field is public, we can interact with it. In particular, I realized that I could take an existing Session instance and update it to reference a new state object, without having to create a second Session instance:

const session = schema.from(entities);
const {Pilot} = session;

const pilot = Pilot.withId(pilotId);
pilot.name = "Natasha Kerensky";

// Immutably apply updates, then point the session at the updated state object.
session.state = session.reduce();

// All field/model lookups now use the updated state object

This approach has allowed me to implement some fairly complex multi-step data updates, while still handling all the data in an immutable fashion.

Since this process does actually modify the current Session instance, I make it a point to never do this with the "shared" Session instance returned from my getEntitiesSession() selector. If I'm doing this in a reducer, I always create a new Session anyway. If I'm doing this in a thunk, I use a second selector to create a separate session instance for this task:

export function getUnsharedEntitiesSession(state) {
    const entities = selectEntities(state);
    return schema.from(entities);
}

Adding Specialized Behavior

Redux-ORM provides some very useful tools for dealing with normalized data, but it only has so much functionality built-in. Fortunately, it also serves as a great starting point for building additional functionality.

Serializing and Deserializing Data

As mentioned in the previous post, the Normalizr library is the de-facto standard for normalizing data received from the server. I've found that Redux-ORM can be used to mostly build a replacement for Normalizr. I added static parse() methods to each of my classes, which know how to handle the incoming data based on the relations:

class Lance extends Model {
    static parse(lanceData) {
        // Because it's a static method, "this" refers to the class itself.
        // In this case, we're running inside a subclass bound to the Session.
        const {Pilot, Battlemech, Officer} = this.session;
        
        // Assume our incoming data looks like:
        // {name, commander : {}, mechs : [], pilots : []}
        
        let clonedData = {
           ...lanceData,
           commander = Officer.parse(clonedData.commander),
           mechs : lanceData.mechs.map(mech => Battlemech.parse(mech)),
           pilots : lanceData.pilots.map(pilot => Pilot.parse(pilot))
        };
        
        return this.create(clonedData);
    }
}

This method could then be called in either a thunk or a reducer to help process data from a response, and queue up the necessary CREATE actions inside of Redux-ORM. If called in a reducer, the updates could be applied directly to the existing state. If used in a thunk, you'd want to take the resulting normalized data and include it in a dispatched action for merging into the store.

Note: My own data is just nested, with no duplication. I had originally assumed that this process would handle duplicate data okay, by merging it together or something similar. However, some testing has shown that assumption was wrong. If an item with an ID already actually exists in the state, and a CREATE action with the same type and ID is queued, Redux-ORM will throw an error. If two CREATE actions with the same ID are queued up together, Redux-ORM will effectively throw away the first created entry and replace it with the second created entry. I've opened up an issue to discuss what the desired behavior should be.

On the flip side, it's often necessary to send a denormalized version of the data back to the server. I've added toJSON() methods to my models to support that:

class Lance extends Model {
    toJSON() {
        const data = {
            // Include all fields from the plain data object
            ...this.ref,
            // As well as serialized versions of all the relations we know about
            commander : this.commander.toJSON(),
            pilots : this.pilots.withModels.map(pilot => pilot.toJSON()),
            mechs : this.mechs.withModels.map(mech => mech.toJSON())
        };
        
        return data;
    }
}

Creation and Deletion

I often need to generate initial data for a new entity in an action creator before either sending it to the server or adding it to the store. I'm still waffling somewhat on what exactly is the best way to approach this. For now, I've added generate methods that can help encapsulate the process:

const defaultAttributes = {
    name : "Unnamed Lance",
};

class Lance extends Model {
    static generate(specifiedAttributes = {}) {
        const id = generateUUID("lance");
        
        const mergedAttributes = {
            ...defaultAttributes,
            id,
            ...specifiedAttributes,     
        }
        
        return this.create(mergedAttributes);
    }
}

function createNewLance(name) {
    return (dispatch, getState) => {
        const session = getUnsharedEntitiesSession(getState());
        const {Lance} = session;
        
        const newLance = Lance.generate({name : "Command Lance"});
        session.state = session.reduce();
        const itemAttributes = newLance.toJSON();
        
        dispatch(createEntity("Lance", newLance.getId(), itemAttributes));
    }
}

Meanwhile, Redux-ORM's Model.delete method doesn't fully cascade, so I've implemented a custom deleteCascade method where neded:

class Lance extends Model {
    deleteCascade() {
        this.mechs.withModels.forEach(mechModel => mechModel.deleteCascade());
        this.pilots.withModels.forEach(pilotModel => pilotModel.deleteCascade());
        this.delete();
    }
}

I've also implemented a number of additions to better handle copying data back and forth between various versions of a model instance (such as a "current" version vs a "WIP draft" version), which I'll discuss in a later post on data editing approaches.

Final Thoughts

Redux-ORM does introduce some additional concepts on top of Redux. Like any abstraction layer, it can be leaky at times, and you do need to understand what's going on at the Redux level. That said, I've found that it really enables me to think about my data management at a higher level of abstraction. In addition, its ability to handle relations and simplify the actual logic for immutably updating my data is a real timesaver, and has made a lot of my code simpler in the process. It's already served me very well, and I can't wait to see what other improvements Tommi Kaikkonen might make in the future.

For links to further information, including documentation and articles, see Part 1: Redux-ORM Basics.

Practical Redux, Part 1: Redux-ORM Basics

Mon, 31 Oct 2016 23:15:00 -0400

Intro

Over the last year, I've become a very big fan of a library called Redux-ORM, by Tommi Kaikkonen. It helps solve a number of use cases that are common to many Redux applications, particularly related to managing normalized relational data in your store. I've used it heavily in my own application, and have come up with some useful techniques and approaches for using it. Hopefully you'll find them useful in your own application as well.

This first post will cover reasons why you might want to use Redux-ORM, and the basics of using it. In Part 2, we'll look at specific concepts you should know when using Redux-ORM, and some of the ways I use it in my own application.

Note: The code examples in this post are intended to demonstrate the general concepts and workflow, and probably won't entirely run as-is. See the series introduction for info on the example scenarios and plans for demonstrating these ideas in a working example application later.

Note: These two posts cover use of Redux-ORM 0.8, but version 0.9 has since been released with several breaking API changes. The basic usage is still the same, but some aspects of behavior are different. See Practical Redux, Part 9: Upgrading Redux-ORM for details on the differences.

Why Use Redux-ORM?

Client-side applications frequently need to deal with data that is nested or relational in nature. The standard advice for a Redux application is to store this data in a "normalized" form. For a Redux app, that means organizing part of your store to look like a set of database tables. Each type of item that you want to store gets an object that is used as a lookup table by mapping item IDs to item entries. Since objects don't have a real sense of order, arrays of item IDs are stored to indicate ordering.

Note: For further information on normalization in Redux, see the Structuring Reducers section of the Redux docs.

Because data is often received from the server in nested form, it needs to be transformed into a normalized form to be properly added to the store. The typical approach is to use the Normalizr library for this. You can define schema objects and how they relate, pass the root schema and some nested data to Normalizr, and it gives you back a normalized version of the data suitable for merging into your state.

However, Normalizr is really only intended for one-time processing of incoming data. It doesn't provide tools for dealing with normalized data once it's in your store. For example, it doesn't include a way to denormalize data and look up related items based on IDs, nor does it help with applying updates to that data. There are a couple of other libraries that can help, such as Denormalizr, but there's a definite need for something that can make these steps easier to deal with.

Fortunately, such a tool exists: Redux-ORM. Let's look at how it's used, and how it can make it easier to manage normalized data within the store.

Basic Usage

Redux-ORM comes with excellent documentation. The main Redux-ORM README, Redux-ORM Primer tutorial, and the API documentation cover the basics very well, but here's a quick recap.

Defining Model Classes

First, you need to determine your different data types, and how they relate to each other (specifically in database terms). Then, declare ES6 classes that extend from Redux-ORM's Model class. Like other file types in a Redux app, there's no specific requirement for where these declarations should live, but you might want to put them into a models.js file, or a /models folder in your project

As part of those declarations, add a static fields section to the class itself that uses Redux-ORM's relational operators to define what relations this class has:

import {Model, fk, oneToOne, many} from "redux-orm";

export class Pilot extends Model{}
Pilot.modelName = "Pilot";
Pilot.fields = {
  mech : fk("Battlemech"),
  lance : oneToOne("Lance")
};

export class Battlemech extends Model{}
Battlemech.modelName = "Battlemech";
Battlemech.fields = {
    pilot : fk("Pilot"),
    lance : oneToOne("Lance"),
};

export class Lance extends Model{}
Lance.modelName = "Lance";
Lance.fields = {
    mechs : many("Battlemech"),
    pilots : many("Pilot")
}

These definitions do not actually need to declare what specific attributes each class has - just the relations to other classes.

Creating a Schema Instance

Once you've defined your models, you need to create an instance of the Redux-ORM Schema class, and pass the model classes to its register method. This Schema instance will be a singleton in your application:

import {Schema} from "redux-orm";
import {Pilot, Battlemech, Lance} from "./models";

const schema = new Schema();
schema.register(Pilot, Battlemech, Lance);
export default schema;

Setting Up the Store and Reducers

Next, you need to decide how to integrate Redux-ORM into your reducer structure. The docs suggest that you should define reducer functions on your model classes, then call schema.reducer() and attach the returned function into your root reducer using combineReducers (probably as a key named orm). That approach looks roughly like this:

// Pilot.js
class Pilot extends Model {
    static reducer(state, action, Pilot, session) {
        case "PILOT_CREATE": {
            Pilot.create(action.payload.pilotDetails);
            break;
        }
    }
}

// rootReducer.js
import {combineReducers} from "redux";
import schema from "models/schema";

const rootReducer = combineReducers({
    orm : schema.reducer()
});
export default rootReducer;

I personally have taken a somewhat different approach. The majority of my reducer logic is more generic and not class-specific, so I opted instead to write my own slice reducer for this data and just use Redux-ORM as a tool to help with that. The basic approach looks like this:

// entitiesReducer.js
import schema from "models/schema";

// This gives us a set of "tables" for our data, with the right structure
const initialState = schema.getDefaultState();

export default function entitiesReducer(state = initialState, action) {
    switch(action.type) {
        case "PILOT_CREATE": {
            const session = schema.from(state);
            const {Pilot} = session;
            
            // Queue up a "creation" action inside of Redux-ORM
            const pilot = Pilot.create(action.payload.pilotDetails);
            
            // Applies the queued actions and returns an updated
            // "tables" structure, with all updates handled immutably
            return session.reduce();            
        }    
        // Other actual action cases would go here
        default : return state;
    }
}

// rootReducer.js
import {combineReducers} from "redux";
import entitiesReducer from "./entitiesReducer";

const rootReducer = combineReducers({
    entities: entitiesReducer
});

export default rootReducer;

Selecting Data

Finally, the schema can be used to look up data and relationships in selectors and mapState functions:

import React, {Component} from "react";
import schema from "./schema";
import {selectEntities} from "./selectors";

export function mapState(state, ownProps) {
    // Create a Redux-ORM Session instance based on the "tables" in our entities slice
    const entities = selectEntities(state);
    const session = schema.from(entities);
    const {Pilot} = session;
    
    const pilotModel = Pilot.withId(ownProps.pilotId);
    
    // Retrieve a reference to the real underlying object in the store
    const pilot = pilotModel.ref;    
    
    // Dereference a relation and get the real object for it as well
    const battlemech = pilotModel.mech.ref;
    
    // Dereference another relation and read a field from that model
    const lanceName = pilotModel.lance.name;

    return {pilot, battlemech, lanceName};
}

export class PilotAndMechDetails extends Component { ....... }

export default connect(mapState)(PilotAndMechDetails);

Redux-ORM and Idiomatic Redux

There's been numerous addon libraries people have built that try to put some kind of OOP layer on top of Redux, as demonstrated by the "Variations" page in my Redux addons catalog. I've frequently pointed out that Redux is primarily focused on Functional Programming principles, and that OOP wrappers over Redux aren't idiomatic. So, given that I usually advise against using those sorts of libraries, you might ask why I encourage the use of Redux-ORM. What makes it different from other libraries like Jumpsuit or Radical?

Most of the OOP wrappers I've seen try to abstract things away by defining action creators as class methods, and often wind up ignoring the idea of multiple reducers being able to respond to a given action (or even making it impossible). They treat Redux as something that needs to be hidden, and end up throwing away many of the concepts that make Redux attractive.

On the other hand, Redux-ORM doesn't try to hide Redux. It doesn't pretend that action constants don't exist, or that actions and reducers are always a 1:1 correspondence. It ultimately just provides an abstraction layer over something you would otherwise would have written yourself: CRUD operations for normalized data. It enables me to think a little less about "What specific steps do I need to follow to update or retrieve this data properly?", and a little more about handling my data at a conceptual level.

Final Thoughts

Redux-ORM has become a vital part of my toolkit for writing Redux apps. The data I'm working with is very nested and relational, and Redux-ORM is a perfect fit for my use cases. Although it's not yet marked as version 1.0, the API has remained consistent and stable since its inception, and Tommi Kaikkonen has been extremely responsive to issues I've filed. The fact that the library actually comes with real meaningful documentation (both tutorials and API docs) is a huge plus as well.

Overall, I highly recommend the use of Redux-ORM in any Redux app that needs to handle normalized nested/relational data. It won't magically keep you from having to think about managing that data, but it will make it easier for you to deal with.

Further Information

Redux-ORM docs:
- Project page: https://github.com/tommikaikkonen/redux-orm
- Tutorial: https://github.com/tommikaikkonen/redux-orm-primer
- API docs: http://tommikaikkonen.github.io/redux-orm/index.html
Redux docs:
Normalizr usage:
Discussion:

Practical Redux, Part 0: Introduction

Mon, 31 Oct 2016 23:00:00 -0400

Intro

I've spent a lot of time learning about Redux, from many different sources. Much of my early learning came from reading the docs, searching for tutorials online, and lurking in the Reactiflux chat channels. As I grew more comfortable, I gained experience answering questions and doing research to help others in Reactiflux, Stack Overflow, and Reddit. In the course of maintaining my React/Redux links list and Redux addons catalog, I've tried to find in-depth articles that dive into some of the complexities and issues involved in building real-world applications, and libraries that help make writing Redux apps better. Finally, I've also pored through numerous issues and discussions in the Redux repo (and even more so now that I'm officially a Redux maintainer).

In addition to all that research, I've also spent much of the last year using Redux in my own application at work. As I've worked on that app, I've run into a variety of challenges, and I've developed a number of interesting tools and techniques in the process. Since I've learned so much from what others have written, I'd like to start giving back, and sharing what I've learned from my own experience.

This series of posts on "Practical Redux" will cover some of the tips, techniques, and concepts I've come up with while building my own application. Since I can't actually share the specific details of what I've built at work, I'll be making up example scenarios to help demonstrate the ideas. I'll be basing the examples on concepts from the Battletech game universe:

A Battlemech is a piloted walking robot, armed with various weapons like missiles, lasers, and autocannons. A Battlemech has one pilot.
There are different types of Battlemechs. Each type can have a different size and set of statistics, including what weapons and other equipment it carries.
Battlemechs are organized into groups of four mechs, called a "Lance". Three lances make up a "Company".

As the series progresses, I'm hoping to actually start building a small app to show off some of the examples in an actual working environment. The tentative plan is to build an application that tracks the pilots and mechs in a fictional combat force, like a miniature version of the existing MekHQ game campaign tracker application. These screenshots from MekHQ illustrate some of the concepts and UI that I'm aiming to imitate:

I definitely do not intend to seriously rebuild all of MekHQ's functionality, but it should serve as a useful inspiration and source of ideas to base my examples on.

The first couple posts will discuss ways to use the Redux-ORM library to help manage normalized state. From there, I hope to cover topics such as ways to manage "draft" data while editing items, building a treeview, form input handling, and more. I also plan to cover some non-Redux-specific topics as well.

Feedback is always appreciated, whether it be in the comments, on Twitter, in Reactiflux, or elsewhere!

Mark's Dev Blog

Practical Redux, Part 11: Nested Data and Trees

Intro

Table of Contents

Library Updates

Adding New Pilots

Pilots Code Cleanup

Creating New Entities

Generating New Pilot Entries

Pilot Form Updates

Fixing Pilot Selection Logic

Reorganizing the Unit Info Display

Loading Nested Unit Data

Parsing Unit Entries

Extracting Factions

Connecting the Unit Model

Displaying Unit Data as a Tree

Loading Lance Data

Connecting the Unit Organization Tree

Final Thoughts

Further Information

Practical Redux course now available on Educative.io!

Practical Redux, Part 10: Managing Modals and Context Menus

Intro

Table of Contents

Adding Modal Dialogs

Driving React Modals from Redux

Making Modals Stackable

Building a Reusable Color Picker Dialog

Creating the ColorPickerDialog

Using the Dialog Result Value

An Alternative Approach to Dialog Results

Designing a Context Menu System

React Portals

Building the Context Menu System

Adding a Context Menu to the Pilots List

Fixing Some Existing Bugs

Final Thoughts

Further Information

Practical Redux, Part 9: Upgrading Redux-ORM and Updating Dependencies

Intro

Table of Contents

Using Redux-ORM 0.9

Redux-ORM 0.9 Changes

Upgrading Project Mini-Mek to Redux-ORM 0.9

Updating Dependencies

Updating React-Scripts

Updating Other Dependencies

Removing the Custom Error Overlay

Fixing PropTypes

Managing Dependency Packages for Offline Installation

Final Thoughts

Further Information

Practical Redux, Part 8: Form Draft Data Management

Intro

Table of Contents

Deleting Pilot Entries

Creating a Redux-ORM Session Selector

Adding Entity Creation and Deletion Reducers

Implementing Pilot Deletion

Improving the Pilot Deletion Logic

Managing Draft Data for Forms

Generic Reducer Logic for Editing Entities

Adding the Draft State Slice

Writing the Core Editing Reducer Logic

Using Draft Data for Editing Pilots

Displaying the Copied Pilot Entry

Updating the Edited Entry

Saving Form Edits

Updating Existing Models

Applying Changes to Entities

Updating Pilot Save Logic

Resetting and Canceling Form Edits

Resetting Entity Edits

Adding "Reset" and "Cancel" Buttons

Final Thoughts

Further Information

Practical Redux, Part 7: Form Change Handling, Data Editing, and Feature Reducers

Intro

Table of Contents

`FormEditWrapper` in Action

Looking Beyond `combineReducers`

Using `reduceReducers`