Shopping List

Note: This is a work in progress.

Shopping List is a series of Offline First demo apps, each built using a different stack. These demo apps cover Progressive Web Apps, hybrid mobile apps, native mobile apps, and desktop apps.

The Shopping List demo apps are brought to you by:

Purposes
Features
Implementations
Interoperability
Domain Model Implementations
- JavaScript
- Swift
- Kotlin
Style Guides
Templates

Purposes

These demo apps will each serve multiple purposes:

Reference Implementations
Live Demos
Tutorials
Workshops
Developer Journeys

Features

Shopping List is a simple demo app, with a limited feature set. Here is a list of features written as user stories grouped by Epic:

Planning
- As a <person planning to shop for groceries>, I want to <create a shopping list> so that .
- As a <person planning to shop for groceries>, I want to <add an item to my shopping list> so that .
- As a <person planning to shop for groceries>, I want to <remove an item from my shopping list> so that .
Shopping
- As a <person shopping for groceries>, I want to <view items on my shopping list> so that .
- As a <person shopping for groceries>, I want to <add an item to my shopping list> so that .
- As a <person shopping for groceries>, I want to <remove an item from my shopping list> so that .
- As a <person shopping for groceries>, I want to <check off an item on my shopping list> so that .
Offline First
- As a <person shopping for groceries>, I want to <have the app installed on my device> so that .
- As a <person shopping for groceries>, I want to <have my shopping list stored locally on my device> so that .
- As a <person shopping for groceries>, I want to <sync my shopping list with the cloud> so that .
Multi-User / Multi-Device
- As a <new user>, I want to <sign up for the app> so that .
- As an <existing user>, I want to <sign in to the app> so that .
- As an <existing user>, I want to <sign out of the app> so that .
Geolocation
- As a <person planning to shop for groceries>, I want to <associate a shopping list with a grocery store> so that .
- As a <person associating a shopping list with a physical store>, I want to <access previously-used locations> so that .
- As a <person shopping for groceries>, I want to <be notified of a shopping list when I am physically at the grocery store associated with that shopping list> so that .

Implementations

Interoperability

Implementations of the Shopping List demo app share a data model. This allows the demo apps to be interoperable with one another. For example, a user could plan a shopping trip with a desktop app built using Electron and PouchDB. The same user could then use a native app built using Kotlin and Cloudant Sync while shopping for groceries. Much of the design of this data model is inspired by the CouchDB Best Practices collection from eHealth Africa.

Shopping List Example

{
  "_id": "list:cj6mj1zfj000001n1ugjfkj33",
  "type": "list",
  "version": 1,
  "title": "Groceries",
  "checked": false,
  "place": {
    "title": "Healthy Living",
    "license": "Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright",
    "lat": "44.46282415",
    "lon": "-73.1799710198028",
    "address": {
      "supermarket": "Healthy Living",
      "road": "Dorset Street",
      "city": "South Burlington",
      "county": "Chittenden County",
      "state": "Vermont",
      "postcode": "05406",
      "country": "United States of America",
      "countryCode": "us"
    }
  },
  "createdAt": "2017-08-21T18:40:00.000Z",
  "updatedAt": "2017-08-21T18:40:00.000Z"
}

Notes:

_id: Unique identifier for the document. Generated from the following values, separated by colons:
- Document type (list).
- Collision-resistant ID (cuid).
type: Document type (will always have a value of list for a shopping list).
version: Document schema version.
title: User-generated title for the shopping list.
checked: Has this shopping list been fully checked off?
place: Associates the shopping list with a geolocation. Derived from OpenStreetMap's Nominatim search tool. The example above is derived from the following search:

http://nominatim.openstreetmap.org/search/Healthy%20Living%20Vermont?format=json&addressdetails=1&namedetails=1

createdAt: Date and time at which the document was created. Expressed as a simplified extended ISO format in zero UTC offset (which can be generated in JavaScript with new Date().toISOString()).
updatedAt: Date and time at which the document was last updated. Expressed as a simplified extended ISO format in zero UTC offset.

Shopping List Item Example

{
  "_id": "item:cj6mn7e36000001p9n14fgk6s",
  "type": "item",
  "version": 1,
  "list": "list:cj6mj1zfj000001n1ugjfkj33",
  "title": "Mangos",
  "checked": false,
  "createdAt": "2017-08-21T18:43:00.000Z",
  "updatedAt": "2017-08-21T18:43:00.000Z"
}

Notes:

_id: Unique identifier for the document. Generated from the following values, separated by colons:
- Document type (item).
- Collision-resistant ID (cuid).
type: Document type (will always have a value of item for a shopping list item).
version: Document schema version.
list: The unique identifier of the parent shopping list
title: User-generated title for the shopping list item.
checked: Has this shopping list item been checked off?
createdAt: Date and time at which the document was created. Expressed as a simplified extended ISO format in zero UTC offset (which can be generated in JavaScript with new Date().toISOString()).
updatedAt: Date and time at which the document was last updated. Expressed as a simplified extended ISO format in zero UTC offset.

Here is an example of a Mango / pouchdb-find / Cloudant Query selector that fetches a single shopping list's items:

{
  "selector": {
    "type": "item",
    "list": "list:cj6mj1zfj000001n1ugjfkj33"
  }
}

Note that the above query can also be used to get a count of items within a shopping list by simply using the Array.length property (or equivalent) and accounting for the shopping list document being included in the results. Since PouchDB just runs every reduce function in memory, there is no benefit to using a _count reduce function when using PouchDB. The Cloudant Sync libraries for iOS and Android do not support map/reduce (but do support Cloudant Query / Mango).

Geolocation Context Example

A geolocation context is used to notify the user when the geolocation capability of their device has indicated that they are near a place associated with a shopping list. This provides the user with quick access to the shopping list for their current geographic context.

{
  "_id": "geo:drguywpyxp4t:cj6mn7e36000001p1q02dlz5q",
  "type": "geo",
  "list": "list:cj6mj1zfj000001n1ugjfkj33",
  "version": 1,
  "notified": false,
  "createdAt": "2017-08-21T18:57:00.000Z",
  "updatedAt": "2017-08-21T18:57:00.000Z"
}

Notes:

_id: Unique identifier for the document. Generated from the following values, separated by colons:
- Document type (geo).
- Geohash of the place.lat and place.lon values from the associated shopping list at a precision of 12 (which can be generated in JavaScript using the latlon-geohash module).
- Collision-resistant ID (cuid).
type: Document type (will always have a value of geo for a geolocation context item).
list: The unique identifier of the parent shopping list
version: Document schema version.
notified: Has a notification already been sent for this geolocation context? Note that the geolocation context document may be deleted after a notification has been sent and the corresponding shopping list has been fully checked off.
createdAt: Date and time at which the document was created. Expressed as a simplified extended ISO format in zero UTC offset (which can be generated in JavaScript with new Date().toISOString()).
updatedAt: Date and time at which the document was last updated. Expressed as a simplified extended ISO format in zero UTC offset.

Here is an example of a Mango / pouchdb-find / Cloudant Query selector that utilizes the built-in _all_docs view to query for geolocation contexts near the current geolocation coordinates of the device (the value drguyw below is the geohash of the user's location at a precision of 6, or ±0.61 km):

{
  "selector": {
    "_id": {
      "$gte": "geo:drguyw",
      "$lte": "geo:drguyw\uffff"
    }
  }
}

Domain Model Implementations

JavaScript

GitHub Repository:
https://github.com/ibm-watson-data-lab/shopping-list-model-js

Swift

GitHub Repository:
https://github.com/ibm-watson-data-lab/shopping-list-model-swift

Kotlin

GitHub Repository:
https://github.com/ibm-watson-data-lab/shopping-list-model-kotlin

Style Guides

General guidelines:

Where possible, a consistent style is maintained between the different demo app implementations.
Where there is a style that is common for a particular type of application we defer to that style.

Implementations:

Vanilla JS: Material Design (using MDC-Web)
Polymer: Material Design (using Polymer App Toolbox)
React: Material Design (using Material-UI)
Preact: Material Design (using preact-material-components)
Vue.js: Material Design (using Vue Material)
Ember.js: Material Design (using MDC-Web)
React Native: iOS Design Themes or Material Design (depending on the target platform)
Ionic: iOS Design Themes or Material Design (depending on the target platform)
Cordova: iOS Design Themes or Material Design (depending on the target platform)
Swift: iOS Design Themes
Kotlin: Material Design
Electron: Material Design (using MDC-Web)

Templates

See the templates directory for templates that can be used for each demo app implementation. This includes the following files:

LICENSE
README.md

ibm-watson-data-lab/shopping-list

Shopping List

Table of Contents

Purposes

Features

Implementations

Vanilla JS and PouchDB

Polymer and PouchDB

React and PouchDB

Preact and PouchDB

Vue.js and PouchDB

Ember.js and PouchDB

React Native and PouchDB

React Native and Cloudant Sync

Ionic and PouchDB

Ionic and Cloudant Sync

Cordova and PouchDB

Cordova and Cloudant Sync

Swift and Cloudant Sync

Kotlin and Cloudant Sync

Electron and PouchDB

Interoperability

Shopping List Example

Shopping List Item Example

Geolocation Context Example

Domain Model Implementations

JavaScript

Swift

Kotlin

Style Guides

Templates