es5-ff-spa-loader/README.md

es5-ff-spa-loader
=========

A javascript library providing server defined loading of assets for a single page application.

## Installation

  npm --save install es5-ff-spa-loader

  Then use the dist/es5-ff-spa-loader.min.js script inline in the index.

## Features

 * Assets caching for offline use.
 * Assets hashing for fast syncing.
 * Assets types: js,css,cssData
 * Caching backends: null,localStorage,webSqlDB,sqllite
 * Server url question ui.
 * Loader error ui. 
 * Build-in Cordova booting.
 * Build-in AngularJS booting.

## Usage

### Usage Multi Server (Minimal)

	FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
	FFSpaLoader.start();

### Usage Single Server

	FFSpaLoader.options.server.url = 'http://myserver';
	FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
	FFSpaLoader.start();

### Usage Angular

	FFSpaLoader.options.debug.enable = true;
	FFSpaLoader.options.boot.angular.modules.push('exampleUI');
	FFSpaLoader.options.server.url = 'http://myserver';
	FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
	FFSpaLoader.start(function() {
		console.log('FFExample.boot done');
	}); 

## Assets format

	{
		"data": {
			"resources": [
			{
				"url": "/static/js/assets.js",
				"type": "js",
				"hash": ​-164319899
			},
			{
				"url": "/static/css/assets.css",
				"type": "css",
				"hash": ​1391550981
			},
			{
				"url": "/static/css/assets-data.css",
				"type": "cssData",
				"hash": ​1371811412
			},
        ]
    }

  The hash key is required as only on hash change the resource will be downloaded again, so multiple small files makes updates faster.


## Options

  The available FFSpaLoader.options.* values;

 * debug.enable = Enable debug output. (default: false)
 * debug.handler = Prints/log debug message. (default: console.log)
 * debug.prefix = Debug message prefix. (default: 'FFSpaLoader.')
 * error.handler = The error handler. (default: internal error handler ui)
 * error.title = The error title. (default: 'Loader Error');
 * error.style = The error ui css style. (default: red border box)
 * boot.cordova.enable = Use deviceready event to boot when cordova is detected. (default: true)
 * boot.cordova.timeout = Boot after (if<0=no-)timeout when deviceready event is not received. (default: -1)
 * boot.cordova.flag = The window flag which is set when cordova is booted. (default: 'FFCordovaDevice')
 * boot.angular.enable = Auto bootstrap angular modules. (default: true)
 * boot.angular.modules = The angular modules to boot. (default: empty)
 * server.url = The server url like 'https://myhost', when null the user will get promted to input it. (default: null)
 * server.assets = The server path to the assets resources definition file, is required (default: null)
 * server.timeout = The timeout to download the server resources. (default: 4096)
 * server.flag = The window flag which is set when the server.url is know. (default: 'FFServerUrl')
 * server.question.transport = The transport to prefix the server.url with. (default: 'http://')
 * server.question.title = The question ui title. (default: 'Server')
 * server.question.text = The question ui text. (default: 'Please provide the server name;')
 * server.question.style = The question ui css style.(note: pending change) (default: green border box)
 * cache.meta = The cache backend for the meta information, null is auto select. (default: null)
 * cache.js = The cache backend for for js, null is auto select. (default: null)
 * cache.css = The cache backend for for css, null is auto select. (default: null)
 * cache.cssData = The cache backend for for cssData, null is auto select. (default: null)


## Factory

  The available FFSpaLoader.factory.* functions;

 * detect.localStorage() = Checks is localStorage is working.
 * detect.openDatabase() = Checks if openDatabase is defined.
 * detect.sqlitePlugin() = Checks if sqlitePlugin is defined.
 * detect.cordova() = Checks if cordova is defined.
 * detect.cordovaDevice() = Checks if cordovaDevive window flag is defined which will be set by the buildin cordova boot code.
 * cache.localStorage() = Creates an localStorage service.
 * cache.websql(opt) = Creates an websql service.

## Cache Config

  Per default all cache type as in auto select mode which detect and used the following;
  
 * sqlitePlugin
 * openDatabase
 * localStorage
 * none
  
  More custom schemas are possible like; (todo: needs testing)
  
	FFSpaLoader.options.cache.meta = null; // use auto -> TODO: currently other cached need meta needs fixing.
	FFSpaLoader.options.cache.js = false;
	FFSpaLoader.options.cache.css = false;
	FFSpaLoader.options.cache.cssData = false; 
	
	if (FFSpaLoader.factory.detect.localStorage()) {
		FFSpaLoader.options.cache.css = FFSpaLoader.factory.cache.localStorage;
		FFSpaLoader.options.cache.cssData = FFSpaLoader.factory.cache.localStorage;
	} 
	FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
	FFSpaLoader.start();
  

## Example Application

  There is a fully working nodejs example application in the example folder.

## Tested Browsers

 * Chromium	46
 * Iceweasel 43
 * Opera 12 Presto
 * Android 5 in Cordova

## Todo

 * Auto cache cleanup code. (!! required before production !!)
 * test in production
 * Server header set+check support
 * Redo css(?divs) of server question
 * Add table+instance websql options so it can also be used in application code.
 * Add more tests
 * css: set tag.media = 'only you';
 * css: add media in resouces
 * Add in browser tests 
  
## Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style.
Add unit tests for any new or changed functionality. Lint and test your code.

## Release History 

### 0.0.4
* Disable cordova timeout per default.
* Remove unused mobileAgent detect.


### 0.0.3
* Fixed example script path.

### 0.0.2
* Fixed example size.

### 0.0.1
* Initial release.