Citolab.QTI.Converter 0.1.1

Citolab.QTI.Converter and Citolab.QTI.Uploader

Small .NET library that:

• validates and extracts QTI package zip files
• optionally converts QTI 2.x packages to QTI 3 (via pluggable converter)
• streams the original zip and extracted entries to a consumer-provided callback (e.g. Blob Storage)

Packages / projects

• Citolab.QTI.Uploader: core uploader abstractions + zip extraction
• Citolab.QTI.Converter: optional (pure .NET) converter implementation that converts QTI 2.x packages to QTI 3

NuGet publishing (GitHub Actions)

This repo includes a GitHub Actions workflow at .github/workflows/nuget.yml that builds/tests/packs on PRs and on pushes to main, and publishes to NuGet.org on:

• a tag push like v0.1.0 (uses the tag as the NuGet version), or
• a manual run (Actions → workflow → Run workflow) with an optional version input.

To enable publishing, add NUGET_API_KEY as a repository secret.

Basic usage (ASP.NET Controller)

Create an IQtiPackageStore that uploads to your storage, then call QtiPackageUploader.UploadAsync(...).

QTI 2.x → QTI 3 conversion

If you want automatic conversion for QTI 2.x packages, configure QtiUploaderOptions:

using Citolab.QTI.Converter;
using Citolab.QTI.Uploader;

var uploader = new QtiPackageUploader();
var options = new QtiUploaderOptions
{
 ConvertQti2ToQti3 = true,
 Converter = new Qti2ToQti3PackageConverter(
 new Qti2ToQti3PackageConverterOptions
 {
 ItemTransformOptions = new QtiItemTransformOptions
 {
 // These are enabled by default; set to false to disable.
 ObjectToImg = true,
 ObjectToVideo = true,
 ObjectToAudio = true,
 SsmlSubToSpan = true,
 StripMaterialInfo = true,
 MinChoicesToOne = true,
 ExternalScored = true,

 // Optional extras (off by default).
 QbCleanup = false,
 DepConvert = false,
 UpgradePci = false,
 StripStylesheets = false
 },

 // Optional per-item hook for consumer-specific transformations.
 OnItemTransformedAsync = async (transform, itemPath, ct) =>
 {
 // Example: add a marker attribute
 await transform.FnChAsync(doc =>
 {
 doc.Root?.SetAttributeValue("data-processed-by", "my-app");
 return Task.CompletedTask;
 });
 }
 })
};

The converter uses the qti2xTo30.xsl XSLT 3.0 upgrader (embedded in the NuGet) when running on net9.0. For netstandard2.0, it falls back to a best-effort built-in conversion.

Item transformations

When converting an assessment item, the converter can apply a set of optional XML transformations via QtiTransform and QtiItemTransformOptions.

Default item transforms (enabled by default)

• ObjectToImg: converts <object type="image/*" data="...">ALT</object> to <img src="..." alt="ALT" .../>.
• ObjectToVideo: converts <object type="video/*" ... data="..."> to <video><source .../></video> and normalizes existing <video controls> usage.
• ObjectToAudio: converts <object type="audio/*" ... data="..."> to <audio><source .../></audio> and normalizes existing <audio controls> usage.
• SsmlSubToSpan: converts SSML elements (e.g. <ssml:sub>, <ssml:break>, <ssml:say-as>, etc.) to <span> elements with data-ssml-* attributes.
• StripMaterialInfo: removes <qti-companion-materials-info>.
• MinChoicesToOne: ensures <qti-choice-interaction min-choices> is at least 1.
• ExternalScored: when there is no <qti-response-processing>, sets external-scored="human" on the SCORE outcome declaration.

Additional item transforms (disabled by default)

• QbCleanup: cleanup for common Question Builder (QB) HTML-ish wrappers (unwraps some <div> wrappers, span cleanup, etc.).
• DepConvert: converts Dutch Extension Profile dialog triggers (.dep-dialogTrigger) into HTML popover buttons.
• DepConvertExtended: converts DEP dialogs into a <dep-popup> structure (trigger + popup slot).
• HideInputsForChoiceInteractionWithImages: adds qti-input-control-hidden when all choices contain images.
• UpgradePci: upgrades TAO-exported portable custom interactions into a structure expected by QTI components (moves properties to data-*, normalizes modules/markup, etc.).
• StripStylesheets: removes <qti-stylesheet> nodes; supports wildcard matching via StripStylesheetsRemovePattern / StripStylesheetsKeepPattern.
• StylesheetsInlineAsync: fetches CSS content from external stylesheet URLs and inlines them into <qti-stylesheet> elements. Supports both HTTP URLs and relative file paths within QTI packages. Use OnItemTransformedAsync hook for custom async transformations like this.

Usage example for StylesheetsInlineAsync with ZIP uploads:

OnItemTransformedAsync = async (transform, itemPath, fileResolver, ct) =>
{
 // Inline external stylesheets from ZIP package files
 await transform.StylesheetsInlineAsync(async (resolvedPath, currentItemPath) =>
 {
 // resolvedPath is the stylesheet path resolved relative to the item
 // Use the provided fileResolver to get CSS content from ZIP package
 return await fileResolver(resolvedPath);
 }, itemPath);
 
 // Alternative: if stylesheets are HTTP URLs, use custom HTTP client
 await transform.StylesheetsInlineAsync(async href => {
 if (href.StartsWith("http"))
 {
 using var client = new HttpClient();
 var response = await client.GetAsync(href, ct);
 return response.IsSuccessStatusCode 
 ? await response.Content.ReadAsStringAsync() 
 : null;
 }
 // For relative paths, use the ZIP file resolver
 var resolvedPath = Path.Combine(Path.GetDirectoryName(itemPath) ?? "", href.Replace('/', Path.DirectorySeparatorChar));
 return await fileResolver(resolvedPath.Replace('\\', '/'));
 });
}

Example QTI Package Structure:

item1/
 ├── question.xml (contains <qti-stylesheet href="../shared/styles.css">)
 └── item-specific.css
shared/
 └── styles.css (CSS file to be inlined)

When processing item1/question.xml, the stylesheet ../shared/styles.css resolves to shared/styles.css in the ZIP package.

Consumer hook

• Qti2ToQti3PackageConverterOptions.OnItemTransformedAsync runs per assessment item after the built-in transforms, and receives a mutable QtiTransform so you can call .FnCh(...) / .FnChAsync(...) or chain additional built-ins.