eXeLearning

Omeka S module for eXeLearning content management. Upload, view and edit eXeLearning .elpx files directly within Omeka S.

ℹ️ The eXeLearning editor is fetched from the shared release and unpacked into the module when the playground boots, so the first load may take a few extra seconds. ELPX upload, viewer and preview work normally.

Features

• ELPX File Support: Upload and manage eXeLearning .elpx files through Omeka S (only .elpx; plain .zip uploads are left to the rest of the installation)
• Automatic Extraction: ELPX files are automatically extracted and ready to display
• Embedded Editor: Edit eXeLearning content directly from Omeka S without leaving the browser
• Automatic Thumbnails: Generates visual thumbnails from the content's first page
• Secure Content Delivery: All content served through a secure proxy with CSP headers and iframe sandboxing

Installation

From Releases (Recommended)

1. Download the latest release from the GitHub Releases page.
2. Extract to your Omeka S modules directory as ExeLearning.
3. Log in to the admin panel, go to Modules and click Install.

Server Configuration (nginx)

Add these rules to your nginx configuration:

# Block direct access to extracted files and uploaded styles
location ^~ /files/exelearning/ {
    return 403;
}
location ^~ /files/exelearning-styles/ {
    return 403;
}

# Route content proxy and style assets to PHP
location ^~ /exelearning/content/ {
    try_files $uri /index.php$is_args$args;
}
location ^~ /exelearning/styles/ {
    try_files $uri /index.php$is_args$args;
}

Apache is supported automatically via the included .htaccess file.

From Source (Development)

git clone https://github.com/exelearning/omeka-s-exelearning.git
cd omeka-s-exelearning
make build-editor

By default, make build-editor fetches https://github.com/exelearning/exelearning from main using a shallow checkout. You can override source/ref at runtime:

EXELEARNING_EDITOR_REF=vX.Y.Z EXELEARNING_EDITOR_REF_TYPE=tag make build-editor

Important: For production use, always install an official release from Releases: release packages include the embedded editor pre-built under dist/static/, and that bundle is the only editor the module ever uses. The module never downloads editor code at runtime, and administrators cannot update the editor independently of the module — updating the editor means updating the module (a new module release is published automatically for every editor release). Source checkouts do not contain dist/static/; build it with make build-editor as shown above. See ADR-28-01.

Usage

Uploading ELPX Files

1. Navigate to an Item in Omeka S
2. Click Add media and select your .elpx file
3. Save the item — the content will be displayed in the media viewer

Editing Content

1. Go to the media page (Admin > Items > [Your Item] > [Media]), or to any public page that shows the content while logged in
2. Click Edit in eXeLearning
3. Make your changes and click Save to Omeka

The button is shown to logged-in users who may update the media in Omeka (its owner, or a global role that may update any resource) and to the owner, admins and editors of a site the item is published on. Site viewers cannot edit. It sits at the top right of the viewer, next to the download and fullscreen buttons. Administrators can hide it on public pages with Show "Edit in eXeLearning" on public pages in the module configuration; it is always offered on the admin media page.

Development

make up          # Start Docker environment (http://localhost:8080)
make down        # Stop containers
make lint        # Check code style + validate the architecture records
make fix         # Auto-fix code style
make test        # Run the unit tests
make test-coverage  # Tests + coverage gate (what CI runs)
make package VERSION=1.2.3  # Build a .zip release

Default credentials: admin@example.com / PLEASE_CHANGEME

make test-coverage is the blocking verification gate: it fails on any failing test and on line coverage below MIN_COVERAGE (90%), and writes its reports to artifacts/coverage/. Coverage is published to Codecov, which annotates pull requests but does not block them — see ADR-32-01.

Releasing

Module releases are normally automatic: whenever the editor publishes a release, check-editor-releases.yml bundles it, records its tag in .editor-version and publishes the module with the same version number.

To ship a module-only change before the next editor release, tag a SemVer pre-release of the next version and push the tag:

git tag v4.0.6-rc.1 && git push origin v4.0.6-rc.1

release.yml then packages module 4.0.6-rc.1 with the editor named in .editor-version (still v4.0.5) and marks the GitHub release as a pre-release, so "latest" keeps pointing at the last stable version. Omeka S orders 4.0.5 < 4.0.6-rc.1 < 4.0.6, so sites upgrade in sequence. Valid module versions are X.Y.Z and X.Y.Z-(alpha|beta|rc).N only: Omeka S parses them with Composer's semver library, which rejects other labels, and make package refuses them. Run the workflow manually to override the editor ref. See ADR-40-01.

Architecture documentation

Architecture Decision Records (ADRs) and change documents live under docs/architecture/. Use them for significant design, security, storage, content-proxy, embedded-editor, or compatibility changes.

Records are identified by the GitHub tracking number of the change that produced them — here always a pull-request number, since issues are tracked upstream in exelearning/exelearning. There is no committed index:

make architecture-records   # print the ADR and change indexes
make architecture-check     # validate identifiers, metadata, cross-references

Requirements

• Omeka S 4.0 or higher
• PHP 7.4 or higher with ZipArchive extension

Issues and Support

Issue tracking for this module is centralized in the main exelearning/exelearning repository. Please open new issues there, and browse existing omeka-s-labeled issues before reporting a bug or requesting a feature.

License

This module is licensed under the AGPL v3 or later.