offline-editor-js/doc/howtousetiles.md

How to use the tiles library

##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.

Approach 1 - ArcGIS.com 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.

Step 1 Include the offline-tiles-basic-min.js library in your app.

	require([
		"esri/map", 
		"..dist/offline-tiles-basic-min.js"], 
		function(Map)
	{
		...
	});

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

	var basemapLayer = map.getLayer( map.layerIds[0] );
	var offlineTilesEnabler = new esri.OfflineTilesEnabler();
	offlineTilesEnabler.extend(basemapLayer, function(success)
	{
		if(success)	{
			// Now we can use offline functionality on this layer 
		} else {
			alert('indexed db is not supported in this browser');
		}
	});

Step 3 Use the 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:

	{
		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
• Integer maxLevel
• Extent extent
• callback reportProgress(Object progress)

This method starts the process of downloading and storing in local storage all tiles within the specified extent.

For each downloaded tile it will call the reportProgress() callback. It will pass an object with the following fields

	{
		countNow: /* current count of downloaded tiles */
		countMax: /* number of total tiles that need to be downloaded */
		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:

var minLevel = 0;
var maxLevel = 16;
var extent = someFeature.geometry.getExtent();
var buffer = 1500; /* approx meters (webmercator units) */
var newExtent = basmapLayer.getExtentBuffer(buffer,extent);
basemapLayer.prepareForOffline(minLevel, maxLevel, newExtent,
   lang.hitch(self,self.reportProgress));

####basemap.deleteAllTiles(callback) Deletes all tiles stored in the indexed db database. The callback is called to indicate success (true) or failure (false,err)

####basemap.getOfflineUsage(callback) It calculates the number of tiles that are stored in the indexed db database and the space used by them. The callback is called with an object containing the result of this calculation:

	{
		tileCount: /* count of tiles */
		size: /* total size of tiles */	
	}

####basemap.getTilePolygons(callback) It calculates the geographic boundary of each of the tiles stored in the indexed db. This method calls the callback once for each tile, passing an esri/geometry/Polygon that can be added to a GraphicsLayer. This method is useful to show graphically which tiles are stored in the local database, like this:

	graphics = new GraphicsLayer();
	map.addLayer( graphics );
	basemapLayer.getTilePolygons(function(polygon,err)
	{
		if(polygon) {
			var graphic = new Graphic(polygon, symbol);
			graphics.add(graphic);
		} else {
			console.log("showStoredTiles: ", err);
		}
	}

Approach #2 - Tiled Map Services

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.

Step 1 Include the offline-tiles-advanced-min.js library in your app.

	require([
		"esri/map", 
		"..dist/offline-tiles-advanced-min.js"], 
		function(Map)
	{
		...
	});

Step 2 Create a new instance of OfflineTilesEnablerLayer. Note, when you instantiate the Map leave off the basemap property because we are adding a customer tile layer as our basemap. OfflineTilesEnablerLayer has three properties in the constructor. The first is the REST endpoint of the basemap you want to use, the second is the callback and the last is an optional parameter to preset the layer as online or offline. This will help with with drawing tiles correctly during offline restarts or reloads.

    tileLayer = new esri.OfflineTilesEnablerLayer("http://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer",function(evt){
        console.log("Tile Layer Loaded.");
    },_isOnline);

    var map = new Map("map",{
        center: [-104.98,39.74], // long, lat
        zoom: 8,
        sliderStyle: "small"
    });

    map.addLayer(tileLayer);

All map events will continue to work normally. Although some methods that are typically available will now have to be accessed through OfflineTilesEnablerLayer such as getLevel(), getMaxZoom(), and getMinZoom().

To get the current extent you will need to monitor the zoom-end and pan-end events like this:

    map.on("zoom-end",function(evt){
        _currentExtent = evt.extent;
    });

    map.on("pan-end",function(evt){
       _currentExtent = evt.extent;
    });