Merge branch 'main' into user-prefs

CONTRIBUTING.md

@@ -15,6 +15,7 @@ Most contribution (we imagine) would be in the form of API-compatible modules, w
 * [Contributing Modules](#contributing-modules)
 * [Info File](#info-file)
 * [Ideas](#Contribution-ideas)
+* [User Preferences](#user-preferences)
 * [Grunt Tasks](#grunt-tasks)
 * [UI Helper Methods](#ui-helper-methods)
 
@@ -368,6 +369,45 @@ module.exports =
         }
     });
 ```
+## User Preferences
+The user preferences API can be used for adding, reading, updating and deleting user preferences in the browser using **indexedDB** API.
+* File Path: [/src/ui/userPrefs.js](https://github.com/publiclab/image-sequencer/blob/main/src/ui/userPrefs.js)
+### Usage
+```js
+var userPrefs = require('/path/to/userPrefs')(options);
+if (userPrefs.error) {
+  console.log(error);
+  return;
+}
+
+userPrefs.addPref('user-name', {name: 'user'}, () => {
+  userPrefs.new().getPref('user-name', (pref) => {
+    console.log(pref.name); // user
+    userPrefs.new().deletePref('user-name', () => {console.log('deleted')}) // preference deleted
+    
+  })
+})
+```
+### Return Value
+A new `userPreferenceManager` object is returned by the function.
+###### note: If an error occured or if **indexedDB** is not supported by he browser, the return value will be an object with a string `error` property.
+#### Properties
+The `userPreferenceManager` object has the following properties.
+- `dbName`: Name of the database the user preferences are stored in.
+- `storeName`: The object store in the database where the user preferences are stored.
+#### Options
+The function accepts a single object called `options` as an argument which has the following properties.
+* `dbName`: Name of a custom database. Default is `user-prefs`.
+* `storeName`: Name of a custom objectStore. Default is `user-prefs`.
+#### Methods
+The following methods are available on the returned object.
+* `addPref(prefName, preference, callback)`: Adds a preference with the name `prefName` and value `preference`. `preference` is an object containing any key but `preference`. `callback` is a function executed once a preference as been added.
+* `deletePref(prefName, callback)`: Deletes he preference with the name `prefName` if it exists. `callback` is executed once the preference is deleted.
+* `updatePref(prefName, preference, callback)`: Updates the value of the preference with the name `prefName` to `preference`.
+* `getPref(prefName, callback)`: Gets the preference with the name `prefName`. The value is passed to `callback` which is executed once the preference is fetched. If the requested preference doesn't exist then the value passed to `callback` will be `undefined`.
+* `new()`: Returns a new `userPreferenceManager` object with the same options as before. This function can be used if the original object is to be reused as the `userPreferenceManager` object can only be used once.
+
+
 
 ## Linting
 

src/ui/userPrefs.js

@@ -0,0 +1,58 @@
+function userPreferenceManager(options) {
+
+  options.dbName = options.dbName || 'user-prefs';
+  options.storeName = options.storeName || 'user-prefs';
+  
+  if (!('indexedDB' in window)) {
+    return { error: 'indexedDB not supported' };
+  }
+  
+  this.storeName = options.storeName;
+  this.dbName = options.dbName;
+  
+  const db = idb.open(dbName, 1, (upgradeDB) => {
+    if (!upgradeDb.objectStoreNames.contains(options.storeName)) {
+      upgradeDB.createObjectStore(options.storeName, {keyPath: 'preference'});
+    }
+  }
+                      
+  this.prototype.addPref = (prefName, preference, cb) => {addPref(db, {preference: prefName, ... preference}, options, cb)};
+  this.prototype.updatePref = (prefName, preference, cb) => {updatePref(db, {preference: prefName, ... preference}, options, cb)};
+  this.prototype.deletePref = (prefName, cb) => {deletePref(db, prefName, options, cb)};
+  this.prototype.getPref = (prefName, cb) => {getPref(db, prefName, options, cb)};
+  this.prototype.new = () => {return new userPreferenceManager(options)};
+      
+  return this;
+}
+    
+function addPref(db, preference, options, cb) {
+  db.then((dbSnap) => {
+    var tx = dbSnap.transaction(options.storeName, 'readwrite');
+    tx.objectStore(options.storeName).add(preference);
+    return tx.complete;
+  }).then(cb);
+}
+
+function updatePref(db, preference, options, cb) {
+  db.then((dbSnap) => {
+    var tx = dbSnap.transaction(options.storeName, 'readwrite');
+    tx.objectStore(options.storeName).put(preference);
+    return tx.complete;
+  }).then(cb);
+}
+    
+function deletePref(db, prefName, options, cb) {
+  db.then((dbSnap) => {
+    var tx = dbSnap.transaction(options.storeName, 'readwrite');
+    tx.objectStore(options.storeName).delete(prefName);
+    return tx.complete;
+  }).then(cb);
+}
+    
+function getPref(db, prefName, options, cb) {
+  db.then((dbSnap) => {
+    var tx = dbSnap.transaction(options.storeName, 'readwrite');
+    var store = tx.objectStore(options.storeName, 'readwrite');
+    return store.get(prefName);
+  }).then(cb);
+}