Getting started with the AIM code - adapt-it/adapt-it-mobile GitHub Wiki

Code organization

The adapt-it-mobile project repository is organized in the standard PhoneGap / Cordova 3.x directory layout as it exists before creating local platforms. This is to account for differences in intermediate files when you create a local build, as well as to allow the PhoneGap Build service to hook into our repository.

Development efforts will be focused on the files in the www directory. This directory contains platform-generic html, css, js, resources and test files. Some files and directories of note:

• config.xml: this file contains packaging information used by the PhoneGap Build service, and conforms to the W3C web widget specification.

• index.html: this file is the landing point for the adapt-it-mobile app. It's mostly empty, as the other parts of the code (app.js, router.js) will swap pieces of HTML in and out of this page at runtime.

• js directory: this directory contains the javascript "code" part of the application. We are using backbone.js to give us a model - view/controller pattern, and require.js to handle javascript dependencies. Some highlights:

  • Application.js: the global Application object. Kicks off the localization, initializes the database, handles the View / page switching (AIM is a single page application).

  • main.js: kicks off the Application, contains the 3rd party lib path info, and the shim config for non-requirejs libraries.

  • router.js: exposes the URL routes of the application. The actual handling happens in the Application class.

  • models: contains both json (remote) and SQLite versions of the model. The SQLite version is the one that is currently implemented.

  • utils: contains utility function classes:

    • HandlebarHelpers: useful HTML templating methods
    • languages: ISO639 language list info
    • pageslider: utility to animate page transitions
    • scrIDs: Scripture ID info
    • usfm: markup info for the united standard format marker markup language.

  • views: contains view/controller classes

• lib directory: this contains the 3rd party javascript libraries we rely on:

  • backbone.js: for Model / View/Controller framework
  • backbone.babysitter and backbone.wreqr: extensions of the MVC framework for Marionettejs
  • fastclick.js: html tweak to speed up the click response on mobile browsers
  • hammer.js: a polyfill for touch and mouse events on the adaptation screen. Allows us to do multi-touch selection.
  • handlebars.js: html templating support
  • hopscotch: help "walkthrough" wizard that displays when you click the (?) button on the adaptation screen
  • i18next: localization / i18n support
  • jquery.js: document object model (DOM) manipulation, event handling, etc.
  • marionettejs: extension of the MVC framework. Provides a "true" controller that backbone doesn't really have.
  • require.js: dependency management
  • spectrum: color palette / selector for the fonts UI
  • text.js: for loading text resources (the html templates compiled by handlebars)
  • typeahead: popup menu that displays when there is more than one possible translation of a word / phrase
  • underscore.js: for generating unique Ids

• res directory: this contains the css, icons and images we rely on. The styling framework Topcoat library also resides in here, as does our icomatic icon buttons used to create / remove phrases, placeholders and retranslations.

• tpl directory: this contains the html templates that get compiled into "real" html and swapped in and out of the main index.html page. We use a library called handlebars.js to do the compiling; the work is controlled by the various javascript files in the code.

Opening the code in Visual Studio Code

We are currently using Visual Studio Code for Adapt It Mobile development, as Adobe's editor offering Brackets (see below) has been abandoned by Adobe. Visual Studio Code is a bit like the Eclipse IDE -- you need to install the product itself, and then install extensions that make the editor more useful for developing your particular development stack.

In our case, we need to install VS code, and then follow the steps to install the Cordova tools and debug helpers at this blog link.

DEPRECATED: Opening the code in Brackets

Install Brackets. Open the source code by doing the following:

1. Launch Brackets.

2. Select File > Open Folder...

3. Select the adapt-it-mobile folder.

You should see the directory structure on the left-hand column of the editor. To view a file, select it in the left-hand column.