flybits-momentdata v1.0.1

Flybits-momentdata.js

Flybits-momentdata.js is an isomorphic JavaScript helper library for the consumption of content from Flybits core Moments.

Table of Contents

1. Compatibility
2. Getting Started
3. Fundamentals
   1. Promises
   2. Standardized Errors
4. Basic Data Consumption
5. Roadmap

Compatibility

To achieve client/server agnosticism, this library utilizes the new ES6 Promise (spec) object and the upcoming standard Fetch API (spec). Both have polyfill support readily available for platforms who have yet to implement them.

To maintain compatibility until all modern browsers and node environments catch up, it is recommended to include the polyfills below by default.

Browser:

• Promise Polyfill: stefanpenner/es6-promise
• Fetch Polyfill: github/fetch

Node:

• Promise Polyfill: stefanpenner/es6-promise
• Fetch Polyfill: matthew-andrews/isomorphic-fetch

• Fetch Cookie Support Polyfill: juicetan/fetch-cookie (npm package: fetch-cookie-es5)

  Note: The Flybits Moment Data library relies on the native AJAX request mechanism to handle cookies for session management. This polyfill decorates the fetch API with automatic cookie handling functionality. Below is an example of how to use it assuming you already have fetch support or have first required the isomorphic-fetch polyfill.

  if(global.fetch){
    global.fetch = require('fetch-cookie-es5')(global.fetch);
  }

Getting Started

Fetch and Include

1. Fetch the library

   The library is available using the Node Package Manager(npm)

   $ npm install flybits-momentdata --save

2. Include the library

   Browser:

   <script src="node_modules/flybits/dist/flybits-momentdata.js"></script>
   <!-- note that Fmd will be available in the global namespace -->

   Node:

   var Fmd = require('flybits-momentdata');

Fundamentals

The library is comprised of a controller for each Flybits core Moment and a main factory method that will return a corresponding controller.

Promises

A Promise represents an operation that has yet to be completed but will in the future.

All asynchronous operations in the library, including the main factory method, returns a Promise which give developers full power and flexibility to manage chained operations, parallel model retrieval and deferred actions.

Below is an example of the power of using Promises in managing asynchronous operations in the flybits-momentdata library.

Standardized Errors

All handled errors in the flybits-momentdata library can be caught by appending a .catch() callback onto any promise and will invoke the callback with an instance of the Flybits.Validation class.

controller.getData().catch(function(validation){
  //handle error
});

The Flybits.Validation class comprises of a state property an errors array containing any and all errors that has been incurred by a library operation, and a type static property holding error code constants. The state property indicates the result of an operation. In the case of a .catch() callback it will always be false.

Each error object found in the errors array will have the properties below:

Below are the internal error code constants found in the static object of Fmd.Validation.type:

Basic Data Consumption

var zmi; //previously fetched ZoneMomentInstance using flybits.js

//pass ZoneMomentInstance model straight into factory method to obtain appropriate controller;
var controller = Fbm.use(zmi);
if(controller){
  controller.getData().then(function(data){
    //consume moment data
    //to determine the type of Moment data in order to render custom UI, access the following properties:
    var momentType = controller.type;
    //this can also be done
    momentType = zmi.moment.iosPkg || zmi.moment.androidPkg;
  });
} else{
  //zmi is not a Moment type that is supported by library;
}

Roadmap

Currently Moment controllers simply retrieve data from a Moment. In the future each Moment type's controller will also have convenience functions for contributing data such as creating events, voting in poll, or even contributing to a shared photo gallery.