Skip to content

Home

Jump to bottom
Ken Manheimer edited this page Mar 31, 2014 · 18 revisions

Table of Contents

Development Tooling and Procedures

Here are app development details and pointers, beyond the installation and basic development instructions found in the app repository's README.md. We assume acquaintance with the fundamental web technologies - HTML5, Javascript, CSS, HTTP, JSON, etc - and currently the building and debugging instructions assume a Mac development platform.

Fundamental Infrastructure

The SpiderOak Storage Server Web API
The app is client of the SpiderOak storage servers via this API.
Web Storage API JSON Data Structures
Representative examples of some of the JSON data to expect from the server.
Backbone.js
An MVC / MVVM framework for javascript applications, we build our architecture around it.
JQuery
Our Javascript DOM-encapsulation library.
Apache Cordova aka PhoneGap
Our HTML5/native mobile platform hyridization framework
mocha, chai, Mocha PhantomJS, and Sinon.JS
Test harness facilities providing a versatile Behavior-Driven Development (BDD) software test-driven framework for Backbone-based applications. Sinon provides a complemnting spying, stubbing and mocking library.
See Testing Backbone applications with Jasmine and Sinon for an fine introduction to this kind of approach.

Establishing The Development Environment

See the distribution's README.md for the installation instructions. Here are some additional details:

  • Install the sources by cloning the repository:
    git clone [email protected]:SpiderOak/SpiderOakMobileClient.git
  • Install the facilities listed in the "Requirements" section (and follow the links for details about these facilities).
  • Follow the steps in the "Getting started" section to install the internal facilities.
About npm install
npm follows the package specifications in package.json . It also does a bower install , which obeys the distribution root .bowerc file to install the ingredients, specified in the components.json file, into the www/components directory.
About cordova platform add ios and cordova platform add android
Use .cordova/config.json to specify Cordova (aka PhoneGap) projects for the respective platforms. The results will be found in the respective platforms subdirectories.

Development Workflow Model

We like the github-flow development model. Our continuous integration facility will notify (annoy (-: ) us promptly about errors in the master. Our aim is to avoid them, so that anyone can fork the master at any time for a working copy of the app.

Essentially:

  • Do all work in a feature branch specifically for that work
    • Frequently push your feature branch to the origin, so nothing is lost if your workstation fails
    • Periodically merge updates to the origin/master to your branch, if your work lasts a while
  • When ready to merge, submit a pull request. This enables others to review your changes, which is suitable for everything except very small changes.
  • When the changes are well assured, someone resolves the pull request and the feature becomes a part of the master.
Add notes about ongoing development obstacles and issues to Ongoing-Development-Issues, and check there for ongoing gotchas.

Running, Testing, and Debugging

Grunt is our operations command facility. The top level file, Gruntfile.js , specifies the grunt task recipes. Grunt automation is also key to our continuous integration setup, at Travis CI.

Our repertoire of grunt commands is evolving as we develop, so get the recipe listing (described first, below) to see what's current, and/or read Gruntfile.js for the details. Here are some of the prominent commands:

grunt ... Action Requirements Effect
grunt --help List the recipe tasks and other options
grunt Prepare the web code for operation - do what's necessary so the app html, css, and javascript, etc, is properly composed
grunt test Run the tests in a headless webkit session (using Phantom JS). The default test is mochaspec, but you can run many alternative test layouts by explicitly invoking the command chain, and using shell:mocha?. For example: grunt jshint && grunt dot && grunt concat && grunt shell:mochamin
grunt debug:ios
grunt debug:android 		Mac, recent Xcode
Android SDK 		Run the app in either the iOS simulator or Android emulator. This runs the hybrid app under Cordova, after jslinting, concatenating templates and code, and testing. An optional third parameter specifies the test format suffix, defeault "dot" for mochadot.
grunt yolo:ios
grunt yolo:android 		Mac, recent Xcode
Android SDK 		The same as debug command, except skip the tests to work around failing tests. Be sure to run and ensure the tests pass before you request a pull of your branch to master!
grunt brand:<name> A proper config dir <name> in custom/brands Configure the repo clone to use custom/brands/name/ as the build brand. If the repo was not already configured for that, then the clone's cordova build environment is re-fabricated to use that brand. See White-label-App-Customization for details.
Drop www/index.html in simulator webkit browser. Run default composition using grunt sans args This may become unavailable when all app operation depends on Cordova
Visit www/index.html in a CORS-enabled desktop browser session Run default composition using grunt sans args; CORS must be disabled This may become unavailable when all app operation depends on Cordova. You must use a browser session operating with Cross-Origin Resource Sharing restrictions inhibited.

Debugging Hints

When running the app on a desktop using a device simulator, you can connect the webkit inspector to the running app:

» iOS remote debugging:
Enable Remote Web Inspector In iOS 6 provides simple instructions for applying your Mac Safari browser's web inspector to the app running in the iOS simulator.
You can run the full app, under Cordova, using grunt debug_android .
For a more streamlined approach, if the app can operation without Cordova, you can drag and drop the application www/index.html onto the iOS simulator's mobile Safari browser.
(In either case, Control-R in the web inspector will reload the app's web code.)
» Android remote debugging
See the Google Developer's Chrome Developer Tools Remote Debugging page for instructions to inspect and debug pages being visited by Mobile Chrome on your device using Desktop Chrome on your workstation.
» Running in a desktop browser
To run the client from local files you must run your browser with Cross Origin Resource Sharing (CORS) restrictions and other security restrictions relaxed.
Beware: this means substantially reduced browser security!
Here are the command options you need to pass to Chrome:
  • --allow-file-access-from-files --allow-http-access-from-files --disable-web-security --enable-file-cookies

Custom branding

See grunt brand ... command mentioned above, and White-label-App-Customization for details.

Architectural Documents

Web Storage API JSON Data Structures
Examples of various web storage api v1 data structures.
Tracing Storage Traversal
Description of control flow in traversal of an account's storage content hierarchy
Clone this wiki locally