Angular wrappers for Trigger.io (forge) modules
JavaScript
Latest commit db1d631 Apr 13, 2016 @sloops77 Update README.md
Permalink
Failed to load latest commit information.
js
release
.eslintignore
.eslintrc
.gitignore
.jscs.json
LICENSE
README.md
bower.json
build.config.js
gulpfile.js
package.json
version.template.json

README.md

ngForge

Angular & Trigger.IO are a great combination for developing mobile apps. Using either iOS or Crosswalk for Android it’s possible to build hybrid mobile apps we could only dream of in the past few years.

ngForge is a set of Angular wrappers for Trigger.io Forge modules with the aim to:

  1. Seemlessly switch between mobile & browser implementations
  2. Provide a AngularJS friendly experience:
    • Dependency Injection not globals.
    • Promises not callbacks.
    • $http API equivalency for the request module using $forgeHttp.
  3. Provide a basis for use in modern JS development:
    • Use the browser as the primary development environment – because there are many commonplace, well supported, free tools.
    • Don’t require trigger.io builds in the browser environment.
    • Be optimised for standard JS build tools: Grunt, Gulp, etc.
  4. Allow services to be configured & reconfigured on the fly in browser mode.

Quickstart

Once you have included the module using

angular.module('app', ['ngForge'])

You can then simply inject in one of the adapters

angular.module('app').factory('UserService', ['$forgeHttp', '$forgePrefs', function($forgeHttp, $forgePrefs) {
  return {
    loadUser: function(userId) {
      $forgePrefs.get('user' + userId).then(function (cachedData) {
        if cachedData
          return cachedData;
        else
          throw new Error('cache miss')
      }).catch(function() {
        //cache miss or any other error
        $forgeHttp.get('user/' + userId).then(function (response) {
          $forgePrefs.set('user' + userId, response.data.user);
          response.data.user
        }); 
      });
    }
  };
}]);

Once you are happy with the javascript, html & css you have produced then deploy the app to the simulator or a phone to perfect the integration side of the app.

Adapters

What's Implemented?

Currently the following adapters are provided:

Trigger.io Module ngForge Service Configurable Properties Web Mock Notes
forge (Core Services) $forge testConnectionUrl is, event & tools only
forge.camera $forgeCamera all implemented
forge.contact $forgeContact sampleContacts select, selectById, selectAll only
forge.facebook $forgeFacebook sampleKeyHash all implemented
forge.file $forgeFile isFile, getLocal, cacheURL, URL, remove only
forge.request $forgeHttp $http.get, $http.head, $http.post, $http.put, $http.delete, $http.jsonp
forge.launchimage $forgeLaunchimage all implemented
forge.logger $forgeLogger all implemented
forge.media $forgeMedia createAudioPlayer only
forge.parse $forgeParse all implemented
forge.payments $forgePayments all implemented
forge.platform $forgePlatform all implemented
forge.prefs $forgePrefs prefsKey all implemented
forge.segmentio $forgeSegmentio all implemented
forge.sms $forgeSms all implemented
forge.ionic_keyboard** $forgeIonicKeyboard all implemented

** There is a wrapper around the ionic_keyboard module (port of drifty/ionic's original with fixes for keyboard behaviour) that is available at https://github.com/sloops77/ionic-keyboard-forge

The purpose of these adapters is to make it simpler to quickly develop your app in the browser using both standard Angular techniques (i.e. promises rather than callbacks) AND using your favourite javascript build framework (gulp, grunt, etc) - with the trigger.io modules switched out and provide mock data instead.

Configuration

In browser mode, ngForge services can be configured by using Angular config methods. You may want to configure:

  1. Mock data: for example the mock contact book data used by $forgeContact, or
  2. Implementation configuration, for example what key to store data under when using the localStorage version of $forgePrefs.

Each service documents what is configurable. Here is an example config:

angular.module('app').config([‘$forgePrefsProvider’, function($forgePrefsProvider) {
    $forgePrefsProvider.prefsKey = ‘customPrefix’
}]);

Using the $forgeHttp wrapper of the forge.request module

Trigger.io’s forge.request module offers cross-origin access and native performance for HTTP request.

However, the request module’s API is based on a subset of the JQuery API and if you are using Angular it would be preferable to replicate the $http service API. (See the Angular $http service documentation

This is what the $forgeHttp API looks like:

$http.get(url, config)
$http.head(url, config)
$http.patch(url, data, config)
$http.post(url, data, config)
$http.put(url, data, config)
$http.delete(url, config)
$http.jsonp(url, config)

The following methods are not implemented as yet:

$http(config)

Additionally, the config object supports the following properties:

  • params{string|Object}: Params that are not already query strings are serialized as query strings and appended to the URL.
  • data{Object}: Data to be sent as the request message data. If it’s a get request then it is serialized as a query string and appended to the URL.
  • headers{Object}: Map of strings representing HTTP headers to send to the server.
  • cache{boolean|Object}: A boolean value or object created with $cacheFactory to enable or disable caching of the HTTP response.
  • timeout{number}: timeout in milliseconds
  • responseType{string}: See XMLHttpRequest.responseType.

All these methods return a promise that support the standard methods: then, catch & finally methods that take function with a single argument of the http response object. It also supports the deprecated success & error methods for handling responses. See the Angular Promises Documentation for more detail.

Results of get are, by default, not cached. Caching is supported in the same way as in $http, that is, by default using simply the value true, or by an instance of $cacheFactory. (See the Angular $http caching documentation for more information)

We also support interceptors that allows you to implement cross cutting concerns for requests or response. Simply add interceptors to the $httpProvider as in the Angular documentation.

Finally

Only a portion of the modules have been mocked so far - so please add your own contributions - make sure that the mock data is scrubbed.