diff --git a/Projects/First-DB-App.md b/Projects/First-DB-App.md new file mode 100644 index 00000000..7c1f62ba --- /dev/null +++ b/Projects/First-DB-App.md @@ -0,0 +1,155 @@ +# Your First DB App + +**Tier:** 1-Beginner + +Understanding database concepts and how to use them in your applications is +knowledge all developers need to acquire. The objective of Your First DB App +is to provide a gentle introduction to database concepts and learning one +use case for databases in a frontend app. + +So, did you know that modern browsers have a database management system +built into them? IndexedDB is built into most modern browsers and provides +developers with basic database features, transaction support, and client-side +cross-session persistance. + +### Requirements & Constraints + +- The primary use case for a browser based database is to maintain state or +status information that needs to persist across sessions, or as a work area +for temporary data. For example, data retrieved from a server that must be +reformatted or cleansed before it's presented to the user. + +- It is important to keep in mind that since the client-side browser +environment cannot be secured you should not maintain any confidential or +personal identifying information (PII) in a browser based database. + +- The following Javascript class is provided with the functionality to allow +your app to initially populate and clear the database from the browser so you +can test the query logic you'll be adding. +``` +class Customer { + constructor(dbName) { + this.dbName = dbName; + if (!window.indexedDB) { + window.alert("Your browser doesn't support a stable version of IndexedDB. \ + Such and such feature will not be available."); + } + } + + /** + * Remove all rows from the database + * @memberof Customer + */ + removeAllRows = () => { + const request = indexedDB.open(this.dbName, 1); + + // Handle any errors + request.onerror = (event) => { + console.log('removeAllRows - Database error: ', event.target.error.code, + " - ", event.target.error.message); + }; + + request.onsuccess = (event) => { + console.log('Deleting all customers...'); + const db = event.target.result; + const txn = db.transaction('customers', 'readwrite'); + txn.onerror = (event) => { + console.log('removeAllRows - Txn error: ', event.target.error.code, + " - ", event.target.error.message); + }; + txn.oncomplete = (event) => { + console.log('All rows removed!'); + }; + const objectStore = txn.objectStore('customers'); + const getAllKeysRequest = objectStore.getAllKeys(); + getAllKeysRequest.onsuccess = (event) => { + getAllKeysRequest.result.forEach(key => { + objectStore.delete(key); + }); + } + } + } + + /** + * Populate the Customer database with an initial set of customer data + * @param {[object]} customerData Data to add + * @memberof Customer + */ + initialLoad = (customerData) => { + const request = indexedDB.open(this.dbName, 1); + + // Handle any errors + request.onerror = (event) => { + console.log('initialLoad - Database error: ', event.target.error.code, + " - ", event.target.error.message); + }; + + request.onupgradeneeded = (event) => { + console.log('Populating customers...'); + const db = event.target.result; + const objectStore = db.createObjectStore('customers', { keyPath: 'userid' }); + objectStore.onerror = (event) => { + console.log('initialLoad - objectStore error: ', event.target.error.code, + " - ", event.target.error.message); + }; + + // Create an index to search customers by name and email + objectStore.createIndex('name', 'name', { unique: false }); + objectStore.createIndex('email', 'email', { unique: true }); + + // Populate the database with the initial set of rows + customerData.forEach(function(customer) { + objectStore.put(customer); + }); + db.close(); + }; + } +} + +// Web page event handlers +const DBNAME = 'customer_db'; + +/** + * Clear all customer data from the database + */ +const clearDB = () => { + console.log('Delete all rows from the Customers database'); + let customer = new Customer(DBNAME); + customer.removeAllRows(); +} + +/** + * Add customer data to the database + */ +const loadDB = () => { + console.log('Load the Customers database'); + + // Customers to add to initially populate the database with + const customerData = [ + { userid: '444', name: 'Bill', email: 'bill@company.com' }, + { userid: '555', name: 'Donna', email: 'donna@home.org' } + ]; + let customer = new Customer(DBNAME); + customer.initialLoad(customerData); +} +``` + + +## User Stories + +- [ ] User can ... first user story + +## Bonus features + +- [ ] User can ... first bonus feature + +## Useful links and resources + +- [IndexedDB Concepts (MDN)](http://tinyw.in/7TIr) +- [Using IndexedDB (MDN)](http://tinyw.in/w6k0) +- [IndexedDB API (MDN)](http://tinyw.in/GqnF) +- [IndexedDB Browser Support](https://caniuse.com/#feat=indexeddb) + +## Example projects + +- N/a diff --git a/README.md b/README.md index 32dc6cea..0422c175 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ required to complete them. | [🌟Countdown Timer](./Projects/Countdown-Timer-App.md) | Event Countdown timer | 1-Beginner | | [CSV2JSON App](./Projects/CSV2JSON-App.md) | CSV to JSON converter | 1-Beginner | | [🌟Dynamic CSS Variables](./Projects/Dynamic-CSSVar-app.md) | Dynamically change CSS variable settings | 1-Beginner | +| [🌟First DB App](./Projects/First-DB-App.md) | Your first Database app! | 1-Beginner | | [Flip Image](./Projects/Flip-Image-App.md) | Change the orientation of images across two axes | 1-Beginner | | [🌟GitHub Status](./Projects/GitHub-Status-App.md) | Display Current GitHub Status | 1-Beginner | | [🌟Hello](./Projects/Hello-App.md) | User native language greeting | 1-Beginner |