Backward Compatibility Breaks 10.1

Backward Compatibility Breaks: 10.0.x to 10.1.0

This document lists all backward compatibility (B/C) breaks between Proclaim 10.0.x and 10.1.0. Review this before upgrading, especially if you have custom templates, direct SQL queries, or third-party integrations.

Status: Initial audit completed 2026-02-16. Needs manual review and testing.

---

Database Schema Changes

Dropped Columns (#__bsms_teachers)

Migration: 10.1.0-20260217.sql

Column	Type	Notes
imageh	INT	Legacy image height
imagew	INT	Legacy image width
thumb	TEXT	Legacy thumbnail path
thumbw	INT	Legacy thumbnail width
thumbh	INT	Legacy thumbnail height
address1	TEXT	Legacy address field
catid	INT	Legacy category ID

Impact: Any direct SQL or custom code referencing these columns will break. The CwmteacherTable class no longer declares these properties.

New Junction Tables

Table	Migration	Purpose
#__bsms_study_scriptures	10.1.0-20260212.sql	Replaces fixed 2-slot scripture columns (unlimited refs)
#__bsms_study_teachers	10.1.0-20260218.sql	Replaces single teacher_id (multiple teachers)
#__bsms_bible_translations	10.1.0-20260208.sql	Bible translation tracking
#__bsms_bible_verses	10.1.0-20260208.sql	Local Bible verse storage
#__bsms_scripture_cache	10.1.0-20260208.sql	API response cache

New Columns on Existing Tables

#__bsms_studies: bible_version, bible_version2, image, created, created_by, created_by_alias, modified, modified_by, checked_out, checked_out_time

#__bsms_series: image, publish_up, publish_down, created, created_by, created_by_alias, modified, modified_by, checked_out, checked_out_time

9 tables gained checked_out/checked_out_time and created/created_by/modified/modified_by audit fields (teachers, series, topics, message_type, servers, podcast, templates, templatecode, comments).

New Indexes

17 composite indexes added for performance (10.1.0-20260207.sql).

Data Migrations

• Tooltip link types remapped (10.1.0-20260214.sql): Link type 4 ("Details with ToolTip") converted to 1, link type 5 ("Media with ToolTip") converted to 2.

---

Removed PHP Classes

Views/Controllers (PR #1057)

Class	Side	Reason
CwmuploadController	Admin	Dead jQuery file upload
CwmdirModel	Admin	Dead directory browser
Cwmdir/HtmlView	Admin	Dead directory browser
Cwmupload/HtmlView	Admin	Dead upload view
Cwmsqueezebox/HtmlView	Site	Dead MooTools popup

All associated tmpl/ directories also removed.

Field Classes

Class	Reason
StudyImageField	Migrated to thumbnailm/image columns (PR #1060)
ListOptionsField	Dead code
SeriesOptionsField	Dead code
PluploadField	jQuery dependency removed

Bible Provider

Class	Reason
BibleGatewayProvider	Scraping replaced with proper API providers

Impact: Any configuration referencing biblegateway as a provider must be reconfigured to use GetBible, API.Bible, or Local.

---

Changed Query Patterns

Teacher Queries Use Junction Table

All queries that previously did:

JOIN #__bsms_teachers ON teachers.id = studies.teacher_id

Now use:

LEFT JOIN #__bsms_study_teachers stj ON stj.study_id = study.id AND stj.ordering = 0
LEFT JOIN #__bsms_teachers teacher ON teacher.id = COALESCE(stj.teacher_id, study.teacher_id)

The COALESCE fallback preserves backward compatibility with the legacy teacher_id column. Affects 20+ query locations across models and helpers.

Impact: Third-party code doing direct teacher JOINs against studies.teacher_id will still work for the primary teacher but will miss secondary teachers.

Scripture Queries Use Junction Table

Legacy columns (booknumber, chapter_begin, verse_begin, chapter_end, verse_end, and *2 variants) are preserved and kept in sync via CwmscriptureHelper::syncLegacyColumns(). The junction table is now the source of truth.

Impact: Old 2-slot limit removed (now supports up to 20 references per message). Direct queries against legacy columns still work but won't see references beyond the first two.

---

Form Field Changes

Message Edit Form (admin/forms/message.xml)

Old Field	New Field	Change
booknumber (BookList)	scriptures (subform)	Scripture entry redesigned
chapter_begin, verse_begin, chapter_end, verse_end	Inside scripture_row.xml	Moved into subform
booknumber2 (BookList)	Removed	Replaced by unlimited subform
teacher_id (TeacherList dropdown)	teacher_id (hidden) + teachers (subform)	Teacher selection redesigned
studyimage (custom param field)	Removed	Migrated to thumbnailm/image columns

New fields added: scriptures, teachers, image, publish_up, publish_down, audit fields, check-in fields.

---

Template Parameter Changes

Renamed Parameters

All handled automatically by CwmtemplatemigrationHelper during upgrade.

Old Name	New Name	Reason
teacher_id	lteacher_id	l-prefix for model filter params
series_id	lseries_id	l-prefix
booknumber	lbooknumber	l-prefix
topic_id	ltopic_id	l-prefix
messagetype	lmessagetype	l-prefix
locations	llocations	l-prefix
show_type_search	show_messagetype_search	Match PHP code
show_locations_search	show_location_search	Match PHP code
teacherimager*r*ow	teacherimagerow	Typo fix (all 6 context prefixes)

Impact: Third-party code reading template params by the old names will get null values.

New Parameters (with defaults)

Parameter	Default	Purpose
show_passage_view	'3'	Bible passage display mode
showpassage_icon	'1'	Passage icon display
allow_version_switch	'0'	Bible version switcher
listheadertype	'table-light'	List header style
scripture_separator	'middot'	Scripture reference separator
pagination_style	'pagination'	Pagination style
infinite_scroll_threshold	'3'	Pages before infinite scroll pauses
series_pagination_style	'pagination'	Series pagination style
series_infinite_scroll_threshold	'3'	Series infinite scroll threshold
default_show_archived	'2'	Archived messages display
default_show_archive_badge	'1'	Archive badge display

Color Format Change

Legacy 0x hex format (e.g., 0xFF0000) auto-converted to # format (e.g., #FF0000). Affected: backcolor, frontcolor, lightcolor, screencolor, popupbackground, teacherdisplay_color, seriesdisplay_color.

Path String Replacement

All template params containing media/com_biblestudy/ converted to media/com_proclaim/.

---

Layout Editor Changes

Deprecated Elements

• scripture1 - hidden from palette, still renders in existing layouts
• scripture2 - hidden from palette, still renders in existing layouts

New Elements

• scriptures - unified replacement for scripture1/scripture2
• teachers-list - all teachers comma-separated
• teacher-title - teacher title + name combined
• dstudytext - message body (details context only)

---

Removed Assets

CSS Files

• biblegateway-print.css (+ minified) - removed with BibleGateway provider
• proclaim-debug.css (+ minified) - removed
• simple-grid.css - removed

Stock Images

• Entire media/images/ directory (150+ legacy stock images) removed

JavaScript

• jQuery completely removed
• All *.es5.js files removed (30+ files)
• All addScript/addStyleSheet/addScriptDeclaration/addStyleDeclaration calls migrated to WebAssetManager

---

Link Type Changes

• Link type 4 ("Link to Details with ToolTip") - removed from UI, silently falls back to type 1
• Link type 5 ("Link to Media with ToolTip") - removed from UI, silently falls back to type 2
• SQL migration converts stored values: 4 -> 1, 5 -> 2

---

Bible Provider Changes

Provider	Status
BibleGateway	Removed - class deleted entirely
GetBible	Active (free, no key required)
API.Bible	Active (free API key required)
Local	Active (offline, always available)

---

Migration Safety

Most breaks are handled automatically by the migration system:

• Junction tables populated from legacy columns (data preserved)
• Template params renamed via CwmtemplatemigrationHelper
• Link types converted via SQL migration
• Color formats converted automatically
• Legacy paths updated (com_biblestudy -> com_proclaim)
• studyimage param migrated to DB columns
• Legacy teacher_id and scripture columns preserved with COALESCE fallback

What Users Need to Know

1. BibleGateway is gone - reconfigure to GetBible, API.Bible, or Local
2. Legacy stock images removed - custom templates referencing media/images/ will 404
3. jQuery removed - any custom JS using jQuery must be updated
4. Tooltip link types silently downgraded - may affect user expectations
5. Teacher table columns dropped - custom queries against dropped columns will fail
6. Template param names changed - custom code reading old param names gets null

---

Last updated: 2026-02-16