From 15fe35a5893c1bdbbf16b90ac0fbc5230a094ed3 Mon Sep 17 00:00:00 2001 From: Sean Nichols Date: Tue, 8 Nov 2016 12:27:30 -0500 Subject: [PATCH] Improve documentation and option/argument names --- src/imageloader.js | 8 ++++---- src/openseadragon.js | 8 ++++---- src/tile.js | 14 +++++++------- src/tilecache.js | 1 + src/tiledimage.js | 18 +++++++++--------- src/tilesource.js | 6 +++--- src/viewer.js | 18 +++++++----------- test/demo/basic.html | 3 +-- test/demo/customheaders.html | 10 +++++----- 9 files changed, 41 insertions(+), 45 deletions(-) diff --git a/src/imageloader.js b/src/imageloader.js index 60f3ba2a..83676af0 100644 --- a/src/imageloader.js +++ b/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, diff --git a/src/openseadragon.js b/src/openseadragon.js index 59f2ffac..a5116963 100644 --- a/src/openseadragon.js +++ b/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) - // on Firefox and 0 on other browsers + // With protocols other than http/https, a successful request status is in + // the 200's on Firefox and 0 on other browsers if ( (request.status >= 200 && request.status < 300) || ( request.status === 0 && protocol !== "http:" && diff --git a/src/tile.js b/src/tile.js index 2dd2b95e..61ba2e64 100644 --- a/src/tile.js +++ b/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 @@ -94,7 +94,7 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, hea */ this.context2D = context2D; /** - * Whether to load this tile's image with an AJAX request. + * Whether to load this tile's image with an AJAX request. * @member {Boolean} loadWithAjax * @memberof OpenSeadragon.Tile# */ @@ -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) { - this.cacheKey = this.url + "+" + JSON.stringify(this.headers); + if (this.ajaxHeaders) { + this.cacheKey = this.url + "+" + JSON.stringify(this.ajaxHeaders); } else { this.cacheKey = this.url; } diff --git a/src/tilecache.js b/src/tilecache.js index 6300427f..05d4e9cd 100644 --- a/src/tilecache.js +++ b/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 diff --git a/src/tiledimage.js b/src/tiledimage.js index 21b9c05c..f9b311cc 100644 --- a/src/tiledimage.js +++ b/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 ); - // Combine tile headers with global headers (if applicable) - if ($.isPlainObject(tiledImage.ajaxRequestHeaders)) { - headers = $.extend({}, tiledImage.ajaxRequestHeaders, headers); + ajaxHeaders = tileSource.getTileAjaxHeaders( level, xMod, yMod ); + // Combine tile AJAX headers with tiled image AJAX headers (if applicable) + if ($.isPlainObject(tiledImage.ajaxHeaders)) { + 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 ){ diff --git a/src/tilesource.js b/src/tilesource.js index 5f058fe9..66bb10ac 100644 --- a/src/tilesource.js +++ b/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 {}; }, diff --git a/src/viewer.js b/src/viewer.js index 6117d572..a5b3104f 100644 --- a/src/viewer.js +++ b/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) { - options.ajaxRequestHeaders = this.ajaxRequestHeaders; - } else if ( - $.isPlainObject(options.ajaxRequestHeaders) && - $.isPlainObject(this.ajaxRequestHeaders) - ) { - options.ajaxRequestHeaders = $.extend({}, - this.ajaxRequestHeaders, options.ajaxRequestHeaders); + if (options.ajaxHeaders === undefined || options.ajaxHeaders === null) { + options.ajaxHeaders = this.ajaxHeaders; + } else if ($.isPlainObject(options.ajaxHeaders) && $.isPlainObject(this.ajaxHeaders)) { + options.ajaxHeaders = $.extend({}, this.ajaxHeaders, options.ajaxHeaders); } 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 ); diff --git a/test/demo/basic.html b/test/demo/basic.html index 2b9481e7..e238e5e1 100644 --- a/test/demo/basic.html +++ b/test/demo/basic.html @@ -25,8 +25,7 @@ id: "contentDiv", prefixUrl: "../../build/openseadragon/images/", tileSources: "../data/testpattern.dzi", - showNavigator:true, - ajaxWithCredentials: true + showNavigator:true }); diff --git a/test/demo/customheaders.html b/test/demo/customheaders.html index bc43263a..4937b231 100644 --- a/test/demo/customheaders.html +++ b/test/demo/customheaders.html @@ -15,7 +15,7 @@

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

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: { - // Example of using the viewer-level ajaxRequestHeaders option + ajaxHeaders: { + // 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