moodle-theme-migration

Moodle Theme Migration to Moodle 5

Migrate Moodle 3.x/4.x themes to Moodle 5, addressing Bootstrap 5 upgrade, deprecated features, and structural changes.

Migration Overview

1. Assess theme structure and dependencies
2. Update version.php and config.php
3. Migrate Bootstrap 4 → Bootstrap 5 changes
4. Refactor data attributes (data-* → data-bs-*)
5. Update SCSS/CSS for new utilities
6. Modify mustache templates
7. Convert jQuery to vanilla JavaScript
8. Test thoroughly on Moodle 5

Step 1: Version Configuration

Update version.php:

$plugin->version = 2025010100;
$plugin->requires = 2024100700; // Moodle 5.0
$plugin->supported = [500, 501];
$plugin->component = 'theme_yourtheme';
$plugin->release = '5.0.0';
$plugin->maturity = MATURITY_STABLE;

For Moodle 5.1+, note theme location changes to /public/theme/yourtheme/.

Step 2: Bootstrap 5 CSS Class Migration

See references/bootstrap5-migration.md for complete class mapping.

Critical Replacements

Bootstrap 4	Bootstrap 5
.ml-*, .mr-*	.ms-*, .me-*
.pl-*, .pr-*	.ps-*, .pe-*
.float-left/right	.float-start/end
.text-left/right	.text-start/end
.border-left/right	.border-start/end
.badge-*	.text-bg-*
.badge-pill	.rounded-pill
.sr-only	.visually-hidden
.font-weight-*	.fw-*
.font-italic	.fst-italic
.no-gutters	.g-0
.close	.btn-close
.rounded-sm/lg	.rounded-1/3
.form-group	margin utilities
.form-inline	.d-flex .flex-wrap .align-items-center
.custom-select	.form-select
.custom-check	.form-check
.media	.d-flex + flex utilities
.card-deck	.row .row-cols-*
.dropdown-menu-left/right	.dropdown-menu-start/end
.input-group-append/prepend	direct children

Step 3: Data Attributes

Replace all Bootstrap data attributes:

<!-- Before -->
<button data-toggle="tooltip" data-target="#modal" data-dismiss="alert">

<!-- After -->
<button data-bs-toggle="tooltip" data-bs-target="#modal" data-bs-dismiss="alert">

Common attributes: toggle, target, dismiss, placement, content, trigger, html, container, parent, slide, ride, interval.

Backwards Compatibility (Temporary)

For gradual migration, use the BS4 compat layer:

$PAGE->requires->js_call_amd('theme_boost/bs4-compat', 'init');

Or in mustache:

{{#js}}
require(['theme_boost/bs4-compat'], function(BS4Compat) {
    BS4Compat.init();
});
{{/js}}

Warning: This is deprecated and will be removed in Moodle 6.0.

Step 4: SCSS Migration

Deprecated Mixins (Remove)

• hover, hover-focus, plain-hover-focus, hover-focus-active
• float-left, float-right, float-none
• nav-divider, img-retina, text-hide, invisible
• form-control-focus, text-emphasis-variant, size
• sr-only() → visually-hidden()

Color Function Changes

// Before (Bootstrap 4)
theme-color-level('primary', 1);

// After (Bootstrap 5)
shift-color($primary, 10%);
// Level 1 = 10%, Level 2 = 20%, etc.

Media Query Breakpoints

// Before: targets < md
@include media-breakpoint-down(sm) { }

// After: targets < md (use the breakpoint itself)
@include media-breakpoint-down(md) { }

Step 5: Mustache Template Updates

Update templates in templates/ directory:

1. Replace deprecated Bootstrap classes
2. Update data attributes to data-bs-*
3. Check partial references for parent theme changes

Template Override Location

theme/yourtheme/templates/core/template_name.mustache
theme/yourtheme/templates/mod_forum/template_name.mustache

Step 6: JavaScript Migration

Convert jQuery Bootstrap calls to vanilla JavaScript:

// Before
import $ from 'jquery';
$('#myModal').modal('show');
$('[data-toggle="tooltip"]').tooltip();

// After
import Modal from 'theme_boost/bootstrap/modal';
import Tooltip from 'theme_boost/bootstrap/tooltip';

const modal = new Modal(document.getElementById('myModal'));
modal.show();

document.querySelectorAll('[data-bs-toggle="tooltip"]')
    .forEach(el => new Tooltip(el));

Available Bootstrap 5 Modules

Import from theme_boost/bootstrap/: alert, button, carousel, collapse, dropdown, modal, offcanvas, popover, scrollspy, tab, toast, tooltip

Step 7: Renderer Updates

If overriding core renderers in classes/output/:

1. Check for deprecated methods
2. Update template paths
3. Verify export_for_template() returns valid data

Step 8: Config.php Verification

Ensure config.php has:

$THEME->parents = ['boost'];
$THEME->rendererfactory = theme_overridden_renderer_factory::class;
$THEME->scss = function($theme) {
    return theme_yourtheme_get_main_scss_content($theme);
};

Moodle 5.1+ Public Folder Structure

For Moodle 5.1+, themes move to /public/theme/yourtheme/:

moodle/
├── public/
│   ├── theme/
│   │   └── yourtheme/
│   ├── mod/
│   └── blocks/
├── lib/
├── admin/
└── config.php

Testing Checklist

• Theme installs without errors
• All pages render correctly
• Dropdowns, modals, tooltips function
• Forms display and submit properly
• Mobile/responsive layouts work
• RTL (right-to-left) support maintained
• No JavaScript console errors
• SCSS compiles without warnings
• Accessibility maintained (screen readers)

Quick Reference Scripts

Use scripts/scan_theme.py to identify migration issues in theme files.

Additional Resources

See references/bootstrap5-migration.md for detailed class and component mapping with code examples.