diff --git a/moodle-plugins/filter_mediacmslti/CHANGELOG.md b/moodle-plugins/filter_mediacmslti/CHANGELOG.md new file mode 100644 index 00000000..03261a76 --- /dev/null +++ b/moodle-plugins/filter_mediacmslti/CHANGELOG.md @@ -0,0 +1,54 @@ +# Changelog + +All notable changes to the MediaCMS LTI Filter plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-01-23 + +### Added +- Initial release of MediaCMS LTI Filter +- Automatic detection of MediaCMS video URLs in Moodle content +- Transparent LTI 1.3 authentication for embedded videos +- Support for `/view?m=TOKEN` and `/embed?m=TOKEN` URL patterns +- Configurable MediaCMS URL setting +- Configurable LTI tool selection from Moodle's LTI tools +- Configurable iframe dimensions (width/height) +- Auto-submit form mechanism for seamless LTI launch +- Support for Moodle 5.0+ +- Privacy provider implementation for GDPR compliance +- Comprehensive documentation (README, INSTALLATION guide) +- Multi-language support framework (English strings included) + +### Security +- Only processes content for logged-in users (no guest access) +- Uses Moodle's LTI 1.3 security framework +- Passes user context via secure `login_hint` parameter +- All URLs properly escaped and sanitized + +## [Unreleased] + +### Planned Features +- Support for additional MediaCMS URL patterns +- Customizable iframe styling options +- Cache optimization for LTI configuration +- Support for playlist URLs +- Admin interface to preview filter behavior +- Bulk URL conversion tool +- Statistics/usage tracking + +--- + +## Version History + +- **1.0.0** (2026-01-23) - Initial release + +## Upgrade Notes + +### Upgrading to 1.0.0 +- First release, no upgrade path needed + +--- + +For detailed information about each release, see the Git commit history. diff --git a/moodle-plugins/filter_mediacmslti/EXAMPLE_OUTPUT.md b/moodle-plugins/filter_mediacmslti/EXAMPLE_OUTPUT.md new file mode 100644 index 00000000..23977237 --- /dev/null +++ b/moodle-plugins/filter_mediacmslti/EXAMPLE_OUTPUT.md @@ -0,0 +1,223 @@ +# Example Output - How the Filter Works + +## Input (What users paste) + +``` +https://deic.mediacms.io/view?m=KmITliaUC +``` + +## Output (What gets rendered) + +### HTML Generated by Filter + +```html +
+ + + + + + + + +
+``` + +## What Happens Step-by-Step + +### 1. User Views Page +``` +User opens Moodle page containing the MediaCMS URL +↓ +Filter detects: https://deic.mediacms.io/view?m=KmITliaUC +↓ +Extracts video token: KmITliaUC +``` + +### 2. HTML Generation +``` +Filter generates: +- Iframe with unique ID +- Hidden form with LTI parameters +- JavaScript to auto-submit +``` + +### 3. LTI Authentication Flow +``` +Form submits to MediaCMS OIDC endpoint +↓ +MediaCMS receives: + - iss: https://your-moodle-site.com + - client_id: ABC123XYZ + - login_hint: 42 (user's Moodle ID) + - target_link_uri: https://deic.mediacms.io/lti/launch/?media_friendly_token=KmITliaUC +↓ +MediaCMS redirects to Moodle's auth endpoint +↓ +Moodle validates and creates JWT token +↓ +Moodle POSTs JWT back to MediaCMS +↓ +MediaCMS validates JWT and creates session +↓ +MediaCMS redirects to /lti/embed/KmITliaUC/ +↓ +MediaCMS checks permissions and redirects to /view?m=KmITliaUC +↓ +Video loads in iframe! +``` + +### 4. User Experience +``` +User sees: +1. Page loads +2. Empty iframe appears briefly (< 1 second) +3. Video player loads inside iframe +4. Video starts playing +``` + +## Real-World Examples + +### Example 1: Course Page + +**Input:** +```html +

Welcome to the course! Watch this introduction:

+

https://deic.mediacms.io/view?m=KmITliaUC

+``` + +**Output:** +```html +

Welcome to the course! Watch this introduction:

+
+ +
...
+ +
+``` + +### Example 2: Multiple Videos + +**Input:** +```html +

Week 1 Videos

+

Lecture 1: https://deic.mediacms.io/view?m=ABC123

+

Lecture 2: https://deic.mediacms.io/view?m=XYZ789

+``` + +**Output:** +```html +

Week 1 Videos

+

Lecture 1: +

+ + ... +
+

+

Lecture 2: +

+ + ... +
+

+``` + +Each video gets its own iframe with its own LTI authentication! + +### Example 3: Mixed Content + +**Input:** +```html +

Check out this resource:

+

Regular link

+

https://deic.mediacms.io/view?m=KmITliaUC

+

Another link: https://google.com

+``` + +**Output:** +```html +

Check out this resource:

+

Regular link

+
+ + ... +
+

Another link: https://google.com

+``` + +Only MediaCMS URLs are converted! Other URLs remain unchanged. + +## Performance Notes + +- **Fast Detection**: Regex-based URL matching is extremely fast +- **No Database Queries**: Configuration is cached +- **Lazy Loading**: Videos only load when iframe initiates LTI flow +- **Minimal Overhead**: Each conversion adds ~500 bytes of HTML + +## Security Notes + +- **User Context**: Each iframe uses the current user's Moodle ID +- **CSRF Protected**: LTI flow includes state/nonce validation +- **Domain Restricted**: Only configured MediaCMS domain is processed +- **Guest Users**: Filter doesn't run for guest users (returns original text) + +## Browser Compatibility + +Works in all modern browsers: +- ✅ Chrome/Edge (Chromium) +- ✅ Firefox +- ✅ Safari +- ✅ Mobile browsers (iOS Safari, Chrome Mobile) + +## Troubleshooting Examples + +### If URL Doesn't Convert + +**Check these patterns:** +``` +✅ https://deic.mediacms.io/view?m=KmITliaUC +✅ https://deic.mediacms.io/embed?m=KmITliaUC +❌ https://deic.mediacms.io/view/KmITliaUC (no ?m= parameter) +❌ http://other-domain.com/view?m=KmITliaUC (wrong domain) +``` + +### If Video Doesn't Load + +**Check browser console:** +```javascript +// Expected: No errors +// If you see CORS errors: Check MediaCMS iframe settings +// If you see 403 Forbidden: Check LTI configuration +// If you see 404: Check MediaCMS URL in settings +``` + +--- + +**This is what makes the transparent LTI authentication possible!** diff --git a/moodle-plugins/filter_mediacmslti/INSTALLATION.md b/moodle-plugins/filter_mediacmslti/INSTALLATION.md new file mode 100644 index 00000000..7f788e18 --- /dev/null +++ b/moodle-plugins/filter_mediacmslti/INSTALLATION.md @@ -0,0 +1,105 @@ +# Quick Installation Guide - MediaCMS LTI Filter + +## Prerequisites + +- Moodle 5.0 or later +- MediaCMS instance with LTI 1.3 support +- LTI External Tool already configured in Moodle for MediaCMS + +## Installation Steps + +### 1. Install the Plugin + +**Option A: Upload via Moodle UI** +``` +1. Log in as Moodle admin +2. Site administration → Plugins → Install plugins +3. Upload the filter_mediacmslti.zip file +4. Click "Install plugin from the ZIP file" +5. Complete the installation wizard +``` + +**Option B: Manual Installation** +```bash +# Copy plugin to Moodle filter directory +cp -r filter_mediacmslti /path/to/moodle/filter/ + +# Set permissions +chown -R www-data:www-data /path/to/moodle/filter/filter_mediacmslti + +# Visit Moodle notifications page to complete installation +``` + +### 2. Configure the Filter + +``` +1. Site administration → Plugins → Filters → MediaCMS LTI Filter +2. Set "MediaCMS URL" to your MediaCMS instance (e.g., https://deic.mediacms.io) +3. Select your LTI tool from the "LTI External Tool" dropdown +4. Optionally adjust iframe width/height (defaults: 960x540) +5. Click "Save changes" +``` + +### 3. Enable the Filter + +``` +1. Site administration → Plugins → Filters → Manage filters +2. Find "MediaCMS LTI Embed" in the list +3. Change from "Disabled" to "On" +4. Click "Save changes" +``` + +### 4. Test It! + +``` +1. Create a Page resource in any course +2. Paste a MediaCMS URL: https://deic.mediacms.io/view?m=KmITliaUC +3. Save the page +4. View the page - video should embed automatically! +``` + +## Configuration Quick Reference + +| Setting | Example Value | Description | +|---------|---------------|-------------| +| MediaCMS URL | `https://deic.mediacms.io` | Your MediaCMS instance (no trailing slash) | +| LTI External Tool | MediaCMS | Select from dropdown | +| Iframe Width | 960 | Width in pixels | +| Iframe Height | 540 | Height in pixels | + +## Troubleshooting Quick Fixes + +**URLs not converting?** +- Check filter is "On" in Filters → Manage filters +- Verify MediaCMS URL matches the URLs you're pasting +- Ensure user is logged in (not guest) + +**Video not loading?** +- Check LTI tool is configured correctly +- Verify client_id and issuer match between Moodle and MediaCMS +- Check browser console for errors + +**Need more help?** +See full README.md for detailed troubleshooting and technical documentation. + +## What URLs Are Supported? + +The filter automatically detects these patterns: +- `https://deic.mediacms.io/view?m=TOKEN` +- `https://deic.mediacms.io/embed?m=TOKEN` + +Replace `deic.mediacms.io` with your configured MediaCMS URL. + +## Quick Test Checklist + +- [ ] Plugin installed successfully +- [ ] Filter settings configured +- [ ] Filter enabled in Manage filters +- [ ] LTI tool configured and working +- [ ] Test URL pasted in Page resource +- [ ] Video embeds and plays correctly + +## Support + +Full documentation: See README.md +MediaCMS docs: https://docs.mediacms.io diff --git a/moodle-plugins/filter_mediacmslti/LICENSE b/moodle-plugins/filter_mediacmslti/LICENSE new file mode 100644 index 00000000..6daf41c5 --- /dev/null +++ b/moodle-plugins/filter_mediacmslti/LICENSE @@ -0,0 +1,22 @@ +GNU GENERAL PUBLIC LICENSE +Version 3, 29 June 2007 + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . + +--- + +Copyright (C) 2026 MediaCMS + +For the full text of the GNU GPL v3 license, visit: +https://www.gnu.org/licenses/gpl-3.0.html diff --git a/moodle-plugins/filter_mediacmslti/README.md b/moodle-plugins/filter_mediacmslti/README.md new file mode 100644 index 00000000..c2d3500f --- /dev/null +++ b/moodle-plugins/filter_mediacmslti/README.md @@ -0,0 +1,264 @@ +# MediaCMS LTI Filter for Moodle 5 + +A Moodle filter plugin that automatically converts MediaCMS video URLs into LTI-authenticated embedded video players. Users can simply paste MediaCMS URLs into any Moodle content area (course descriptions, page content, etc.) and the videos will be embedded with transparent LTI authentication. + +## Features + +- **Automatic URL Detection**: Detects MediaCMS video URLs and converts them to embedded iframes +- **Transparent LTI Authentication**: Automatically initiates LTI 1.3 authentication flow without user interaction +- **Seamless Integration**: Works in any Moodle text area (Pages, Activities, Descriptions, etc.) +- **Configurable**: Admin can set MediaCMS URL, LTI tool, and iframe dimensions +- **Moodle 5 Compatible**: Built specifically for Moodle 5.0+ + +## How It Works + +1. User pastes a MediaCMS URL (e.g., `https://deic.mediacms.io/view?m=KmITliaUC`) +2. Filter detects the URL and extracts the video token +3. Generates an iframe with an auto-submitting form that initiates LTI authentication +4. Form includes: + - Current user's Moodle ID as `login_hint` + - LTI platform issuer (ISS) + - LTI client ID + - Target video via custom parameters +5. Video loads in iframe with proper LTI authentication + +## Prerequisites + +Before installing this filter, you must have: + +1. **MediaCMS with LTI Support**: Your MediaCMS instance must have LTI 1.3 integration enabled +2. **LTI External Tool Configured**: An LTI External Tool must be configured in Moodle that connects to MediaCMS +3. **Moodle 5.0 or later** + +## Installation + +### Method 1: Via Moodle Plugin Directory (Recommended) + +1. Download the plugin ZIP file +2. Log in as Moodle admin +3. Go to **Site administration → Plugins → Install plugins** +4. Upload the ZIP file +5. Click "Install plugin from the ZIP file" +6. Follow the on-screen prompts + +### Method 2: Manual Installation + +1. Copy the `filter_mediacmslti` directory to your Moodle installation: + ```bash + cp -r filter_mediacmslti /path/to/moodle/filter/ + ``` + +2. Set proper permissions: + ```bash + cd /path/to/moodle + chown -R www-data:www-data filter/filter_mediacmslti + ``` + +3. Log in as Moodle admin and go to **Site administration → Notifications** +4. Moodle will detect the new plugin and prompt you to upgrade +5. Click "Upgrade Moodle database now" + +## Configuration + +### Step 1: Configure LTI External Tool (if not already done) + +1. Go to **Site administration → Plugins → Activity modules → External tool → Manage tools** +2. Click "Configure a tool manually" +3. Enter the following details: + - **Tool name**: MediaCMS + - **Tool URL**: `https://deic.mediacms.io/lti/launch/` + - **LTI version**: LTI 1.3 + - **Public key type**: Keyset URL + - **Public keyset**: `https://deic.mediacms.io/lti/jwks/` + - **Initiate login URL**: `https://deic.mediacms.io/lti/oidc/login/` + - **Redirection URI(s)**: `https://deic.mediacms.io/lti/launch/` +4. Enable: + - Deep Linking (Content-Item Message) + - Share launcher's name with tool + - Share launcher's email with tool +5. Click "Save changes" +6. **Note the Tool ID** (you'll need this for the filter configuration) + +### Step 2: Configure Filter Settings + +1. Go to **Site administration → Plugins → Filters → MediaCMS LTI Filter** +2. Configure the following settings: + + - **MediaCMS URL**: Enter your MediaCMS instance URL + - Example: `https://deic.mediacms.io` + - Do NOT include trailing slash + + - **LTI External Tool**: Select the MediaCMS tool you configured in Step 1 + - Choose from the dropdown of available LTI tools + + - **Iframe Width**: Default width in pixels (default: 960) + + - **Iframe Height**: Default height in pixels (default: 540) + +3. Click "Save changes" + +### Step 3: Enable the Filter + +1. Go to **Site administration → Plugins → Filters → Manage filters** +2. Find "MediaCMS LTI Embed" in the list +3. Change the setting from "Disabled" to **"On"** + - Alternatively, use "Off, but available" to allow course-level control +4. Adjust the filter order if needed (higher = runs earlier) +5. Click "Save changes" + +## Usage + +### For Content Creators + +Once the filter is enabled, simply paste MediaCMS URLs into any Moodle content area: + +#### Example 1: In a Page Resource + +1. Create or edit a Page resource +2. In the content editor, paste the MediaCMS URL: + ``` + https://deic.mediacms.io/view?m=KmITliaUC + ``` +3. Save the page +4. The URL will automatically be replaced with an embedded video player + +#### Example 2: In Course Description + +1. Edit course settings +2. In the "Course description" field, paste: + ``` + Watch this introduction video: https://deic.mediacms.io/view?m=KmITliaUC + ``` +3. Save +4. The video will be embedded directly in the course summary + +#### Example 3: In Activity Description + +1. Create any activity (Forum, Assignment, etc.) +2. In the description field, paste MediaCMS URLs +3. Students will see embedded videos when viewing the activity + +### Supported URL Formats + +The filter recognizes these URL patterns: +- `https://deic.mediacms.io/view?m=TOKEN` +- `https://deic.mediacms.io/embed?m=TOKEN` +- `http://` versions (if your MediaCMS uses HTTP) + +### For End Users (Students/Teachers) + +No action required! When viewing content with MediaCMS URLs: +1. Page loads normally +2. Video player appears in an iframe +3. LTI authentication happens transparently in the background +4. Video starts playing (if user has permission) + +**Note**: Users must be logged into Moodle. Guest users will see the original URL without embedding. + +## Troubleshooting + +### URLs are not being converted + +**Check**: +1. Filter is enabled: **Site admin → Plugins → Filters → Manage filters** +2. MediaCMS URL in settings matches the URLs you're pasting +3. LTI tool is selected in filter settings +4. User is logged in (not guest) + +### Video shows "Access Denied" error + +**Possible causes**: +1. LTI tool not configured correctly +2. MediaCMS not receiving proper authentication +3. User doesn't have permission to view the video in MediaCMS + +**Debug**: +- Check Moodle logs: **Site admin → Reports → Logs** +- Check MediaCMS LTI logs on the MediaCMS admin panel +- Verify LTI tool configuration (client_id, issuer, etc.) + +### Iframe shows blank or loading forever + +**Check**: +1. MediaCMS URL is accessible from your network +2. Browser console for JavaScript errors +3. LTI tool ID is correct +4. MediaCMS OIDC login endpoint is working: `https://deic.mediacms.io/lti/oidc/login/` + +### Multiple iframes from same URL + +The filter replaces ALL occurrences of MediaCMS URLs. If you paste the same URL twice, you'll get two embedded players. + +**Solution**: Paste the URL only once per page, or use HTML mode to add the URL as plain text (wrap in `` tags). + +## Technical Details + +### How the Filter Works + +1. **Text Processing**: Filter scans all text content using regex patterns +2. **URL Extraction**: Identifies MediaCMS URLs and extracts video tokens +3. **LTI Configuration**: Retrieves LTI settings (issuer, client_id) from configured tool +4. **HTML Generation**: Creates: + - An `