Category: Flutter

This post is part of my “Building a Flutter App” dev journal, which begins here.

In this post: I develop a feature that allows the user to “link” stores and shopping lists to each other. This link is managed on the “edit store” and “edit shopping list” pages. A link is bidirectional: adding a store to a shopping list also adds that shopping list to the store.

First, the final product

The user can toggle every one of their stores on/off for each shopping list.

Feature description and purpose

This feature has a few purposes:

• allow items from multiple shopping lists to appear in one store (so when you’re at, for example, “Fred Meyer”, you can see items for “groceries” and “home improvement”)
• allow the user to save different item orders for different stores (this work was documented in this article)
• make it easier for the user to know which store they need to go sooner to based on which items they need

Deciding how to represent the store/list links in the database

First, I consulted Firebase’s docs on structuring data to see what they had to say about representing this kind of many-to-many relationship. Their “users and groups” example is very close to what I want to build here.

They recommend using an index of groups, like so:

// An index to track Ada's memberships
{
  "users": {
    "alovelace": {
      "name": "Ada Lovelace",
      // Index Ada's groups in her profile
      "groups": {
         // the value here doesn't matter, just that the key exists
         "techpioneers": true,
         "womentechmakers": true
      }
    },
    ...
  },
  "groups": {
    "techpioneers": {
      "name": "Historical Tech Pioneers",
      "members": {
        "alovelace": true,
        "ghopper": true,
        "eclarke": true
      }
    },
    ...
  }
}

(This was taken directly from the Firebase docs)

Next, I adapted their example to match my project. This is just mock data in a text file, it’s not in the project’s codebase anywhere.

// An index to track a shopping list's stores
{
  "shopping_lists": {
    "list123": {
      "name": "Groceries",
      "stores": {
         "store890": true,
         "store567": true
      }
    },
    ...
  },
  "stores": {
    "store890": {
      "name": "Safeway, Kirkland",
      "shopping_lists": {
        "list123": true,
        "list124": true
      }
    },
    ...
  }
}

Now I have a clear goal to work towards, but this should be straightforward to implement. I will have to update/maintain the link data in two places, so my Database Manager functions will account for that.

Inserting the data into the database by hand

My data differs from Firebase’s sample data in that I use the auto-generated IDs to identify my records, but I don’t show the user those IDs, I show them the name instead. I decided to change my mock data to look like this, instead:

  "shopping_lists": {
    "list123": {
      "name": "Groceries",
      "stores": {
         "store890": "Safeway, Kirkland",
         "store567": "Fred Meyer, Kirkland"
      }
    },
    ...
  },

Now the store ID are the key and store name is the value.

The next step was to put this data into my Firebase document by hand. Here is my “Back to school stuff” shopping list with two stores associated with it.

Now I’ll have something to display in the UI (and later edit).

Building the store/list linking UI

The first page I worked on was the “Edit shopping list” page. I considered doing a list of toggle switches under the “List name” field, but that list could potentially be very long and I didn’t want to push the “Save” button off screen.

Instead, I decided to show a short (truncated) list of linked stores on this page and provide a link that opens up a new view full of toggle switches that represent each possible store link.

Note: I knew that whatever UI I built for this feature would also be used by the “Edit Store” page, so I built everything using (reusable) components and named them generically.

shopping_list_form.dart now contains an internally-used method titled _formFields. This method builds a List of widgets and includes _nameField() in it by default. Whether you’re editing or creating a new shopping list, you’ll always get _nameField.

If the shopping list id is not null, then we can also show the “linked entities”.

 _formFields() {
    List<Widget> fields = [_nameField()];
    // if we're editing an existing shopping list, add the linked stores
    if (widget.shoppingList?.id != null) {
      fields.add(_linkedEntities());
    }

    return Container(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: fields,
      ),
    );
  }

_linkedEntities is a separate method that returns another widget, LinkedEntitiesList.

  _linkedEntities() {
    return LinkedEntitiesList(
        widget.shoppingList.id, "shopping list", widget.shoppingList.name, widget.shoppingList.stores, "Stores");
  }

linked_entities_list.dart is shown here in its entirety from the final version of the feature branch. The thing that’s interesting here is the use of the spread operator to build an “entity list” out of some unknown number of list elements. This turned out to be a good technique for adding a variable number of children to a column’s children array.

import 'package:flutter/material.dart';
import 'package:grocery_go/views/manage_links.dart';
import '../../db/database_manager.dart';

class LinkedEntitiesList extends StatelessWidget {
  final String parentID;
  final String parentName;
  final String listType;
  final Map linkedEntities;
  final String entities;

  LinkedEntitiesList(this.parentID, this.listType, this.parentName, this.linkedEntities, this.entities);

  final DatabaseManager db = DatabaseManager();

  @override
  Widget build(BuildContext context) {

    _goToManageLinks() {
      var stream;
      if (listType == "shopping list") {
        stream = db.getStoresStream();
      } else if (listType == "store") {
        stream = db.getShoppingListStream();
      } else {
        print("Error: unrecognized list type in linked_entities_list.dart");
      }

      Navigator.pushNamed(context, ManageLinks.routeName, arguments: ManageLinksArguments(dbStream: stream, linkedEntities: linkedEntities, parentID: parentID, parentName: parentName, parentType: listType));
    }

    var _list = linkedEntities != null ? linkedEntities.values.toList() : [];

    return Container(
      height:300,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: <Widget>[
          _listTitle(),
          ..._entityList(_list),
          _manageLinksButton(_goToManageLinks),
        ],
      ));
    }

  _listTitle() {
    return Text("$entities", style: TextStyle(fontSize:16, fontWeight: FontWeight.bold));
  }

  _entityList(list) {
    const MAX_LIST_LEN = 4;

    if (list == null || list?.length == 0) {
      return [Text("This $listType is not attached to any $entities yet.")];
    } else {
      var listLen = list.length > MAX_LIST_LEN ? MAX_LIST_LEN : list.length;
      var entityList = List();
      for (var i = 0; i < listLen; i++) {
        entityList.add(Text(list[i].toString()));
      }
      if (list.length > MAX_LIST_LEN) {
        entityList.add(Text('+${list.length - MAX_LIST_LEN} more'));
      }
      return entityList;
    }
  }

  _manageLinksButton(onPressedAction) {

    return FlatButton(
      onPressed: () => onPressedAction(),
      child: Text("Add/Remove $entities"),
      textColor:Colors.blue,
      padding: EdgeInsets.all(0),
    );
  }
}

Notes:

• I called them “entities” here because these widgets work for stores or shopping lists
• I had to make a similar set of changes to the store_form.dart component
• Getting a Column widget to have different children based on some condition was a new challenge. The best solution I could come up with was to use a List, called “fields” in this example, to hold the widgets that should be the column’s children. If a condition is met (in my case, shopping list id is not null), then a widget is pushed to the fields List (otherwise, it is not pushed). That approach seemed to be a good way to make the Columns children vary as needed.
• user2875289‘s answer in this Stack Overflow question (method 2 and method 3 to be exact) helped me figure out how to iterate through a list to create Text widgets and how to include another Text widget child in that same array of children.

Firebase updates: adding a new store (or shopping list) to the map

Every Shopping List is going to have a map of Stores, like this:

"shoppingListID01" : {
  "name": "Groceries",
  "stores" : {
    "storeID01": "Safeway",
    "storeID02": "Fred Meyer"
  }
}

And when a new store is added, it has to be added without affecting the rest of the. map:

"stores" : {
  "storeID01": "Safeway",
  "storeID02": "Fred Meyer",
  "storeID03": "Home Depot" // NEW ONE, didn't mess up Safeway or Fred Meyer
}

And vice versa for Stores – every Store record keeps a map of its linked Shopping Lists.

"storeID01" : {
  "name": "Safeway",
  "stores" : {
    "shoppingListID01": "Groceries",
    "shoppingListID02": "Pool party stuff"
  }
}

Every “link” is created in two places:

• Adding a store to a shopping list also adds that shopping list to that store
• Adding a shopping list to a store also adds that store to that shopping list

For the sake of “Step 1” here I am just going to work on adding a new store link to the map of stores.

My initial (dead end) approach with “update” and “merge: true” and why that didn’t work with Cloud Firestore

From reading the Firebase docs I knew I was going to need to use update and {merge: true} because I want to keep the rest of the object untouched.

This was my first attempt, but it doesn’t work because apparently “update” is not usable if you’re using the cloud firestore package.

Future updateShoppingListLink(String parentStoreID, String entityID, bool val) async {

    DocumentReference storeRef =  stores.document(parentStoreID);

    Map<String, Map> data = {
      "shoppingLists": {
        entityID: val
      },
    };

    storeRef.update(data, {merge: true}); // doesn't work, "update" doesn't exist 
  }
}

I looked more closely at the cloud firestore docs, and they show “updateData” instead of “update”, so I swapped update for updateData:

storeRef.updateData(data, {merge: true}); // doesn't work, doesn't accept "merge"

updateData doesn’t accept the “merge” object, though. It says “too many positional arguments”.

Just to see what would happen, I took off the merge object and updated my database entry without the merge flag present.

storeRef.updateData(data);

The good news was – this “worked” in the sense that the new shopping list ID was successfully added to the store document:

… but as soon as you add a second store, that first store was overwritten and replaced with the new one:

At this point, I figured I was just not correctly passing “merge true” to updateData. I found this seemingly-related thread from 2017 that referenced this merged code that suggested SetOptions.merge() could be applied.

Here’s their example (I took this from their test, I couldn’t find it in their docs):

test('merge set', () async {
        await collectionReference
            .document('bar')
            .setData(<String, String>{'bazKey': 'quxValue'}, SetOptions.merge);
        expect(SetOptions.merge, isNotNull);

Which I adapted to my code:

storeRef.updateData(data, SetOptions.merge); // doesn't work, expects 1 parameter not 2

Making it all one object didn’t work, either:

storeRef.updateData({data, SetOptions.merge}); // also does not work

Then I found this downvoted Stack Overflow reply suggesting this syntax, which also does not work (it wants 1 argument, not 2):

storeRef.updateData(data, SetOptions(merge: true)); // also does not work

I kept digging and found this thread on the issue, which was last updated less than two months ago and says that merge and mergeFields are coming to the FlutterFire plugin set (which includes the cloud firestore plugin) in this update. Specifically, here are the “patch notes” for the upcoming changes to cloud firestore, which are still in review as of this writing (July 2020).

Ahh, so it seems there’s a big update coming soon that will fix this, but “merge true” is a lost cause at this point in time. If you’re reading this in the future, perhaps you have the updated cloud firestore package and none of this is a problem, but for those of us using it as it is now, I thought I’d see if I could find a workaround.

I started to wonder if I could just access shoppingLists with dot notation and gave this a try:

// working example of how to update one field in an existing map without deleting the others
  
Future updateShoppingListLink(String parentStoreID, String entityID, bool val) async {
    DocumentReference storeRef =  stores.document(parentStoreID);
    storeRef.updateData({'shoppingLists.$entityID': val});
  }

Yay, it worked!

This technique makes it possible to add a new field to the map without deleting the existing ones in the process.

Perhaps I didn’t need “merge true” in the first place, but I’ll leave my notes up in case they’re helpful to anyone else trying to update one entry in a map in a Firebase document.

TL;DR: “dot notation” was a good way to update specific field in a map contained within a Firebase document.

storeRef.updateData({'shoppingLists.$entityID': val});

Passing the store name as the value

Currently, the “val” passed to the shoppingList map is a boolean value but what I really need is the store’s name.

I changed the database_manager.dart method to take a String called name instead:

  Future updateShoppingListLink(String parentStoreID, String entityID, String name) async {
    DocumentReference storeRef =  stores.document(parentStoreID);
    storeRef.updateData({'shoppingLists.$entityID': name});
  }

And then I changed the toggleItem method in toggle_list.dart to pass the name instead of the value:

class _ToggleListState extends State<ToggleList> {

  final DatabaseManager db = DatabaseManager();

  toggleItem(entityID, entityName) {
    print(widget.parentType);
    if (widget.parentType == "shopping list") {
      db.updateStoreLink(widget.parentID, entityID, entityName);
    } else if (widget.parentType == "store") {
      db.updateShoppingListLink(widget.parentID, entityID, entityName);
    }
  }

  @override
  Widget build(BuildContext context) {

    return ListView.builder(
        shrinkWrap: true, // gives it a size
        itemCount: widget.list.length,
        itemBuilder: (BuildContext context, int index) {
          var item = LinkedEntity(widget.list[index]);

          return SwitchListTile(
            title: Text(item.name),
            value: widget.linkedEntities?.containsKey(item.id) ?? false,
            onChanged: (bool value) => toggleItem(item.id, item.name),
          );
        }
    );
  }
}

This works – hooray! – but it reveals a new problem: what happens when the user changes the shopping list’s name?

Thoughts on what happens when a shoppingList (or Store) gets renamed:

Firebase doesn’t seem to shy away from redundant data, and the alternative seems to be to store the IDs alone and then perform a “what name goes with this ID?” look up every time the user views or manages the linked lists (or stores).

In my app, it’s probably way more common to view/manage the links than it is to rename a shopping list or store, and I don’t anticipate users having more than about 5-10 of each, so I am going to (cautiously) proceed with the idea that it’s better to update the name in multiple places if the name changes vs. the idea that the name should be looked up every time the user views a list.

I’ll revisit what happens when a shopping list or store is renamed later on in this article.

Removing an existing link from the map

Everything I’ve done so far is for creating a link.

The user can also remove a link (by toggling it to “false” in the list), which I imagined would have a database equivalent of removing the item from the map entirely. What I don’t want to do is make a copy of the entire linkings map, remove the single entry that’s going away, and then push the entire updated map.

As usual, I began with a bit of research and found that the “dot notation” that served me so well for adding a field to a map can also be used with FieldValue.delete().

Here, I’ve written a ternary that looks at the value of val. If true, it updates the ‘stores’ or ‘shoppingLists’ map with the entity’s ID and name. If false, it removes the given entity ID from ‘stores’ or ‘shoppingLists’.

  Future updateStoreLink(String parentListID, String entityID, String name, bool val) async {
    DocumentReference shoppingListRef = shoppingLists.document(parentListID);
    val == true ? shoppingListRef.updateData({'stores.$entityID': name}) : shoppingListRef.updateData({'stores.$entityID': FieldValue.delete()});
  }

  Future updateShoppingListLink(String parentStoreID, String entityID, String name, bool val) async {
    DocumentReference storeRef =  stores.document(parentStoreID);
    val == true ? storeRef.updateData({'shoppingLists.$entityID': name}) : storeRef.updateData({'shoppingLists.$entityID': FieldValue.delete()});
  }

In toggle_list.dart I had to make a few changes to the toggleItem method. If widget.linkedEntities is null, it creates an empty new Map(). Without this, a store (or shopping list) that doesn’t have anything in its linked shoppingLists (or stores) map will be interpreted as ‘null’, causing .containsKey to throw an exception.

Here is toggle_list.dart in its entirety.

import 'package:flutter/material.dart';
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:grocery_go/db/database_manager.dart';

class LinkedEntity {
  String id;
  String name;

  LinkedEntity(DocumentSnapshot document) {
    this.id = document['id'];
    this.name = document['name'];
  }
}

class ToggleList extends StatefulWidget {

  final String parentType;
  final String parentID;
  final List list;
  Map linkedEntities;

  ToggleList({Key key, @required this.parentType, @required this.parentID, @required this.list, @required this.linkedEntities});

  @override
  _ToggleListState createState() => _ToggleListState();
}

class _ToggleListState extends State<ToggleList> {

  final DatabaseManager db = DatabaseManager();

  toggleItem(entityID, entityName, value) {

    if (widget.linkedEntities == null) {
        widget.linkedEntities = Map();
    }

    // update "locally"
    if (widget.linkedEntities.containsKey(entityID)) {
      setState(() {
        widget.linkedEntities.remove(entityID);
      });
    } else {
      setState(() {
        widget.linkedEntities[entityID] = entityName;
      });
    }
    // update in database
    if (widget.parentType == "shopping list") {
      db.updateStoreLink(widget.parentID, entityID, entityName, value);
    } else if (widget.parentType == "store") {
      db.updateShoppingListLink(widget.parentID, entityID, entityName, value);
    }
  }

  @override
  Widget build(BuildContext context) {

    return ListView.builder(
        shrinkWrap: true, // gives it a size
        itemCount: widget.list.length,
        itemBuilder: (BuildContext context, int index) {
          var item = LinkedEntity(widget.list[index]);

          return SwitchListTile(
            title: Text(item.name),
            value: widget.linkedEntities?.containsKey(item.id) ?? false,
            onChanged: (bool value) => toggleItem(item.id, item.name, value),
          );
        }
    );
  }
}

Here’s where we’re at now:

• Stores and Shopping Lists have a map of their “linked entities” (stores keep track of their linked shopping lists, shopping lists keep track of their linked stores)
• Linked entities can be linked/unlinked using a toggle switch
• The data is changed in the database as the user toggles a link on/off

Making the link a two-way link

If the user adds the “swim stuff” list to the “Toys R Us” store, then “swim stuff” list should also get an association with the “Toys R Us” store. In other words, adding or removing a store from a shopping list should also add or remove that same shopping list from that same store.

Each existing method basically had to repeat the code of the other – once I wrote this out, I realized I could combine them into one method.

Future updateStoreLink(String shoppingListID, String storeID, String name, bool val) async {
    // add a store to the specified shopping list
    DocumentReference shoppingListRef = shoppingLists.document(shoppingListID);
    val == true ? shoppingListRef.updateData({'stores.$storeID': name}) : shoppingListRef.updateData({'stores.$storeID': FieldValue.delete()});

    // do the opposite - add this shopping list to the specified store
    DocumentReference storeRef =  stores.document(storeID);
    val == true ? storeRef.updateData({'shoppingLists.$shoppingListID': 'temp'}) : storeRef.updateData({'shoppingLists.$shoppingListID': FieldValue.delete()});
  }

  Future updateShoppingListLink(String storeID, String shoppingListID, String name, bool val) async {
    // add a shopping list to the specified store
    DocumentReference storeRef =  stores.document(storeID);
    val == true ? storeRef.updateData({'shoppingLists.$shoppingListID': name}) : storeRef.updateData({'shoppingLists.$shoppingListID': FieldValue.delete()});

    // do the opposite - add this store to the specified shopping list
    DocumentReference shoppingListRef = shoppingLists.document(shoppingListID);
    val == true ? shoppingListRef.updateData({'stores.$storeID': 'temp'}) : shoppingListRef.updateData({'stores.$storeID': FieldValue.delete()});
  }

Here they are refactored into one method, with a change made to the signature to take both the shopping list name and store name.

Future updateStoreShoppingListLink(String shoppingListID, String storeID, String shoppingListName, String storeName, bool val) async {
  // add this store to the specified shopping list
  DocumentReference shoppingListRef = shoppingLists.document(shoppingListID);
  val == true ? shoppingListRef.updateData({'stores.$storeID': storeName}) : shoppingListRef.updateData({'stores.$storeID': FieldValue.delete()});

  // and add this shopping list to the specified store
  DocumentReference storeRef =  stores.document(storeID);
  val == true ? storeRef.updateData({'shoppingLists.$shoppingListID': shoppingListName}) : storeRef.updateData({'shoppingLists.$shoppingListID': FieldValue.delete()});
}

Back in toggle_list.dart, I still have to call db.updateStoreShoppingListLink(...); in two different places because the concept of ‘parentID’ and ‘entityID’ are variable based on whether the user came in from the “edit store” flow or the “edit shopping list” flow.

When the user came in from “edit shopping list”, the parentID is a shoppingList’s ID. When the user comes in from “edit store”, the parentID is a store’s ID.

The updateStoreShoppingListLink method always expects the params in this order:

method params: (shoppingListID, storeID, shoppingListName, storeName, value)

… so we change the order of widget.parentID and entityID as dictated by the list type.

// update in database
// method params: (shoppingListID, storeID, shoppingListName, storeName, value)

if (widget.parentType == "shopping list") {
  // if we're editing a shopping list then the parent ID is the list ID and the entity is the store
  db.updateStoreShoppingListLink(widget.parentID, entityID, widget.parentName, entityName, value);
} else if (widget.parentType == "store") {
  // if we're editing a store, then the parent ID is the store ID and the entity is the shopping list
  db.updateStoreShoppingListLink(entityID, widget.parentID, entityName, widget.parentName, value);
}

In this demo, toggling the “Swim stuff” list on for the “Toys R Us” store also adds the “Toys R Us” store to the “swim stuff” list.

All of these use cases work now:

• Add a shopping list to a store adds that same store to that shopping list
• Remove a shopping list from a store removes that same store from the shopping list
• Add a store to a shopping list adds that same shopping list to that store
• Remove a store from a shopping list removes that same shopping list from the store
• User can remove all the shopping lists from a store
• User can remove all the stores from a shopping list
• Create a new store and add/remove shopping lists to it
• Create a new shopping list and/remove stores to it

Handling long lists of linked entities

It’s possible that a user will add lots of stores to a shopping list (or lots of shopping lists to a store), so the list has to truncate after a to-be-determined number of items.

Already, we’re seeing some overflow after just three linked entities are present:

Currently, the logic that creates this list looks like so:

  _entityList(list) {
    var shortList = List();
    shortList.add(Text("This $listType is not attached to any $entities yet."));
    // if 'list' is empty, default to shortList which is guaranteed to have something
    return list?.map((item) => Text(item.toString(), style: TextStyle(height: 1.6)))?.toList() ?? shortList;
  }

The refactor needs to do the following:

• display up to N (probably 4 or 5) items
• append a Text widget showing count of how many items remain, ie: “+ 2 more”
• still return a Text widget that says “This listType is not attached to any $entities yet” when the list is empty

Here’s what I ended up with. (There are probably more succinct ways to write this, but hopefully it’s clear what it’s doing.)

  _entityList(list) {
    const MAX_LIST_LEN = 4;

    if (list == null || list?.length == 0) {
      return [Text("This $listType is not attached to any $entities yet.")];
    } else {
      var listLen = list.length > MAX_LIST_LEN ? MAX_LIST_LEN : list.length;
      var entityList = List();
      for (var i = 0; i < listLen; i++) {
        entityList.add(Text(list[i].toString()));
      }
      if (list.length > MAX_LIST_LEN) {
        entityList.add(Text('+${list.length - MAX_LIST_LEN} more'));
      }
      return entityList;
    }
  }

The result:

Adding “store address” anywhere store names are displayed (store list, toggle list)

When I built the ToggleList and the linked entities list, I overlooked the (common) use case of the user having multiple stores with the same name. Without each store’s address on display, it’s hard to tell identically named stores apart.

However, I have a bit of a conundrum: “entities” (as they are), are just persisted to the database as a string representing the store (or shopping list’s) name. There’s no address field, nor do I really want to add one at this point.

I decided the simplest course of action would be appending the location information to the name right before it’s pushed into the database, like so: “Safeway (Kirkland)” and see how far that carries me. Is this hacky? Maybe ;) But it feels good enough for now.

In toggle_list.dart, the full list of shopping lists or stores is passed in as a Map, known as this.list:

ToggleList({Key key, @required this.parentType, @required this.parentID, @required this.parentName, @required this.list, @required this.linkedEntities});

Around line 72, each of these list items (which can be stores or shopping lists) are turned into LinkedEntity instances:

var item = LinkedEntity(widget.list[index]);

Both stores and shopping lists become instances of LinkedEntity, and they can share this “base class” because the only things used are their id and name. But now they have a third field: address. If there is an address it’s saved to the address field, but if there is no address (ie: shopping lists), it’ll just set address to be empty.

class LinkedEntity {
  String id;
  String name;
  String address;

  LinkedEntity(DocumentSnapshot document) {
    this.id = document['id'];
    this.name = document['name'];
    this.address = document['address'] ?? '';
  }
}

Then, when the list is built, the itemName is assembled out of either item.name + item.address, or just item.name if there was no address.

@override
  Widget build(BuildContext context) {

    return ListView.builder(
        shrinkWrap: true, // gives it a size
        itemCount: widget.list.length,
        itemBuilder: (BuildContext context, int index) {
          var item = LinkedEntity(widget.list[index]);
          var itemName = item.address.length > 0 ? item.name + ' (${item.address})' : item.name;
          return SwitchListTile(
            title: Text(itemName),
            value: widget.linkedEntities?.containsKey(item.id) ?? false,
            onChanged: (bool value) => toggleItem(item.id, item.name, value),
          );
        }
    );
  }

Now it’s much easier to tell same-name stores apart in the toggle list:

The same address treatment would be useful on the form page, too:

This page is trickier, because this list is taken from the saved “stores” data in the database. I considered a few different solutions, all of which felt cumbersome (on top of some already-cumbersome-feeling logic), until it dawned on me that I could just persist the “StoreName (Address)” string to the database.

It ended up being a one-line (one word, really) change in toggle_list.dart:

          return SwitchListTile(
            title: Text(itemName),
            value: widget.linkedEntities?.containsKey(item.id) ?? false,
            onChanged: (bool value) => toggleItem(item.id, itemName, value),

Now when toggleItem is called, the same “StoreName (Address)” string is passed to the database.

I’ll go with this approach for now, which seems “good enough” for the sake of this project. (I toggled each store on/off to update it to the new StoreName (Address) format.)

Two more changes…

Before moving on, I had to make two more (small) changes to the code that runs when an existing shopping list or store is updated (renamed) or when a new shopping list or store is created.

store_form.dart

void updateStore(BuildContext context) async {
    final formState = formKey.currentState;

    if (formState.validate()) {
      formKey.currentState.save();
      storeFields.date = DateTime.now().toString();

      if (widget.store != null) {
        storeFields.id = widget.store.id;
        // 1
        storeFields.shoppingLists = widget.store.shoppingLists;
        await db.updateStore(widget.store.id, storeFields);
      } else {
        // 2
        storeFields.shoppingLists = Map();
        await db.addStore(storeFields);
      }

      Navigator.of(context).pop();
    }
  }

1. If the store already exists (it’s not null), then copy its shoppingLists into storeFields.shoppingLists and send them along to db.updateStore(...).
2. If the store is null, then it’s a new one being created, so create a new Map() for storeFields.shoppingLists and send that along to the db. Without this, a new shopping list has “null” for its shoppingLists map and the code that adds a new shopping list ID to it fails.

I made a similar set of changes to shopping_list_form.dart.

Updating renaming shopping lists and renaming stores to also update any saved links

The last major piece of work on this feature is making it so that updating a shopping list’s name (or a store’s name) is properly propagated to all of the documents that have it stored.

As far as I can tell, having redundancies like this (such as storing a store’s name or shopping list in multiple places) is oftentimes the preferred way of storing records in Firebase.

Per my own logic, it’s fairly uncommon to change the name of a list or a store but very common to view a store or a list in multiple places. It seemed better to take on the burden of having to update multiple records with a name change once in a rare while vs. the burden of looking up the name for every store and shopping list, by ID, every time the user viewed a list of them.

This piece of work needs to achieve the following:

• When the user changes the name of a Store, step through each existing Shopping List and look for that store.id in each Shopping List’s “stores” map. If any match is found, update the name saved for that store entry.
• When the user changes the name of a Shopping List, step through each existing Store and look for that shoppingList.id in each Store’s “shoppingList” map. If any match is found, update the name saved for that shopping list entry.

I started my work with renaming stores first, because stores are more complicated. Stores record their name separate from their location (also called “address” in the code), but their name and location are concatenated together when saving them into a shopping list’s list of stores.

In database_manager.dart, I confirmed that the name and address are accessible on the store DTO with a couple of print statements:

  Future updateStore(String id, StoreDTO store) async {
    print(store.name);
    print(store.address);
    if (id != null && id.length > 0) {
      DocumentReference docRef = stores.document(id);
      Firestore.instance.runTransaction((transaction) async {
        await transaction.update(docRef, store.toJson());
      }).catchError((e) {
        print(e.toString());
      });
    } else {
      print("ID is null/has no length");
    }
  }

Then passed them along to a new method called updateLinkedShoppingLists:

  Future updateStore(String id, StoreDTO store) async {
    if (id != null && id.length > 0) {
      DocumentReference docRef = stores.document(id);
      Firestore.instance.runTransaction((transaction) async {
        await transaction.update(docRef, store.toJson());
      }).catchError((e) {
        print(e.toString());
      });
      updateLinkedShoppingLists(store.id, store.name + " (" + store.address + ")");
    } else {
      print("ID is null/has no length");
    }
  }

    Future updateLinkedShoppingLists(storeID, newName) async {
    // update all the shopping lists's "stores" maps to use the new store name
    await shoppingLists
        .getDocuments()
        .then((querySnapshot) => {
          querySnapshot.documents.forEach((doc) => {
            if (doc.data['stores'][storeID] != null) { // can't use ['stores.$storeID']
              doc.reference.updateData({'stores.$storeID': newName})
            }
          })
        });
  }

updateLinkedShoppingLists gets all the shopping list documents from the shoppingLists collection then iterates through them. On each one, it checks if doc.data['stores'][storeID] is not null, and if it’s not null, it updates the stores entry to have the new name.

The hardest part of this process was figuring out how to only updates the stores {"storeID": "storeName"} entry for shopping lists that actually had this store in their store map. Without this logic check, every shopping list gets the store added, whether it had it before or not, but figuring out how to limit the updateData call to just the documents that had that particular store ID in its store map was a challenge. The docs didn’t really cover this scenario, and the stores.$storeID syntax didn’t work.

In other words, I couldn’t do this:

if (doc.data['stores.$storeID'] != null) { // doesn't work

It seems the handy-dandy store.$storeID lookup is only for use in the updateData({...}) call. For checking if a Firebase document had a particular entry in a map, this was the syntax that worked:

if (doc.data['stores'][storeID] != null) { ... 

Perhaps because it doesn’t know the structure of ‘stores’ so it can’t use the dot notation. Either way, here is the “rename everywhere” feature working for Stores:

And getting it working for renaming shopping lists was as easy as writing the same thing again, but for shopping lists and their linked stores:

  Future updateShoppingList(String id, ShoppingListDTO shoppingList) async {
    if (id != null && id.length > 0) {
      DocumentReference docRef = shoppingLists.document(id);
      Firestore.instance.runTransaction((transaction) async {
        await transaction.update(docRef, shoppingList.toJson());
      }).catchError((e) {
        print(e.toString());
      });
      updateLinkedStores(shoppingList.id, shoppingList.name); // call new method
    } else {
      print("ID is null/has no length");
    }
  }

  Future updateLinkedStores(shoppingListID, newName) async {
    // update all the stores' "shopping lists" maps to use the new shopping list name
    await stores
        .getDocuments()
        .then((querySnapshot) => {
      querySnapshot.documents.forEach((doc) => {
        if (doc.data['shoppingLists'][shoppingListID] != null) {
          doc.reference.updateData({'shoppingLists.$shoppingListID': newName})
        }
      })
    });
  }

And that’s it! Here’s the feature’s pull request.

Here’s what we did:

• Added a new view that lets the user toggle stores “on/off” for shopping lists (and shopping lists “on/off” for stores)
• Wrote new Database Manager methods to create/delete a two-way link between stores and shopping lists whenever one is added or removed
• Added a map to the store documents (and a map to the shopping list documents) that tracks the IDs and names of any linked entities
• Made it so that changing the name of a store or shopping list also updates its name in any documents that have it in their linked entities map
• Updated the store form and shopping list forms to display a list of linked entities, with special handling for cases where there are more than 4 linked entities

Go back to Part 7’s feature work list.