From c58dfe0a2dba73db5bdf66e18ae9b11ff4b2b7fa Mon Sep 17 00:00:00 2001 From: Andy Gup Date: Thu, 18 Jun 2015 14:03:11 -0600 Subject: [PATCH] update how to use tiles --- doc/howtousetiles.md | 53 ++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/doc/howtousetiles.md b/doc/howtousetiles.md index 7dde9ce..9d43692 100644 --- a/doc/howtousetiles.md +++ b/doc/howtousetiles.md @@ -5,14 +5,16 @@ How to use the tiles library The `tiles` library allows a developer to extend a tiled layer with offline support. -There are two approaches to using this set of libraries. The first approach is if you are using an ArcGIS.com Web Map, and the second approach is if you need to be able to restart or reload your application offline. +There are two primary approaches to using this set of libraries. The first approaches is for intermittent offline use cases where you only expect occasional and temporary internet outages and you don't need to worry about restarting the application while offline. The first approach works with both an `ArcGISTiledMapServiceLayer` and ArcGIS.com Web maps. -You should also be aware that there are storage limitations imposed by the browser and the device operating system. +The second approach is if you need to be able to restart or reload your application offline and only works with `ArcGISTiledMapServiceLayer`. + +You should also be aware that there are storage limitations imposed by the browser and the device operating system. There is a brief discussion on this at the bottom of the document. -## Approach 1 - ArcGIS.com Map +## Approach 1 - ArcGIS.com or tiled Map -Approach #1 is best for partial offline use cases and it uses the `offline-tiles-basic-min.js` library. This approach will not allow you to reload or restart the application while offline. +Approach #1 is for intermittent offline use cases and it uses the `offline-tiles-basic-min.js` library. This approach will not allow you to reload or restart the application while offline. The `tiles-indexed-db.html` sample is a working example of how to implement offline patterns and practices with an ArcGIS.com basemap. **Step 1** Include the `offline-tiles-basic-min.js` library in your app. @@ -25,7 +27,7 @@ Approach #1 is best for partial offline use cases and it uses the `offline-tiles ... }); ``` -**Step 2** Once your map is created (either using _new Map()_ or using _esriUtils.createMap(webmapid,...)_, you extend the basemap layer with the offline functionality +**Step 2** Once your map is created using either _new Map()_ or using _esriUtils.createMap(webmapid,...)_, then extend the basemap layer with the offline functionality ```js var basemapLayer = map.getLayer( map.layerIds[0] ); @@ -39,20 +41,8 @@ Approach #1 is best for partial offline use cases and it uses the `offline-tiles } }); ``` -**Step 3** Use the new offline methods on the layer to prepare for offline mode while still online: +**Step 3** This will enable new offline methods on the layer to prepare for offline mode while still online: -####basemap.getLevelEstimation(extent, level, tileSize) -Returns an object that contains the number of tiles that would need to be downloaded for the specified extent and zoom level, and the estimated byte size of such tiles. This method is useful to give the user an indication of the required time and space before launching the actual download operation: - -```js - { - level: /* level number */ - tileCount: /* count of tiles */ - sizeBytes: /* total size of tiles */ - } - -**NOTE**: The byte size estimation is very rough. -``` ####basemap.prepareForOffline(minLevel,maxLevel,extent,reportProgress) * Integer minLevel @@ -71,8 +61,9 @@ For each downloaded tile it will call the reportProgress() callback. It will pas error: /* if some error has happened, it contains an error object with cell and msg fields, otherwise it is undefined */ finishedDownloading: /* boolean that informs if this is the last cell */ cancelRequested: /* boolean that informs if the operation has been cancelled at user's request */ - } + } ``` + **NOTE:** The reportProgress() callback function should return `true` if the download operation can be cancelled or `false` if it doesn't need to be. You can also add a buffer around the view's extent: @@ -87,6 +78,12 @@ basemapLayer.prepareForOffline(minLevel, maxLevel, newExtent, lang.hitch(self,self.reportProgress)); ``` +####basemap.goOnline() +This method puts the layer in online mode. When in online mode, the layer will behave as regular layers, fetching all tiles from the remote server. If there is no internet connectivity the tiles may appear thanks to the browsers cache, but no attempt will be made to look up tiles in the local database. + +####basemap.goOffline() +This method puts the layer in offline mode. When in offline mode, the layer will not fetch any tile from the remote server. It will look up the tiles in the IndexedDB database and display them in the layer. If the tile can't be found in the local database it will show up blank (even if there is actual connectivity). The pair of methods `goOffline()` and `goOnline()` allows the developer to manually control the behaviour of the layer. Used in conjunction with the offline dectection library, you can put the layer in the appropriate mode when the offline condition changes. + ####basemap.deleteAllTiles(callback) Deletes all tiles stored in the indexed db database. The callback is called to indicate success (true) or failure (false,err) @@ -116,10 +113,24 @@ It calculates the geographic boundary of each of the tiles stored in the indexed } } ``` +####basemap.getLevelEstimation(extent, level, tileSize) +Returns an object that contains the number of tiles that would need to be downloaded for the specified extent and zoom level, and the estimated byte size of such tiles. This method is useful to give the user an indication of the required time and space before launching the actual download operation: -## Approach #2 - Tiled Map Services +```js + { + level: /* level number */ + tileCount: /* count of tiles */ + sizeBytes: /* total size of tiles */ + } + +**NOTE**: The byte size estimation is very rough. +``` -This approach is best if you have requirements for restarting or reloading your browser application while offline. For this approach use the `offline-tiles-advanced-min.js` library. This library extends TileMapServiceLayer and you can use it with any Esri tiled basemap layer. +## Approach #2 - Tiled Map Services (Full Offline) + +This approach is best if you have requirements for restarting or reloading your browser application while offline. For this approach use the `offline-tiles-advanced-min.js` library. This library extends TileMapServiceLayer and you can use it with any Esri tiled basemap layer. You will not be able to use an ArcGIS.com Web map for this approach. + +**NOTE:** This approach requires the use of an [Application Cache](https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache) to store the application's HTML, CSS, and JavaScript. See the `appcache-tiles.html` sample for a working example of how to configure an application for this scenario. **Step 1** Include the `offline-tiles-advanced-min.js` library in your app.