Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 29 additions & 18 deletions design/scorm.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,9 @@ one row each; an LMS added here gets a row there.
the package and plans its parts, and returns the facts, the main library with the version its
`preloadedDependencies` give it (`mainLibraryOf`), the title, the size, the parts and their size
from the pack's index, with `write`, which fetches the files and writes the zip, as often as
asked; `buildScormInPage` is the two at once. A refusal comes at planning, by name, before
asked, hashing the package for the build stamp on the first write only, since the package and
its parts are the same for every write (#142); `buildScormInPage` is the two at once, and a
`title` given to the plan is the plan's and its writes' default. A refusal comes at planning, by name, before
anything but the pack's index is fetched. **The title** is `title` on both builders and
`--title` on the command, cleaned by `scormTitle` as `h5p.json`'s is, an empty one leaving the
package's; it goes into the manifest's organisation and item, which the LMS lists, and the
Expand All @@ -317,7 +319,9 @@ one row each; an LMS added here gets a row there.
works in steps where it holds `#files`, a list, and `#build`, a button, as both pages here do:
① choose, ② review, ③ download, each step the closest `[data-step]` around them, shown once it
can be reached. A file chosen or dropped gets a row (the same file twice, by name, size and date,
is one), whose facts sit in a live region (`role="status"`) from the moment the row appears, so
is one), during a build too, since a drop lands anywhere on the page: it is read at once and
waits for the next Build, where it was dropped without a word until #142. Its facts sit in a
live region (`role="status"`) from the moment the row appears, so
that what the reading found is announced. Every row is drawn again on any change, a key typed
in a title among them, so the page writes a region's text, and `#status`'s, only when it
changes: written again as it was, a region may be read out again, and a test types a title key
Expand Down Expand Up @@ -352,7 +356,9 @@ one row each; an LMS added here gets a row there.
and each answer's latency as ISO 8601 durations to the hundredth; each answer with its
words in `description` (250 characters, as text, the character references a question writes
read: `’` came through as itself in Moodle until then), an id that is a URI as 2004 asks,
`urn:uuid:` and the part's id, `learner_response`, `incorrect` where 1.2 says `wrong`,
`urn:uuid:` and the part's id, the type before the pattern and `learner_response`, which 2004
refuses without one (408), so an answer whose statement names no type has neither (#142),
`incorrect` where 1.2 says `wrong`,
`timestamp` in UTC, and `long-fill-in` and `other` kept as themselves; `suspend_data` up to
64,000 characters, compressed as in 1.2. **A 2004 session always ends `suspend`**, finished
or not, where 1.2 ends a finished one with nothing. Measured in Moodle 4.5 with `normal`
Expand Down Expand Up @@ -380,24 +386,28 @@ one row each; an LMS added here gets a row there.
its second question, finished completed and passed at 66.67 (scaled 0.6667), the gradebook
66.67, the total time the two sessions' sum, the four answers with their ids and words; a
launch after the finish resumed with the result kept. With a mark of 80, the same 66.67
failed in 2004 and in 1.2, the gradebook still 66.67; with completion as 100, a finish with
no score recorded 100 and passed in both, the gradebook 100. In SCORM Cloud, through its v2
API: both 2004 zips imported as `SCORM20044THEDITION` with no parser warnings; the same two
sessions resumed on the second question, the registration completed and passed at 66.67, and
a launch after the finish kept it; a mark of 80 failed at 66.67 with completion still
completed, where 1.2 shows a failed attempt as incomplete; a finish with no score, completed,
passed and 100; and 1.2 with a mark of 80 failed at 66.67, the registration incomplete as for
any failed 1.2 attempt there. The finishes with no score were the element's `finished`
dispatched in the SCO's frame, as the tests do, since no package here finishes without one.
failed in 2004 and in 1.2, the gradebook still 66.67; with completion as 100 in a zip that
also held the mark of 80, a finish with no score recorded 100 and passed in both, the
gradebook 100. In SCORM Cloud, through its v2 API: both 2004 zips imported as
`SCORM20044THEDITION` with no parser warnings; the same two sessions resumed on the second
question, the registration completed and passed at 66.67, and a launch after the finish kept
it; a mark of 80 failed at 66.67 with completion still completed, where 1.2 shows a failed
attempt as incomplete; a finish with no score, in the zip with the mark of 80 and completion
as 100, completed, passed and 100; and 1.2 with a mark of 80 failed at 66.67, the
registration incomplete as for any failed 1.2 attempt there. The finishes with no score were
the element's `finished` dispatched in the SCO's frame, as the tests do, since no package here
finishes without one. Completion as 100 without a mark ran in no LMS: it gives `completed`
and 100, and in 2004 leaves success `unknown`, which a test holds (#142).

`scorm-page.test.ts` drives the written site's page in Chromium: a chosen file read into its row
and built on Build, the download, which is the command's zip and plays unpacked; three files at
once, a refusal in its row beside two that build, a title given, each row's zip and the zip of
all, a row taken out, a title changed after the build; files dropped, the same one only once;
and a page with only the four elements, which builds at once and refuses in `#notice`.
`scorm-browser.test.ts` holds the plan's facts to the command's zip, two writes of one plan
under two titles to the same zip but for the manifest and the page, and a title given to the
page's builder to the command's `--title`, entry for entry.
all, a row taken out, a title changed after the build; files dropped, the same one only once,
and one dropped during a build, which waits for the next; and a page with only the four
elements, which builds at once and refuses in `#notice`. `scorm-browser.test.ts` holds the
plan's facts to the command's zip, two writes of one plan under two titles to the same zip but
for the manifest and the page, a title given to the page's builder to the command's `--title`,
entry for entry, and a title given to the plan to its writes, which hash the package once.

`tests/scorm.test.ts` checks the zip, the parts it carries, its stored entries' local headers and
its refusals in Node. In Chromium it plays the unpacked zip under a page that holds the API and
Expand All @@ -424,7 +434,8 @@ frames the launch page, as Moodle's player does. It covers:
content's pass, and an LMS's own mark that wins over the zip's; completion as 100, passing a
mark; and, under a page that holds `API_1484_11`, the quiz played to the end in 2004 with its
answers, the session suspended and resumed with the result kept, a state past 4,096
characters kept, and a score held to the LMS's passing score;
characters kept, a score held to the LMS's passing score, and an answer's type written before
its pattern and response, and neither for an answer that names no type;
- playing with no LMS.

Not covered:
Expand Down
15 changes: 8 additions & 7 deletions packages/embed/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -270,9 +270,9 @@ export, which `libraries=pack` then plays from) or `packBase` (the folder of a c
`buildScorm` from `@missing-elements/h5p-embed/scorm` is `--scorm`: it takes `h5p`, `out`,
`force`, `title`, and the options, `scormVersion` (`'1.2'`, the default, or `'2004'`),
`passMark` (0 to 100, or `null`) and `completionScore` (`false` by default), and returns the zip's
path, its title, its `scormVersion`, size, the `libraries` it carries from the pack, and `build`,
the stamp saved state is kept against. Every entry ships with TypeScript
declarations.
path, its title, the options as written into it (`scormVersion`, `passMark` kept to the
hundredth, `completionScore`), size, the `libraries` it carries from the pack, and `build`, the
stamp saved state is kept against. Every entry ships with TypeScript declarations.

`buildScormInPage` from `@missing-elements/h5p-embed/scorm/browser` is the same build in a page:
it takes `file`, a `File` or `Blob`; `base`, the folder with the player's three files and
Expand All @@ -283,12 +283,13 @@ beside the player as the written site does, where a page that gives the template
compressor gets the one at `base`, or a zip without it that keeps the saved state plain, as 1.4
did;
`version` and `packVersion`, for the zip's notice; `title` and the options, as `buildScorm`
takes them; and `onProgress`. It returns the zip as a `Blob`, with its `name`, `title`,
`scormVersion`, `libraries`, `build` and `size`. `planScormInPage`, from the same module, takes the same options and stops before
anything is written: it reads the package and returns what its zip will hold, its `title`,
takes them; and `onProgress`. It returns the zip as a `Blob`, with its `name`, `title`, the
options as `buildScorm` returns them, `libraries`, `build` and `size`. `planScormInPage`, from
the same module, takes the same options and stops before anything is written: it reads the
package and returns what its zip will hold, its `title` (the one given, else the package's),
`mainLibrary`, `size`, the `libraries` from the pack and their `librariesSize`, or refuses it as
the build would, and `write({ title, scormVersion, passMark, completionScore })` then writes the
zip, as often as asked. `startScormPage`
zip, as often as asked, each of the four defaulting to the plan's. `startScormPage`
from `@missing-elements/h5p-embed/scorm-page.js` is the page's script, which reads the page's
`#file`, `#status`, `#download` and `#notice`, and works in steps where the page also holds
`#files`, the list it puts a row in for each file, and `#build`, the button that builds them, and
Expand Down
3 changes: 2 additions & 1 deletion packages/embed/bin/h5p-embed.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,8 @@ if (values.scorm !== undefined) {
})
const count = zip.libraries.length
const supplied = count > 0 ? `, the H5P runtime and ${count} ${count === 1 ? 'library' : 'libraries'} from the library pack, which it does not carry` : ' and the H5P runtime'
const graded = [values['pass-mark'] !== undefined ? `pass mark ${Number(values['pass-mark'])}` : null, values['completion-score'] ? 'completion counts as 100' : null].filter(Boolean)
// The options as written into the zip, the mark kept to the hundredth, not as typed.
const graded = [zip.passMark !== null ? `pass mark ${zip.passMark}` : null, zip.completionScore ? 'completion counts as 100' : null].filter(Boolean)
console.log(`Wrote ${shown(zip.out)} (${megabytes(zip.size)}): "${zip.title}" as a SCORM ${zip.scormVersion === '2004' ? '2004 4th Edition' : '1.2'} package${graded.length ? ` (${graded.join(', ')})` : ''},
with the player ${zip.version}${supplied}.

Expand Down
31 changes: 19 additions & 12 deletions packages/embed/lib/scorm-browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ import { EmbedError, PLAYER_FILES } from './shared.mjs'
* @property {string} version the player's version, as given
* @property {string[]} libraries the folders of the libraries the zip carries from the pack
* @property {'1.2' | '2004'} scormVersion the SCORM version it was written for
* @property {number | null} passMark the pass mark it holds a score to, as `buildScorm` returns it
* @property {boolean} completionScore whether content that finishes without a score counts as 100
* @property {string} build the build stamp, as `buildScorm` returns it
* @property {number} size the zip's size in bytes
*/
Expand All @@ -76,18 +78,19 @@ import { EmbedError, PLAYER_FILES } from './shared.mjs'
* @typedef {object} PlannedScorm
* @property {string} name the package's file name
* @property {number} size the package's size in bytes
* @property {string} title the title the zip takes unless `write` is given another: `h5p.json`'s,
* or the file's name
* @property {string} title the title the zip takes unless `write` is given another: the one given
* to the plan, else `h5p.json`'s, else the file's name
* @property {{ machineName: string, majorVersion?: number, minorVersion?: number } | null} mainLibrary
* the package's main library, as `h5p.json` names it, with the version its dependencies give
* it; `null` when it names none
* @property {string[]} libraries the folders of the libraries the zip will carry from the pack;
* none for a package that carries its own
* @property {number} librariesSize their archives' size in bytes, as the pack's index gives it
* @property {(options?: { title?: string, scormVersion?: '1.2' | '2004', passMark?: number | null, completionScore?: boolean, onProgress?: (progress: ScormProgress) => void }) => Promise<PageScorm>} write
* fetches the parts, the player and the runtime, and writes the zip, under `title` when one is
* given, and with the version and the grading options given, each defaulting to the plan's, as
* `onProgress` does. It can be called again, for another title or other options
* fetches the parts, the player and the runtime, and writes the zip, under the title and with
* the version and the grading options given, each defaulting to the plan's, as `onProgress`
* does. It can be called again, for another title or other options; the package is hashed for
* the build stamp on the first call only
*/

/**
Expand Down Expand Up @@ -167,10 +170,13 @@ export async function planScormInPage(options) {
throw error
}
const stem = name.replace(/\.[^.]+$/, '')
const defaultTitle = scormTitle(manifest, stem)
// A title given to the plan is the plan's, and its writes' unless they give another.
const plannedTitle = scormTitle(manifest, stem, options.title)
/** @type {string | null} the build stamp, from the first write on */
let stamp = null

/** @type {PlannedScorm['write']} */
const write = async ({ title: chosen, onProgress: report = onProgress, ...given } = {}) => {
const write = async ({ title: chosen = options.title, onProgress: report = onProgress, ...given } = {}) => {
const title = scormTitle(manifest, stem, chosen)
const scorm = scormOptions({ ...planned, ...Object.fromEntries(Object.entries(given).filter(([, value]) => value !== undefined)) })
const { assets = {}, version = 'unknown', packVersion = null } = options
Expand Down Expand Up @@ -214,21 +220,22 @@ export async function planScormInPage(options) {
librariesText: parts.length === 0 ? null : assets.libraries !== undefined ? asBlob(assets.libraries) : await blob(at('libraries.txt'), "The pack's licence list")
}

// The whole package in memory once, for its hash: `crypto.subtle` takes no stream.
const build = await buildStamp(await sha256Hex(await file.arrayBuffer()), parts)
// The whole package in memory once, for its hash: `crypto.subtle` takes no stream. Once per
// plan, too: the package and its parts are the same for every write.
const build = (stamp ??= await buildStamp(await sha256Hex(await file.arrayBuffer()), parts))
const { entries, xml } = scormEntries({ manifest, source: name, title, build, version, packVersion, parts, files, options: scorm })

report({ step: 'writing' })
const zip = new ZipWriter(new BlobWriter('application/zip'), { useWebWorkers: false })
await addScormEntries(zip, { entries, xml })
const out = await zip.close()
return { blob: out, name: `${stem}.scorm.zip`, title, version, libraries: parts.map((part) => part.folder), scormVersion: scorm.scormVersion, build, size: out.size }
return { blob: out, name: `${stem}.scorm.zip`, title, version, libraries: parts.map((part) => part.folder), ...scorm, build, size: out.size }
}

return {
name,
size: file.size,
title: defaultTitle,
title: plannedTitle,
mainLibrary: mainLibraryOf(manifest),
libraries: parts.map((part) => part.folder),
librariesSize: parts.reduce((sum, part) => sum + part.size, 0),
Expand All @@ -244,5 +251,5 @@ export async function planScormInPage(options) {
* @returns {Promise<PageScorm>}
*/
export async function buildScormInPage(options) {
return (await planScormInPage(options)).write({ title: options?.title })
return (await planScormInPage(options)).write()
}
5 changes: 4 additions & 1 deletion packages/embed/lib/scorm.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,9 @@ async function filesUnder(dir) {
* @property {string[]} libraries the folders of the libraries the zip carries from the library
* pack, for a package that does not carry them itself; none for one that does
* @property {'1.2' | '2004'} scormVersion the SCORM version it was written for
* @property {number | null} passMark the pass mark it holds a score to, out of 100 and kept to the
* hundredth; `null` for the content's own result
* @property {boolean} completionScore whether content that finishes without a score counts as 100
* @property {string} build the first 16 hex digits of the package's SHA-256, or, with libraries
* from the pack, of one over its and theirs: a learner's saved place is kept against it, and
* handed back only to the same package playing with the same libraries
Expand Down Expand Up @@ -172,5 +175,5 @@ export async function buildScorm({ h5p, out, force = false, title: chosen, scorm
throw error
}

return { out: target, title, version, libraries: parts.map((part) => part.folder), scormVersion: options.scormVersion, build, size: (await stat(target)).size }
return { out: target, title, version, libraries: parts.map((part) => part.folder), ...options, build, size: (await stat(target)).size }
}
7 changes: 5 additions & 2 deletions packages/embed/scorm/scorm.js
Original file line number Diff line number Diff line change
Expand Up @@ -468,10 +468,13 @@ function recordAnswer(statement) {
const types = /** @type {Record<string, string>} */ (scorm2004 ? INTERACTION_TYPES_2004 : INTERACTION_TYPES)
const type = typeof definition?.interactionType === 'string' ? types[definition.interactionType] : undefined
if (type) set(at('type'), type)
// 2004 takes a pattern and a response only after the type that gives their form, and refuses
// them without one (408); 1.2 takes them as they come.
const typed = Boolean(type) || !scorm2004
const pattern = Array.isArray(definition?.correctResponsesPattern) ? definition.correctResponsesPattern[0] : undefined
if (typeof pattern === 'string') set(at('correct_responses.0.pattern'), pattern.slice(0, FEEDBACK_LIMIT))
if (typed && typeof pattern === 'string') set(at('correct_responses.0.pattern'), pattern.slice(0, FEEDBACK_LIMIT))
const result = statement.result ?? {}
if (typeof result.response === 'string') set(at(scorm2004 ? 'learner_response' : 'student_response'), result.response.slice(0, FEEDBACK_LIMIT))
if (typed && typeof result.response === 'string') set(at(scorm2004 ? 'learner_response' : 'student_response'), result.response.slice(0, FEEDBACK_LIMIT))
set(at('result'), outcomeOf(result))
if (typeof result.score?.max === 'number') set(at('weighting'), String(result.score.max))
const latency = latencyOf(result.duration)
Expand Down
Loading
Loading