terriajs
Version:
Geospatial data visualization platform.
582 lines (497 loc) • 22.6 kB
JavaScript
'use strict';
/*global require*/
var clone = require('terriajs-cesium/Source/Core/clone');
var defaultValue = require('terriajs-cesium/Source/Core/defaultValue');
var defined = require('terriajs-cesium/Source/Core/defined');
var defineProperties = require('terriajs-cesium/Source/Core/defineProperties');
var freezeObject = require('terriajs-cesium/Source/Core/freezeObject');
var knockout = require('terriajs-cesium/Source/ThirdParty/knockout');
var RuntimeError = require('terriajs-cesium/Source/Core/RuntimeError');
var when = require('terriajs-cesium/Source/ThirdParty/when');
var DeveloperError = require('terriajs-cesium/Source/Core/DeveloperError');
var combine = require('terriajs-cesium/Source/Core/combine');
var combineFilters = require('../Core/combineFilters');
var createCatalogMemberFromType = require('./createCatalogMemberFromType');
var CatalogMember = require('./CatalogMember');
var inherit = require('../Core/inherit');
var raiseErrorOnRejectedPromise = require('./raiseErrorOnRejectedPromise');
/**
* A group of data items and other groups in the {@link Catalog}. A group can contain
* {@link CatalogMember|CatalogMembers} or other
* {@link CatalogGroup|CatalogGroups}.
*
* @alias CatalogGroup
* @constructor
* @extends CatalogMember
*
* @param {Terria} terria The Terria instance.
*/
var CatalogGroup = function(terria) {
CatalogMember.call(this, terria);
this._lastLoadInfluencingValues = undefined;
/**
* Gets or sets a value indicating whether the group is currently expanded and showing
* its children. This property is observable.
* @type {Boolean}
*/
this.isOpen = false;
/**
* Gets the collection of items in this group. This property is observable.
* @type {CatalogMember[]}
*/
this.items = [];
/**
* Gets or sets flag to prevent items in group being sorted. Subgroups will still sort unless their own preserveOrder flag is set. The value
* of this property only has an effect during {@CatalogGroup#load} and {@CatalogItem#updateFromJson}.
*/
this.preserveOrder = false;
/**
* Gets or sets the function to be used when sorting the group's items.
* This function takes two {@link CatalogItem} parameters and should return a negative,
* zero, or positive value depending on the order in which they should be sorted.
* @type {function}
*/
this.sortFunction = function(itemA, itemB) {
if (itemA.isPromoted && !itemB.isPromoted) {
return -1;
} else if (!itemA.isPromoted && itemB.isPromoted) {
return 1;
} else {
var aNameSortKey = itemA.nameSortKey;
var bNameSortKey = itemB.nameSortKey;
for (var i = 0; i < aNameSortKey.length && i < bNameSortKey.length; ++i) {
if (aNameSortKey[i] < bNameSortKey[i]) {
return -1;
} else if (aNameSortKey[i] > bNameSortKey[i]) {
return 1;
}
}
if (aNameSortKey.length === bNameSortKey.length) {
return 0;
} else {
return aNameSortKey.length > bNameSortKey.length ? 1 : -1;
}
}
};
knockout.track(this, ['isOpen', 'items']);
var that = this;
// knockout.defineProperty(this, 'isAnyEnabled', {
// // Defining this knockout computed property makes it easy to track changes to the isEnabled properties on the items
// get : function() {
// var isAnyEnabled = false;
// for (var i = that.items.length - 1; i >= 0; i--) {
// isAnyEnabled = that.items[i].isEnabled || isAnyEnabled; // order is important so knockout watches every item
// }
// return isAnyEnabled;
// }
// });
knockout.getObservable(this, 'isOpen').subscribe(function(newValue) {
// Load this group's items (if we haven't already) when it is opened.
if (newValue) {
raiseErrorOnRejectedPromise(that.terria, when.all([that.waitForDisclaimerIfNeeded(), that.load()]));
}
});
knockout.getObservable(this, 'isLoading').subscribe(function(newValue) {
// Call load() again immediately after finishing loading, if the group is still open. Normally this will do nothing,
// but if the URL has changed since we started, it will kick off loading the new URL.
// If this spins you into a stack overflow, verify that your derived-class load method only
// loads when it actually needs to do so!
if (newValue === false && that.isOpen) {
raiseErrorOnRejectedPromise(that.terria, that.load());
}
});
this._setupItemListeners();
};
inherit(CatalogMember, CatalogGroup);
defineProperties(CatalogGroup.prototype, {
/**
* Gets the type of data member represented by this instance.
* @memberOf CatalogGroup.prototype
* @type {String}
*/
type: {
get: function() {
return 'group';
}
},
/**
* Gets a human-readable name for this type of data source, such as 'Web Map Service (WMS)'.
* @memberOf CatalogGroup.prototype
* @type {String}
*/
typeName: {
get: function() {
return 'Group';
}
},
/**
* Gets a value that tells the UI whether this is a group.
* Groups, when clicked, expand to show their constituent items.
* @memberOf CatalogGroup.prototype
* @type {Boolean}
*/
isGroup: {
get: function() {
return true;
}
},
/**
* Gets the set of functions used to update individual properties in {@link CatalogMember#updateFromJson}.
* When a property name in the returned object literal matches the name of a property on this instance, the value
* will be called as a function and passed a reference to this instance, a reference to the source JSON object
* literal, and the name of the property.
* @memberOf CatalogGroup.prototype
* @type {Object}
*/
updaters: {
get: function() {
return CatalogGroup.defaultUpdaters;
}
},
/**
* Gets the set of functions used to serialize individual properties in {@link CatalogMember#serializeToJson}.
* When a property name on the model matches the name of a property in the serializers object literal,
* the value will be called as a function and passed a reference to the model, a reference to the destination
* JSON object literal, and the name of the property.
* @memberOf CatalogGroup.prototype
* @type {Object}
*/
serializers: {
get: function() {
return CatalogGroup.defaultSerializers;
}
},
/**
* Gets the set of names of the properties to be serialized for this object for a share link.
* @memberOf CatalogGroup.prototype
* @type {String[]}
*/
propertiesForSharing: {
get: function() {
return CatalogGroup.defaultPropertiesForSharing;
}
}
});
/**
* Gets or sets the set of default updater functions to use in {@link CatalogMember#updateFromJson}. Types derived from this type
* should expose this instance - cloned and modified if necesary - through their {@link CatalogMember#updaters} property.
* @type {Object}
*/
CatalogGroup.defaultUpdaters = clone(CatalogMember.defaultUpdaters);
CatalogGroup.defaultUpdaters.items = function(catalogGroup, json, propertyName, options) {
// Let the group finish loading first. Otherwise, these changes could get clobbered by the load.
return when(catalogGroup.load(), function() {
return CatalogGroup.updateItems(json.items, options, catalogGroup);
});
};
CatalogGroup.defaultUpdaters.isLoading = function(catalogGroup, json, propertyName) {};
freezeObject(CatalogGroup.defaultUpdaters);
/**
* Gets or sets the set of default serializer functions to use in {@link CatalogMember#serializeToJson}. Types derived from this type
* should expose this instance - cloned and modified if neccesary - through their {@link CatalogMember#serializers} property.
* @type {Object}
*/
CatalogGroup.defaultSerializers = clone(CatalogMember.defaultSerializers);
CatalogGroup.defaultSerializers.items = function(catalogGroup, json, propertyName, options) {
json.items = catalogGroup.items.filter(function(item) {
return !defined(options.itemFilter) || options.itemFilter(item);
}).map(function(item) {
return item.serializeToJson(options);
}).filter(function(serializedItem) {
return defined(serializedItem);
});
};
/**
* Call {@link CatalogGroup#defaultSerializers#items}, filtering out non-shareable properties and non-enabled items.
* This is used when serializing a number of kinds of item groups where most details can be fetched from a URL and hence
* there's no need to serialize anything that can't be changed by the user.
*/
CatalogGroup.enabledShareableItemsSerializer = function(catalogGroup, json, propertyName, options) {
return CatalogGroup.defaultSerializers.items(catalogGroup, json, propertyName, combine({
propertyFilter: combineFilters([options.propertyFilter, CatalogMember.propertyFilters.sharedOnly]),
itemFilter: combineFilters([options.itemFilter, CatalogMember.itemFilters.enabled])
}, options));
};
CatalogGroup.defaultSerializers.isLoading = function(catalogGroup, json, propertyName, options) {};
freezeObject(CatalogGroup.defaultSerializers);
/**
* Gets or sets the default set of properties that are serialized when serializing a {@link CatalogItem}-derived object
* for a share link.
* @type {String[]}
*/
CatalogGroup.defaultPropertiesForSharing = clone(CatalogMember.defaultPropertiesForSharing);
CatalogGroup.defaultPropertiesForSharing.push('items');
CatalogGroup.defaultPropertiesForSharing.push('isOpen');
freezeObject(CatalogGroup.defaultPropertiesForSharing);
CatalogGroup.prototype._setupItemListeners = function() {
var itemsChangeListeners = {
added: function(item) {
item.parent = this;
// Only index this in catalog if it's actually connected to catalog, otherwise we get situations where an
// item is added to the index before its actually built up a correct path to use as a default id.
if (item.connectsWithRoot()) {
indexWithDescendants([item], this.terria.catalog.shareKeyIndex);
}
}.bind(this),
deleted: function(item) {
if (item.connectsWithRoot()) {
deIndexWithDescendants([item], this.terria.catalog.shareKeyIndex);
}
item.parent = undefined;
}.bind(this)
};
knockout.getObservable(this, 'items').subscribe(function(changes) {
changes.forEach(function(change) {
if (!defined(change.moved)) {
itemsChangeListeners[change.status](change.value);
}
});
}, null, "arrayChange");
};
var NUMBER_AT_END_OF_KEY_REGEX = /\((\d+)\)$/;
/**
* Adds all passed items to the passed index, and all the children of those items recursively.
* @private
* @param {CatalogMember[]} items
* @param {Object} index
*/
function indexWithDescendants(items, index) {
items.forEach(function(item) {
item.allShareKeys.forEach(function(key) {
var insertionKey = key;
if (index[insertionKey]) {
insertionKey = generateUniqueKey(index, key);
if (item.uniqueId === key) {
// If this duplicate was the item's main key that will be used for sharing it in general, set this
// to the new key. This means that sharing the item will still work most of the time.
item.id = insertionKey;
}
console.warn('Duplicate shareKey: ' + key + '. Inserting new item under ' + insertionKey);
}
index[insertionKey] = item;
}, this);
if (defined(item.items)) {
indexWithDescendants(item.items, index);
}
});
}
/**
* Generates a unique key from a non-unique one by adding a number after it. If the key already has a number added,
* it will increment that number.
* @private
* @param index An index to check for uniqueness.
* @param initialKey The key to start from.
* @returns {String} A new, unique key.
*/
function generateUniqueKey(index, initialKey) {
var currentCandidate = initialKey;
var counter = 0;
while (index[currentCandidate]) {
var numberAtEndOfKeyMatches = currentCandidate.match(NUMBER_AT_END_OF_KEY_REGEX);
if (numberAtEndOfKeyMatches !== null) {
var nextNumber = parseInt(numberAtEndOfKeyMatches[1], 10) + 1;
currentCandidate = currentCandidate.replace(NUMBER_AT_END_OF_KEY_REGEX, '(' + nextNumber + ')');
} else {
currentCandidate += ' (1)';
}
// This loop should always find something eventually, but because it's a bit dangerous looping endlessly...
counter++;
if (counter >= 100000) {
throw new DeveloperError('Was not able to find a unique key for ' + initialKey + ' after 100000 iterations.' +
' This is probably because the regex for matching keys was somehow unable to work for that key.');
}
}
return currentCandidate;
}
/**
* Removes all passed items to the passed index, and all the children of those items recursively.
*
* @param {CatalogMember[]} items
* @param {Object} index
*/
function deIndexWithDescendants(items, index) {
items.forEach(function(item) {
item.allShareKeys.forEach(function(key) {
index[key] = undefined;
}, this);
if (defined(item.items)) {
deIndexWithDescendants(item.items, index);
}
});
}
/**
* Loads the contents of this group, if the contents are not already loaded. It is safe to
* call this method multiple times. The {@link CatalogGroup#isLoading} flag will be set while the load is in progress.
* Derived classes should implement {@link CatalogGroup#_load} to perform the actual loading for the group.
* Derived classes may optionally implement {@link CatalogGroup#_getValuesThatInfluenceLoad} to provide an array containing
* the current value of all properties that influence this group's load process. Each time that {@link CatalogGroup#load}
* is invoked, these values are checked against the list of values returned last time, and {@link CatalogGroup#_load} is
* invoked again if they are different. If {@link CatalogGroup#_getValuesThatInfluenceLoad} is undefined or returns an
* empty array, {@link CatalogGroup#_load} will only be invoked once, no matter how many times
* {@link CatalogGroup#load} is invoked.
*
* @returns {Promise} A promise that resolves when the load is complete, or undefined if the group is already loaded.
*
*/
CatalogGroup.prototype.load = function() {
var parentPromise = CatalogMember.prototype.load.call(this);
if (parentPromise) {
return parentPromise.then(function() {
this.sortItems(true);
}.bind(this)).otherwise(function(e) {
this.isOpen = false;
throw e; // keep throwing this so we can chain more otherwises.
}.bind(this));
}
};
/**
* When implemented in a derived class, this method loads the group. The base class implementation does nothing.
* This method should not be called directly; call {@link CatalogGroup#load} instead.
* @return {Promise} A promise that resolves when the load is complete.
* @protected
*/
CatalogGroup.prototype._load = function() {
return when();
};
var emptyArray = freezeObject([]);
/**
* When implemented in a derived class, gets an array containing the current value of all properties that
* influence this group's load process. See {@link CatalogGroup#load} for more information on when and
* how this is used. The base class implementation returns an empty array.
* @return {Array} The array of values that influence the load process.
* @protected
*/
CatalogGroup.prototype._getValuesThatInfluenceLoad = function() {
return emptyArray;
};
/**
* Adds an item or group to this group.
*
* @param {CatalogMember} item The item to add.
*/
CatalogGroup.prototype.add = function(item) {
this.items.push(item);
};
/**
* Removes an item or group from this group.
*
* @param {CatalogMember} item The item to remove.
*/
CatalogGroup.prototype.remove = function(item) {
this.items.remove(item); // available for knockout observable arrays.
};
/**
* Toggles the {@link CatalogGroup#isOpen} property of this group. If it is open, calling this method
* will close it. If it is closed, calling this method will open it.
*/
CatalogGroup.prototype.toggleOpen = function() {
this.isOpen = !this.isOpen;
};
/**
* Finds the first item in this group that has the given name. The search is case-sensitive.
*
* Instead of using this function, consider using {@link Catalog#shareKeyIndex} to look the item up, as this works in
* constant time and allows lookups to continue working for items that have been renamed or moved as long as they have
* a stable shareKey set. This function is retained mainly for backwards-compatibility with existing share links that
* used names for matching.
*
* @param {String} name The name of the item to find.
* @return {CatalogMember} The first item with the given name, or undefined if no item with that name exists.
*/
CatalogGroup.prototype.findFirstItemByName = function(name) {
for (var i = 0; i < this.items.length; ++i) {
if (this.items[i].name === name) {
return this.items[i];
}
}
return undefined;
};
/**
* Sorts the items in this group.
*
* @param {Boolean} [sortRecursively=false] true to sort the items in sub-groups as well; false to sort only the items in this group.
*/
CatalogGroup.prototype.sortItems = function(sortRecursively) {
// Allow a group to be non-sorted, while still containing sorted groups.
if (this.preserveOrder) {
// Bubble promoted items to the top without changing their relative order.
var promoted = this.items.filter(function(item) { return item.isPromoted; });
var nonPromoted = this.items.filter(function(item) { return !item.isPromoted; });
if (promoted.length > 0 && nonPromoted.length > 0) {
this.items = promoted.concat(nonPromoted);
}
} else {
this.items.sort(this.sortFunction);
}
if (defaultValue(sortRecursively, false)) {
for (var i = 0; i < this.items.length; ++i) {
var item = this.items[i];
if (defined(item.sortItems)) {
item.sortItems(sortRecursively);
}
}
}
};
CatalogGroup.prototype.enableWithParents = function() {
this.isOpen = true;
if (this.parent) {
this.parent.enableWithParents();
}
};
/**
* Reads an array of catalog members in JSON format (as objects, not strings) and transforms them into actual Terria
* models (i.e. {@link CatalogMember} instances), and adds them to the {@link CatalogMember#items} property of the
* supplied catalogGroup, or updates only the existing items in the catalogGroup.
*
* @param {Object} itemsJson The items as simple JSON data. The JSON should be in the form of an object literal, not a
* string.
* @param {Object} [options] Object with the following properties:
* @param {Boolean} [options.onlyUpdateExistingItems] true to only update existing items and never create new ones, or false is new items
* may be created by this update.
* @param {Boolean} [options.isUserSupplied] If specified, sets the {@link CatalogMember#isUserSupplied} property of updated catalog members
* to the given value. If not specified, the property is left unchanged.
* @param {CatalogGroup} catalogGroup The catalogGroup to update.
*
* @returns {Promise} A promise that resolves when the update is complete.
*/
CatalogGroup.updateItems = function(itemsJson, options, catalogGroup) {
if (!(itemsJson instanceof Array)) {
throw new DeveloperError('JSON catalog description must be an array of groups.');
}
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
var onlyUpdateExistingItems = defaultValue(options.onlyUpdateExistingItems, false);
var promises = [];
for (var itemIndex = 0; itemIndex < itemsJson.length; ++itemIndex) {
var itemJson = itemsJson[itemIndex];
if (!defined(itemJson.name) && !defined(itemJson.id)) {
throw new RuntimeError('A catalog member must have a name or a id for matching.');
}
var itemObject;
if (itemJson.id) {
itemObject = catalogGroup.terria.catalog.shareKeyIndex[itemJson.id];
} else if (itemJson.name) {
itemObject = catalogGroup.findFirstItemByName(itemJson.name);
}
var updating = defined(itemObject);
if (!updating) {
// Skip this item entirely if we're not allowed to create it.
if (onlyUpdateExistingItems) {
continue;
}
if (!defined(itemJson.name)) {
throw new RuntimeError('A newly created catalog member must have a name.');
}
if (!defined(itemJson.type)) {
throw new RuntimeError('A catalog member must have a type.');
}
itemObject = createCatalogMemberFromType(itemJson.type, catalogGroup.terria);
}
promises.push(itemObject.updateFromJson(itemJson, options));
if (!updating) {
catalogGroup.add(itemObject);
}
}
catalogGroup.sortItems();
return when.all(promises);
};
module.exports = CatalogGroup;