Improve documentation and option/argument names

src/imageloader.js

@@ -41,7 +41,7 @@
  * @param {Object} options - Options for this ImageJob.
  * @param {String} [options.src] - URL of image to download.
  * @param {String} [options.loadWithAjax] - Whether to load this image with AJAX.
- * @param {String} [options.headers] - Headers to add to the image request.
+ * @param {String} [options.ajaxHeaders] - Headers to add to the image request if using AJAX.
  * @param {String} [options.crossOriginPolicy] - CORS policy to use for downloads
  * @param {Function} [options.callback] - Called once image has been downloaded.
  * @param {Function} [options.abort] - Called when this image job is aborted.
@@ -93,7 +93,7 @@ ImageJob.prototype = {
             this.request = $.makeAjaxRequest({
                 url: this.src,
                 withCredentials: this.ajaxWithCredentials,
-                headers: this.headers,
+                headers: this.ajaxHeaders,
                 responseType: "arraybuffer",
                 success: function(request) {
                     // Make the raw data into a blob
@@ -174,7 +174,7 @@ $.ImageLoader.prototype = {
      * @param {Object} options - Options for this job.
      * @param {String} [options.src] - URL of image to download.
      * @param {String} [options.loadWithAjax] - Whether to load this image with AJAX.
-     * @param {String} [options.headers] - Headers to add to the image request.
+     * @param {String} [options.ajaxHeaders] - Headers to add to the image request if using AJAX.
      * @param {String|Boolean} [options.crossOriginPolicy] - CORS policy to use for downloads
      * @param {Boolean} [options.ajaxWithCredentials] - Whether to set withCredentials on AJAX
      * requests.
@@ -189,7 +189,7 @@ $.ImageLoader.prototype = {
             jobOptions = {
                 src: options.src,
                 loadWithAjax: options.loadWithAjax,
-                headers: options.loadWithAjax ? options.headers : null,
+                ajaxHeaders: options.loadWithAjax ? options.ajaxHeaders : null,
                 crossOriginPolicy: options.crossOriginPolicy,
                 ajaxWithCredentials: options.ajaxWithCredentials,
                 callback: complete,

src/openseadragon.js

@@ -591,7 +591,7 @@
   *     Whether to load tile data using AJAX requests.
   *     Note that this can be overridden at the {@link OpenSeadragon.TileSource} level.
   *
-  * @property {Object} [ajaxRequestHeaders={}]
+  * @property {Object} [ajaxHeaders={}]
   *     A set of headers to include when making AJAX requests for tile sources or tiles.
   *
   */
@@ -1013,7 +1013,7 @@ function OpenSeadragon( options ){
             crossOriginPolicy:      false,
             ajaxWithCredentials:    false,
             loadTilesWithAjax:      false,
-            ajaxRequestHeaders:     {},
+            ajaxHeaders:            {},
 
             //PAN AND ZOOM SETTINGS AND CONSTRAINTS
             panHorizontal:          true,
@@ -2163,8 +2163,8 @@ function OpenSeadragon( options ){
                 if ( request.readyState == 4 ) {
                     request.onreadystatechange = function(){};
 
-                    // With protocols other than http/https, the status is in [200, 300)
+                    // With protocols other than http/https, a successful request status is in
-                    // on Firefox and 0 on other browsers
+                    // the 200's on Firefox and 0 on other browsers
                     if ( (request.status >= 200 && request.status < 300) ||
                         ( request.status === 0 &&
                           protocol !== "http:" &&

src/tile.js

@@ -48,9 +48,9 @@
  * @param {CanvasRenderingContext2D} context2D The context2D of this tile if it
  * is provided directly by the tile source.
  * @param {Boolean} loadWithAjax Whether this tile image should be loaded with an AJAX request .
- * @param {Object} headers The headers to send with this tile's AJAX request (if applicable).
+ * @param {Object} ajaxHeaders The headers to send with this tile's AJAX request (if applicable).
  */
-$.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, headers) {
+$.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, ajaxHeaders) {
     /**
      * The zoom level this tile belongs to.
      * @member {Number} level
@@ -102,17 +102,17 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, hea
     /**
      * The headers to be used in requesting this tile's image.
      * Only used if loadWithAjax is set to true.
-     * @member {Object} headers
+     * @member {Object} ajaxHeaders
      * @memberof OpenSeadragon.Tile#
      */
-    this.headers = headers;
+    this.ajaxHeaders = ajaxHeaders;
     /**
      * The unique cache key for this tile.
      * @member {String} cacheKey
      * @memberof OpenSeadragon.Tile#
      */
-    if (this.headers) {
+    if (this.ajaxHeaders) {
-        this.cacheKey = this.url + "+" + JSON.stringify(this.headers);
+        this.cacheKey = this.url + "+" + JSON.stringify(this.ajaxHeaders);
     } else {
         this.cacheKey = this.url;
     }

src/tilecache.js

@@ -140,6 +140,7 @@ $.TileCache.prototype = {
      * may temporarily surpass that number, but should eventually come back down to the max specified.
      * @param {Object} options - Tile info.
      * @param {OpenSeadragon.Tile} options.tile - The tile to cache.
+     * @param {String} options.tile.cacheKey - The unique key used to identify this tile in the cache.
      * @param {Image} options.image - The image of the tile to cache.
      * @param {OpenSeadragon.TiledImage} options.tiledImage - The TiledImage that owns that tile.
      * @param {Number} [options.cutoff=0] - If adding this tile goes over the cache max count, this

src/tiledimage.js

@@ -79,7 +79,7 @@
  * @param {Boolean} [options.loadTilesWithAjax]
  *      Whether to load tile data using AJAX requests.
  *      Defaults to the setting in {@link OpenSeadragon.Options}.
- * @param {Object} [options.ajaxRequestHeaders={}]
+ * @param {Object} [options.ajaxHeaders={}]
  *      A set of headers to include when making tile AJAX requests.
  *      Note that these headers will be merged over any headers specified in {@link OpenSeadragon.Options}.
  */
@@ -1309,7 +1309,7 @@ function getTile(
         bounds,
         exists,
         url,
-        headers,
+        ajaxHeaders,
         context2D,
         tile;
 
@@ -1329,13 +1329,13 @@ function getTile(
 
         // Headers are only applicable if loadTilesWithAjax is set
         if (tiledImage.loadTilesWithAjax) {
-            headers = tileSource.getTileHeaders( level, xMod, yMod );
+            ajaxHeaders = tileSource.getTileAjaxHeaders( level, xMod, yMod );
-            // Combine tile headers with global headers (if applicable)
+            // Combine tile AJAX headers with tiled image AJAX headers (if applicable)
-            if ($.isPlainObject(tiledImage.ajaxRequestHeaders)) {
+            if ($.isPlainObject(tiledImage.ajaxHeaders)) {
-                headers = $.extend({}, tiledImage.ajaxRequestHeaders, headers);
+                ajaxHeaders = $.extend({}, tiledImage.ajaxHeaders, ajaxHeaders);
             }
         } else {
-            headers = null;
+            ajaxHeaders = null;
         }
 
         context2D = tileSource.getContext2D ?
@@ -1353,7 +1353,7 @@ function getTile(
             url,
             context2D,
             tiledImage.loadTilesWithAjax,
-            headers
+            ajaxHeaders
         );
     }
 
@@ -1376,7 +1376,7 @@ function loadTile( tiledImage, tile, time ) {
     tiledImage._imageLoader.addJob({
         src: tile.url,
         loadWithAjax: tile.loadWithAjax,
-        headers: tile.headers,
+        ajaxHeaders: tile.ajaxHeaders,
         crossOriginPolicy: tiledImage.crossOriginPolicy,
         ajaxWithCredentials: tiledImage.ajaxWithCredentials,
         callback: function( image, errorMsg, tileRequest ){

src/tilesource.js

@@ -65,7 +65,7 @@
  * @param {Boolean} [options.ajaxWithCredentials]
  *      If this TileSource needs to make an AJAX call, this specifies whether to set
  *      the XHR's withCredentials (for accessing secure data).
- * @param {Object} [options.ajaxRequestHeaders]
+ * @param {Object} [options.ajaxHeaders]
  *      A set of headers to include in AJAX requests.
  * @param {Number} [options.width]
  *      Width of the source image at max resolution in pixels.
@@ -477,7 +477,7 @@ $.TileSource.prototype = {
             $.makeAjaxRequest( {
                 url: url,
                 withCredentials: this.ajaxWithCredentials,
-                headers: this.ajaxRequestHeaders,
+                headers: this.ajaxHeaders,
                 success: function( xhr ) {
                     var data = processResponse( xhr );
                     callback( data );
@@ -588,7 +588,7 @@ $.TileSource.prototype = {
      * @param {Number} y
      * @returns {Object}
      */
-    getTileHeaders: function( level, x, y ) {
+    getTileAjaxHeaders: function( level, x, y ) {
         return {};
     },
 

src/viewer.js

@@ -1236,7 +1236,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @param {Boolean} [options.loadTilesWithAjax]
      *      Whether to load tile data using AJAX requests.
      *      Defaults to the setting in {@link OpenSeadragon.Options}.
-     * @param {Object} [options.ajaxRequestHeaders]
+     * @param {Object} [options.ajaxHeaders]
      *      A set of headers to include when making tile AJAX requests.
      *      Note that these headers will be merged over any headers specified in {@link OpenSeadragon.Options}.
      * requests.
@@ -1284,14 +1284,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         if (options.loadTilesWithAjax === undefined) {
             options.loadTilesWithAjax = this.loadTilesWithAjax;
         }
-        if (options.ajaxRequestHeaders === undefined) {
+        if (options.ajaxHeaders === undefined || options.ajaxHeaders === null) {
-            options.ajaxRequestHeaders = this.ajaxRequestHeaders;
+            options.ajaxHeaders = this.ajaxHeaders;
-        } else if (
+        } else if ($.isPlainObject(options.ajaxHeaders) && $.isPlainObject(this.ajaxHeaders)) {
-            $.isPlainObject(options.ajaxRequestHeaders) &&
+            options.ajaxHeaders = $.extend({}, this.ajaxHeaders, options.ajaxHeaders);
-            $.isPlainObject(this.ajaxRequestHeaders)
-        ) {
-            options.ajaxRequestHeaders = $.extend({},
-                this.ajaxRequestHeaders, options.ajaxRequestHeaders);
         }
 
         var myQueueItem = {
@@ -1409,7 +1405,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     crossOriginPolicy: queueItem.options.crossOriginPolicy,
                     ajaxWithCredentials: queueItem.options.ajaxWithCredentials,
                     loadTilesWithAjax: queueItem.options.loadTilesWithAjax,
-                    ajaxRequestHeaders: queueItem.options.ajaxRequestHeaders,
+                    ajaxHeaders: queueItem.options.ajaxHeaders,
                     debugMode: _this.debugMode
                 });
 
@@ -2182,7 +2178,7 @@ function getTileSourceImplementation( viewer, tileSource, imgOptions, successCal
                 crossOriginPolicy: imgOptions.crossOriginPolicy !== undefined ?
                     imgOptions.crossOriginPolicy : viewer.crossOriginPolicy,
                 ajaxWithCredentials: viewer.ajaxWithCredentials,
-                ajaxRequestHeaders: viewer.ajaxRequestHeaders,
+                ajaxHeaders: viewer.ajaxHeaders,
                 useCanvas: viewer.useCanvas,
                 success: function( event ) {
                     successCallback( event.tileSource );

test/demo/basic.html

@@ -25,8 +25,7 @@
             id: "contentDiv",
             prefixUrl: "../../build/openseadragon/images/",
             tileSources: "../data/testpattern.dzi",
-            showNavigator:true,
+            showNavigator:true
-            ajaxWithCredentials: true
         });
 
     </script>

test/demo/customheaders.html

@@ -15,7 +15,7 @@
 </head>
 <body>
     <p>
-        Demo of how the loadTilesWithAjax and ajaxRequestHeaders options as well as the getTileHeaders() method on TileSource can be applied.
+        Demo of how the loadTilesWithAjax and ajaxHeaders options as well as the getTileHeaders() method on TileSource can be applied.
     </p>
     <p>
         Examine the network requests in your browser developer tools to see the custom headers sent with each request.
@@ -42,7 +42,7 @@
             },
             // This method will send the appropriate range header for this tile based on the data
             // in tileByteRanges.
-            getTileHeaders: function(level, x, y) {
+            getTileAjaxHeaders: function(level, x, y) {
                 return {
                     Range: "bytes=" + tileManifest.tileRanges[level][x][y].join("-") + "/" + tileManifest.totalSize
                 }
@@ -55,8 +55,8 @@
             prefixUrl: "../../build/openseadragon/images/",
             showNavigator: true,
             loadTilesWithAjax: true,
-            ajaxRequestHeaders: {
+            ajaxHeaders: {
-                // Example of using the viewer-level ajaxRequestHeaders option
+                // Example of using the viewer-level ajaxHeaders option
                 // for providing an authentication token.
                 'Authentication': 'Bearer MY_AUTH_TOKEN'
             }
@@ -64,7 +64,7 @@
 
         viewer.addTiledImage({
             // The headers specified here will be combined with those in the Viewer object (if any)
-            ajaxRequestHeaders: {
+            ajaxHeaders: {
                 "X-My-TileSource-Header": "Something"
             },
             tileSource: myCustomTileSource