terriajs/lib/Models/CatalogMember.js

Geospatial data visualization platform.

'use strict';

/*global require*/

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 DeveloperError = require('terriajs-cesium/Source/Core/DeveloperError');
var freezeObject = require('terriajs-cesium/Source/Core/freezeObject');
var when = require('terriajs-cesium/Source/ThirdParty/when');
var knockout = require('terriajs-cesium/Source/ThirdParty/knockout');
var serializeToJson = require('../Core/serializeToJson');
var updateFromJson = require('../Core/updateFromJson');
var runLater = require('../Core/runLater');
var arraysAreEqual = require('../Core/arraysAreEqual');

/**
 * A member of a {@link CatalogGroup}.  A member may be a {@link CatalogItem} or a
 * {@link CatalogGroup}.
 *
 * @alias CatalogMember
 * @constructor
 * @abstract
 *
 * @param {Terria} terria The Terria instance.
 */
var CatalogMember = function(terria) {
    if (!defined(terria)) {
        throw new DeveloperError('terria is required');
    }

    this._terria = terria;

    /**
     * Gets or sets the name of the item.  This property is observable.
     * @type {String}
     */
    this.name = 'Unnamed Item';

    /**
     * Gets or sets the description of the item.  This property is observable.
     * @type {String}
     */
    this.description = '';

    /**
     * Gets or sets the array of section titles and contents for display in the layer info panel.
     * In future this may replace 'description' above - this list should not contain
     * sections named 'description' or 'Description' if the 'description' property
     * is also set as both will be displayed.
     * The object is of the form {name:string, content:string}.
     * Content will be rendered as Markdown with HTML.
     * This property is observable.
     * @type {Object[]}
     * @default []
     */
    this.info = [];

    /**
     * Gets or sets the array of section titles definining the display order of info sections.  If this property
     * is not defined, {@link DataPreviewSections}'s DEFAULT_SECTION_ORDER is used.  This property is observable.
     * @type {String[]}
     */
    this.infoSectionOrder = undefined;

    /**
     * Gets or sets a value indicating whether this member was supplied by the user rather than loaded from one of the
     * {@link Terria#initSources}.  User-supplied members must be serialized completely when, for example,
     * serializing enabled members for sharing.  This property is observable.
     * @type {Boolean}
     * @default true
     */
    this.isUserSupplied = true;

    /**
     * Gets or sets a value indicating whether this item is kept above other non-promoted items.
     * This property is observable.
     * @type {Boolean}
     * @default false
     */
    this.isPromoted = false;

    /**
     * Gets or sets a value indicating whether this item is hidden from the catalog.  This
     * property is observable.
     * @type {Boolean}
     * @default false
     */
    this.isHidden = false;

    /**
     * A message object that is presented to the user when an item or group is initially clicked
     * The object is of the form {title:string, content:string, key: string, confirmation: boolean, confirmText: string, width: number, height: number}.
     * This property is observable.
     * @type {Object}
     */
    this.initialMessage = undefined;

    /**
     * Gets or sets the cache duration to use for proxied URLs for this catalog member.  If undefined, proxied URLs are effectively cachable
     * forever.  The duration is expressed as a Varnish-like duration string, such as '1d' (one day) or '10000s' (ten thousand seconds).
     * @type {String}
     */
    this.cacheDuration = undefined;

    /**
     * Gets or sets whether or not this member should be forced to use a proxy.
     * This property is not observable.
     * @type {Boolean}
     */
    this.forceProxy = false;

    /**
     * Gets or sets the dictionary of custom item properties. This property is observable.
     * @type {Object}
     */
    this.customProperties = {};

    /**
     * An optional unique id for this member, that is stable across renames and moves.
     * Use uniqueId to get the canonical unique id for this CatalogMember, which is present even if there is no id.
     * @type {String}
     */
    this.id = undefined;

    /**
     * An array of all possible keys that can be used to match to this catalog member when specified in a share link -
     * used for maintaining backwards compatibility when adding or changing {@link CatalogMember#id}.
     *
     * @type {String[]}
     */
    this.shareKeys = undefined;

    /**
     * The parent {@link CatalogGroup} of this member.
     *
     * @type {CatalogGroup}
     */
    this.parent = undefined;

    /**
     * A short report to show on the now viewing tab.  This property is observable.
     * @type {String}
     */
    this.shortReport = undefined;

    /**
     * The list of collapsible sections of the short report.  Each element of the array is an object literal
     * with a `name` and `content` property.
     * @type {ShortReportSection[]}
     */
    this.shortReportSections = [];


    /*
     * Gets or sets a value indicating whether this data source is currently loading.  This property is observable.
     * @type {Boolean}
     */
    this.isLoading = false;

    /**
     * Whether this catalog member is waiting for a disclaimer to be accepted before showing itself.
     *
     * @type {boolean}
     */
    this.isWaitingForDisclaimer = false;

    /**
     * Indicates that the source of this data should be hidden from the UI (obviously this isn't super-secure as you
     * can just look at the network requests).
     *
     * @type {boolean}
     */
    this.hideSource = false;

    /**
     * The names of items in the {@link CatalogMember#info} array that contain details of the source of this
     * CatalogMember's data. This should be overridden by children of this class.
     *
     * @type {Array}
     * @private
     */
    this._sourceInfoItemNames = [];

    /**
     * The name of the item to show in the catalog, if different from `name`. Default undefined.
     * This property is observed.
     * @type {String}
     * @private
     */
    this._nameInCatalog = undefined;

    this._loadingPromise = undefined;

    /** Lookup table for _sourceInfoItemNames, access through {@link CatalogMember#_infoItemsWithSourceInfoLookup} */
    this._memoizedInfoItemsSourceLookup = undefined;

    knockout.track(this, ['name', 'info', 'infoSectionOrder', 'description', 'isUserSupplied', 'isPromoted',
        'initialMessage', 'isHidden', 'cacheDuration', 'customProperties', 'shortReport', 'shortReportSections',
        'isLoading', 'isWaitingForDisclaimer', '_nameInCatalog']);

    knockout.defineProperty(this, 'nameSortKey', {
        get: function() {
            var parts = this.nameInCatalog.split(/(\d+)/);
            return parts.map(function(part) {
                var parsed = parseInt(part, 10);
                if (parsed === parsed) {
                    return parsed;
                } else {
                    return part.trim().toLowerCase();
                }
            });
        }
    });

    /**
     * Gets or sets the name of this catalog member in the catalog. By default this is just `name`, but can be overridden.
     * @member {String} nameInCatalog
     * @memberOf CatalogMember.prototype
     */
    knockout.defineProperty(this, 'nameInCatalog', {
        get : function() {
            return defaultValue(this._nameInCatalog, this.name);
        },
        set : function(value) {
            this._nameInCatalog = value;
        }
    });
};

var descriptionRegex = /description/i;

defineProperties(CatalogMember.prototype, {
    /**
     * Gets the type of data item represented by this instance.
     * @memberOf CatalogMember.prototype
     * @type {String}
     */
    type : {
        get : function() {
            throw new DeveloperError('Types derived from CatalogMember must implement a "type" property.');
        }
    },

    /**
     * Gets a human-readable name for this type of data source, such as 'Web Map Service (WMS)'.
     * @memberOf CatalogMember.prototype
     * @type {String}
     */
    typeName : {
        get : function() {
            throw new DeveloperError('Types derived from CatalogMember must implement a "typeName" property.');
        }
    },

    /**
     * Gets a value that tells the UI whether this is a group.
     * Groups, when clicked, expand to show their constituent items.
     * @memberOf CatalogMember.prototype
     * @type {Boolean}
     */
    isGroup : {
        get : function() {
            return false;
        }
    },

    /**
      * Gets the Terria instance.
     * @memberOf CatalogMember.prototype
     * @type {Terria}
     */
    terria : {
        get : function() {
            return this._terria;
        }
    },

    /**
     * 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.  If part of the update happens asynchronously, the updater function should
     * return a Promise that resolves when it is complete.
     * @memberOf CatalogMember.prototype
     * @type {Object}
     */
    updaters : {
        get : function() {
            return CatalogMember.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 CatalogMember.prototype
     * @type {Object}
     */
    serializers : {
        get : function() {
            return CatalogMember.defaultSerializers;
        }
    },

    /**
     * Gets the set of names of the properties to be serialized for this object when {@link CatalogMember#serializeToJson}
     * is called for a share link.
     * @memberOf CatalogMember.prototype
     * @type {String[]}
     */
    propertiesForSharing : {
        get : function() {
            return CatalogMember.defaultPropertiesForSharing;
        }
    },

    /**
    * Tests whether a description is available, either in the 'description' property
    * or as a member of the 'info' array.
    * @memberOf CatalogMember.prototype
    * @type {Boolean}
    */
    hasDescription : {
        get : function() {
            return this.description ||
                (this.info &&
                 this.info.some(function(i){
                    return descriptionRegex.test(i.name);
                }));
        }
    },

    /**
     * The canonical unique id for this CatalogMember. Will be the id property if one is present, otherwise it will fall
     * back to the uniqueId of this item's parent + this item's name. This means that if no id is set anywhere up the
     * tree, the uniqueId will be a complete path of this member's location.
     * @memberOf  CatalogMember.prototype
     * @type {String}
     */
    uniqueId : {
        get : function() {
            if (this.id) {
                return this.id;
            }

            var parentKey = this.parent ? this.parent.uniqueId + '/' : '';

            return parentKey + this.name;
        }
    },

    /**
     * All keys that have historically been used to resolve this member - the current uniqueId + past shareKeys.
     */
    allShareKeys : {
        get: function() {
            var allShareKeys = [this.uniqueId];

            return this.shareKeys ? allShareKeys.concat(this.shareKeys) : allShareKeys;
        }
    },

    needsDisclaimerShown: {
        get: function() {
            return defined(this.initialMessage) && (!defined(this.initialMessage.key) || !this.terria.getLocalProperty(this.initialMessage.key));
        }
    },

    /**
     * A filtered view of {@link CatalogMember#info} that excludes info items that divulge details about the data's
     * source, as determined by {@link CatalogMember#__sourceInfoItemNames}.
     */
    infoWithoutSources: {
        get: function() {
            return defaultValue(this.info, []).filter(function(infoItem) {
                return !defined(this._infoItemsWithSourceInfoLookup[infoItem.name]);
            }.bind(this));
        }
    },

    /**
     * Returns a lookup of _sourceInfoItemNames as a map of names to a true value. Memoizes after being called for the
     * first time.
     *
     * @private
     */
    _infoItemsWithSourceInfoLookup: {
        get: function() {
            if (!defined(this._memoizedInfoItemsSourceLookup)) {
                this._memoizedInfoItemsSourceLookup = this._sourceInfoItemNames.reduce(function(lookupSoFar, name) {
                    lookupSoFar[name] = true;
                    return lookupSoFar;
                }, {});
            }

            return this._memoizedInfoItemsSourceLookup;
        }
    }
});

/**
 * 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}
 */
CatalogMember.defaultUpdaters = {
    nameSortKey: function() {},
    info: function(catalogItem, json, propertyName) {
        if (defined(json.info)) {
            json.info.forEach(function(infoItem) {
                var existingItem = catalogItem.info.filter(item => item.name === infoItem.name)[0];
                if (defined(existingItem)) {
                    var index = catalogItem.info.indexOf(existingItem);
                    catalogItem.info.splice(index, 1, infoItem);
                } else {
                    catalogItem.info.push(infoItem);
                }
            });
        }
    }
};

freezeObject(CatalogMember.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 necesary - through their {@link CatalogMember#serializers} property.
 * @type {Object}
 */
CatalogMember.defaultSerializers = {
    nameSortKey: function() {}
};

freezeObject(CatalogMember.defaultSerializers);

/**
 * Gets or sets the default set of properties that are serialized when serializing a {@link CatalogMember}-derived object
 * for a share link.
 * @type {String[]}
 */
CatalogMember.defaultPropertiesForSharing = [
    'name'
];

freezeObject(CatalogMember.defaultPropertiesForSharing);

/**
 * Updates the catalog member from a JSON object-literal description of it.
 * Existing collections with the same name as a collection in the JSON description are
 * updated.  If the description contains a collection with a name that does not yet exist,
 * it is created.  Because parts of the update may happen asynchronously, this method
 * returns at Promise that will resolve when the update is completely done.
 *
 * @param {Object} json The JSON description.  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.
  * @returns {Promise} A promise that resolves when the update is complete.
*/
CatalogMember.prototype.updateFromJson = function(json, options) {
    if (defined(options) && defined(options.isUserSupplied)) {
        this.isUserSupplied = options.isUserSupplied;
    }

    var updatePromise = updateFromJson(this, json, options);

    // Updating from JSON may trigger a load (e.g. if isEnabled is set to true).  So if this catalog item
    // is now loading, wait on the load promise as well, which we can get by calling load.
    if (this.isLoading) {
        return when.all([updatePromise, this.load()]);
    } else {
        return updatePromise;
    }
};

/**
 * Serializes the data item to JSON.
 *
 * @param {Object} [options] Object with the following properties:
 * @param {Function} [options.propertyFilter] Filter function that will be executed to determine whether a property
 *          should be serialized.
 * @param {Function} [options.itemFilter] Filter function that will be executed for each item in a group to determine
 *          whether that item should be serialized.
 * @return {Object} The serialized JSON object-literal.
 */
CatalogMember.prototype.serializeToJson = function(options) {
    options = defaultValue(options, defaultValue.EMPTY_OBJECT);

    var result = serializeToJson(this, options.propertyFilter, options);
    result.type = this.type;
    result.id = this.uniqueId;

    if (defined(this.parent)) {
        result.parents = getParentIds(this.parent).reverse();
    }

    return result;
};

/**
 * Gets the ids of all parents of a catalog member, ordered from the closest descendant to the most distant. Ignores
 * the root.
 * @private
 * @param catalogMember The catalog member to get parent ids for.
 * @param parentIds A starting list of parent ids to add to (allows the function to work recursively).
 * @returns {String[]}
 */
function getParentIds(catalogMember, parentIds) {
    parentIds = defaultValue(parentIds, []);

    if (defined(catalogMember.parent)) {
        return getParentIds(catalogMember.parent, parentIds.concat([catalogMember.uniqueId]));
    }

    return parentIds;
}

/**
 * Finds an {@link CatalogMember#info} section by name.
 * @param {String} sectionName The name of the section to find.
 * @return {Object} The section, or undefined if no section with that name exists.
 */
CatalogMember.prototype.findInfoSection = function(sectionName) {
    for (var i = 0; i < this.info.length; ++i) {
        if (this.info[i].name === sectionName) {
            return this.info[i];
        }
    }
    return undefined;
};

/**
 * Goes up the hierarchy and determines if this CatalogMember is connected with the root in terria.catalog, or whether it's
 * part of a disconnected sub-tree.
 */
CatalogMember.prototype.connectsWithRoot = function() {
    var item = this;
    while (item.parent) {
        item = item.parent;
    }
    return item === this.terria.catalog.group;
};

/**
 * "Enables" this catalog member in a way that makes sense for its implementation (e.g. isEnabled for items, isOpen for
 * groups, and all its parents and ancestors in the tree.
 */
CatalogMember.prototype.enableWithParents = function() {
    throw new DeveloperError('Types derived from CatalogMember must implement a "enableWithParents" function.');
};

CatalogMember.prototype.waitForDisclaimerIfNeeded = function() {
    if (this.needsDisclaimerShown) {
        this.isWaitingForDisclaimer = true;
        var deferred = when.defer();
        this.terria.disclaimerListener(this, function() {
            this.isWaitingForDisclaimer = false;
            deferred.resolve();
        }.bind(this));
        return deferred.promise;
    } else {
        return when();
    }
};

CatalogMember.prototype.load = function() {
    if (defined(this._loadingPromise)) {
        // Load already in progress.
        return this._loadingPromise;
    }

    var loadInfluencingValues = [];
    if (defined(this._getValuesThatInfluenceLoad)) {
        loadInfluencingValues = this._getValuesThatInfluenceLoad();
    }

    if (arraysAreEqual(loadInfluencingValues, this._lastLoadInfluencingValues)) {
        // Already loaded, and nothing has changed to force a re-load.
        return undefined;
    }

    this.isLoading = true;

    var that = this;

    this._loadingPromise = runLater(function() {
        that._lastLoadInfluencingValues = [];
        if (defined(that._getValuesThatInfluenceLoad)) {
            that._lastLoadInfluencingValues = that._getValuesThatInfluenceLoad();
        }

        return that._load();
    }).then(function(result) {
        that._loadingPromise = undefined;
        that.isLoading = false;
        return result;
    }).otherwise(function(e) {
        that._lastLoadInfluencingValues = undefined;
        that._loadingPromise = undefined;
        that.isLoading = false;
        throw e; // keep throwing this so we can chain more otherwises.
    });

    return this._loadingPromise;
};

/** A collection of static filters functions used during serialization */
CatalogMember.itemFilters = {
    /** Item filter that returns true if the item is user supplied */
    userSuppliedOnly: function(item) {
        return item.isUserSupplied;
    },
    /** Item filter that returns true if the item is a {@link CatalogItem} that is enabled, or another kind of {@link CatalogMember}. */
    enabled: function(item) {
        return !defined(item.isEnabled) || item.isEnabled;
    },
    /** Item filter that returns true if an item has no local data. */
    noLocalData: function(item) {
        return !defined(item.data);
    }
};

CatalogMember.propertyFilters = {
    /**
     * Property filter that returns true if the property is in that item's {@link CatalogMember#propertiesForSharing} array.
     */
    sharedOnly: function(property, item) {
        return item.propertiesForSharing.indexOf(property) >= 0;
    }
};

module.exports = CatalogMember;