issue/2760 Added ChildViews API for rendering control (v5.7.0)

src/core/js/adapt.js

@@ -140,20 +140,22 @@ define([
     }
 
     /**
-     * Allows a selector to be passed in and Adapt will navigate to this element
+     * Allows a selector to be passed in and Adapt will navigate to this element. Resolves
+     * asynchronously when the element has been navigated to.
      * @param {string} selector CSS selector of the Adapt element you want to navigate to e.g. `".co-05"`
-     * @param {object} [settings={}] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
-     * You may also include a `replace` property that you can set to `true` if you want to update the URL without creating an entry in the browser's history.
+     * @param {Object} [settings] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
+     * @param {Object} [settings.replace=false] Set to `true` if you want to update the URL without creating an entry in the browser's history.
      */
-    navigateToElement() {}
+    async navigateToElement() {}
 
     /**
-     * Allows a selector to be passed in and Adapt will scroll to this element
+     * Allows a selector to be passed in and Adapt will scroll to this element. Resolves
+     * asynchronously when the element has been navigated/scrolled to.
      * @param {string} selector CSS selector of the Adapt element you want to navigate to e.g. `".co-05"`
-     * @param {object} [settings={}] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
-     * You may also include a `replace` property that you can set to `true` if you want to update the URL without creating an entry in the browser's history.
+     * @param {Object} [settings={}] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
+     * @param {Object} [settings.replace=false] Set to `true` if you want to update the URL without creating an entry in the browser's history.
      */
-    scrollTo() {}
+    async scrollTo() {}
 
     /**
      * Used to register models and views with `Adapt.store`
@@ -343,7 +345,9 @@ define([
       }
 
       const foundView = idPathToView.reduce((view, currentId) => {
-        return view && view.childViews && view.childViews[currentId];
+        if (!view) return;
+        const childViews = view.getChildViews();
+        return childViews && childViews.find(view => view.model.get('_id') === currentId);
       }, this.parentView);
 
       return foundView;
@@ -398,8 +402,10 @@ define([
     async remove() {
       const currentView = this.parentView;
       if (currentView) {
-        currentView.model.setOnChildren('_isReady', false);
-        currentView.model.set('_isReady', false);
+        currentView.model.setOnChildren({
+          '_isReady': false,
+          '_isRendered': false
+        });
       }
       this.trigger('preRemove', currentView);
       await this.wait.queue();

src/core/js/childEvent.js

@@ -0,0 +1,104 @@
+define([
+  'core/js/adapt'
+], function(Adapt) {
+
+  /**
+   * Event object triggered for controlling child view rendering.
+   * Sent with 'view:addChild' and 'view:requestChild' events.
+   * All plugins receive the same object reference in their event handler and
+   * as such, this object becomes a place of consensus for plugins to decide how
+   * to handle rendering for this child.
+   */
+  class ChildEvent extends Backbone.Controller {
+
+    /**
+     * @param {string} type Event type
+     * @param {AdaptView} target Parent view
+     * @param {AdaptModel} model Child model
+     */
+    initialize(type, target, model) {
+      /** @type {string} */
+      this.type = type;
+      /** @type {AdaptView} */
+      this.target = target;
+      /** @type {boolean} Force the child model to render */
+      this.isForced = false;
+      /** @type {boolean} Stop rendering before the child model */
+      this.isStoppedImmediate = false;
+      /** @type {boolean} Stop rendering after the child model */
+      this.isStoppedNext = false;
+      /** @type {boolean} Contains a model to render in response to a requestChild event */
+      this.hasRequestChild = false;
+      this._model = model;
+    }
+
+    /**
+     * Get the model to be rendered.
+     * @returns {AdaptModel}
+     */
+    get model() {
+      return this._model;
+    }
+
+    /**
+     * Set the model to render in response to a 'view:requestChild' event.
+     * @param {AdaptModel}
+     */
+    set model(model) {
+      if (this.type !== 'requestChild') {
+        Adapt.log.warn(`Cannot change model in ${this.type} event.`);
+        return;
+      }
+      if (this._model) {
+        Adapt.log.warn(`Cannot inject two models in one sitting. ${model.get('_id')} attempts to overwrite ${this._model.get('_id')}`);
+        return;
+      }
+      this._model = model;
+      this.hasRequestChild = true;
+    }
+
+    /**
+     * Reset all render stops.
+     */
+    reset() {
+      this.isStoppedImmediate = false;
+      this.isStoppedNext = false;
+    }
+
+    /**
+     * Force model to render.
+     */
+    force() {
+      this.isForced = true;
+    }
+
+    /**
+     * General stop. Stop immediately or stop next with flag to false.
+     * @param {boolean} [immediate=true] Flag to stop immediate or next.
+     */
+    stop(immediate = true) {
+      if (!immediate) {
+        return this.stopNext();
+      }
+      this.isStoppedImmediate = true;
+    }
+
+    /**
+     * Shortcut to stop(false). Stop the render after the contained model is rendered.
+     */
+    stopNext() {
+      this.isStoppedNext = true;
+    }
+
+    /**
+     * Trigger an event to signify that a final decision has been reached.
+     */
+    close() {
+      this.trigger('closed');
+    }
+
+  }
+
+  return ChildEvent;
+
+});

src/core/js/models/adaptModel.js

@@ -30,6 +30,7 @@ define([
         _canShowFeedback: true,
         _classes: '',
         _canReset: false,
+        _canRequestChild: false,
         _isComplete: false,
         _isInteractionComplete: false,
         _isA11yRegionEnabled: false,
@@ -39,6 +40,7 @@ define([
         _isResetOnRevisit: false,
         _isAvailable: true,
         _isOptional: false,
+        _isRendered: false,
         _isReady: false,
         _isVisible: true,
         _isLocked: false,
@@ -208,16 +210,30 @@ define([
       }
     }
 
-    checkReadyStatus() {
+    /**
+     * Checks if any child models which have been _isRendered are not _isReady.
+     * If all rendered child models are marked ready then this model will be
+     * marked _isReady: true as well.
+     * @param {AdaptModel} [model]
+     * @param {boolean} [value]
+     * @returns {boolean}
+     */
+    checkReadyStatus(model, value) {
+      if (value === false) {
+        // Do not respond to _isReady: false as _isReady is unset throughout
+        // the rendering process
+        return false;
+      }
       // Filter children based upon whether they are available
-      // Check if any return _isReady:false
+      // Check if any _isRendered: true children return _isReady: false
       // If not - set this model to _isReady: true
       const children = this.getAvailableChildModels();
-      if (children.find(child => child.get('_isReady') === false)) {
-        return;
+      if (children.find(child => child.get('_isReady') === false && child.get('_isRendered'))) {
+        return false;
       }
 
       this.set('_isReady', true);
+      return true;
     }
 
     setCompletionStatus() {
@@ -734,6 +750,19 @@ define([
       this.checkLocking();
     }
 
+    /**
+     * Used before a model is rendered to determine if it should be reset to its
+     * default values.
+     */
+    checkIfResetOnRevisit() {
+      var isResetOnRevisit = this.get('_isResetOnRevisit');
+      if (!isResetOnRevisit) {
+        return;
+      }
+      // If reset is enabled set defaults
+      this.reset(isResetOnRevisit);
+    }
+
     /**
      * Clones this model and all managed children returning a new branch.
      * Assign new unique ids to each cloned model.

src/core/js/router.js

@@ -145,7 +145,7 @@ define([
         // Allow navigation.
         this.model.set('_canNavigate', true, { pluginName: 'adapt' });
         // Scroll to element
-        Adapt.navigateToElement('.' + id, { replace: true });
+        Adapt.navigateToElement('.' + id, { replace: true, duration: 400 });
         return;
       }
 
@@ -319,12 +319,14 @@ define([
     }
 
     /**
-     * Allows a selector to be passed in and Adapt will navigate to this element
+     * Allows a selector to be passed in and Adapt will navigate to this element. Resolves
+     * asynchronously when the element has been navigated to.
+     * Backend for Adapt.navigateToElement
      * @param {string} selector CSS selector of the Adapt element you want to navigate to e.g. `".co-05"`
-     * @param {object} [settings] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
-     * You may also include a `replace` property that you can set to `true` if you want to update the URL without creating an entry in the browser's history.
+     * @param {Object} [settings] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
+     * @param {Object} [settings.replace=false] Set to `true` if you want to update the URL without creating an entry in the browser's history.
      */
-    navigateToElement(selector, settings = {}) {
+    async navigateToElement(selector, settings = {}) {
       // Removes . symbol from the selector to find the model
       const currentModelId = selector.replace(/\./g, '');
       const currentModel = Adapt.findById(currentModelId);
@@ -338,17 +340,20 @@ define([
         return Adapt.scrollTo(selector, settings);
       }
 
-      // If the element is on another page navigate and wait until pageView:ready is fired
-      // Then scrollTo element
-      Adapt.once('contentObjectView:ready', _.debounce(() => {
-        this.model.set('_shouldNavigateFocus', true, { pluginName: 'adapt' });
-        Adapt.scrollTo(selector, settings);
-      }, 1));
-
       const shouldReplaceRoute = settings.replace || false;
 
-      this.model.set('_shouldNavigateFocus', false, { pluginName: 'adapt' });
-      this.navigate('#/id/' + pageId, { trigger: true, replace: shouldReplaceRoute });
+      await new Promise(resolve => {
+        // If the element is on another page navigate and wait until pageView:ready is fired
+        // Then scrollTo element
+        Adapt.once('contentObjectView:ready', _.debounce(async () => {
+          this.model.set('_shouldNavigateFocus', true, { pluginName: 'adapt' });
+          await Adapt.scrollTo(selector, settings);
+          resolve();
+        }, 1));
+
+        this.model.set('_shouldNavigateFocus', false, { pluginName: 'adapt' });
+        this.navigate('#/id/' + pageId, { trigger: true, replace: shouldReplaceRoute });
+      });
     }
 
     get(...args) {

src/core/js/scrolling.js

@@ -100,7 +100,24 @@ define([
       });
     }
 
-    scrollTo(selector, settings = {}) {
+    /**
+     * Allows a selector to be passed in and Adapt will scroll to this element. Resolves
+     * asynchronously when the element has been navigated/scrolled to.
+     * Backend for Adapt.scrollTo
+     * @param {string} selector CSS selector of the Adapt element you want to navigate to e.g. `".co-05"`
+     * @param {Object} [settings={}] The settings for the `$.scrollTo` function (See https://github.com/flesler/jquery.scrollTo#settings).
+     * @param {Object} [settings.replace=false] Set to `true` if you want to update the URL without creating an entry in the browser's history.
+     */
+    async scrollTo(selector, settings = {}) {
+
+      const currentModelId = selector.replace(/\./g, '');
+      const currentModel = Adapt.findById(currentModelId);
+      if (!currentModel) return;
+
+      if (!currentModel.get('_isRendered') || !currentModel.get('_isRendered')) {
+        await Adapt.parentView.renderTo(currentModelId);
+      }
+
       // Get the current location - this is set in the router
       const location = (Adapt.location._contentType) ?
         Adapt.location._contentType : Adapt.location._currentLocation;
@@ -136,10 +153,13 @@ define([
 
       // Trigger an event after animation
       // 300 milliseconds added to make sure queue has finished
-      _.delay(() => {
-        Adapt.a11y.focusNext(selector);
-        Adapt.trigger(`${location}:scrolledTo`, selector);
-      }, settings.duration + 300);
+      await new Promise(resolve => {
+        _.delay(() => {
+          Adapt.a11y.focusNext(selector);
+          Adapt.trigger(`${location}:scrolledTo`, selector);
+          resolve();
+        }, settings.duration + 300);
+      });
     }
 
   }