274 lines
10 KiB
Markdown
274 lines
10 KiB
Markdown
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,dss
|
||
* Caching backends: localStorage,webSqlDB,sqllite,none
|
||
* Multi server/version support by url question ui.
|
||
* Progress indicator ui.
|
||
* Loader error ui.
|
||
* No external dependencies.
|
||
* Technology agnostic booting.
|
||
|
||
## Todo
|
||
|
||
* Make cordova example work again
|
||
* Make tests work again
|
||
* Add instance websql options so it can also be used in application code.
|
||
* Split assets per type so do js first then boot then css + dss.
|
||
* Add more tests
|
||
* css: set tag.media = 'only you';
|
||
* css: add media in resouces
|
||
* Add in browser tests
|
||
* cache limits for soft fallback to injecting ?
|
||
|
||
## 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'; // or window.location.href;
|
||
FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
|
||
FFSpaLoader.start();
|
||
|
||
## Assets format
|
||
|
||
{
|
||
"data": {
|
||
"resources": [
|
||
{
|
||
"url": "/static/js/some-asset.js",
|
||
"type": "js",
|
||
"hash": -164319899
|
||
},
|
||
{
|
||
"url": "/static/css/some-asset.css",
|
||
"type": "css",
|
||
"hash": 1391550981
|
||
},
|
||
{
|
||
"url": "/static/css/more-asset-data.css",
|
||
"type": "dss",
|
||
"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;
|
||
|
||
* boot.debug.enable = Enable debug output. (default: false)
|
||
* boot.debug.handler = Prints/log debug message. (default: console.log)
|
||
* boot.debug.prefix = Debug message prefix. (default: 'FFSpaLoader.')
|
||
* boot.error.enable = Enables the ui error handler. (default: true)
|
||
* boot.error.title = The error title. (default: 'Loader ');
|
||
* boot.cleanup.enable = Auto cleanup the loader html tags. (default: true)
|
||
* boot.cleanup.timeout = Cleanup after timeout(in ms) so css effects are done. (default: 1000)
|
||
* boot.cleanup.tags = The array of tag ids to remove. (default: empty)
|
||
* server.url = The server url like 'https://myhost', when null the user will get promted to input it. (default: null)
|
||
* server.depath = Strip this path from the server.url needed when the ui has prefix from application root.
|
||
* 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.header.request = An key value object with the request headers. (default: {'X-FFSpaLoader': 'sync'})
|
||
* server.header.response = An key value object with the required response headers. (default: {})
|
||
* question.transport = The transport to prefix the server.url with. (default: 'http://')
|
||
* question.title = The question ui title. (default: 'Server')
|
||
* question.submit = The start button text. (default: 'Start')
|
||
* question.text = The question ui text. (default: 'Please provide the server name;')
|
||
* question.size = The question ui input size. (default: 32)
|
||
* question.validate.min.value = The minimal hostname length, false is disabled (default: 3)
|
||
* question.validate.min.message = The error message (default: 'Server name is to short.')
|
||
* question.validate.max.value = The maximal hostname length, false is disabled (default: 255)
|
||
* question.validate.max.message =The error message (default: 'Server name is to long.')
|
||
* question.validate.regex.value = The regex to validate the hostname, false is disabled. (default: '^([a-zA-Z0-9\.\:])*$')
|
||
* question.validate.regex.message = The error message (default: 'Server name is invalid.')
|
||
* loader.title = The loader title (default: 'Loading Application')
|
||
* loader.footer = The loader footer (default: '© FFSpaLoader')
|
||
* loader.await = The timeout in ms before the loader displays. (default: 250)
|
||
* loader.progres.items.enable = Enables the per item progres. (default: true)
|
||
* loader.progres.items.size = Shorten longer urls to this size. (default: 50)
|
||
* loader.progres.bar.enable = Enables the progres bar. (default: true)
|
||
* loader.progres.bar.percentage = Print percentage's in bar. (default: true)
|
||
* cache.meta = The cache backend for the meta information(server.url+content), null is auto select,false is disable. (default: null)
|
||
* cache.js = The cache backend for for js, null is auto select,false is disable. (default: null)
|
||
* cache.css = The cache backend for for css, null is auto select,false is disable. (default: null)
|
||
* cache.dss = The cache backend for for dss, null is auto select,false is disable. (default: null)
|
||
|
||
## Functions
|
||
|
||
The functions in FFSpaLoader.*;
|
||
|
||
* start(cb) = Starts loading your application, optional function argument can be used for done and/or error callback.
|
||
* clearServerUrl(cb) = Clears the cached server url so after reload user get promted again.
|
||
* clearCache(cb) = Clears the cached values so after reload all assets get refetched.
|
||
|
||
## 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.
|
||
* cache.localStorage() = Creates an localStorage service.
|
||
* cache.websql(opt) = Creates an websql service.
|
||
|
||
## Cache Types
|
||
|
||
The cache types in FFSpaLoader.options.cache.* store different types data;
|
||
|
||
* meta = Stores the server url and server assets.
|
||
* js = Store application javascript data.
|
||
* css = Stores application css data.
|
||
* dss = Stores application css large data like base64 fonts/svg/etc.
|
||
|
||
## Cache Config
|
||
|
||
Per default all cache types are auto selected in the following order;
|
||
|
||
* detect.sqlitePlugin()
|
||
* detect.openDatabase()
|
||
* detect.localStorage()
|
||
* none
|
||
|
||
More custom schemas are possible like; (todo: needs testing)
|
||
|
||
FFSpaLoader.options.cache.meta = false;
|
||
FFSpaLoader.options.cache.js = false;
|
||
FFSpaLoader.options.cache.css = false;
|
||
FFSpaLoader.options.cache.dss = false;
|
||
|
||
if (FFSpaLoader.factory.detect.localStorage()) {
|
||
FFSpaLoader.options.cache.css = FFSpaLoader.factory.cache.localStorage();
|
||
FFSpaLoader.options.cache.dss = FFSpaLoader.factory.cache.localStorage();
|
||
}
|
||
FFSpaLoader.options.server.url = 'http://myserver';
|
||
FFSpaLoader.options.server.assets = '/api/path/to/spa/client/resources';
|
||
FFSpaLoader.start();
|
||
|
||
|
||
## Example Application
|
||
|
||
There is a nodejs example application in the example folder;
|
||
|
||
* git clone https://bitbucket.org/immetoo/es5-ff-spa-loader.git
|
||
* cd es5-ff-spa-loader
|
||
* npm install
|
||
* npm start
|
||
|
||
For the mobile example install+build steps are;
|
||
|
||
* export ANDROID_HOME=/my/android-sdk/path
|
||
* npm install cordova -g
|
||
* cd es5-ff-spa-loader
|
||
* cd example
|
||
* cd app_mobile
|
||
* cordova platform add android
|
||
* cordova build
|
||
|
||
## Tested Browsers
|
||
|
||
* Chromium 46
|
||
* Iceweasel 43
|
||
* Firefox Aurora 45
|
||
* Opera 12 Presto
|
||
* IE 11 Edge
|
||
* Android 5.1.1 in Cordova + Site
|
||
* Android 4.4.4 in Cordova + Site
|
||
* Android 4.2.2 in Cordova + Site
|
||
|
||
## 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.3.1
|
||
* Removed cordova support
|
||
* Removed AngularJS support
|
||
|
||
### 0.3.0
|
||
* Fixed clearServerUrl() to also clean the cached server resources json.
|
||
* Auto clean option.server.url from # and ? endings for: FFSpaLoader.options.server.url = window.location.href;
|
||
* Added server.depath option to strip the ui-prefix from the server.url.
|
||
* Added auto resetting server.url when is file:// for "Page save as" feature.
|
||
* Fixed askUrl to accept host and context path with auto clean/depathing.
|
||
* Fixed duplicate starts on askUrl submit multiple clicks.
|
||
* Switch to karma + jasmine unit tests.
|
||
* Fixed define.amd module constructor.
|
||
* Integrated example package.json to main file.
|
||
* Removed options.error.[handler|title].
|
||
* Added options.boot.error.[enable|title].
|
||
* start(cb) function callback now includes error.
|
||
* Moved options.debug.* to options.boot.debug.*.
|
||
* Fixed example page/app offline use. (safe page as(html only))
|
||
|
||
### 0.2.1
|
||
* Fixed clearCache method to added json header.
|
||
* Added url to non 200 http status error message.
|
||
* Added boot.cleanup.tags options.
|
||
|
||
### 0.2.0
|
||
* Moved error.style and question.style to css file.
|
||
* Changed dist with extra css/js folder.
|
||
* Added loader progress bar.
|
||
* refined css so question/loader/error are equal.
|
||
* Added response header check support.
|
||
* Added json accept header on assets resources list.
|
||
* Added cb errors on assets resources json parse + result obj.
|
||
* Renamed cssData type to dss for enum easiness.
|
||
* Added unknown resource type error.
|
||
|
||
### 0.1.1
|
||
* Moved websql delete timeout to cleanServerlUrl for faster boot.
|
||
* Fixed websql db-size and db-name for older androids.
|
||
* Added more jsdoc.
|
||
* Added question.size option.
|
||
* Changed websql option openDatabase to returning open function.
|
||
* Fixed sqlitePlugin open function was 2x typo on openDatabase.
|
||
* Added websql table option. (defaults to 'cache_store')
|
||
* Added clearCache function.
|
||
* Fixed removed question div on loader error.
|
||
* Updated example and removed it from npm.
|
||
* Added cordova app with example.
|
||
|
||
### 0.1.0
|
||
* Moved options.server.question to options.question.
|
||
* Added question.validate.[min|max|regex].value|message options.
|
||
* Strip question value to hostname+port before use and validating.
|
||
* Allow user upgrade to https in question input from default of transport option.
|
||
* Added server request headers option.
|
||
* Updated css of question and error ui.
|
||
* Fixed cordova booting.
|
||
|
||
### 0.0.4
|
||
* Added auto cache clean code.
|
||
* Disable cordova timeout per default.
|
||
* Remove unused mobileAgent detect.
|
||
* Fixed cached resources injection order.
|
||
|
||
### 0.0.3
|
||
* Fixed example script path.
|
||
* Fixed example size.
|
||
* Initial release.
|