Merge pull request #422 from andygup/3.0

v3.0

.gitmodules

@@ -1,9 +1,3 @@
-[submodule "vendor/offline"]
- path = vendor/offline
- url = https://github.com/HubSpot/offline.git
-[submodule "vendor/IndexedDBShim"]
- path = vendor/IndexedDBShim
- url = https://github.com/axemclion/IndexedDBShim.git
 [submodule "vendor/jasmine.async"]
  path = vendor/jasmine.async
  url = https://github.com/derickbailey/jasmine.async.git

CHANGELOG.md

@@ -1,5 +1,40 @@
 # offline-editor-js - Changelog
 
+## Version 3.0 - Nov. 23, 2015
+
+Has many breaking changes due to new naming conventions. 
+
+This version adds a new, lightweight (14Kb) editing library aimed at intermittent offline-only workflows. And, there was a significant amount of refactoring aimed at fixing and simplifying the library's naming conventions.
+
+This version implements a consistent naming convention that uses "basic" and "advanced". If `basic` is in the name of the distribution library that means support for intermittent offline-only. `advanced` in the name means support for both intermittent and full offline usage including browser restarts while offline.
+
+In general, migrating from v2.x to 3.x should be a straightforward exercise in simple refactoring of library names. 
+
+**Enhancements**
+* Creates a new `OfflineEditBasic` library. This lightweight (14Kb) library is designed specifically for easy use and intermittent offline-only editing use cases. 
+* Created `offline-edit-basic` and `offline-edit-advanced` for both `src` and `min` versions.
+* Updates documentation, samples and unit tests to reflect the name changes.
+
+**Refactored**
+* `offlineFeaturesManager.js` renamed `OfflineEditAdvanced.js`. No other changes were made to this library.
+* `offlineTilesEnabler.js` renamed `OfflineTilesBasic.js`.
+* `OfflineTilesEnablerLayer.js` renamed `OfflineTilesAdvanced`. No other changes made.
+* `tiles-indexed-db.html` renamed to `simple-tiles.html`.
+* All samples have been updated to reflect the new library names.
+* All test specs have been updated and refactored to reflect the new library names.
+
+**Deprecated**
+* Deprecated `offline-edit-min.js` and `offline-edit-src.js`.
+* In `OfflineEditAdvanced.js` removed deprecated functions `_cleanSuccessfulEditsDatabaseRecords()`, `_internalApplyEdits()`.
+* In `editStore.js` removed deprecated function `resetLimitedPhantomGraphicsQueue()`.
+* In `editStore.js` removed unused functions `_serialize()`, `_deserialize()`.
+* Deleted `/demo/samples` directory.
+* Removed Offline.js and IndexedDBShim from sub-module depencies. You'll need to reference these via their respective CDNs for gh-pages URL.
+
+**Bug Fixes**
+* Minor - `OfflineEditAdvanced` no longer throws an error when reinitialized with a featureCollection.
+
+
 ## Version 2.16 - Oct. 29, 2015
 
 No breaking changes. Recommended update.

Gruntfile.js

@@ -28,8 +28,8 @@ module.exports = function(grunt) {
  'Gruntfile.js',
  'lib/edit/*.js',
  'lib/tiles/base64utils.js',
- 'lib/tiles/OfflineTilesEnabler.js',
- 'lib/tiles/OfflineTilesEnablerLayer.js',
+ 'lib/tiles/OfflineTilesBasic.js',
+ 'lib/tiles/OfflineTilesAdvanced.js',
  'lib/tiles/OfflineTilesNS.js',
  'lib/tiles/TilesCore.js',
  'lib/tiles/TilesStore.js',
@@ -49,19 +49,29 @@ module.exports = function(grunt) {
  '*/\n'
  },
  /* All feature editing capabilities: adds, updates and deletes */
- edit: {
+ editAdvanced: {
  src: [
- 'lib/edit/offlineFeaturesManager.js',
+ 'lib/edit/offlineJSOptions.js',
+ 'lib/edit/OfflineEditAdvanced.js',
  'lib/edit/OfflineEditNS.js',
  'lib/edit/editsStore.js',
  'lib/edit/attachmentsStore.js'
  ],
- dest: 'dist/offline-edit-src.js'
+ dest: 'dist/offline-edit-advanced-src.js'
+ },
+ editBasic: {
+ src: [
+ 'lib/edit/offlineJSOptions.js',
+ 'lib/edit/OfflineEditBasic.js',
+ 'lib/edit/OfflineEditNS.js',
+ 'lib/edit/editStorePOLS.js'
+ ],
+ dest: 'dist/offline-edit-basic-src.js'
  },
  /* Tiles basic is for use with WebMaps. Cannot be reloaded or restarted while offline */
  tilesBasic: {
  src: [
- 'lib/tiles/offlineTilesEnabler.js',
+ 'lib/tiles/OfflineTilesBasic.js',
  'lib/tiles/OfflineTilesNS.js',
  'lib/tiles/base64utils.js',
  'lib/tiles/FileSaver.js',
@@ -74,7 +84,7 @@ module.exports = function(grunt) {
  /* Tiles advanced is for use with tiled map services. Works with reload or restart while offline */
  tilesAdvanced: {
  src: [
- 'lib/tiles/offlineTilesEnablerLayer.js',
+ 'lib/tiles/OfflineTilesAdvanced.js',
  'lib/tiles/OfflineTilesNS.js',
  'lib/tiles/base64utils.js',
  'lib/tiles/FileSaver.js',
@@ -104,6 +114,9 @@ module.exports = function(grunt) {
  compress: {
  drop_console: true //remove console.log statements :)
  },
+ beautify: {
+ semicolons: false //Required: prevents dojo parser errors w/ minified files in this project
+ },
  preserveComments: 'some',
  wrap: false
 // mangle: {
@@ -112,7 +125,8 @@ module.exports = function(grunt) {
  },
  dist: {
  files: {
- 'dist/offline-edit-min.js': ['dist/offline-edit-src.js'],
+ 'dist/offline-edit-advanced-min.js': ['dist/offline-edit-advanced-src.js'],
+ 'dist/offline-edit-basic-min.js': ['dist/offline-edit-basic-src.js'],
  'dist/offline-tiles-basic-min.js': ['dist/offline-tiles-basic-src.js'],
  'dist/offline-tiles-advanced-min.js': ['dist/offline-tiles-advanced-src.js'],
  'dist/offline-tpk-min.js': ['dist/offline-tpk-src.js']

README.md

@@ -1,21 +1,28 @@
 offline-editor-js
 =================
 
-Offline-editor-js is a family of libraries for building offline capabilities into web mapping applications. It's specifically designed to work with the ArcGIS API for JavaScript and ArcGIS Online. It enables you to store feature edits, attachments, map tiles and TPKs (Tile Packages). 
+Offline-editor-js is a family of libraries for building offline capabilities into web mapping applications. It's specifically designed to work with the ArcGIS API for JavaScript and ArcGIS Online. With these libraries you can store feature edits, attachments, map tiles and TPKs (Tile Packages). 
+
+***IMPORTANT:*** If you need a fully integrated, robust offline solution then you should be using our native ArcGIS Runtime SDKs for .NET, WPF, Java, iOS, Android and Qt.
+
+# Getting Started
 
 Online samples and getting started tutorials are available here: **[http://esri.github.io/offline-editor-js/demo/](http://esri.github.io/offline-editor-js/demo/)**
 
-*IMPORTANT:* If you need a fully integrated, robust offline solution then you should be using our native ArcGIS Runtime SDKs for .NET, WPF, Java, iOS, Android and Qt.
 
-This repo contains the following libraries:
+# Libraries
+
+This repo contains the following libraries in the `/dist` directory. The use of `basic` in the name indicates intermittent offline-only, and `advanced` indicates the library can be used for both intermittent and full offline.
+
+Use_Case | Name, Description and gh-pages URL
+--- | ---
+Basic editing | **`offline-edit-basic-min.js`** Simple, lightweight *(14k minimized)* offline editing library that automatically caches adds, updates and deletes when the internet is temporarily interrupted.<br><br>[`http://esri.github.io/offline-editor-js/dist/offline-edit-basic-min.js`](http://esri.github.io/offline-editor-js/dist/offline-edit-basic-min.js)
+Advanced editing | **`offline-edit-advanced-min.js`** Used for intermittent and full offline editing workflows. Also includes limited support for attachments. <br><br>[`http://esri.github.io/offline-editor-js/dist/offline-edit-advanced-min.js`](http://esri.github.io/offline-editor-js/dist/offline-edit-advanced-min.js)
+Basic map tiles | **`offline-tiles-basic-min.js`** Caches map tiles for simple, intermittent-only offline workflows. Use this library with ArcGIS Online Web maps as well as with tiled map services.<br><br> [`http://esri.github.io/offline-editor-js/dist/offline-tiles-basic-min.js`](http://esri.github.io/offline-editor-js/dist/offline-tiles-basic-min.js) 
+Advanced map tiles | **`offline-tiles-advanced-min.js`** Used for intermittent and full offline tile caching. Extends any ArcGIS Tiled Map Service. This library should be used in conjunction with an HTML5 Application Cache Manifest coding pattern.<br><br>[`http://esri.github.io/offline-editor-js/dist/offline-tiles-advanced-min.js`](http://esri.github.io/offline-editor-js/dist/offline-tiles-advanced-min.js)
+TPK files | **`offline-tpk-min.js`** Reads TPK files and displays and caches them as a tiled map layer.<br><br>[`http://esri.github.io/offline-editor-js/dist/offline-tpk-min.js`](http://esri.github.io/offline-editor-js/dist/offline-tpk-min.js)
 
-- `/dist` - contains src and min versions of each library: 
- * `offline-edit-min.js` - stores adds, updates and deletes of features as well as limited attachment support while offline. Resync's edits with server once connection is reestablished.
- * `offline-tiles-basic-min.js` - caches map tiles for partial offline use cases. Use this library with ArcGIS Online Web maps as well as with tiled map services. This repo will not work with browser restarts or reloads while offline. 
- * `offline-tiles-advanced-min.js` - Extends any ArcGIS Tiled Map Service that has a requirement for offline browser reload and/or restart. This library should be used in conjunction with an HTML5 application cache coding pattern.
- * `offline-tpk-min.js` - parses a TPK file and displays it as a tiled map layer.
-- `/utils`: contains various helper library modules. These modules are all AMD compliant.
-- `/samples`: samples that show how to use the different offline libraries capabilities.
+`src` files are for software development-only. The`min` versions are minified and should be used in production. 
 
 #Workflows Supported
 The following workflow is currently supported for both both features and tiles:
@@ -63,6 +70,7 @@ Go __[here](https://github.com/Esri/offline-editor-js/wiki/FAQ)__ for answers to
 ##Limitations
 
 * Currently does not support related tables, domains or subtypes. The ArcGIS Runtime SDKs fully support these and more.
+* There are browser limitations and technical dependencies. The offline capabilities in this toolkit depend on certain JavaScript capabilities being present in the browser. Go [here](doc/dependencies.md) for a detailed breakdown.
 * Attachments are supported with some limitations listed [here](./doc/attachments.md).
 * Browser storage space on mobile devices is a known limitation. This applies to stand-alone web applications and hybrid applications.
 
@@ -72,17 +80,15 @@ Go __[here](https://github.com/Esri/offline-editor-js/wiki/FAQ)__ for answers to
 
 ##Dependencies
 
-* ArcGIS API for JavaScript (v3.12+)
+* [ArcGIS API for JavaScript (v3.12+)](https://developers.arcgis.com/javascript/)
+* [Offline.js](http://github.hubspot.com/offline/docs/welcome/) - it allows detection of the online/offline condition and provides events to hook callbacks on when this condition changes
 * Node.js required for building the source
-* NOTE: browser limitations and technical dependencies. The offline capabilities in this toolkit depend on certain HTML5 capabilities being present in the browser. Go [here](doc/dependencies.md) for a detailed breakdown of the information.
+* [IndexedDBShim](https://github.com/axemclion/IndexedDBShim) - polyfill to simulate indexedDB functionality in browsers/platforms where it is not supported notably older versions desktop Safari and iOS Safari.
 * Sub-modules (see `/vendor` directory)
 
- * [offline.js](https://github.com/hubspot/offline) - it allows detection of the online/offline condition and provides events to hook callbacks on when this condition changes
- * [IndexedDBShim](https://github.com/axemclion/IndexedDBShim) - polyfill to simulate indexedDB functionality in browsers/platforms where it is not supported (notably desktop Safari and iOS Safari)
- - IMPORTANT: There are known [issues](https://github.com/axemclion/IndexedDBShim/issues/115) with IndexedDBShim on Safari. For Safari, the storage error workaround is to switch from using /dist/IndexedDBShim.min.js to just using IndexedDBShim.js and then search for and modify the line that defines the value for `DEFAULT_DB_SIZE`. Set this to more appropriate size that will meet all your storage needs, for example: ```var DEFAULT_DB_SIZE = 24 * 1024 * 1024```
- * [jasmine.async](https://github.com/derickbailey/jasmine.async.git) - library to help implementing tests of async functionality (used in tests)
+ * [jasmine.async](https://github.com/derickbailey/jasmine.async.git) - Used specifically for unit testing.
 
-* Non sub-module based libraries
+* Non sub-module based libraries that are used internally by this project
  * [FileSaver.js](https://github.com/Esri/offline-editor-js/blob/master/lib/tiles/README.md) - library to assist with uploading and downloading of files containing tile information.
  * [grunt-manifest](https://github.com/gunta/grunt-manifest) node.js library to assist with the creation of manifest files.
  * [zip](http://gildas-lormeau.github.io/zip.js/) A library for zipping and unzipping files.