888888 8888888b. .d8888b. "88b 888 Y88b d88P Y88b 888 888 888 Y88b. 888 888 d88P "Y888b. 888 8888888P" "Y88b. 888 888 "888 88P 888 Y88b d88P 888 888 "Y8888P" .d88P .d88P" 888P" JPS Developer Documentation (devdoc.txt) Matt Thompson Document last updated: 17 November, 2016 --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- Hello there. This document is meant to provide a brief technical overview of the stuff that makes JPS work. This should be especially useful if you are a developer planning to add to or modify JPS. This document will be broken down into the following parts: CONTENTS: PART_01 ........... INTRO TO JPS PART_02 ........... JPS UI FUNCTIONS PART_02.5 ......... Brief Overview of js/main.js PART_03 ........... JPS DEPENDENCIES PART_04 ........... A BRIEF NOTE ON FIREBASE PART_04.5 ......... JPS' Firebase Data Structure PART_05 ........... HOSTING --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_01 | INTRO TO JPS JPS is a simple single page web aplication written in Javascript that utilizes two "back end as a service" tools made by Firebase (now owned by Google). This application uses the Firebase Auth API for admin login and the Firebase Realtime Database API for data storage. JPS is designed to be able to operate using Firebase's free tier. Currently, hosting for the static JPS front end is also being done at Firebase, using a service called Firebase Hosting (you can really run JPS on any environment that supports static files like CSS, HTML, and JavaScript). --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_02 | JPS UI FUNCTIONS JPS operates on a single HTML page. /index.html. In general (the search page is an exception), each different page is represented in /js/main.js as a function in jps.ui. When one of these "page" functions is called, the currently dislayed page is removed, all events from that page are unbinded, and the HTML code contained in the function is inserted into the HTML page. --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_02.5 | Brief Overview of js/main.js main.js is a reasonably large (and messy) file, but if you're modifying JPS this is probably the file you'll find yourself wanting to be in. This part of the document will attempt to make it easier to find what you're looking for in main.js. The following is a hierarchical breakdown of main.js Note: JavaScript //Comment Notation is used to label various sections jps | | |---- init() | | |---+ utilities | | | |---- genKey() | |---- htmlEscape(str) | |---- format_date(timestamp) | |---- remove_node(path) | |---- customComparison(cat, val1, val2) | | |---- temp | | |---+ actions | | | | // AUTH ACTIONS | |---- logOut() | |---- logIn(email, password) | | | | // UI ACTIONS | |---- addNewContrib() | |---- chooseVolWorkUser(id, name) | |---- chooseDonationUser(id, name) | |---- chooseContributor(uid) | |---- showUpdateUser() | |---- getIndex(table, sortBy) | |---- sortDecision(theArray, isString, sortBy) | |---- displayContributorTable(searchCat, searchVal, sortBy) | |---- displayDonationsTable(searchCat, searchVal, sortBy) | |---- displayVolunteerTable(searchCat, searchVal, sortBy) | |---- displayProgramTable(searchCat, searchVal, sortBy) | |---- deleteConfirm(path) | | | | // EXPORT ACTIONS | |----exportToExcel(element, filename, columns) | | |---+ ui | | | | // JQUERY BIND MANAGMENT | |---- pageListeners[] | |---- addPageListener(divId, eventName, callBack) | |---- clearPageListeners() | |---- clearPage() | | | | // NAVBAR FUNCTIONS | |---- initEasyNav() | |---- killEasyNav() | |---- easyNavToggle(divName) | | | | // TOGGLES | |---- restoreDateFilterState() | |---- contributorToggle() | |---- donationToggle() | |---- volunteerWorkToggle() | |---- programToggle() | |---- propToggle() | | | | // PAGE FUNCTIONS | |---- logInPage() | |---- resetPassword() | |---- homePage() | |---- newContribPage() | |---- adminPage() | |---- databasePage() | |---- addDonationPage() | |---- addVolWorkPage() | |---- searchPage() | |---- contributorInfoPage() | |---- donationEditPage() | |---- volunteerEditPage() | |---- programEditPage() | |---- helpPage() --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_03 | JPS DEPENDENCIES Here are the external dependencies that JPS relies on. jquery jquery UI (for fallback datepicker) Google Fonts (for Google Material Icons) Firebase (Auth, Realtime data, Hosting) Travis Clarke's TableExport.js Eli Grey's FileSaver.js --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_04 | A BRIEF NOTE ON FIREBASE Using another Firebase backend with JPS So you want to run another instance of JPS that manages an entirely seperate set of data from this instance of JPS? OK. 1). Make a new firebase app. 2). Swap out Firebase apikey and other Firebase settings in the jps.init function 3). Set the firebase security rules to match what you see in docs/rules.json 4). In Firebase auth settings, create a user. 5). You should be able to log in to JPS with your Fresh Backend! Firebase Docs If you're not super familiar with Firebase, the Firebase web API docs will be super helpful if you're planning on adding to/improving JPS. These can be found here: https://firebase.google.com/docs/reference/js/ Firebase Console The Firebase console lets you do pratcially anything the API can do. You are given full access to the Realtime database, all Auth users, and more. ***REASONABLY IMPORTANT NOTE: Be careful... Any and all changes made in the console are REAL and deletions made within the console can not be undone!!!!*** Firebase "Spark Plan" (Free) Limits The Free Plan of Firebase does have its limits. 1). 100 devices may be connected to JPS at any given moment 2). 10 GB of data transfer per month 3). 1 GB of data stored If you find in the future that JPS is exceeding these limits, upgrades are avaliable at https://firebase.google.com/pricing/. With that said, we don't see JPS needing more than 1GB of total storage for quite some time (we're storing some very lightweight data). --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_04.5 | JPS' Firebase Data Structure The following is the data structure of JPS. (This should look very similar to what the Firebase Realtime DB console shows you.) **** HEY: If you're setting this up in Firebase from scratch, note that CAPS MATTER **** jpsystem | | |---+ Donations | | | +---+ donation entry id (str, auto generated) | | | | | |---- cat (str, see special note 1) | | |---- class (str, see special note 2) | | |---- date (str, timestamp) | | |---- logged (str, timestamp) | | |---- num (float) | | |---- pid (str) | | |---- uid (str) | | | +---+ another donation entry id (str, auto generated) | | | | | |---- cat (str, see special note 1) | | |---- class (str, see special note 2) | | |---- date (str, timestamp) | | |---- logged (str, timestamp) | | |---- num (float) | | |---- pid (str) | | |---- uid (str) | | |---+ Users | | | +---+ user id (str, auto generated) | | | | | |---- address (str) | | |---- city (str) | | |---- email (str) | | |---- name (str) | | |---- state (str) | | |---- zip (str) | | | +---+ another user id (str, auto generated) | | | | | |---- address (str) | | |---- city (str) | | |---- email (str) | | |---- name (str) | | |---- state (str) | | |---- zip (str) | | |---+ VolWork | | | +---+ vol work entry id (str, auto generated) | | | | | |---- date (str, timestamp) | | |---- hours (float) | | |---- logged (str, timestamp) | | |---- pid (str) | | |---- type (str, see special note 3) | | |---- uid (str) | | | +---+ another vol work entry id (str, auto generated) | | | | | |---- date (str, timestamp) | | |---- hours (float) | | |---- logged (str, timestamp) | | |---- pid (str) | | |---- type (str, see special note 3) | | |---- uid (str) | | |---+ programs | | | +---+ program id (str, auto generated) | | | | | |---- list (boolean) | | |---- name (str) | | | +---+ another program id (str, auto generated) | | | | | |---- list (boolean) | | |---- name (str) DATA STRUCTURE SPECIAL NOTES Special Note 1 | donation category The following are the possible values for donation category: 1). mon ....... monetary 2). food ...... food 3). clothes ... clothes 4). ff ........ Friday Friends 5). school .... school supplies 6). diapers ... diapers 7). personalc . personal care 8). produce ... produce 9). meat ...... meat Special Note 2 | donation class The following are the possible values for donation class: 1). individual ....... individual 2). church ........... church 3). corp ............. corporation 4). foundation ....... foundation 5). gov_public_fund .. Gov/Public Fund 6). grant ............ grant 7). service_org ...... Service Org 8). inkind_salary .... In-kind Salary Special Note 3 | Vol Work Type The following are the possible values for vol work type: 1). pantry ....... Pantry 2). mentor ....... Mentor 3). silver_cord .. Silver Cord --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- PART_05 | HOSTING Alternate Title: "Where can/does JPS' Code Live?!?!?!" Alternate Title 2: "Can I Run JPS at [[[INSERT WEBHOST NAME]]]?!?!?!" Current Hosting Situation We went ahead and deployed JPS to Firebase Hosting. Firebase Hosting allows you to "deploy" static files (js, css, html, images) using their command line tool. To deploy to Firebase Hosting you'll need node.js and npm (installing node.js gives you npm too). If and when you have node.js installed, simply type `npm install -g firebase-tools` to install the CLI. Then, follow the instructions here to setup and deploy. ***IMPORTANT NOTE: You must be given editor access to the Firebase console to deploy*** Hosting JPS Somewhere Else: You can host JPS ANYWHERE that supports static files (js, css, html, images). JPS' entire backend is Firebase, meaning you don't have to worry about your host provider having backend langage support (php, python, node.js, ruby, other stuff). Just move the source directory onto whatever webhost you want and you should be allllll set!