clean up and documentation

2016-02-23 11:17:50 -06:00
parent ce9cd68470
commit ccf4a88986
8 changed files with 133 additions and 27 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,8 @@
 node_modules/
 server/bin/
-client/build/
-shared/data/
+client/build/design/assets
+client/build/design/dashboard
+client/build/design/data
+client/build/development
+server/data/
 sass/
--- a/client/build/design/index.html
+++ b/client/build/design/index.html
@@ -4,8 +4,7 @@
    <meta charset="utf-8">
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href="/assets/css/vendor.css" rel="stylesheet" type="text/css">
-    <link href="/assets/css/application.css" rel="stylesheet" type="text/css">
+    <link href="/assets/style.css" rel="stylesheet" type="text/css"/>
    <title>Spike Prototype</title>
  </head>
  <body>
@@ -23,7 +22,10 @@
            </div>
          </div>
        </nav>
-        <div id="root"></div>
+        <div class="container">
+          <div id="compiling_layouts" class="alert alert-warning">Compiling layouts and styles....</div>
+          <div id="root"></div>
+        </div>
      </div>
      <div id="spike_footer">
        <div class="container">Footer</div>
@@ -35,7 +37,6 @@
    // in developer tools for the native `fetch`.
    self.fetch = null;
  </script>
-  <script src="http://localhost:3000/webpack-dev-server.js"></script>
-  <script src="/assets/js/vendor.js"></script>
-  <script src="/assets/js/application.js"></script>
+  <script src="/assets/sass/dist/sass.js"></script>
+  <script src="/assets/app.js"></script>
 </html>
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
    "babel-preset-stage-0": "6.3.13",
    "babel-core": "6.3.21",
    "babel-loader": "6.2.0",
+    "babel-cli": "^6.3.17",
    "express": "4.13.3",
    "react": "0.14.3",
    "react-dom": "0.14.3",
@@ -41,18 +42,11 @@
    "extend": "3.0.0",
    "through2": "2.0.1",
    "lokijs": "1.3.11",
-    "babel-cli": "^6.3.17",
-    "babel-standalone": "6.4.4",
    "gulp": "^3.9.0",
    "gulp-util": "3.0.7",
    "gulp-copy": "0.0.2",
    "jasmine-core": "2.4.1",
-    "karma": "^0.13.19",
-    "karma-babel-preprocessor": "^6.0.1",
-    "karma-chrome-launcher": "^0.2.2",
-    "karma-jasmine": "^0.3.6",
    "react-templates": "0.4.1",
-    "requirejs": "~2.1",
    "jasmine-es6": "0.1.4"
  }
 }
--- a/readme.md
+++ b/readme.md
@@ -1 +1,119 @@
 # Spike
+
+## Installing
+
+To run the development server, you'll need node and npm. This is easiest with [nvm](https://github.com/creationix/nvm):
+
+```sh
+sudo nvm install 5.4.1
+nvm use 5.4.1
+```
+
+Then install the necessary Node packages:
+
+```sh
+sudo npm install
+```
+
+## Running development server
+
+### Setting up development database
+
+The development server requires a Postgresql database:
+
+```sql
+CREATE DATABASE spike2;
+CREATE USER spikeuser WITH PASSWORD '123456';
+GRANT ALL ON DATABASE spike2 TO spikeuser;
+```
+
+The database dump can be found in the Google Drive [spike folder](https://drive.google.com/drive/u/0/folders/0B6Ys-9_Te2cFNktOU3VwSzA1VWs). Then import:
+
+```sh
+psql spike2 < spike.dump
+```
+
+### Compiling React Templates
+
+The React views are all located in `client/dashboard`. They are organized by feature with their `scss` and React Component files. React templates have an `rt` extension. To compile them to Js code, run:
+
+```sh
+gulp compile_react_templates
+```
+
+If you're running the dev server, you'll need to run this command in another window to see the changes in the app.
+
+### Launching express app
+
+The dev server runs a Rest API with express and hosts the compiled assets with [Webpack dev server](https://webpack.github.io/docs/webpack-dev-server.html). Webpack will watch imported files and refresh the page when changes are saved.
+
+```sh
+npm start
+```
+
+### Clearing data in client storage
+
+When developing, it can be really useful to clear all of the data saved to local client storage. A better alternative to clearing all data in your browser cache, hit the 'Refresh Data' button on the main page below the houses dropdown.
+
+## Building the designer pack
+
+To build a design pack, you first need to install [sass.js](https://github.com/medialize/sass.js/) in the design build directory so the design build can compile the sass in the browser.
+
+```sh
+cd client/build/design
+git clone https://github.com/medialize/sass.js.git
+```
+
+Then to build the app, you'll need to build the app with webpack:
+
+```sh
+gulp build --design
+```
+
+You'll also need to download the design data in Google Drive [spike folder](https://drive.google.com/drive/u/0/folders/0B6Ys-9_Te2cFNktOU3VwSzA1VWs) and save it to `client/build/design/data`.
+
+The design app requires no backend, just a server so files can be downloaded with jQuery. For instance with Python:
+
+```
+cd client/build/design
+python -m SimpleHTTPServer 8000
+python3 -m http.server
+```
+
+Access the app at localhost:8000. The app will run slow because json responses are not as finely paginated and both React templates and sass are compiled in the browser before the app runs.
+
+The designer can change React templates and sass files in `/dashboard`. Refresh the page to see the changes reflected. They can then share this directory with us so we can update the files in this repository.
+
+## Testing
+
+Tests are currently limited to critical utility functions. Integration tests, especially focused on data caching, should be added at a later more stable state.
+
+```sh
+jasmine
+```
+
+## App Summary
+
+Two main purposes for this app structure and set of dependencies:
+
+1. Take a large dataset (the current database dump yields json responses of 500 MB) and enable the client to parse through it efficiently.
+2. Bundle the app so that it can run offline and reflect changes to sass and layout files when the page is refreshed.
+
+The functionality and structure of the app reflect usage of the following libraries:
+- [LokiJs](http://lokijs.org/#/): A client side no-SQL database. Persists data in memory and can be written to browser storage with `db#save()`. The in memory data can then be cleared with `Databasable#closeDb()` - see `client/lib/databasable.js`.
+- [ReactJs](https://facebook.github.io/react/).
+- [React Templates](http://wix.github.io/react-templates/): This library compiles a lightly extended HTML syntax to React Js. This is viewed as a better alternative to JSX, since it more closely reflects native HTML (see #2 above) and more easily enables separation between code and view.
+- [Babel](https://babeljs.io/): Compiles ES6 (or even ES7) to ES5 for browser compatibility.
+- [Webpack](https://webpack.github.io/): Javascript module bundler. Compiles dependencies and repository code to single file, which can be optimized or run in development for easy debugging. Can also compile sass assets. Configurable for different options. See `client/config/:environment/webpack.js` for our configuration files.
+
+### Alternatives
+
+We may also want to consider the following client side persistence, no-SQL databases:
+
+- [localForage](http://mozilla.github.io/localForage/): Simpler key value storage. Supported by Mozilla Foundation. Elected against this primarily because it does not enable advanced querying (eg gte, lte, etc).
+- [pouchdb](http://pouchdb.com/): Based on CouchDb API and intended to sync with CouchDb instances. Well supported and documented. However, data is stored and accessed directly from browser storage, rather than maintaining data in memory and explicitly persisted to browser storage (as LokiJs does). There is an in memory adapter, but this would have to be maintained as a separate pouchdb instance until the data is copied to a persistence pouchdb instance.
+
+### Aspirations
+
+See [Trello board](https://trello.com/b/OUlqsBo5/spike) for a to do list.
+
--- a/server/helpers/api_helper.js
+++ b/server/helpers/api_helper.js
--- a/server/models/energy_datum.js
+++ b/server/models/energy_datum.js
@@ -1,6 +1,6 @@
 import DB from "./../config/database";
 import extend from 'extend';
-import ApiHelper from './../helpers/api_helper';
+import ApiHelper from './../lib/api_helper';

 const NAME = 'EnergyDatum';

--- a/server/models/power_datum.js
+++ b/server/models/power_datum.js
@@ -1,6 +1,6 @@
 import DB from "./../config/database";
 import extend from 'extend';
-import ApiHelper from './../helpers/api_helper';
+import ApiHelper from './../lib/api_helper';

 const NAME = 'PowerDatum';

--- a/shared/models/house.js
+++ b/shared/models/house.js
@@ -1,10 +0,0 @@
-import moment from 'moment';
-
-class House {
-
-  timeToDateString(timestamp){
-    var house = this;
-    return moment.tz(timestamp, house.timezone).format("YYYY-MM-DD");
-  }
-
-}