From a336b2366701ca44dbc92ea6dcdfe10447128795 Mon Sep 17 00:00:00 2001 From: Ian Gilman Date: Fri, 2 Jan 2015 16:07:11 -0800 Subject: [PATCH] Documentation for ajaxWithCredentials-related changes --- changelog.txt | 1 + src/openseadragon.js | 12 ++++++++---- src/tilesource.js | 41 ++++++++++++++++++++++++----------------- 3 files changed, 33 insertions(+), 21 deletions(-) diff --git a/changelog.txt b/changelog.txt index 98a94fd0..9649171b 100644 --- a/changelog.txt +++ b/changelog.txt @@ -39,6 +39,7 @@ OPENSEADRAGON CHANGELOG * Rect and Point toString() functions are now consistent: rounding values to nearest hundredth * Overlays appear in the DOM immediately on open or addOverlay (#507) * imageLoaderLimit now works (#544) +* Added ajaxWithCredentials option (#543) 1.2.0: (in progress) diff --git a/src/openseadragon.js b/src/openseadragon.js index 81028d19..dc7a5638 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -556,6 +556,7 @@ * * @property {Boolean} [ajaxWithCredentials=false] * Whether to set the withCredentials XHR flag for AJAX requests (when loading tile sources). + * Note that this can be overridden at the {@link OpenSeadragon.TileSource} level. * */ @@ -1920,15 +1921,18 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){ /** * Makes an AJAX request. - * @function - * @param {String} url - the url to request - * @param {Function} onSuccess - a function to call on a successful response - * @param {Function} onError - a function to call on when an error occurs + * @param {Object} options + * @param {String} options.url - the url to request + * @param {Function} options.success - a function to call on a successful response + * @param {Function} options.error - a function to call on when an error occurs + * @param {Boolean} [options.withCredentials=false] - whether to set the XHR's withCredentials * @throws {Error} */ makeAjaxRequest: function( url, onSuccess, onError ) { var withCredentials; + // Note that our preferred API is that you pass in a single object; the named + // arguments are for legacy support. if( $.isPlainObject( url ) ){ onSuccess = url.success; onError = url.error; diff --git a/src/tilesource.js b/src/tilesource.js index 8d6ab5fb..1c0d29d2 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -38,39 +38,46 @@ /** * @class TileSource * @classdesc The TileSource contains the most basic implementation required to create a - * smooth transition between layer in an image pyramid. It has only a single key - * interface that must be implemented to complete it key functionality: + * smooth transition between layers in an image pyramid. It has only a single key + * interface that must be implemented to complete its key functionality: * 'getTileUrl'. It also has several optional interfaces that can be * implemented if a new TileSource wishes to support configuration via a simple * object or array ('configure') and if the tile source supports or requires - * configuration via retreival of a document on the network ala AJAX or JSONP, + * configuration via retrieval of a document on the network ala AJAX or JSONP, * ('getImageInfo'). *
- * By default the image pyramid is split into N layers where the images longest + * By default the image pyramid is split into N layers where the image's longest * side in M (in pixels), where N is the smallest integer which satisfies * 2^(N+1) >= M. * * @memberof OpenSeadragon * @extends OpenSeadragon.EventSource - * @param {Number|Object|Array|String} width - * If more than a single argument is supplied, the traditional use of - * positional parameters is supplied and width is expected to be the width - * source image at its max resolution in pixels. If a single argument is supplied and - * it is an Object or Array, the construction is assumed to occur through - * the extending classes implementation of 'configure'. Finally if only a - * single argument is supplied and it is a String, the extending class is - * expected to implement 'getImageInfo' and 'configure'. - * @param {Number} height + * @param {Object} options + * You can either specify a URL, or literally define the TileSource (by specifying + * width, height, tileSize, tileOverlap, minLevel, and maxLevel). For the former, + * the extending class is expected to implement 'getImageInfo' and 'configure'. + * For the latter, the construction is assumed to occur through + * the extending classes implementation of 'configure'. + * @param {String} [options.url] + * The URL for the data necessary for this TileSource. + * @param {Function} [options.success] + * A function to be called upon successful creation. + * @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 {Number} [options.width] * Width of the source image at max resolution in pixels. - * @param {Number} tileSize + * @param {Number} [options.height] + * Height of the source image at max resolution in pixels. + * @param {Number} [options.tileSize] * The size of the tiles to assumed to make up each pyramid layer in pixels. * Tile size determines the point at which the image pyramid must be * divided into a matrix of smaller images. - * @param {Number} tileOverlap + * @param {Number} [options.tileOverlap] * The number of pixels each tile is expected to overlap touching tiles. - * @param {Number} minLevel + * @param {Number} [options.minLevel] * The minimum level to attempt to load. - * @param {Number} maxLevel + * @param {Number} [options.maxLevel] * The maximum level to attempt to load. */ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLevel ) {