diff --git a/js/models/articleModel.js b/js/models/articleModel.js index 01eb21e8..9aa3fc7f 100644 --- a/js/models/articleModel.js +++ b/js/models/articleModel.js @@ -1,7 +1,23 @@ +/** + * @file Article Model - Article data model + * @module core/js/models/articleModel + * @description Data model for article content. Extends + * {@link module:core/js/models/adaptModel~AdaptModel} to represent articles in the + * Adapt content hierarchy. Articles are children of content objects (pages) and + * parents of blocks. Registered as the 'article' component type. + */ + import components from 'core/js/components'; import logging from 'core/js/logging'; import AdaptModel from 'core/js/models/adaptModel'; +/** + * @class ArticleModel + * @classdesc Data model for an article. Articles are mid-level content containers + * in the Adapt hierarchy, sitting between content objects (pages) and blocks. + * Each article holds one or more blocks. + * @extends AdaptModel + */ class ArticleModel extends AdaptModel { get _parent() { diff --git a/js/models/blockModel.js b/js/models/blockModel.js index 65335059..9391a6da 100644 --- a/js/models/blockModel.js +++ b/js/models/blockModel.js @@ -1,7 +1,23 @@ +/** + * @file Block Model - Block data model + * @module core/js/models/blockModel + * @description Data model for block content. Extends + * {@link module:core/js/models/adaptModel~AdaptModel} to represent blocks in the + * Adapt content hierarchy. Blocks are children of articles and parents of components. + * Registered as the 'block' component type. + */ + import components from 'core/js/components'; import logging from 'core/js/logging'; import AdaptModel from 'core/js/models/adaptModel'; +/** + * @class BlockModel + * @classdesc Data model for a block. Blocks are the direct containers of components + * in the Adapt hierarchy. Each block holds one or more components and sits within + * an article. + * @extends AdaptModel + */ class BlockModel extends AdaptModel { get _parent() { diff --git a/js/models/componentModel.js b/js/models/componentModel.js index e042551f..1b916e6a 100644 --- a/js/models/componentModel.js +++ b/js/models/componentModel.js @@ -1,8 +1,29 @@ +/** + * @file Component Model - Base component data model + * @module core/js/models/componentModel + * @description Base data model for all Adapt components. Extends + * {@link module:core/js/models/adaptModel~AdaptModel} to provide attempt tracking, + * user answer storage, and state restoration. Registered as the abstract 'component' + * type to support deprecated view-only components. + * + * Attempt state is stored as a compact array format `[numbers[], booleans[], arrays[]]` + * for efficient SCORM tracking. Use {@link module:core/js/models/componentModel~ComponentModel#getAttemptObject} + * to retrieve a readable key-value representation. + */ + import components from 'core/js/components'; import Adapt from 'core/js/adapt'; import logging from 'core/js/logging'; import AdaptModel from 'core/js/models/adaptModel'; +/** + * @class ComponentModel + * @classdesc Base data model for Adapt components. Manages user answer storage, + * attempt state serialization, and state restoration for SCORM tracking. All + * interactive Adapt components extend this model. Component models are leaf nodes + * in the Adapt content hierarchy, held within blocks. + * @extends AdaptModel + */ class ComponentModel extends AdaptModel { get _parent() { diff --git a/js/models/contentObjectModel.js b/js/models/contentObjectModel.js index 43a248f9..575ddaf2 100644 --- a/js/models/contentObjectModel.js +++ b/js/models/contentObjectModel.js @@ -1,7 +1,23 @@ +/** + * @file Content Object Model - Base model for pages and menus + * @module core/js/models/contentObjectModel + * @description Base data model for content objects (pages and menus). Extends + * {@link module:core/js/models/adaptModel~AdaptModel} to represent navigable course + * sections that are direct children of the course root or a nested menu. + */ + import Adapt from 'core/js/adapt'; import logging from 'core/js/logging'; import AdaptModel from 'core/js/models/adaptModel'; +/** + * @class ContentObjectModel + * @classdesc Base data model for content objects — pages and menus. Content objects are + * the navigable sections of a course, sitting directly below the course root or nested + * inside menus. Provides base type-group identification and deprecated navigation helpers + * for the content object hierarchy. + * @extends AdaptModel + */ export default class ContentObjectModel extends AdaptModel { get _parent() { diff --git a/js/models/courseModel.js b/js/models/courseModel.js index 64825688..f472a02b 100644 --- a/js/models/courseModel.js +++ b/js/models/courseModel.js @@ -1,7 +1,22 @@ +/** + * @file Course Model - Top-level course data model + * @module core/js/models/courseModel + * @description Data model for the course root node. Extends {@link module:core/js/models/menuModel~MenuModel} + * to represent the top-level course container. Registered as the 'course' component type. + */ + import components from 'core/js/components'; import logging from 'core/js/logging'; import MenuModel from 'core/js/models/menuModel'; +/** + * @class CourseModel + * @classdesc Top-level course data model. Represents the root course node in the Adapt + * content hierarchy. The course is the parent of all content objects and has no parent + * of its own. Extends {@link module:core/js/models/menuModel~MenuModel} with course-specific + * type identification. + * @extends MenuModel + */ class CourseModel extends MenuModel { get _parent() { diff --git a/js/models/menuModel.js b/js/models/menuModel.js index 39af435e..bff2450e 100644 --- a/js/models/menuModel.js +++ b/js/models/menuModel.js @@ -1,7 +1,24 @@ +/** + * @file Menu Model - Menu content object data model + * @module core/js/models/menuModel + * @description Data model for menu content objects. Extends + * {@link module:core/js/models/contentObjectModel~ContentObjectModel} to represent + * menus that contain other content objects. Menus apply locking logic to their + * children via {@link module:core/js/models/menuModel~MenuModel#setCustomLocking}. + * Registered as the 'menu' component type. + */ + import components from 'core/js/components'; import logging from 'core/js/logging'; import ContentObjectModel from 'core/js/models/contentObjectModel'; +/** + * @class MenuModel + * @classdesc Data model for a menu content object. Menus are container nodes in the + * content object hierarchy that hold other content objects (pages or nested menus). + * Applies lock state to children based on the configured locking strategy. + * @extends ContentObjectModel + */ class MenuModel extends ContentObjectModel { get _children() { @@ -17,6 +34,10 @@ class MenuModel extends ContentObjectModel { return 'menu'; } + /** + * Applies lock state to each available child model using the configured locking strategy. + * Recursively triggers locking on any child that is itself a {@link MenuModel}. + */ setCustomLocking() { const children = this.getAvailableChildModels(); children.forEach(child => { diff --git a/js/models/pageModel.js b/js/models/pageModel.js index fa69bdbd..909ad214 100644 --- a/js/models/pageModel.js +++ b/js/models/pageModel.js @@ -1,7 +1,23 @@ +/** + * @file Page Model - Page content object data model + * @module core/js/models/pageModel + * @description Data model for page content objects. Extends + * {@link module:core/js/models/contentObjectModel~ContentObjectModel} to represent + * learner-facing pages. Pages are leaf-level content objects that contain articles. + * Registered as the 'page' component type. + */ + import components from 'core/js/components'; import logging from 'core/js/logging'; import ContentObjectModel from 'core/js/models/contentObjectModel'; +/** + * @class PageModel + * @classdesc Data model for a page content object. Pages are the learner-facing navigable + * sections of a course that contain articles. They are leaf nodes in the content object + * hierarchy — unlike menus, pages do not contain other content objects. + * @extends ContentObjectModel + */ class PageModel extends ContentObjectModel { get _children() { diff --git a/js/mpabc.js b/js/mpabc.js index b8e4814d..19f8b694 100644 --- a/js/mpabc.js +++ b/js/mpabc.js @@ -1,3 +1,16 @@ +/** + * @file MPABC - Menus, Pages, Articles, Blocks and Components controller + * @module core/js/mpabc + * @description Singleton controller that bootstraps the core Adapt content hierarchy. + * Registers the primary content type models and views (menus, pages, articles, blocks, + * components), then creates {@link AdaptSubsetCollection} instances on the `Adapt` global + * for each type: `Adapt.contentObjects`, `Adapt.articles`, `Adapt.blocks`, and + * `Adapt.components`. Coordinates data loading via the wait API. + * + * @example + * import 'core/js/mpabc'; // imported for side-effects; bootstraps the content hierarchy + */ + import Adapt from 'core/js/adapt'; import wait from 'core/js/wait'; import Data from 'core/js/data'; @@ -14,6 +27,15 @@ import 'core/js/views/pageView'; import 'core/js/views/articleView'; import 'core/js/views/blockView'; +/** + * @class MPABC + * @classdesc Singleton controller responsible for bootstrapping the core content type + * hierarchy. Sets up `Adapt.contentObjects`, `Adapt.articles`, `Adapt.blocks`, and + * `Adapt.components` as {@link AdaptSubsetCollection} instances filtered by model type. + * Coordinates with the data loader via the wait API to ensure collections are ready + * before the framework proceeds. + * @extends Backbone.Controller + */ class MPABC extends Backbone.Controller { initialize() {