add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / mixin / Container.js

/**\r
 * @private\r
 * Common methods for both classic & modern containers\r
 */\r
Ext.define('Ext.mixin.Container', {\r
    extend: 'Ext.Mixin',\r
\r
    mixinConfig: {\r
        id: 'container'\r
    },\r
\r
    /**\r
     * @property {Boolean} isContainer\r
     * `true` in this class to identify an object as an instantiated Container, or subclass thereof.\r
     */\r
    isContainer: true,\r
\r
    config: {\r
        /**\r
         * @cfg {Boolean} referenceHolder\r
         * If `true`, this container will be marked as being a point in the hierarchy where\r
         * references to items with a specified `reference` config will be held. The container\r
         * will automatically become a referenceHolder if a {@link #controller} is specified.\r
         *\r
         * See the introductory docs for {@link Ext.container.Container} for more information\r
         * about references & reference holders.\r
         */\r
        referenceHolder: false\r
    },\r
\r
    /**\r
     * Returns an object holding the descendants of this view keyed by their\r
     * `{@link Ext.Component#cfg-reference reference}`. This object should not be held\r
     * past the scope of the function calling this method. It will not be valid if items\r
     * are added or removed from this or any sub-container.\r
     *\r
     * The intended usage is shown here (assume there are 3 components with reference\r
     * values of "foo", "bar" and "baz" at some level below this container):\r
     *\r
     *      onClick: function () {\r
     *          var refs = this.getReferences();\r
     *\r
     *          // using "refs" we can access any descendant by its "reference"\r
     *\r
     *          refs.foo.getValue() + refs.bar.getValue() + refs.baz.getValue();\r
     *      }\r
     *\r
     * If `this` component has a `{@link Ext.Component#cfg-reference reference}` assigned\r
     * to it, that is **not** included in this object. That reference is understood to\r
     * belong to the ancestor container configured as the `referenceHolder`.\r
     *\r
     * @return {Object} An object with each child reference. This will be `null` if this\r
     * container has no descendants with a `{@link Ext.Component#cfg-reference reference}`\r
     * specified.\r
     * @since 5.0.0\r
     */\r
    getReferences: function () {\r
        Ext.ComponentManager.fixReferences();\r
        return this.refs || null;\r
    },\r
\r
    /**\r
     * Gets a reference to the component with the specified {@link #reference} value.\r
     *\r
     * The method is a short-hand for the {@link #lookupReference} method.\r
     *\r
     * @param {String} key The name of the reference to lookup.\r
     * @return {Ext.Component} The referenced component or `null` if it is not found.\r
     * @since 6.0.1\r
     */\r
    lookup: function (key) {\r
        var refs = this.getReferences();\r
        return (refs && refs[key]) || null;\r
    },\r
\r
    /**\r
     * Gets a reference to the component with the specified {@link #reference} value.\r
     *\r
     * The {@link #lookup} method is a short-hand version of this method.\r
     *\r
     * @param {String} key The name of the reference to lookup.\r
     * @return {Ext.Component} The referenced component or `null` if it is not found.\r
     * @since 5.0\r
     */\r
    lookupReference: function (key) {\r
        return this.lookup(key);\r
    },\r
\r
    privates: {\r
        /**\r
         * Sets up a component reference.\r
         * @param {Ext.Component} component The component to reference.\r
         * @private\r
         */\r
        attachReference: function (component) {\r
            var me = this,\r
                key, refs;\r
\r
            // Cleaning all this up later anyway\r
            if (me.destroying || me.destroyed) {\r
                return;\r
            }\r
\r
            refs = me.refs || (me.refs = {});\r
            key = component.referenceKey;\r
            //<debug>\r
            if (refs[key] && refs[key] !== component) {\r
                Ext.log.warn('Duplicate reference: "' + key + '" on ' + me.id);\r
            }\r
            //</debug>\r
            refs[key] = component;\r
        },\r
\r
        /**\r
         * Clear a component reference.\r
         * @param {Ext.Component} component The component to remove.\r
         * @private\r
         */\r
        clearReference: function (component) {\r
            var refs = this.refs,\r
                key = component.referenceKey;\r
\r
            if (refs && key) {\r
                // viewModelKey would be better placed in app.Container however\r
                // it's not really worth introducing a second method call to clear\r
                // a single property.\r
                component.viewModelKey = component.referenceKey = refs[key] = null;\r
            }\r
        },\r
\r
        containerOnAdded: function(component, instanced) {\r
            // We have been added to a container, we may have child references\r
            // or be a reference ourself. At this point we have no way of knowing if \r
            // our references are correct, so trigger a fix.\r
            if (instanced) {\r
                Ext.ComponentManager.markReferencesDirty();\r
            }\r
        },\r
\r
        containerOnRemoved: function(destroying) {\r
            var refHolder;\r
        \r
            // If we're destroying this will get cleaned up anyway\r
            if (!destroying) {\r
                refHolder = this.lookupReferenceHolder();\r
                if (refHolder) {\r
                    // Clear any references here, they will be reset after the \r
                    // next call to lookupReference after being marked dirty.\r
                    // It's easier to wipe & re-establish them than attempt to \r
                    // track what changed and prune the collection\r
                    \r
                    Ext.ComponentManager.markReferencesDirty();\r
                    refHolder.clearReferences();\r
                }\r
            }\r
        },  \r
\r
        /**\r
         * Invalidates the references collection. Typically called when\r
         * removing a container from this container, since it's difficult\r
         * to know what references got removed.\r
         *\r
         * @private\r
         */\r
        clearReferences: function () {\r
            this.refs = null;\r
        },\r
\r
        initContainerInheritedState: function(inheritedState, inheritedStateInner) {\r
            var me = this,\r
                controller = me.getController(),\r
                session = me.getSession(),\r
                // Don't instantiate it here, we just want to know whether we\r
                // were configured with a VM\r
                viewModel = me.getConfig('viewModel', true),\r
                reference = me.getReference(),\r
                referenceHolder = me.getReferenceHolder();\r
\r
\r
\r
            if (controller) {\r
                inheritedState.referenceHolder = controller;\r
                referenceHolder = true;\r
            } else if (referenceHolder) {\r
                inheritedState.referenceHolder = me;\r
            }\r
\r
            if (referenceHolder) {\r
                inheritedState.referencePath = '';\r
            } else if (reference && me.isParentReference) {\r
                inheritedState.referencePath = me.referenceKey + '.';\r
            }\r
\r
            if (session) {\r
                inheritedState.session = session;\r
            }\r
\r
            if (viewModel) {\r
                inheritedState.viewModelPath = '';\r
            } else if (reference && me.isParentReference) {\r
                inheritedState.viewModelPath = me.viewModelKey + '.';\r
            }\r
        },\r
        \r
        setupReference: function(reference) {\r
            var len;\r
\r
            if (reference && reference.charAt(len = reference.length - 1) === '>') {\r
                this.isParentReference = true;\r
                reference = reference.substring(0, len);\r
            }\r
\r
            //<debug>\r
            if (reference && !Ext.validIdRe.test(reference)) {\r
                Ext.Error.raise('Invalid reference "' + reference + '" for ' + this.getId() +\r
                    ' - not a valid identifier');\r
            }\r
            //</debug>\r
\r
            return reference;\r
        }\r
    }\r
});