core/context.js

/*
 * Your installation or use of this SugarCRM file is subject to the applicable
 * terms available at
 * http://support.sugarcrm.com/Resources/Master_Subscription_Agreements/.
 * If you do not agree to all of the applicable terms or do not have the
 * authority to bind the entity as an authorized representative, then do not
 * install or use this SugarCRM file.
 *
 * Copyright (C) SugarCRM Inc. All rights reserved.
 */

const Bean = require('../data/bean');
const BeanCollection = require('../data/bean-collection');
const DataManager = require('../data/data-manager');

/**
 * Helper function to determine if {@link Core/Context#loadData} can be called
 * on this context.
 *
 * @return {boolean} `true` if {@link Core/Context#loadData} can be called.
 *   `false` otherwise.
 * @private
 */
function shouldFetch() {
    return (this.get('fetch') === void 0 || this.get('fetch')) &&
        !this.isDataFetched() && !this.get('create');
}

/**
 * The Context object is a state variable to hold the current application state.
 * It extends `Backbone.Model`.
 *
 * The context contains various states of the current {@link View/View View} or
 * {@link View/Layout Layout} -- this includes the current model and collection,
 * as well as the current module focused and also possibly the url hash that was
 * matched.
 *
 * ### Instantiate a context.
 *
 * ```
 * const Context = require('./context');
 * let myContext = new Context();
 * ```
 *
 * ### Creating a child context or retrieving an existing one.
 * Assuming `myContext` is a context instance.
 *
 * ```
 * let childContext = myContext.getChildContext({cid: <contextId>});
 * ```
 *
 * If <contextId> does not match any child context, a new child context will be
 * created.
 *
 * ### Retrieving Data from the Context
 * A context is a Backbone Model, so its data is stored in the attributes:
 *
 * ```
 * var module = myContext.get('module'); // module = "Contacts"
 * ```
 *
 * @module Core/Context
 * @class
 */
const Context = Backbone.Model.extend({
    /**
     * Calls Backbone's `initialize` and initializes this context's properties.
     *
     * @param {Object} [attributes] The initial hash of attributes.
     * @memberOf Core/Context
     * @instance
     */
    initialize: function(attributes) {
        Backbone.Model.prototype.initialize.call(this, attributes);
        this.id = this.cid;
        this.parent = null;
        this.children = [];
        this._fetchCalled = false;
    },

    /**
     * Recursively clears this context and its children.
     *
     * Unbinds the event listeners, clears the attributes, aborts the request
     * in progress if any, and resets the load flag (calls
     * {@link Core/Context#resetLoadFlag}).
     *
     * @param {Object} [options] Standard `Backbone.Model` options.
     * @memberOf Core/Context
     * @instance
     */
    clear: function(options) {
        var collection = this.get('collection');

        if (collection) {
            collection.abortFetchRequest();
        }

        _.each(this.children, function(child) {
            child.clear(options);
        });

        this.children = [];
        this.parent = null;

        // Remove event listeners attached to models and collections in the
        // context before clearing them.
        _.each(this.attributes, function(value) {
            if (value && (value.off === Backbone.Events.off)) {
                value.off();
                value.stopListening();
                if (_.isFunction(value.dispose)) {
                    value.dispose();
                }
            }
        }, this);

        this.off();
        Backbone.Model.prototype.clear.call(this, options);

        this.resetLoadFlag();
    },

    /**
     * Resets `load-data` state for this context and its child contexts.
     *
     * The {@link Core/Context#loadData} method sets an internal boolean flag
     * to prevent multiple identical requests to the server.
     * This method resets this flag.
     *
     * @param {Object} [options] A hash of options.
     * @param {boolean} [options.recursive = true] `true` to reset the child
     * contexts too.
     * @param {boolean} [options.resetModel = true] `true` to reset the flag on
     * the model.
     * @param {boolean} [options.resetCollection = true] `true` to reset the
     * flag on the collection.
     * @memberOf Core/Context
     * @instance
     */
    resetLoadFlag: function (options) {
        options = options || {};
        var recursive = _.isUndefined(options.recursive) ? true : options.recursive;
        var resetModel = _.isUndefined(options.resetModel) ? true : options.resetModel;
        var resetCollection = _.isUndefined(options.resetCollection) ? true : options.resetCollection;

        this._fetchCalled = false;

        if (this.get('model') && resetModel) {
            this.get('model').dataFetched = false;
        }

        if (this.get('collection') && resetCollection) {
            this.get('collection').dataFetched = false;
        }

        if (recursive) {
            _.each(this.children, function(child) {
                child.resetLoadFlag();
            });
        }
    },

    /**
     * Checks if this context is used for a create view.
     *
     * @return {boolean} `true` if this context has the `create` flag set.
     * @memberOf Core/Context
     * @instance
     */
    isCreate: function() {
        return this.get("create") === true;
    },

    /**
     * Gets an existing related context or creates a new one.
     *
     * @param {Object} [def] Child context definition.
     * @param {string} [def.cid] The id of the context to retrieve. This takes
     *   precedence over the passed name, the link and the module.
     * @param {string} [def.name] The name of the context to retrieve. This
     *   takes precedence over passed the link and the module.
     * @param {string} [def.link] The link name to retrieve a context from. This
     *   takes precedence over the passed module name.
     * @param {string} [def.module] The module name to retrieve a context from.
     *   The first child context matching the module attribute will be returned.
     * @param {boolean} [def.forceNew] `true` to force the creation a new
     *   context, without trying to retrieve an existing one.
     * @return {Core/Context} The child context.
     * @memberOf Core/Context
     * @instance
     */
    getChildContext: function(def) {
        def = def || {};
        var context;
        var force = def.forceNew || false;

        delete def.forceNew;

        // Re-use a child context if it already exists
        // We search by either link name or module name
        // Consider refactoring the way we store children: hash v.s. array
        var name = def.cid || def.name || def.link || def.module;
        if (name && !force) {
            context = _.find(this.children, function(child) {
                return ((child.cid == name) || (child.get("link") == name) || (child.get("module") == name));
            });
        }

        if (!context) {
            def = _.extend({ fetch: this.get('fetch') }, def);
            context = new Context(def);
            this.children.push(context);
            context.parent = this;
        }

        if (def.link) {
            var parentModel = this.get("model");
            context.set({
                parentModel: parentModel,
                parentModule: parentModel ? parentModel.module : null
            });
        } else if(!def.module){
            context.set({module:this.get("module")});
        }

        this.trigger("context:child:add", context);

        return context;
    },

    /**
     * Prepares instances of model and collection and sets them to this context.
     *
     * The method also create related contexts, based on the created bean fields:
     * It creates child context for each `link` of each `collection` field
     * present on the bean.
     * This method does nothing if this context already contains an instance of
     * a model or a collection.
     *
     * @param {boolean} [force] `true` to force the creation of the model and
     *   collection.
     * @param {boolean} prepareRelated `true` to always prepare related contexts.
     * @return {Core/Context} Returns this context instance.
     * @memberOf Core/Context
     * @instance
     */
    prepare: function (force, prepareRelated) {
        var link;
        if (force || (!this.get('model') && !this.get('collection'))) {
            var modelId = this.get('modelId');
            var create = this.get('create');
            link = this.get('link');

            this.set(link ?
                this._prepareRelated(link, modelId, create) :
                this._prepare(modelId, create)
            );
        }

        if ((force || !this._relatedCollectionsPopulated) && (!link || prepareRelated)) {
            this._populateRelatedContexts();
        }

        return this;
    },

    /**
     * Sets the `fetch` attribute recursively on the context and its children.
     *
     * A context with `fetch` set to `false` won't load the data.
     *
     * @param {boolean} fetch `true` to recursively set `fetch` to `true`
     *   in this context and its children.
     * @param {Object} [options] A hash of options.
     * @param {boolean} [options.recursive] `true` to recursively set the
     *   `fetch` boolean on the children.
     * @memberOf Core/Context
     * @instance
     */
    setFetch: function (fetch, options) {
        options = options || {};
        this.set('fetch', fetch);
        var recursive = options.recursive === void 0 ? true : options.recursive;
        if (recursive) {
            _.each(this.children, (child) => { child.setFetch(fetch); });
        }
    },

    /**
     * Prepares instances of model and collection.
     *
     * This method assumes that the module name (`module`) is set on the context.
     * If not, instances of standard `Backbone.Model` and `Backbone.Collection`
     * are created.
     *
     * @param {string} modelId Bean ID.
     * @param {boolean} create Create flag.
     * @return {Object} State to set on this context.
     * @private
     * @memberOf Core/Context
     * @instance
     */
    _prepare: function(modelId, create) {
        var model, collection,
            module = this.get("module"),
            mixed = this.get("mixed"),
            models;

        if (modelId) {
            model = DataManager.createBean(module, { id: modelId });
            models = [model];
        } else if (create === true) {
            model = DataManager.createBean(module);
            models = [model];
        } else {
            model = DataManager.createBean(module);
        }

        collection = mixed === true ?
            DataManager.createMixedBeanCollection(models) :
            DataManager.createBeanCollection(module, models);

        return {
            collection: collection,
            model: model
        };
    },

    /**
     * Prepares instances of related model and collection.
     *
     * This method assumes that either a parent model (`parentModel`) or
     * parent model ID (`parentModelId`) and parent model module name
     * (`parentModule`) are set on this context.
     *
     * @param {string} link Relationship link name.
     * @param {string} modelId Related bean ID.
     * @param {boolean} create Create flag.
     * @return {Object} State to set on this context.
     * @private
     * @memberOf Core/Context
     * @instance
     */
    _prepareRelated: function(link, modelId, create) {
        var model, collection,
            parentModel = this.get("parentModel");

        parentModel = parentModel || DataManager.createBean(this.get("parentModule"), { id: this.get("parentModelId") });
        if (modelId) {
            model = DataManager.createRelatedBean(parentModel, modelId, link);
            collection = DataManager.createRelatedCollection(parentModel, link, [model]);
        } else if (create === true) {
            model = DataManager.createRelatedBean(parentModel, null, link);
            collection = DataManager.createRelatedCollection(parentModel, link, [model]);
        } else {
            model = DataManager.createRelatedBean(parentModel, null, link);
            collection = DataManager.createRelatedCollection(parentModel, link);
        }

        if (!this.has("parentModule")) {
            this.set({ "parentModule": parentModel.module }, { silent: true });
        }

        if (!this.has("module")) {
            this.set({ "module": model.module }, { silent: true });
        }

        return {
            parentModel: parentModel,
            collection: collection,
            model: model
        };
    },

    /**
     * Sets the `fields` attribute on this context by extending the current
     * `fields` attribute with the passed-in `fieldsArray`.
     *
     * @param {string[]} fieldsArray The list of field names.
     * @return {Core/Context} Instance of this model.
     * @memberOf Core/Context
     * @instance
     */
    addFields: function(fieldsArray) {
       if (!fieldsArray) {
           return;
       }
       var fields = _.union(fieldsArray, this.get('fields') || []);
       return this.set('fields', fields);
    },

    /**
     * Loads data (calls fetch on either model or collection).
     *
     * This method sets an internal boolean flag to prevent consecutive fetch
     * operations. Call {@link Core/Context#resetLoadFlag} to reset the
     * context's state.
     *
     * @param {Object} [options] A hash of options passed to
     *   collection/model's fetch method.
     * @param {boolean} [options.fetch] `true` to always fetch the data.
     * @memberOf Core/Context
     * @instance
     */
    loadData: function(options) {
        options = options || {};
        if (!options.forceFetch && !shouldFetch.call(this)) {
            return;
        }

        delete options.forceFetch;

        var objectToFetch,
            modelId = this.get("modelId"),
            module = this.get("module"),
            defaultOrdering = (SUGAR.App.config.orderByDefaults && module) ? SUGAR.App.config.orderByDefaults[module] : null;

        objectToFetch = modelId ? this.get("model") : this.get("collection");

        // If we have an orderByDefaults in the config, and this is a bean collection,
        // try to use ordering from there (only if orderBy is not already set.)
        if (defaultOrdering &&
            objectToFetch instanceof BeanCollection &&
            !objectToFetch.orderBy)
        {
            objectToFetch.orderBy = defaultOrdering;
        }

        // TODO: Figure out what to do when models are not
        // instances of Bean or BeanCollection. No way to fetch.
        if (objectToFetch && (objectToFetch instanceof Bean ||
            objectToFetch instanceof BeanCollection)) {

            if (this.get('dataView') && _.isString(this.get('dataView'))) {
                objectToFetch.setOption('view', this.get('dataView'));
            }

            if (this.get('fields')) {
                objectToFetch.setOption('fields', this.get('fields'));
            }

            if (this.get('limit')) {
                objectToFetch.setOption('limit', this.get('limit'));
            }

            if (this.get('module_list')) {
                objectToFetch.setOption('module_list', this.get('module_list'));
            }

            // Track models that user is actively viewing
            if (this.get('viewed')) {
                objectToFetch.setOption('viewed', this.get('viewed'));
            }

            options.context = this;

            if (this.get("skipFetch") !== true) {
                objectToFetch.fetch(options);
            }

            this._fetchCalled = true;
        } else {
            SUGAR.App.logger.warn("Skipping fetch because model is not Bean, Bean Collection, or it is not defined, module: " + this.get("module"));
        }
    },

    /**
     * Creates child context for each `link` of each `collection` field
     * present on the bean.
     *
     * @private
     * @memberOf Core/Context
     * @instance
     */
    _populateRelatedContexts: function () {
        if (!this.get('collection')) {
            return;
        }

        this.get('collection').each(function(bean) {
            var collectionFields = bean.fieldsOfType('collection');
            if (!_.isEmpty(collectionFields)) {
                _.each(collectionFields, function(field) {
                    var links = field.links;
                    if (_.isString(links)) {
                        links = [links];
                    }

                    var linkCollections = {};
                    _.each(links, function(link) {
                        var rc = this.getChildContext({link: link});
                        rc.prepare();
                    }, this);
                }, this);
            }
        }, this);

        this._relatedCollectionsPopulated = true;
    },

    _shouldFetch: function() {
        if (!SUGAR.App.config.sidecarCompatMode) {
            SUGAR.App.logger.error('Core.Context#_shouldFetch is a private method that you are not allowed ' +
                'to access. Please use only the public API.');
            return;
        }

        SUGAR.App.logger.warn('Core.Context#_shouldFetch is a private method that you should not access. ' +
            'You will NOT be allowed to access it in the next release. Please update your code to rely on the public ' +
            'API only.');

        return shouldFetch.call(this);
    },

    /**
     * Refreshes the context's data and refetches the new data if
     * the `skipFetch` attribute is `true`.
     *
     * @param {Object} [options] Options for {@link Core/Context#loadData} and
     *   the `reload` event.
     * @fires reload
     * @memberOf Core/Context
     * @instance
     */
    reloadData: function(options) {
        options = options || {};

        this.resetLoadFlag(options);
        this.loadData(options);

        /**
         * Triggered before and after the context is reloaded.
         * @param {Core/Context} this The context instance where the event is
         *   triggered.
         * @param {Object} [options] The options passed during
         *   {@link Core/Context#reloadData} call.
         * @memberOf Core/Context
         * @event reload
         */
        this.trigger('reload', this, options);
    },

    /**
     * Checks if data has been successfully loaded.
     *
     * @return {boolean} `true` if data has been fetched, `false` otherwise.
     * @memberOf Core/Context
     * @instance
     */
    isDataFetched: function() {
        var objectToFetch = this.get('modelId') ? this.get('model') : this.get('collection');
        return this._fetchCalled || (objectToFetch && !!objectToFetch.dataFetched);
    },
});

module.exports = Context;