Setting up uMobile PhoneGap for HTML5-only Development

Table of Contents:

General

Depending upon your organization's needs, you may want to augment or extend the lightweight HTML5-based umobile wrapper. The umobile wrapper is responsible for logging a user into the portal server and rendering an icon-based grid layout based upon a user's defined layout (i.e. layout.json). The below documentation outlines specific details related to the umobile wrapper. It is important to note, that all development can take place within a browser and a mobile device is not necessarily needed.

Requirements

1. Download & install node.
   
   1. Node is used to automate the build process for our JavaScript, HTML and CSS assets.
   2. Node is installed locally and is leveraged for convenience.
   3. Node v0.8.12 is recommended for this documentation.

Getting Setup

Install Node & NPM

At the core of the umobile-phonegap implementation is umobile running as an HTML5 web application. The application code base leverages node.js for its development server. The application also makes use of npm, a package manager for installing node modules. The latest releases of node ships with npm so only a node installation is required. Node offers platform installers for both Windows and Mac OSX. They also offer binaries for Windows, Mac OSX and Linux systems. Visit the download page for more information.

1. To verify your node installation, open a terminal and enter the node -v command: 
   
   

   node -v // example output: v0.8.9 

2. To verify your npm installation, open a terminal and enter the npm -v command:

    npm -v // example output: 1.1.61

Clone the Project

1. Clone the master branch of the umobile-app-phonegap github project into a directory on your file system.

   git clone git@github.com:Jasig/umobile-app-phonegap umobile-ui

2. Navigate to the root of the cloned repository.

    cd umobile-ui

Install Node Modules

Once node and npm are installed you will need to install all of the node modules leveraged by umobile. You can view all of the module dependencies by examining the package.json file located at the root of the project.

To install node modules:

1. Open a terminal window and navigate to the root of the umobile project.
   

    cd path/to/umobile-ui

2. Run the npm install command. (You must run the npm install command in the same directory that contains the package.json file).
   

    npm install

3. Depending upon your system permissions, you may need to run the npm install as root.
   

    sudo npm install

4. You may also encounter a warning about installing grunt with the -g parameter. The -g installs grunt globally so it is accessible across all projects.
   

    npm install -g grunt-cli

5. Once complete, the node_modules directory, containing all of your project's node modules, will be added to your project.

Configure Authentication

uMobile currently supports three different authentication strategies: CAS, Local & Mock.

1. Each strategy has a cooresponding configuration file under the umobile-ui/src/js/src/config directory (i.e., cas.js, local.js and mock.js).
2. Choose one of the three authentication strategies. For this documentation, we will use mock.js.
3. Open mock.js.
   
   1. Set config.uMobileServerUrl to: 'http://localhost:5000'.
   2. Set config.uMobileServerContext to: '/data'.

Run the Development Build

cd path/to/umobile-ui
grunt dev

Start Development Server

1. Open a terminal window and navigate to the root of the umobile-ui directory.
   

   cd path/to/umobile-ui
   node app.js

2. Open a browser and navigate to http://localhost:5000.

Development Server

The umobile HTML5 application leverages node and express for a convenient development server. The development server provides a quick way for developers to standup a server without having to configure  a servlet container like Tomcat to perform simple development tasks on the umobile HTML5 application. 

Start the Server

1. Open a terminal window and navigate to the root of the umobile-ui directory.
    

    cd path/to/umobile-ui

   
   

2. Run the node app.js command to start the server.
    

    node app.js

   
   

3. Open a browser and navigate to http://localhost:5000
   

Stop the Server

1. Using the same terminal window to start the server, the CTRL + C command will stop the server.

Toggle the Server Mode

The development server supports two modes: dev and prod. By default, the server runs in dev mode and all files are served up from the /src directory. When set to prod mode, the server serves files from the /www directory, which contains production-ready code. In short, the server mode allows developers the ability to toggle the location of the files being served between the /src and /www directories. This can be useful, if a developer wishes to preview and test production-ready code in a browser before pushing the code to the phonegap wrapper.

1. To run the server in prod mode, open a terminal window and navigate to the root of the umobile-ui directory.
   

    cd path/to/umobile-ui

2. Run the node app.js command with the --mode=prod option.

    node app.js --mode=prod

3. The terminal will output the location of served files.

   $ node app.js --mode=prod
   Express public directory:  /path/to/umobile-ui/www
   Express server listening on port 5000
   

Build Process

The project build uses the Grunt tool, which is a JavaScript task runner similar to Apache Ant that automates the build process. There are two main build processes: a development build process and a production build process. A build process is needed for both development and production environments due to the fact that our application relies upon a pre-compilation process to output both css and template files. The umobile HTML5 web application leverages node and grunt to compile the application's less files into css. In addition, node and grunt are also used to precompile template files and to append template partials to the main index file. Depending upon the environment that you are developing for (i.e., iOS, Android, Web, etc.), different resources are added or removed from the application's templates. To develop the umobile HTML5 application we rely upon the system's defaults, which assumes you are developing for a Web environment. For more information on templates and additional options, check out the following sections: Working with Templates and Build Options.

Run the Development Build Process

1. Navigate to the project root directory and execute the development build with the grunt dev command.
   

   cd path/to/umobile-ui
   grunt dev

   
   
   

2. Running the grunt dev command performs the following actions:
   1. Less files are compiled to css
      
      1. The css files are output to: /src/css
   2. JavaScript code is linted
      
      1. JavaScript code exists by default in the /src/js directory
      2. The build process does not touch the JavaScript aside from linting operations.
   3. HTML index template is compiled
      
      1. The index.html file is output to: /src
   4. HTML partial templates are appended
      
      1. Partial templates are appended to index.html under the /src directory
   5. Auto-generated documentation builds documentation site based upon code comments.
      
      1. Documentation is output to /src/docs
   6. All generated code is pushed to the /src directory.

Run the Production Build Process

1. Navigate to the project root directory and execute the production build with the grunt prod command.
   

   cd path/to/umobile-ui
   grunt prod

   
   
   

2. Running the grunt prod command performs the following actions:
   

   1. Assets are copied to production directory
      
      1. images are copied to /www/images
   2. Less files are compiled to css
      
      1. The css files are output to: /www/css
         
   3. JavaScript code is linted
   4. JavaScript code is compressed and optimized
      
      1. The JavaScript files are output to: /www/js
   5. HTML index template is compiled
      
      1. The index.html file is output to: /www
   6. HTML partial templates are appended
      
      1. Partial templates are appended to index.html under the /www directory
   7. Auto-generated documentation builds documentation site based upon code comments.
      
      1. Documentation is output to /www/docs

Build Options

--environment

The --environment option adds and removes phonegap dependencies for a specific platform (i.e., web, android and ios). More specifically, when this option is set to android, the build process will include the cordova-android.js file. Likewise, when set to ios, the build process will include the cordova-ios.js file. By default, this option is set to web, which notifies the build process not to include either cordova dependencies. In general, this option should only be used when preparing and packaging production-ready code for the phonegap wrapper for either the android or ios platforms. This option should also be used in conjunction with the --auth option.

Supported Values:

• web (default)
• android
• ios

Usage:

1. To configure the build to include android specific dependencies, navigate to the project root directory and execute the production build command with the --environment option set to android.
   

   cd path/to/umobile-ui
   grunt prod --environment=android --auth=local

2. To configure the build to include ios specific dependencies, navigate to the project root directory and execute the production build command with the --environment option set to ios.
   

    cd path/to/umobile-ui
   grunt prod --environment=ios --auth=local

--auth

The --auth option adds a umobile configuration file based upon an organization's authentication strategy (i.e., mock, cas and local). More specifically, when this option is set to cas, the build process will include the cas.js file. Likewise, when set to local, the build process will include the local.js file. By default, this option is set to mock, which includes a mock authentication strategy. The mock authentication strategy mocks the layout data (layout.json) for a guest and student user in the context of a web browser. The mock authentication strategy should not be used with the phonegap wrapper. This option should only be used when preparing and packaging production-ready code for the phonegap wrapper for either the android or ios platforms. In addition, this option should only be set if a portal server exists and is configured to handle either cas or local login strategies. This option should also be used in conjunction with the --environment option.

Supported Values:

• mock (default)
• cas
• local

Usage:

1. To configure the build to include the local authentication strategy, navigate to the project root directory and execute the production build command with the --auth option set to local.
   

   cd path/to/umobile-ui
   grunt prod --environment=android --auth=local

2. To configure the build to include the cas authentication strategy, navigate to the project root directory and execute the production build command with the --auth option set to cas.

   cd path/to/umobile-ui
   grunt prod --environment=ios --auth=cas

UI Architecture

Templates

Template files are located under the /views directory. The umobile HTML5 web application is a single page application. As such, it consists of an index.html file and several partial templates that are appended to the index.html file during the build process. As previously mentioned, templates are pre-compiled in order to add or remove dependencies based upon the platform. To that end, two grunt tasks, compilehtml and appendpartials manage the compiling and appending of templates for the umobile HTML5 application.

grunt compilehtml

The compilehtml task is a custom grunt task. The source for the custom task can be found under the /tasks directory. The compilehtml task consists of two main targets: devViews and prodViews. The devViews target compiles the index.html file and copies the file to the /src directory. The prodViews target compiles the index.html file and copies the file to the /www directory.

Usage:

1. To compile templates for the development environment, navigate to the project root directory and execute the grunt compilehtml:devViews command. The index.html file will be compiled and placed at the root of /src.
   

   cd path/to/umobile-ui
   grunt compilehtml:devViews

2. To compile templates for the production environment, navigate to the project root directory and execute the grunt compilehtml:prodViews command. The index.html file will be compiled and placed at the root of /www.
   

   cd path/to/umobile-ui
   grunt compilehtml:prodViews

grunt appendpartials

The appendpartials task is a custom grunt task. The source for the custom task can be found under the /tasks directory. The appendpartials tasks takes all the partial templates located under the /views/partials directory and appends them to the index.html file. The appendpartials task consists of two main targets: dev and prod. The dev target appends partials to the index.html file located under the /src directory. The prod target appends partials to the index.html file located under the /www directory.

Usage:

1. To append partial templates for the development environment, navigate to the project root directory and execute the grunt appendpartials:dev command. The index.html file located under the /src directory will be appended.
   

   cd path/to/umobile-ui
   grunt appendpartials:dev

2. To append templates for the production environment, navigate to the project root directory and execute the grunt appendpartials:prod command. The index.html file located under the /www directory will be appended.
   

   cd path/to/umobile-ui
   grunt appendpartials:prod

Automation 

Both the compilehtml and appendpartials tasks can be automated by executing the grunt watcher command. When the grunt watcher is executed, it watches for any changes to the template files located under the /views directory. When detected both the compilehtml and appendpartials tasks are executed.

1. Navigate to the project root directory and execute the grunt watcher command.

   cd path/to/umobile-ui
   grunt watcher

Theme

The theme or presentation layer is built using the less preprocessor. All files leveraged to construct the presentation layer can be found under the /less directory. The theme is composed of 4 main sections: libs, base, layout and components. Each section contains several .less files. All sections and .less files are aggregated under the umobile.less file. 

Sections

1. libs
   
   1. Houses css libraries ( i.e., Bootstrap ).
2. base
   
   1. Houses css definitions that formulate the theme's foundation.
   2. Houses variables ( i.e., color & path definitions )
   3. Houses mixins ( i.e., reusable, parameterized definitions )
   4. Houses helpers ( i.e., generic reusable classes such as a .hidden )
3. components
   
   1. Houses component specific definitions ( i.e., navbar, buttons, alerts, modulelist, etc. )
4. layout
   1. Houses layout-specific definitions

grunt less

The grunt less task compiles all .less files. The less task consists of two main targets: dev and prod. The dev target compiles .less files to the umobile.css file located under the /src/css directory. The prod target compiles .less files to the umobile.css file located under the /www/css directory.

Usage:

1. To compile less files for the development environment, navigate to the project root directory and execute the grunt less:dev command.
   

   cd path/to/umobile-ui
   grunt less:dev

2. To compile less files for the production environment, navigate to the project root directory and execute the grunt less:prod command.
   

   cd path/to/umobile-ui
   grunt less:prod

Automation

The grunt less task can be automated by executing the grunt watcher command. When the grunt watcher is executed, it watches for any changes to .less files located under the /less directory. When detected the grunt less task is executed.

1. Navigate to the project root directory and execute the grunt watcher command.

   cd path/to/umobile-ui
   grunt watcher

Backbone

The application logic is built using the Backbone framework. Implementation files can be found under the /src/js directory. Application code is primarily organized into four sections: models, collections, services and views. 

Sections

• Model - a model contains the application data as well as logic surrounding the model ( conversions, validations, computed properties, and access control ). 
• Collection - a collection is an ordered set of models ( i.e., an array of models ).
• Services - a service is a object that is accessible throughout the application (i.e., utility, authentication, etc.).
• Views - contain logic and methods that bind your HTML templates to your data model. 

Models

State

• authenticated: Boolean flag. Indication of authentication status.
• lastSessionAccess: Timestamp of last session-maintaining page / resource load, in milliseconds since the epoch.
• currentView: The fname of the current module, used to load application into correct module upon application relaunch.

Credentials

• username: A user's username.
• password: A user's password.
• The credential model may need to be extended to accomodate other credential types.

Module

• fname: Human-readable string identifier for portlet or module (i.e., news, calendar, etc.)
• title: Title of portlet or module.
• url: Location of the portlet or module.
• iconUrl: Location of portlet or module icon.
• newItemCount: Indicator to illustrate updates to the module or portlet.
• isNative: Indicates uMobile native support for module or portlet.
• Post-processing makes URLs absolute, etc.

Collections

ModuleCollection

• models: Ordered array of Modules corresponding to merged user layout and native modules.
• Needs to be extended to accomodate alternate folder-based layout.

Services

• Authentication: Houses authentication methods to manage mock, local and cas login implementations.
• SessionTracker: Currently disabled. Houses custom cordova plugin logic used to retrieve session timestamp.
• Storage: Houses storage methods.
• Utils: Houses utility methods.

Views

• Architecture
  
  • Base.js
  • LoadedView.js
• Components
  
  • Page.js
  • Header.js
  • Breadcrumb.js
  • Module.js
  • Footer.js
  • Notifier.js
• Loaded Views
  
  • DashboardView.js
  • LoginView.js
  • ModuleView.js

Documentation

YUIDocs

The umobile HTML5 application uses the YUIDoc tool to produce automated JavaScript documentation. For the development build process, documentation is placed in the /src/docs directory. For the production build process,  documentation is placed in the /www/docs directory. Regardless of build (dev or prod), documentation can be viewed by navigating your browser to localhost:5000/docs.

grunt docs

The grunt docs task leverages the YUIDoc tool to output JavaScript documentation. The docs task consists of two main targets: dev and prod. The dev target outputs documentation to the /src/docs directory. The prod target outputs documentation to the /www/docs directory.

Usage:

1. To output documentation for the development environment, navigate to the project root directory and execute the grunt docs:dev command.
   

   cd path/to/umobile-ui
   grunt docs:dev

2. To output documentation for the production environment, navigate to the project root directory and execute the grunt docs:prod command.
   

   cd path/to/umobile-ui
   grunt docs:prod

Publish Documentation to Github

To publish the documentation on github's project site, execute the following:

git checkout master
grunt docs
git checkout gh-pages
npm install
grunt

The project documentation will be published to: http://jasig.github.com/umobile-app-phonegap/

Debugging

The application leverages the Debug plugin from Ben Alman. The debug plugin allows for logs to be output to each browser's developer console as well as set the logging level. Examine the debug API for more information on the debug plugin and its usage. Its important to note that logging is disabled during the production build cycle.