diff --git a/js/views/articleView.js b/js/views/articleView.js index 4c3ba853..939aaf03 100644 --- a/js/views/articleView.js +++ b/js/views/articleView.js @@ -1,6 +1,21 @@ +/** + * @file Article View - Renders an article within a page + * @module core/js/views/articleView + * @description Renders an article content object containing one or more blocks. + * Registered as the 'article' component type. Provides standard Adapt class + * composition including visibility, hidden, complete, and optional state flags. + */ import components from 'core/js/components'; import AdaptView from 'core/js/views/adaptView'; +/** + * @class ArticleView + * @classdesc View for article content objects. An article is a top-level grouping + * within a page and contains one or more blocks. Registered as the default 'article' + * component view. All rendering and child-view management is provided by + * {@link module:core/js/views/adaptView~AdaptView}. + * @extends AdaptView + */ class ArticleView extends AdaptView { className() { diff --git a/js/views/blockView.js b/js/views/blockView.js index 9ffe8b12..bf0d4a6f 100644 --- a/js/views/blockView.js +++ b/js/views/blockView.js @@ -1,6 +1,21 @@ +/** + * @file Block View - Renders a block within an article + * @module core/js/views/blockView + * @description Renders a block content object containing one or more components. + * Registered as the 'block' component type. Components inside the block are + * laid out according to each component's `_layout` attribute. + */ import components from 'core/js/components'; import AdaptView from 'core/js/views/adaptView'; +/** + * @class BlockView + * @classdesc View for block content objects. A block is a row-level grouping + * within an article and contains one or more components. Registered as the + * default 'block' component view. All rendering and child-view management is + * provided by {@link module:core/js/views/adaptView~AdaptView}. + * @extends AdaptView + */ class BlockView extends AdaptView { className() { diff --git a/js/views/componentView.js b/js/views/componentView.js index 9d4a568d..1646f674 100644 --- a/js/views/componentView.js +++ b/js/views/componentView.js @@ -1,6 +1,23 @@ +/** + * @file Component View - Base view for all Adapt component types + * @module core/js/views/componentView + * @description Base class for all Adapt presentation and question component views. + * Provides optional ARIA region labelling, inview scroll-based completion tracking + * via {@link ComponentView#setupInviewCompletion}, and standard remove lifecycle + * cleanup. Registered as the 'component' type. + */ import logging from 'core/js/logging'; import AdaptView from 'core/js/views/adaptView'; +/** + * @class ComponentView + * @classdesc Base view for Adapt components. All presentation and question component + * views extend this class. Provides: + * - Optional ARIA `role="region"` and `aria-labelledby` when `_isA11yRegionEnabled` is set + * - Inview-based completion via {@link ComponentView#setupInviewCompletion} + * - Automatic inview listener cleanup on removal + * @extends AdaptView + */ class ComponentView extends AdaptView { attributes() { @@ -38,6 +55,7 @@ class ComponentView extends AdaptView { * @param {function} [callback] Allows you to specify what function is called when the component has been viewed, should * you want to perform additional checks before setting the component to completed - see adapt-contrib-assessmentResults * for an example. Defaults to `view.setCompletionStatus` if not specified. + * @returns {void} */ setupInviewCompletion(inviewElementSelector = '.component__inner', callback = this.setCompletionStatus) { this.$inviewElement = this.$(inviewElementSelector); diff --git a/js/views/contentObjectView.js b/js/views/contentObjectView.js index d2e82ba5..012aaf57 100644 --- a/js/views/contentObjectView.js +++ b/js/views/contentObjectView.js @@ -1,3 +1,12 @@ +/** + * @file Content Object View - Base view for page and menu content objects + * @module core/js/views/contentObjectView + * @description Renders top-level Adapt content objects (pages and menus). Manages the + * async ready lifecycle, animated fade-in, scroll position reset on load, and the + * full hierarchy of child article/block/component views. Fires prefixed events for + * both the concrete type (e.g. `pageView:ready`) and the base type + * (`contentObjectView:ready`) so plugins can target either level. + */ import Adapt from 'core/js/adapt'; import wait from 'core/js/wait'; import AdaptView from 'core/js/views/adaptView'; @@ -5,6 +14,24 @@ import ReactDOM from 'react-dom'; import data from 'core/js/data'; import router from 'core/js/router'; +/** + * @class ContentObjectView + * @classdesc Base view for Adapt content objects. Handles the full render lifecycle: + * template or JSX rendering, async ready state (triggered by `model.change:_isReady`), + * scroll-to-top, velocity fade-in animation, and recursive child-view removal via + * ReactDOM or standard DOM cleanup. Subclassed by {@link module:core/js/views/pageView~PageView} + * and menu views. + * @extends AdaptView + * @fires contentObjectView:preRender + * @fires contentObjectView:render + * @fires contentObjectView:postRender + * @fires contentObjectView:preReady + * @fires contentObjectView:ready + * @fires contentObjectView:postReady + * @fires contentObjectView:preRemove + * @fires contentObjectView:remove + * @fires contentObjectView:postRemove + */ export default class ContentObjectView extends AdaptView { attributes() { @@ -34,6 +61,13 @@ export default class ContentObjectView extends AdaptView { this._loadingErrorTimeout = setTimeout(() => data.logReadyError(this), 10000); } + /** + * Renders the view using either a JSX template (via `this.changed()`) or a + * Handlebars template, then defers a `postRender` call. Fires the + * `preRender`, `render`, and `postRender` lifecycle events for both the + * concrete type (e.g. `pageView:render`) and `contentObjectView:render`. + * @returns {ContentObjectView} This view instance + */ render() { const type = this.constructor.type; Adapt.trigger(`${type}View:preRender contentObjectView:preRender view:preRender`, this); @@ -97,8 +131,14 @@ export default class ContentObjectView extends AdaptView { } /** - * Force render up to specified id. Resolves when views are ready. - * @param {string} id + * Force-renders descendant views down to the specified model ID. All models + * between the content object root and `id` (inclusive) are forced to render + * even when lazy-rendering would normally skip them. + * @param {string} id - The `_id` of the target descendant model + * @returns {Promise} Resolves once the target view is rendered and ready + * @throws {Error} If `id` is not a descendant of this content object + * @throws {Error} If any model up to `id` is locked + * @throws {Error} If the target view fails to reach a rendered and ready state */ async renderTo(id) { const isRenderToSelf = (id === this.model.get('_id')); @@ -141,6 +181,14 @@ export default class ContentObjectView extends AdaptView { this.trigger('preRemove'); } + /** + * Removes the view and all descendant views from the DOM. Unmounts React + * components via `ReactDOM.unmountComponentAtNode` when JSX is in use, + * otherwise removes descendant views in reverse order. Fires the `remove` + * and deferred `postRemove` lifecycle events. Uses {@link module:core/js/wait} + * to ensure removal completes before the next queued operation. + * @returns {ContentObjectView} This view instance + */ remove() { const type = this.constructor.type; this.preRemove(); diff --git a/js/views/menuItemView.js b/js/views/menuItemView.js index 64241264..31e779e8 100644 --- a/js/views/menuItemView.js +++ b/js/views/menuItemView.js @@ -1,5 +1,20 @@ +/** + * @file Menu Item View - Renders a single menu item within a parent menu + * @module core/js/views/menuItemView + * @description Renders a menu item card representing a child content object + * (page or nested menu) inside a parent menu. Checks completion and interaction + * completion status before rendering, and signals ready only after all images + * within the item have loaded. + */ import AdaptView from 'core/js/views/adaptView'; +/** + * @class MenuItemView + * @classdesc Renders a clickable menu item card for a child content object. Applies + * state CSS classes for visited, complete, locked, and optional states. Defers the + * ready signal until all embedded images have loaded via `imageready`. + * @extends AdaptView + */ class MenuItemView extends AdaptView { attributes() { diff --git a/js/views/menuView.js b/js/views/menuView.js index dd5cd1f3..72d6021d 100644 --- a/js/views/menuView.js +++ b/js/views/menuView.js @@ -1,6 +1,23 @@ +/** + * @file Menu View - Renders a menu-type content object + * @module core/js/views/menuView + * @description Extends {@link module:core/js/views/contentObjectView~ContentObjectView} + * for menu content objects. Renders child content objects as + * {@link module:core/js/views/menuItemView~MenuItemView} instances inside + * `.js-children`. The child view class is currently fixed; making it configurable + * is a planned improvement. + */ import ContentObjectView from 'core/js/views/contentObjectView'; import MenuItemView from 'core/js/views/menuItemView'; +/** + * @class MenuView + * @classdesc View for menu-type content objects. Displays child content objects + * (pages or nested menus) as a list of {@link module:core/js/views/menuItemView~MenuItemView} + * cards inside `.js-children`. All ready-state and lifecycle handling is inherited + * from {@link module:core/js/views/contentObjectView~ContentObjectView}. + * @extends ContentObjectView + */ class MenuView extends ContentObjectView {} Object.assign(MenuView, { diff --git a/js/views/pageView.js b/js/views/pageView.js index 32058510..85c646d7 100644 --- a/js/views/pageView.js +++ b/js/views/pageView.js @@ -1,8 +1,30 @@ +/** + * @file Page View - Renders a page-type content object + * @module core/js/views/pageView + * @description Extends {@link module:core/js/views/contentObjectView~ContentObjectView} + * for page content objects. Registered as the 'page' component type. Cleans up + * any injected page-label element when the view is removed. + */ import components from 'core/js/components'; import ContentObjectView from 'core/js/views/contentObjectView'; +/** + * @class PageView + * @classdesc View for page-type content objects. A page is the primary learner-facing + * screen and contains one or more articles. This view adds cleanup of any page-label + * element on removal; all other lifecycle behaviour is inherited from + * {@link module:core/js/views/contentObjectView~ContentObjectView}. + * @extends ContentObjectView + */ class PageView extends ContentObjectView { + /** + * Removes the page view from the DOM. Cleans up the injected + * `$pageLabel` element (added by the page heading plugin) before + * delegating full removal to + * {@link module:core/js/views/contentObjectView~ContentObjectView#remove}. + * @returns {PageView} This view instance + */ remove() { if (this.$pageLabel) { this.$pageLabel.remove(); diff --git a/js/views/questionView.js b/js/views/questionView.js index e24aa1ca..e3ff896b 100644 --- a/js/views/questionView.js +++ b/js/views/questionView.js @@ -1,3 +1,13 @@ +/** + * @file Question View - Base view for interactive question components + * @module core/js/views/questionView + * @description Base class for all Adapt question component views. Orchestrates the + * full question lifecycle: setup, submission, marking, feedback display, answer + * reset, and correct-answer reveal. Business logic is delegated to + * {@link module:core/js/models/questionModel~QuestionModel} where available. + * A backwards-compatibility layer (`ViewOnlyQuestionViewCompatibilityLayer`) supports + * components that have not yet migrated question logic to a model. + */ import Adapt from 'core/js/adapt'; import ComponentView from 'core/js/views/componentView'; import ButtonsView from 'core/js/views/buttonsView'; @@ -8,6 +18,21 @@ import data from 'core/js/data'; import location from 'core/js/location'; import 'core/js/models/questionModel'; +/** + * @class QuestionView + * @classdesc Base view for question components. Coordinates button state updates, + * the submit pipeline (canSubmit → mark → score → feedback → updateButtons), + * answer reset, and correct-answer reveal. Delegates to + * {@link module:core/js/models/questionModel~QuestionModel} for business logic + * where available; legacy view-only components are supported by + * `ViewOnlyQuestionViewCompatibilityLayer`. + * @extends ComponentView + * @fires questionView:submitted + * @fires questionView:showFeedback + * @fires questionView:disabledFeedback + * @fires questionView:showInstructionError + * @fires questionView:recordInteraction + */ class QuestionView extends ComponentView { className() { @@ -38,7 +63,7 @@ class QuestionView extends ComponentView { /** * Used to determine whether the learner is allowed to interact with the question component or not. - * @return {Boolean} + * @returns {Boolean} * @deprecated since v6.0.5 please use this.model.isInteractive, this.model.get('_shouldShowMarking') or this.model.shouldShowMarking */ isInteractive() { @@ -64,7 +89,13 @@ class QuestionView extends ComponentView { this.setupQuestion(); } - // Used in the question view to disabled the question when _isEnabled has been set to false + /** + * Toggles the `is-disabled` CSS class on the component widget and calls + * `disableQuestion` or `enableQuestion` in response to `_isEnabled` changing. + * @param {Backbone.Model} model - The question model + * @param {boolean} changedAttribute - The new value of `_isEnabled` + * @returns {void} + */ onEnabledChanged(model, changedAttribute) { // If isEnabled == false add disabled class @@ -79,10 +110,20 @@ class QuestionView extends ComponentView { } - // Used by the question to disable the question during submit and complete stages + /** + * Called when the question is disabled (e.g. during submit or after completion). + * Override in component views to prevent learner interaction. + * @protected + * @returns {void} + */ disableQuestion() {} - // Used by the question to enable the question during interactions + /** + * Called when the question is re-enabled (e.g. after a reset). + * Override in component views to restore learner interaction. + * @protected + * @returns {void} + */ enableQuestion() {} /** @@ -124,7 +165,12 @@ class QuestionView extends ComponentView { */ resetQuestionOnRevisit(type) {} - // Left blank for question setup - should be used instead of preRender + /** + * Override this method to perform question-specific setup before rendering. + * Prefer this over overriding `preRender` in question components. + * @protected + * @returns {void} + */ setupQuestion() {} // Calls default methods to setup after the question is rendered @@ -133,7 +179,12 @@ class QuestionView extends ComponentView { this.onQuestionRendered(); } - // Used to setup buttonsView and sets up the internal events for the question + /** + * Creates a {@link module:core/js/views/buttonsView~ButtonsView} and attaches + * it to `.btn__container`. Listens for `buttons:stateUpdate` to drive the + * question state machine. + * @returns {void} + */ addButtonsView() { this.buttonsView = new ButtonsView({ model: this.model, el: this.$('.btn__container') }); @@ -141,6 +192,12 @@ class QuestionView extends ComponentView { } + /** + * Routes a {@link module:core/js/enums/buttonStateEnum~BUTTON_STATE} value + * from `ButtonsView` to the appropriate question handler method. + * @param {string} buttonState - A `BUTTON_STATE` enum value + * @returns {void} + */ onButtonStateUpdate(buttonState) { switch (buttonState) { @@ -163,10 +220,26 @@ class QuestionView extends ComponentView { } - // Blank method used just like postRender is for presentational components + /** + * Called after the question has been rendered and the buttons view created. + * Override in component views for any post-render DOM setup, equivalent to + * `postRender` for presentational components. + * @protected + * @returns {void} + */ onQuestionRendered() {} - // Triggered when the submit button is clicked + /** + * Runs the full submission pipeline: validates input, records attempts, marks + * the question, calculates score, checks completion, shows marking and feedback, + * updates button state, and triggers `questionView:submitted`. + * @fires questionView:submitted + * @fires questionView:showFeedback + * @fires questionView:disabledFeedback + * @fires questionView:showInstructionError + * @fires questionView:recordInteraction + * @returns {void} + */ onSubmitClicked() { // canSubmit is setup in questions and should return a boolean // If the question stops the user form submitting - show instruction error @@ -238,29 +311,57 @@ class QuestionView extends ComponentView { this.recordInteraction(); } + /** + * Fires the `questionView:showInstructionError` event so plugins (e.g. tutor) + * can display a validation message when the learner tries to submit without + * making a selection. + * @fires questionView:showInstructionError + * @returns {void} + */ showInstructionError() { Adapt.trigger('questionView:showInstructionError', this); } - // Blank method for question to fill out when the question cannot be submitted + /** + * Called when `canSubmit` returns false (e.g. no answer selected). + * Override in component views to provide additional validation feedback. + * @protected + * @returns {void} + */ onCannotSubmit() {} - // Blank method for question to fill out when the question was successfully submitted + /** + * Called after a successful submission has been fully processed. + * Override in component views for any post-submit UI updates. + * @protected + * @returns {void} + */ onSubmitted() {} - // Used to set _isEnabled and _isSubmitted on the model - // Also adds a 'submitted' class to the widget + /** + * Delegates to `model.setQuestionAsSubmitted()` and adds the `is-submitted` + * CSS class to the component widget. + * @returns {void} + */ setQuestionAsSubmitted() { this.model.setQuestionAsSubmitted(); this.$('.component__widget').addClass('is-submitted'); } - // This is important and should give the user feedback on how they answered the question - // Normally done through ticks and crosses by adding classes + /** + * Override in component views to display answer marking (e.g. ticks and + * crosses) on the question after submission or when showing the user answer. + * @protected + * @returns {void} + */ showMarking() {} - // Checks if the question should be set to complete - // Calls setCompletionStatus and adds complete classes + /** + * Delegates to `model.checkQuestionCompletion()` and adds `is-complete` and + * `show-user-answer` CSS classes to the component widget when the question + * is complete. + * @returns {void} + */ checkQuestionCompletion() { const isComplete = this.model.checkQuestionCompletion(); @@ -271,13 +372,27 @@ class QuestionView extends ComponentView { } + /** + * Fires `questionView:recordInteraction` unless `_recordInteraction` is + * explicitly set to `false` on the model. Called at the end of + * `onSubmitClicked` to allow tracking plugins (e.g. SCORM) to record the + * learner's interaction. + * @fires questionView:recordInteraction + * @returns {void} + */ recordInteraction() { if (this.model.get('_recordInteraction') === true || !this.model.has('_recordInteraction')) { Adapt.trigger('questionView:recordInteraction', this); } } - // Used to show feedback based upon whether _canShowFeedback is true + /** + * Triggers feedback display if `_canShowFeedback` is true, otherwise signals + * that feedback is disabled. Can be called by plugins to re-trigger feedback. + * @fires questionView:showFeedback + * @fires questionView:disabledFeedback + * @returns {void} + */ showFeedback() { if (this.model.get('_canShowFeedback')) { @@ -288,6 +403,13 @@ class QuestionView extends ComponentView { } + /** + * Resets the question to its pre-submission state: clears submitted classes, + * restores the stored user answer, re-evaluates canSubmit, and updates button + * state. When called after the view is ready, shifts focus to the first + * tabbable element for accessibility. + * @returns {void} + */ onResetClicked() { this.setQuestionAsReset(); @@ -320,11 +442,20 @@ class QuestionView extends ComponentView { } /** - * Used by the question view to reset the look and feel of the component. - * This is triggered when the reset button is clicked so it shouldn't be a full reset. + * Override in component views to reset the visual state of the question + * (e.g. deselect items). Called when the reset button is clicked — this is a + * UI-only reset, not a full model reset. + * @protected + * @returns {void} */ resetQuestion() {} + /** + * Re-evaluates button state and optionally re-renders marking. Called in + * response to the `question:refresh` model event. Defers `buttonsView.refresh` + * to allow any pending DOM updates to complete first. + * @returns {void} + */ refresh() { this.model.set('_buttonState', this.model.getButtonState()); @@ -337,6 +468,11 @@ class QuestionView extends ComponentView { } } + /** + * Handles the show-correct-answer button press. Updates DOM state classes, + * refreshes buttons, then calls `showCorrectAnswer`. + * @returns {void} + */ onShowCorrectAnswerClicked() { this.setQuestionAsShowCorrect(); @@ -351,11 +487,21 @@ class QuestionView extends ComponentView { .removeClass('show-user-answer'); } - // Used by the question to display the correct answer to the user + /** + * Override in component views to display the correct answer. Also sets + * `_isCorrectAnswerShown` to `true` on the model. + * @protected + * @returns {void} + */ showCorrectAnswer() { this.model.set('_isCorrectAnswerShown', true); } + /** + * Handles the hide-correct-answer button press. Updates DOM state classes, + * refreshes buttons, then calls `hideCorrectAnswer`. + * @returns {void} + */ onHideCorrectAnswerClicked() { this.setQuestionAsHideCorrect(); @@ -370,18 +516,36 @@ class QuestionView extends ComponentView { .removeClass('show-correct-answer'); } - // Used by the question to display the users answer and - // hide the correct answer - // Should use the values stored in storeUserAnswer + /** + * Override in component views to restore the learner's submitted answer + * after the correct answer has been shown. Should use the values stored by + * `storeUserAnswer`. Also sets `_isCorrectAnswerShown` to `false` on the model. + * @protected + * @returns {void} + */ hideCorrectAnswer() { this.model.set('_isCorrectAnswerShown', false); } - // Time elapsed between the time the interaction was made available to the learner for response and the time of the first response + /** + * Returns the time elapsed (in seconds) between when the question became + * available and the learner's first response. Override in component views to + * provide a measured value for SCORM interaction tracking. + * @returns {number|null} Latency in seconds, or `null` if not measured + */ getLatency() { return null; } + /** + * Dispatches a named method call to the question model. Overridden in + * `ViewOnlyQuestionViewCompatibilityLayer` to redirect to view-only + * implementations when the component has not yet migrated to a model. + * @param {string} name - Method name to call on the model + * @param {string} [lookForViewOnlyFunction] - Alternative method name to check for a view override + * @returns {*} Return value from the delegated method + * @private + */ // This function is overridden if useQuestionModeOnly: false. see below. _runModelCompatibleFunction(name, lookForViewOnlyFunction) { return this.model[name](); // questionModel Only @@ -406,42 +570,71 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { * Please remove them from your question component's view. */ + /** + * Returns an object describing the learner's interaction for SCORM/xAPI reporting. + * @returns {Object} Interaction object specific to the question type + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#getInteractionObject} instead + */ // Returns an object specific to the question type. getInteractionObject() { log.deprecated('QuestionView.getInteractionObject, please use QuestionModel.getInteractionObject'); return this.model.getInteractionObject(); } + /** + * Returns a string describing how the learner answered the question. + * @returns {string} The learner's response + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#getResponse} instead + */ // Retturns a string detailing how the user answered the question. getResponse() { log.deprecated('QuestionView.getResponse, please use QuestionModel.getResponse'); return this.model.getResponse(); } - // Returns a string describing the type of interaction: "choice" and "matching" supported (see scorm wrapper) + /** + * Returns a string describing the interaction type (e.g. `"choice"` or + * `"matching"`) for SCORM wrapper compatibility. + * @returns {string} The interaction type + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#getResponseType} instead + */ getResponseType() { log.deprecated('QuestionView.getResponseType, please use QuestionModel.getResponseType'); return this.model.getResponseType(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupDefaultSettings} instead + */ // Calls default methods to setup on questions setupDefaultSettings() { log.deprecated('QuestionView.setupDefaultSettings, please use QuestionModel.setupDefaultSettings'); return this.model.setupDefaultSettings(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupButtonSettings} instead + */ // Used to setup either global or local button text setupButtonSettings() { log.deprecated('QuestionView.setupButtonSettings, please use QuestionModel.setupButtonSettings'); return this.model.setupButtonSettings(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupWeightSettings} instead + */ // Used to setup either global or local question weight/score setupWeightSettings() { log.deprecated('QuestionView.setupWeightSettings, please use QuestionModel.setupWeightSettings'); return this.model.setupWeightSettings(); } + /** + * Returns whether the learner's current selection is valid for submission. + * @returns {boolean} + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#canSubmit} instead + */ // Use to check if the user is allowed to submit the question // Maybe the user has to select an item? canSubmit() { @@ -449,12 +642,20 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { return this.model.canSubmit(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#updateAttempts} instead + */ // Used to update the amount of attempts the user has left updateAttempts() { log.deprecated('QuestionView.updateAttempts, please use QuestionModel.updateAttempts'); return this.model.updateAttempts(); } + /** + * Stores the learner's current answer for later retrieval (e.g. when + * toggling between user answer and correct answer views). + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#storeUserAnswer} instead + */ // This is important for returning or showing the users answer // This should preserve the state of the users answers storeUserAnswer() { @@ -462,12 +663,21 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { return this.model.storeUserAnswer(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#resetUserAnswer} instead + */ // Used by the question view to reset the stored user answer resetUserAnswer() { log.deprecated('QuestionView.resetUserAnswer, please use QuestionModel.resetUserAnswer'); return this.model.resetUserAnswer(); } + /** + * Sets `_isCorrect` on the model based on `isCorrect()`, then calculates + * raw, max, and min scores. Falls back to `model.markQuestion()` when not + * in view-only compatible mode. + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#markQuestion} instead + */ // Sets _isCorrect:true/false based upon isCorrect method below markQuestion() { @@ -490,18 +700,29 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { } } + /** + * Returns whether the learner's answer is correct. + * @returns {boolean} + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#isCorrect} instead + */ // Should return a boolean based upon whether to question is correct or not isCorrect() { log.deprecated('QuestionView.isCorrect, please use QuestionModel.isCorrect'); return this.model.isCorrect(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setScore} instead + */ // Used to set the score based upon the _questionWeight setScore() { log.deprecated('QuestionView.setScore, please use QuestionModel.setScore'); return this.model.setScore(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#updateButtons} instead + */ // Updates buttons based upon question state by setting // _buttonState on the model which buttonsView listens to updateButtons() { @@ -509,6 +730,12 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { return this.model.updateButtons(); } + /** + * Sets up the appropriate feedback (correct, partly correct, or incorrect) + * based on the question outcome. Uses view-based feedback methods when in + * view-only compatible mode, otherwise delegates to `model.setupFeedback()`. + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupFeedback} instead + */ // Used to setup the correct, incorrect and partly correct feedback setupFeedback() { @@ -530,6 +757,11 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { } + /** + * Returns whether the learner's answer is partly correct. + * @returns {boolean} + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#isPartlyCorrect} instead + */ // Used by the question to determine if the question is incorrect or partly correct // Should return a boolean isPartlyCorrect() { @@ -537,16 +769,25 @@ class ViewOnlyQuestionViewCompatibilityLayer extends QuestionView { return this.model.isPartlyCorrect(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupCorrectFeedback} instead + */ setupCorrectFeedback() { log.deprecated('QuestionView.setupCorrectFeedback, please use QuestionModel.setupCorrectFeedback'); return this.model.setupCorrectFeedback(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupPartlyCorrectFeedback} instead + */ setupPartlyCorrectFeedback() { log.deprecated('QuestionView.setupPartlyCorrectFeedback, please use QuestionModel.setupPartlyCorrectFeedback'); return this.model.setupPartlyCorrectFeedback(); } + /** + * @deprecated Use {@link module:core/js/models/questionModel~QuestionModel#setupIncorrectFeedback} instead + */ setupIncorrectFeedback() { log.deprecated('QuestionView.setupIncorrectFeedback, please use QuestionModel.setupIncorrectFeedback'); return this.model.setupIncorrectFeedback();