Building a Flutter app: re-ordering lists

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

In this post: I develop a feature that allows a user to manually re-order a shopping list. Taking inspiration from the way Spotify lets users re-order a playlist, Grocery Go’s users should be able to put the items in any order they like.

First, the final product

You can view this step’s pull request here.

This gif demonstrates the feature. The user re-orders items in a list and changes which “store” is active to set different item orders for different stores.

Getting set up – where we’re starting from

When I started work on this feature, the user could already create a shopping list and populate it with items, like so:

However, there is no way to sort or re-order those items.

As a user, I think it’d be useful if the items could be re-ordered to match the order I actually pick them up in when I’m at the store.

But which store? I shop at many different stores, and they’re all laid out differently, so in addition to creating a default order I also want to be able to create variations on the default order and “save” those variations to each store that this list applies to.

Planning the work: UI inspiration

For inspiration, I looked at how Spotify’s phone app (or at least iOS app) gives the user the ability to reorder items in a list.

To change the order of items in this playlist, the user taps the “three dots” adjacent to the “down arrow” above the “add songs” button.

A separate screen pops up and offers the option to “Edit” the playlist:

Tapping “Edit” opens up a modal in which the individual songs can be pressed on and dragged up and down in the list.

In this screenshot, I am dragging the song named “Passage” up in the list. It follows my finger as long as I keep pressing the screen.

Feature list

  • Every shopping list has a “default” order
  • Every shopping list can be linked with 1 or more stores, and each of those store links has its own item order (initially copied from ‘default’)
  • The user can re-order items in the “default” list and the store-specific lists
  • The user can change which store list is being displayed via the shopping list view
  • Creating a brand new item adds it to the end of the “default” list as well as to the end of all store-specific lists

Modeling the data

The user can store different item sequences for different stores, like so:

Default – items are, by default, shown in the order they were created for this list. The user can re-order this list, though. Newly created items are added to the bottom (end) of this list.

  • Party size bag of M&Ms
  • Bread
  • Bananas
  • Milk
  • Eggs

Safeway – the user wants to see the items in this order when they are at Safeway. Newly created items are added at the bottom of this list.

  • Bananas
  • Bread
  • Milk
  • Eggs
  • Party size bag of M&Ms

In the Firebase data structure, I imagined each item would have a map of key/value pairs where the key is the store’s ID and the value is the position in that store’s list.

This worked well and I duplicated this structure for the shopping lists themselves, allowing the shopping lists to be re-ordered on the main screen in addition to the items in each list.

Trouble with “orderBy” and Streams

Initially, I tried to get the items in order (for whatever store list was selected) like this:

Stream<QuerySnapshot> getItemsStream(shoppingListID, isCrossedOff, storeID) {
    return shoppingLists.document(shoppingListID).collection('items').where('isCrossedOff', isEqualTo: isCrossedOff).orderBy('listPositions.$storeID').snapshots();
  }

I thought this was a very clever and the “quite obvious” approach, but the more I tested it, the more apparent it became that using “orderBy” made it so the widget(s) displaying the contents of that stream wouldn’t redraw in the UI, even if coming back from another route. It also broke the ability to cross off items: they would appear in the active and inactive lists at the same time, or they would appear in neither list, until the user reloaded that page of the app.

I went down a lot of different roads trying to fix this, but ultimately all I did was stop using .orderBy and sorted everything on the front-end (in-widget) instead. I don’t know if that’ll end up being a bad idea, but it was the only way I could get both streams and data ordered by some criteria to work together.

Sorting the Stream results

The stream-getting methods in database_manager.dart return a Stream of QuerySnapshots, like so:

Stream<QuerySnapshot> getActiveItemsStream(shoppingListID, storeID) {
    return shoppingLists.document(shoppingListID).collection('items')
        .where('isCrossedOff', isEqualTo: false)
        .snapshots();
  }	  }

And then over here in main_shopping_list.dart, I set a state variable (activeItemsStream) to the return value of that “get stream” call:

void initState() {
    super.initState();
    getSharedPrefs().then((storeIDFromPrefs) {
      activeItemsStream = db.getActiveItemsStream(widget.list.id, storeIDFromPrefs); // should get selectedStoreID from state
      inactiveItemsStream = db.getInactiveItemsStream(widget.list.id, storeIDFromPrefs);
    }); // sets selectedStoreID
  }

To display it, I used a custom widget that I made myself called ItemListStream that takes that state variable as a parameter (called dbStream, first one in the list) and a sortBy parameter.

ItemListStream(dbStream: activeItemsStream, sortBy: selectedStoreID, listType: 'item', onTap: _updateCrossedOffStatus, onInfoTap: _editItem, parentList: widget.list),

That widget file is actually pretty short, here is item_list_stream.dart in its entirety. Notice the sort performed on the list items, this takes the place of “orderBy” on the database call.

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:flutter/material.dart';
import 'package:grocery_go/components/item_list.dart';
import 'package:grocery_go/models/shopping_list.dart';

class ItemListStream extends StatelessWidget {

  final dbStream;
  final sortBy;
  final listType; // item, crossedOff
  final onTap;
  final onInfoTap;
  final ShoppingList parentList;

  ItemListStream({@required this.dbStream, @required this.sortBy, @required this.listType, @required this.onTap, @required this.onInfoTap, this.parentList});

  @override
  Widget build(BuildContext context) {
    return StreamBuilder(
      stream: dbStream,
      builder: (context, snapshot) {
        if (snapshot.hasError) {
          return Text('Error: ${snapshot.error}');
        }
        if (snapshot.hasData && !snapshot.data.documents.isEmpty) {
          List<DocumentSnapshot> docs = snapshot.data.documents;

          if (listType != 'crossedOff') {
            docs.sort((a, b) {
              return a.data['listPositions'][sortBy].compareTo(b.data['listPositions'][sortBy]);
            });
          } else {
            docs.sort((b, a) {
              return a.data['lastUpdated'].toDate().compareTo(b.data['lastUpdated'].toDate());
            });
          }

          return ItemList(list: docs, listType: listType, onItemTap: onTap, onInfoTap: onInfoTap, parentList: parentList);
        } else {
          return Column(
              children: [
                Padding(
                  padding: EdgeInsets.all(8),
                  child: Text("No items yet!"),
                ),
              ],
          );
        }
      }
    );
  }
}

Building the “reorder” UI

I tap the “three dots in a row” in the blue “Items” bar, then I drag “Bag of potatoes” up one spot. The change is reflected on the previous screen and in Firebase.

Check out reorderable_list.dart to see how this works.

I adapted the reorder logic from this very helpful example: https://gist.github.com/slightfoot/bfaaf6338d85e27b2acfe1b265ee5f27

Building the “store change” UI

Finally, the user needed a way to change which store was selected. Here’s what I built:

I built this using a Cupertino Action Sheet. Look in main_shopping_list.dart for the full code. Changing the selected store calls _setSelectedStore, which updates the selectedStoreID state variable and “re-gets” the active items and inactive items streams with that updated ID.

_setSelectedStore(String id, String name) async {
    final SharedPreferences prefs = await SharedPreferences.getInstance();
    prefs.setString(widget.list.id, id);

    setState(() {
      selectedStoreID = id;
      selectedStoreName = _getStoreName(id);
      activeItemsStream = db.getActiveItemsStream(widget.list.id, id);
      inactiveItemsStream = db.getInactiveItemsStream(widget.list.id, id);
    });

    Navigator.pop(context, id);
  }

The final product

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

Here’s what we did:

  • Added a new view that lets the user change the order of shopping list items by dragging and dropping them individually
  • Added the ability to change which store is active for a shopping list
  • Added “listPositions” map to each item so each item knows where it appears in each store

Go back to Part 7’s feature work list.

Building a Flutter app: “Cross off” feature

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

In this post: I built the “cross off” feature to my “Grocery Go” shopping list management app.

First, the final product

Watch as items move between the top list (the “active” list) and the bottom list (the “crossed off” list).

Feature list

Here are all the things that should happen when this feature is considered done:

  • When the user taps the item, it is visibly removed from the shopping list and added to the “Crossed off” list below the shopping list
  • The parent shopping list itemCount is decreased by one
  • A “crossed off” item appears at the top of the crossed off items list
  • The time/date of this action is saved to the item so we know when it was crossed off [dateLastMoved]
  • If the user taps a “crossed off” item, it returns to the shopping list and the itemCount is increased by one
  • The time/date of this action is saved to the item so we know when it was added to the list [dateLastMoved]
  • Shopping Lists maintain their own lists of Crossed Off items, so that the user doesn’t see a crossed off item from their “home improvement” list in their “groceries” list – add CrossedOff subcollection to Shopping List

Adding the isCrossedOff property to Item

I thought it might be simple to just have each item track whether it is “active” or “crossed off”. isCrossedOff will be a boolean value on Item instances, so it had to be added to any code that models Item’s data.

That includes item_dto.dart:

class ItemDTO {

  String id;
  String name;
  String date;
  int quantity;
  bool subsOk;
  List substitutions;
  String addedBy;
  String lastUpdated;
  bool private;
  bool urgent;
  bool isCrossedOff;

  String toString() {
    return 'id: $id, name: $name, date: $date, '
        'quantity: $quantity, subsOk: $subsOk, substitutions: $substitutions, '
        'addedBy: $addedBy, lastUpdated: $lastUpdated, private: $private, urgent: $urgent, isCrossedOff: $isCrossedOff';
  }

  Map<String, dynamic> toJson() => <String, dynamic> {
    'id': this.id,
    'name': this.name,
    'date': this.date,
    'quantity': this.quantity,
    'subsOk': this.subsOk,
    'substitutions': this.substitutions,
    'addedBy': this.addedBy,
    'lastUpdated': this.lastUpdated,
    'private': this.private,
    'urgent':this.urgent,
    'isCrossedOff':this.isCrossedOff,
  };
}

models/item.dart:

import 'package:cloud_firestore/cloud_firestore.dart';

class Item {
  String id;
  String name;
  String date;
  int quantity;
  bool subsOk;
  List substitutions;
  String addedBy;
  String lastUpdated;
  bool private;
  bool urgent;
  bool isCrossedOff;

  Item(DocumentSnapshot document) {
    this.id = document['id'];
    this.name = document['name'];
    this.date = document['date'];
    this.quantity = document['quantity'];
    this.subsOk = document['subsOk'];
    this.substitutions = document['substitutions'];
    this.addedBy = document['addedBy'];
    this.lastUpdated = document['lastUpdated'];
    this.private = document['private'];
    this.urgent = document['urgent'];
    this.isCrossedOff = document['isCrossedOff'];
  }
}

new_item_form.dart

    if (formState.validate()) {
      formKey.currentState.save();

      itemFields.date = DateTime.now().toString();
      itemFields.lastUpdated = DateTime.now().toString();
      itemFields.addedBy = "TILCode";
      itemFields.subsOk = true;
      itemFields.substitutions = new List<String>();
      itemFields.private = false;
      itemFields.quantity = 1;
      itemFields.urgent = false;
      itemFields.isCrossedOff = false;

      var docRef = await db.createItem(args.parentListID, itemFields);

and edit_item_form.dart:

  @override
  void initState() {
    print(args.item.date.toString());
    itemFields.id = args.item.id;
    itemFields.name = args.item.name;
    itemFields.addedBy = args.item.addedBy;
    itemFields.date = args.item.date;
    itemFields.quantity = args.item.quantity;
    itemFields.subsOk = args.item.subsOk;
    itemFields.private = args.item.private;
    itemFields.urgent = args.item.urgent;
    itemFields.isCrossedOff = args.item.isCrossedOff;
    return super.initState();

To avoid having to delete my existing items and re-create them through the form just now, I also went into their Firebase documents and added isCrossedOff to my three test items:

Filtering the item stream by isCrossedOff’s value

Next up: adding a second “get item stream” method to database_manager.dart.

Originally, getItemsStream() returned all the items. Now, I want it to only return items where isCrossedOff is set to false, like so:

Stream<QuerySnapshot> getItemsStream(shoppingListID) {
    return shoppingLists.document(shoppingListID).collection('items').where('isCrossedOff', isEqualTo: false).snapshots();
}

A second stream method can return items where crossedOff is true.

Stream<QuerySnapshot> getCrossedOffStream(shoppingListID) {
    return shoppingLists.document(shoppingListID).collection('items').where('isCrossedOff', isEqualTo: true).snapshots();
  }

Back in main_shopping_list.dart I added another use of my ItemListStream widget and pass it db.getCrossedOffStream for the given shopping list ID:

return SingleChildScrollView(
  child: Column(
    mainAxisSize: MainAxisSize.min,
    mainAxisAlignment: MainAxisAlignment.start,
    children: <Widget>[
      ItemListHeader(text: args.list.id), 
      ItemListStream(dbStream: db.getItemsStream(args.list.id), listType: 'item', onTap: _crossOff, onInfoTap: _editItem, parentList: args.list),
      ItemListHeader(text: "Crossed off"),
      ItemListStream(dbStream: db.getCrossedOffStream(args.list.id), listType: 'item', onTap: _moveBack, onInfoTap: _editItem, parentList: args.list),
    ],

Now the items are being filtered by their isCrossedOff value:

Once I saw it working and was satisfied that I could filter the items this way, I decided to do a quick refactor to turn getItemsStream() in database_manager.dart into one method that takes a second parameter indicating whether I want the active items or the crossed off items.

  Stream<QuerySnapshot> getItemsStream(shoppingListID, isCrossedOff) {
    return shoppingLists.document(shoppingListID).collection('items').where('isCrossedOff', isEqualTo: isCrossedOff).snapshots();
  }

Which looks like this when I call getItemsStream():

 ItemListStream(dbStream: db.getItemsStream(args.list.id, false), listType: ...

Making crossed off items look “crossed off” by drawing a line through them

This step was easy – in main_shopping_list.dart, I changed the existing listType param from ‘item’ to ‘crossedOff’.

ItemListStream(dbStream: db.getItemsStream(args.list.id, true), listType: 'crossedOff', ... 

In item_list.dart, I added an additional check for the ‘crossedOff’ list type in the itemBuilder so that an Item instance it still created for it.

...

var listItem;

if (listType == 'shopping list') {
  listItem = ShoppingList(list[index]);
} else if (listType == 'store') {
  listItem = Store(list[index]);
} else if (listType == 'item' || listType == 'crossedOff') {
  listItem = Item(list[index]);
} else {
  print("Unhandled list item type");
}

list_item.dart was already set up to apply a lineThrough style if the listType is ‘crossedOff’.

return ListTile(
      title: Text(buildTitleString(), style: (listType == 'crossedOff' ? TextStyle(decoration: TextDecoration.lineThrough) : TextStyle(decoration: TextDecoration.none))),
...

Crossed off text result:

Moving items between the “active” list and the “crossed off” list

In main_shopping_list.dart, there are two methods that get passed all the way down to the Item instances:

  _crossOff(Item item) {
    print("Remove this id from this list: " + item.id);
  }

  _addToList(Item item) {
    print("Moving this item back to the list: " + item.id);
  }

They are fed into the ItemListStream as onTap: methods. Items that are ‘active’ get the _crossOff method:

ItemListStream(dbStream: db.getItemsStream(args.list.id, false), listType: 'item', onTap: _crossOff, onInfoTap: _editItem, parentList: args.list),

Items that are on the ‘crossedOff’ list get the _addToList method:

ItemListStream(dbStream: db.getItemsStream(args.list.id, true), listType: 'crossedOff', onTap: _addToList, onInfoTap: _editItem, parentList: args.list),

In my first attempt at this, I ended up with two methods that almost looked identical:

    _crossOff(Item item) async {
      await db.updateItemCrossedOffStatus(
          args.list.id,
          item.id,
          {
            'isCrossedOff': true,
            'lastUpdated': DateTime.now().toString()
          }
        );
    }

    _addToList(Item item) async {
      await db.updateItemCrossedOffStatus(
          args.list.id,
          item.id,
          {
            'isCrossedOff': false,
            'lastUpdated': DateTime.now().toString()
          }
      );
    }

They both call the same DatabaseManager method:

  Future updateItemCrossedOffStatus(String parentListID, String itemID, data) async {
    if (parentListID != null && parentListID.length > 0) {
      // adjust the shopping list's item count accordingly
      if (data['isCrossedOff']) {
        shoppingLists.document(parentListID).updateData({'itemCount': FieldValue.increment(-1)});
      } else {
        shoppingLists.document(parentListID).updateData({'itemCount': FieldValue.increment(1)});
      }
      // update the item itself
      DocumentReference itemDocRef = shoppingLists.document(parentListID).collection('items').document(itemID);
      Firestore.instance.runTransaction((Transaction tx) async {
        await tx.update(itemDocRef, data);
      }).catchError((e) {
        print(e.toString());
      });
    } else {
      print("ID is null/has no length");
    }
  }

I refactored them into one method that just flips whatever the item’s current value for isCrossedOff currently is:

    _updateCrossedOffStatus(Item item) async {
      await db.updateItemCrossedOffStatus(
          args.list.id,
          item.id,
          {
            'isCrossedOff': !item.isCrossedOff,
            'lastUpdated': DateTime.now().toString()
          }
        );
    }

Note: I initially set out to use the “ItemDTO” for this update, but I couldn’t figure out how to use it “partially” – ie, the only parts of the item I want to update are the lastUpdated and isCrossedOff fields, but the ItemDTO requires all of the fields to be present. I could copy the entire item into it, but I wonder if there’s just some better way to do this in general…

View this feature’s pull request.

Now the user can cross items off and add them back to the active list by tapping on them. Return to the feature work list.