nextcloud-exelearning

ℹ️ The eXeLearning editor is bundled into the app, so it works out of the box when the playground boots; the first load may take a few extra seconds while the app is installed. Viewer, preview and editing work normally.

Preview and edit eXeLearning .elpx packages directly inside Nextcloud Files.

The fastest way to try this app is the Nextcloud Playground — a full Nextcloud running in your browser via WebAssembly, no server required. Click the badge at the top of this README and you'll get a fresh Nextcloud with:

• The exelearning app installed and enabled.
• The Files app open, logged in as admin / admin.

Upload an .elpx package in Files and click it to open the viewer. Nothing is installed locally; everything runs in the browser and is discarded when you close the tab.

The instance is provisioned from blueprint.json, which installs the app with the playground's installApp step from a built exelearning.zip artifact. Every pull request gets its own one-click playground link (posted as a PR comment) built from that branch — see .github/workflows/playground-preview.yml.

When a user clicks a .elpx file in Nextcloud Files:

1. A full-page view opens at /apps/exelearning/view. The Nextcloud Viewer modal is deliberately not used: its built-in chrome cannot be customised, and the preview wants a full-bleed layout with a single Edit affordance.
2. The package is downloaded for the current user.
3. The browser extracts the ZIP archive in memory.
4. The internal index.html renders inside a sandboxed iframe.
5. Relative assets (html/, content/, libs/, theme/, idevices/, images, CSS, JS, audio, video, …) are served by a scoped Service Worker from the in-memory extraction — no second request to the server.

Thumbnails are powered by the screenshot.png inside the .elpx package.

Editing and creation both need the bundled editor, so both are optional. The release package (GitHub release / app store) already bundles it; only a source checkout needs make download-editor. Preview-only installs are first-class and no preview code path depends on js/editor/ being present.

• "Edit with eXeLearning" opens the static editor over the current package.
• "New eXeLearning resource" in the Files New menu writes a blank .elpx from a server-side template and opens it in the editor. The file is created either way, but without the editor bundle the page it lands on returns 404.

• gdrive-exelearning is a static, browser-only web app that integrates with Google Drive. This project is a real Nextcloud app: no OAuth, no Drive Picker, no GitHub Pages, no Google client SDKs. Permission and permission checks live in Nextcloud's APIs.
• exeviewer is the architectural inspiration for in-browser ZIP extraction and Service Worker routing. This project keeps that core idea but binds the entry points (URL routing, authentication, file access) to Nextcloud.

Each cell below is exercised in CI on a real Nextcloud install with the listed PHP version (sqlite throughout — this app has no DB schema of its own, so a multi-DB sweep would only re-test Nextcloud core). The matrix is defined in .github/workflows/ci.yml; reproduce it locally with make ci-matrix.

Older Nextcloud versions (28, 29, 30) are EOL and not part of the matrix. NC 31 enters the supported range as best effort because upstream maintenance ends mid-2026; NC 32 and 33 are the reference targets.

The CI matrix checks that the app installs and enables on each version. It does not drive the Files app in a browser, so the Files integration (New menu entry, file actions) is not covered by it: NC 31-32 read those registrations through @nextcloud/files v3 and NC 33 through v4, and the app registers through whichever one the running server reads.

Browsers must support Service Workers in the Nextcloud origin. The viewer will refuse to start otherwise.

A single make target builds the frontend, starts a Nextcloud container with auto-install enabled (admin user + SQLite), copies the app files into the container, configures apps_paths so Nextcloud can write to custom_apps/, enables the app, and registers the .elpx MIME mapping:

make up

The first run pulls the nextcloud:stable image (resolves to the current upstream major) and the SQLite install finishes in seconds; subsequent make up invocations skip the pull. Pin a specific major with NC_VERSION=33 make up.

When the script prints "Nextcloud + eXeLearning is ready" open http://localhost:8080 and log in as admin / admin. Upload an .elpx in the Files app and click it.

The Makefile copies appinfo/, lib/, js/, templates/, img/ and src/sw/ into the container with docker cp after Nextcloud is installed. It does not bind-mount the repo (-v $(pwd):…). On Docker-on-macOS bind mounts go through a slow shared filesystem, and pulling node_modules/ (≈1 GB, hundreds of thousands of files) through it during Nextcloud's startup stalls the install. Copying just the runtime files (a few MB) brings make up down to seconds.

If you change PHP or rebuild the frontend, make sync re-copies the same six directories into the running container so you do not have to make restart:

npm run build && make sync

make up DOCKER_PORT=9000           # serve on http://localhost:9000
make up NC_VERSION=33              # pin a Nextcloud major (default: stable)
make up DOCKER_IMAGE=nextcloud:33-apache  # full image override
make up NC_ADMIN_USER=ernesto NC_ADMIN_PASS=changeme
make up DOCKER_NAME=nc-test        # use a different container name

Reproduce the full CI matrix locally:

make ci-matrix                     # iterates NC 31/32/33 × PHP 8.2/8.3/8.4
NC_VERSIONS=33 PHP_VERSIONS=8.4 make ci-matrix  # narrow to one cell

Data lives only in the container; make down is destructive — add your own -v mount on /var/www/html/data if you need to keep uploads.

If you would rather wire it up by hand (no Make), the equivalent commands are documented in DEVELOPMENT.md under "The 'apps' folder is not writable".

Developer documentation lives in DEVELOPMENT.md:

• Local development — composer / npm setup, linking into a Nextcloud install, watch mode.
• Running tests — Vitest and PHPUnit.
• Verifying the viewer works — what to look for in DevTools.
• MIME mapping — .elpx / .elp registration plus the static icon alias.
• Viewer integration — the data flow from click to sandboxed iframe.
• Thumbnails — preview provider and fallback.
• Optional editor support — enabling the in-app eXeLearning editor.
• Security model — sandbox flags, SW scope, ZIP limits.
• Known limitations and Troubleshooting.

Coding agents should also read AGENTS.md for the rules and conventions that apply when generating code.

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

AGPL-3.0-or-later. See LICENSE.