| 1 | # QED
|
|---|
| 2 |
|
|---|
| 3 | This document describes how to develop this code base and the source
|
|---|
| 4 | code organisation.
|
|---|
| 5 |
|
|---|
| 6 | ## Development, Install and Deploy
|
|---|
| 7 |
|
|---|
| 8 | Source files are located in `src`. Build and deployment is managed
|
|---|
| 9 | with _Grunt_, a node based task runner.
|
|---|
| 10 |
|
|---|
| 11 | First make sure _node_, _npm_ and _couchdb_ are installed. Then
|
|---|
| 12 | install all dependencies by running `npm install`. To run _grunt_,
|
|---|
| 13 | you'll have to install the commandline client with `npm install -g
|
|---|
| 14 | grunt-cli`.
|
|---|
| 15 |
|
|---|
| 16 | From source to a deployable version goes in few steps.
|
|---|
| 17 | 1. Develop in `src`.
|
|---|
| 18 | 1. Create a development version with `grunt build`. This will put a
|
|---|
| 19 | complete uncompressed version in `build/development`.
|
|---|
| 20 | 1. Run the development version with `node server/standalone.js` or
|
|---|
| 21 | `foreman start`. For the last option, you have to have the Heroku
|
|---|
| 22 | chain installed.
|
|---|
| 23 | 1. When editing more files, you can skip copying the fixed
|
|---|
| 24 | dependencies and only process our own source files by running
|
|---|
| 25 | `grunt compile`. If dependencies change (e.g. you installed node
|
|---|
| 26 | modules) or you have the feeling something is weird, just do a
|
|---|
| 27 | clean build by running `grunt build` again. Don't forget to
|
|---|
| 28 | restart the server.
|
|---|
| 29 | 1. When you feel your changes are production ready, create a
|
|---|
| 30 | production version by running `grunt deploy`. This will do a
|
|---|
| 31 | _Dojo_ build on the client, creating compressed CSS and
|
|---|
| 32 | Javascript.
|
|---|
| 33 | 1. You can test this version with the same commands as the
|
|---|
| 34 | development version, but now from the `build/production`
|
|---|
| 35 | directory. You can distribute the content is this directory as a
|
|---|
| 36 | release.
|
|---|
| 37 | 1. If you want to deploy to Heroku, do the following:
|
|---|
| 38 | ```sh
|
|---|
| 39 | $ git clone git@heroku.com:quod-erat.git build/quod-erat
|
|---|
| 40 | $ cd build/quod-erat
|
|---|
| 41 | $ rm -rf *
|
|---|
| 42 | cp -r ../production/* .
|
|---|
| 43 | git add .
|
|---|
| 44 | git commit -a -m "Something informative goes here..."
|
|---|
| 45 | git push
|
|---|
| 46 | ```
|
|---|
| 47 |
|
|---|
| 48 | File organisation
|
|---|
| 49 | -----------------
|
|---|
| 50 |
|
|---|
| 51 | * _/_ Project root
|
|---|
| 52 | * _build/_ Builds go here
|
|---|
| 53 | * _development/_ Uncompressed build
|
|---|
| 54 | * _production/_ Minified build
|
|---|
| 55 | * _docs/_ Project documentation, design documents etc
|
|---|
| 56 | * _src/_ Source code
|
|---|
| 57 | * _client/_ Dojo web client
|
|---|
| 58 | * _server/_ Node/Express server
|
|---|
| 59 | * _Procfile_ Heroku process description
|
|---|
| 60 |
|
|---|
| 61 | ```
|
|---|
| 62 | client/
|
|---|
| 63 | The web application for QED.
|
|---|
| 64 | routes.js
|
|---|
| 65 | Contains the mapping from URLs to pages.
|
|---|
| 66 | run.js
|
|---|
| 67 | The script for starting the web application (the researchers part).
|
|---|
| 68 | stddeps.js
|
|---|
| 69 | Contains many dependencies that are used declarativly in the
|
|---|
| 70 | templates. Maybe it can be deprecated with Dojo 1.8+'s auto require
|
|---|
| 71 | if the build scans templates as well.
|
|---|
| 72 | store.js
|
|---|
| 73 | Module that returns a fully configured store for the rest of the
|
|---|
| 74 | application to use for database access. Handles caching and exposes
|
|---|
| 75 | some common serialization functions.
|
|---|
| 76 | view.js
|
|---|
| 77 | Script that starts the survey part (the respondent part).
|
|---|
| 78 | data/
|
|---|
| 79 | Apache proxy configuration for transparant access to CouchDB.
|
|---|
| 80 | dijit/
|
|---|
| 81 | Dijit library (UI components)
|
|---|
| 82 | dojo/
|
|---|
| 83 | Dojo library (Dojo JS framework)
|
|---|
| 84 | dojox/
|
|---|
| 85 | DojoX library (contrib library for Dojo and Dijit)
|
|---|
| 86 | qed/
|
|---|
| 87 | Sourcecode of the QED application
|
|---|
| 88 | app/
|
|---|
| 89 | Small app framework for handling pages, content, notifications
|
|---|
| 90 | and URL history. Our application is build on this.
|
|---|
| 91 | css/
|
|---|
| 92 | Contains all CSS of the application. Should be distributed better
|
|---|
| 93 | with the widgets. The styling is based on LESS, although a copy
|
|---|
| 94 | of the CSS is still there.
|
|---|
| 95 | model/
|
|---|
| 96 | Contains all code dependent on our model, that is, the concrete
|
|---|
| 97 | representation of our database documents.
|
|---|
| 98 | classes/
|
|---|
| 99 | Smart classes on top of the database documents, to help with
|
|---|
| 100 | creating and validating objects.
|
|---|
| 101 | widgets/
|
|---|
| 102 | All widgets that are specific for objects of our model.
|
|---|
| 103 | pages/
|
|---|
| 104 | The pages in the application. Are wired up to URLs in the routes.js
|
|---|
| 105 | file.
|
|---|
| 106 | store/
|
|---|
| 107 | Dojo Store implementations for Couch and Elastic.
|
|---|
| 108 | ui/
|
|---|
| 109 | Deprecated. Used to contain all widgets, but these are now split
|
|---|
| 110 | between general and model specific widgets. Contains a few widgets
|
|---|
| 111 | that were not yet refactored.
|
|---|
| 112 | widgets/
|
|---|
| 113 | Contains general widgets that are used in our application but do
|
|---|
| 114 | not depend on our model.
|
|---|
| 115 | util/
|
|---|
| 116 | Dojo utils (e.g. build infrastructure)
|
|---|
| 117 | ```
|
|---|
