feat(embed): SCORM 1.2 ids a person reads, and responses only where 1.2 takes them

Merged
AL
12d ago
+230-71

Summary

A SCORM 1.2 zip now names each answer so a person can read the id in a report, and sends an answer's response only where 1.2 accepts H5P's form of it. Both follow the Reddit commenter's advice described in the issue. Closes #157.

Changes

  • Ids (1.2). The id is the question's number, its index from 1, followed by up to 40 characters of its words, cut at a word. It uses only a-z, 0-9 and _: accents are dropped, and letters such as ß, æ, ø and ł are spelled in ASCII. Where the words have no Latin letters, the id is the number alone. Examples: Q3_which_rivers_cross_germany, Q2.
    • The number keeps two questions with the same words apart, so the -2 suffix is gone.
    • The fallback that could carry an activity's URL, with its colon and slashes, is gone.
    • An attempt under way keeps the ids its saved state holds, so its report columns don't change.
    • The words are read as text first, with the markup taken out and character references such as   and ’ decoded. Before this, the id spelled them out, as in Q1_don_rsquo_t. The 2004 description already read them, and it now shares the same code.
  • Responses (1.2). student_response and correct_responses.0.pattern are now written only for fill-in (Essay included) and numeric. Choice, true-false, matching, sequencing, likert, performance and untyped answers carry their type, result, weighting, latency and time.
    • Written as plain text. H5P writes them in 2004's notation, which a 1.2 report shows exactly as written: {case_matters=false}stored[,]Range. The {case_matters=…} and {lang=…} at the start of the right answer are dropped, and the [,] between blanks becomes , in both answers. So Moodle shows stored, Range. Every fill-in type in the pack writes them this way: Blanks, Advanced Blanks, Drag Text, Crossword, Dictation, Flashcards and Goals Page.
    • Answered again. The interaction is written over, and 1.2 keeps any field nothing writes again. So in 1.2, an answer that writes over an earlier one empties whichever of the response and the right answer it has no value for. Otherwise, a fill-in typed before and left empty now would keep its old response. And in an attempt begun under an earlier zip, a choice would keep the 0[,]2 that zip wrote, beside the new result. A question answered for the first time writes neither, as before.
    • Numeric answers are written only when they're a number, 1.2's CMIDecimal. Anything else, such as 2004's range 1[:]5, is left out. No library in the pack sends numeric, so this only matters for a package that carries its own.
  • SCORM 2004 is unchanged: ids are URNs, the words go in description, and H5P's notation is 2004's own.
  • suspend_data is unchanged: it was already base64, through compressToBase64.
  • The embed README and design/scorm.md describe the new behaviour.

Verification

pnpm --filter @missing-elements/h5p-embed typecheck passes, and pnpm --filter @missing-elements/h5p-embed test passes 83 of 83, after the self-review fix as well: the 81 before, with their expectations updated, plus two new tests. With the answers written as plain text, 83 of 83 again: the real-quiz and responses-by-type tests extended, and the 2004 quiz test checking that the notation is kept.

  • Ids: a German question with ß, ü and Łódź gives Q1_wie_heisst_die_strasse_uber_den_fluss, a Russian one gives Q2, a long hyphenated word is cut where its words end, <p>Don&rsquo;t&nbsp;stop &amp; go</p> gives Q4_don_t_stop_go, and Kızılırmak nehri gives Q5_kizilirmak_nehri.
  • Responses by type:
    • Fill-in and numeric keep their response and the right one, as plain text. {case_matters=false}{lang=en}North Sea[,]Baltic is written as North Sea, Baltic.
    • A numeric range and a numeric answer in words are left out.
    • A fill-in answered again with nothing typed empties its earlier response.
    • A choice answered again, with an earlier zip's 0[,]1 and 0[,]2 already in the LMS, empties both. With the emptying switched off, both tests fail.
    • True-false, sequencing and matching carry their type and result alone.
  • Updated tests:
    • an attempt the LMS starts over renumbers its questions from Q1;
    • a lagging LMS count still puts new questions after it, as Q4_… and Q5_…;
    • the demo quiz played in the mock LMS reports Q1_… ids, its fill-in answer as stored, Range, deflated, front against stored, Range, compressed, front, and its choice and true-false answers without a response;
    • in SCORM 2004, the same fill-in keeps H5P's notation, which is 2004's own.

Not checked in a real LMS, since LMS testing is paused. Moodle stores ids as plain strings, so its interactions report should show the new ids, with an empty Response column for choice questions.

Release: a minor for embed. Under docs/compatibility.md, both changes are conformance fixes: what the zip writes now matches SCORM 1.2, though Moodle accepted the old form. So the release notes list them first. A Moodle report keeps the result of a choice, true/false, matching or sequencing answer but no longer shows what was chosen; there's nothing for a site to do. The ids that reports show change for new answers, and an attempt under way keeps its old ids.

  • Tests added or updated where behavior changed
  • Documentation updated where public behavior or deployment changed
  • Relevant type checks, tests, and builds pass
  • No security-sensitive details or credentials are included