Bootstrap 5 vs Legacy System

Oidis Framework contains two GUI systems that currently coexist in the same CORE packages. Understanding the difference is essential for writing correct new code and recognizing what to avoid when maintaining older projects.

Legacy System — Deprecated

The legacy GUI system (Io.Oidis.Gui.Primitives.*) is deprecated and must not be used for new development. If you encounter legacy classes in an existing project, maintain them in place but do not add new features using legacy patterns.

---

Overview

	Bootstrap 5 System	Legacy System
Status	✅ Active — all new development	❌ Deprecated — maintenance only
Namespace	Io.Oidis.Gui.Bootstrap.*	Io.Oidis.Gui.Primitives.*
Pattern	MVC: BasePanelController<Panel>	Viewer: BasePanelViewer
Rendering	Bootstrap 5 CSS + shadow DOM generator	Self-contained render engine
Browser support	Modern browsers only	IE6+
Base class size	Small, focused (27–100 LOC)	Monolithic (BasePanel = 2,600+ LOC)
Typing	Generic: BasePanelController<TPanel>	Untyped: IBasePanel
Copyright era	Oidis 2019+	Freescale 2014–2016, NXP 2017–2018

---

Bootstrap 5 System (Active)

The Bootstrap 5 system is a modern OOP-oriented GUI ecosystem built on top of Bootstrap 5 CSS. It uses a custom shadow DOM generator to produce SPA pages as typed TypeScript object graphs, where the framework manages the HTML rendering pipeline and Bootstrap 5 handles layout, components, and theming.

Architecture

BasePanelController<MyPanel>    ← controller: all logic
        │
        └── manages → MyPanel   ← panel: view only (innerHtml() template)
                          │
                          └── contains typed component references
                                  (Button, TextField, Table, …)
                                  connected via data-oidis-bind

Key classes

Class	Location	Purpose
BasePanelController<Panel>	Bootstrap/Primitives/	MVC controller — FetchData(), beforeLoad(), resolver()
BasePanel	Bootstrap/Primitives/	Thin view base — innerHtml() template string
GuiCommons	Bootstrap/Primitives/	Visibility/enable wrappers for Bootstrap panels
Button, TextField, Table, …	Bootstrap/UserControls/	Typed component references

How to identify Bootstrap code

• Namespace contains Bootstrap/ in the path
• BasePanelController<T> generic — controller has a typed panel parameter
• Panel class has innerHtml() method returning a template string
• Copyright: Copyright 20xx Oidis (Oidis-era files)
• Small, focused classes (controller ~100 LOC, panel ~30 LOC)

Example

// Panel — view only
export class ProductsPanel extends BasePanel {
    public readonly productsTable : Table<Product>;
    public readonly addButton : Button;

    constructor() {
        super();
        this.productsTable = new Table<Product>();
        this.addButton = new Button();
    }

    public innerHtml() : string {
        return `
            <div data-oidis-bind="${this.productsTable}"></div>
            <button data-oidis-bind="${this.addButton}">Add Product</button>
        `;
    }
}

// Controller — all logic
export class ProductsPanelController extends BasePanelController<ProductsPanel> {
    public async FetchData() : Promise<void> {
        // load data
    }
    public async resolver($instance : ProductsPanel) : Promise<void> {
        EventsBinding.SingleClick($instance.addButton, async () : Promise<void> => {
            // handle click
        });
    }
}

Instantiate every component in the constructor

Panel members are not created by the framework — there is no decorator, reflection or build-time transform that does it. Declare each user control, child panel or dialog as public readonly x : T; and create it with new T() in the constructor after super(). A member declared as = undefined stays undefined: the template renders the text undefined and GuiCommons logs "was declared but instance is missing".

---

Legacy System (Deprecated)

The legacy system originated in the embedded systems era (Freescale Semiconductor, 2014). It was designed for extreme cross-browser compatibility (IE6+) and contains its own complete rendering engine — scrollbars, layout pipeline, keyboard navigation, async loading, and more — without any dependency on external CSS frameworks.

While the legacy system contains a large amount of sophisticated code, its design predates modern browser standardization, TypeScript generics, and the Bootstrap CSS ecosystem. It is heavyweight, complex, and incompatible with the Bootstrap 5 development model.

Architecture

BasePanelViewer              ← viewer: rendering + controller combined
        │
        └── renders → BasePanel (Primitives)   ← monolithic view + render engine
                          │
                          └── built-in: scrollbars, async loader, keyboard nav,
                                        layout engine, child panel management, …

Key classes

Class	Location	Purpose
BasePanelViewer	Primitives/	Viewer-based controller + renderer
BasePanel	Primitives/	Monolithic panel: view AND renderer (2,600+ LOC)
BaseViewer	Primitives/	Abstract base for all viewer controllers
BaseGuiObject	Primitives/	Base for non-panel GUI objects
AbstractGuiObject	Primitives/	Framework-internal component base

How to identify legacy code

• Namespace contains Primitives/ in the path (NOT Bootstrap/Primitives/)
• Controller class extends BasePanelViewer or BaseViewer
• Panel class extends the large BasePanel from Primitives/ (not Bootstrap/Primitives/)
• Copyright: Freescale Semiconductor (2014–2016) or NXP (2017–2018) in file header
• Very large class files (BasePanel alone is ~98 KB, 2,600+ lines)
• No generic typing — methods accept IBasePanel not a typed panel class

---

Decision Guide

For new projects

Always use the Bootstrap 5 system. There is no case where new panels or controllers should be created using legacy classes.

For maintenance of existing legacy projects

• Bug fixes and minor changes: Stay in the legacy system — keep the existing patterns intact
• New features in a legacy project: Use Bootstrap 5 panels/controllers if the project structure allows. Do not add new legacy-pattern classes
• Full migration: Per-project business decision — some projects will remain on legacy indefinitely

For AI code generation

warning

When generating Oidis GUI code:

• Always import from Bootstrap/Primitives/ and Bootstrap/UserControls/ namespaces
• Never generate imports from Io.Oidis.Gui.Primitives.* for new panels or controllers
• If existing code uses legacy classes, maintain their style but flag as deprecated in comments

---

Copyright as an Era Indicator

The copyright headers in Oidis CORE source files reliably indicate which era (and therefore which system) a file belongs to:

Copyright	Era	System
Freescale Semiconductor 2014–2016	Embedded systems origin	Legacy
NXP 2017–2018	NXP acquisition period	Legacy
Oidis 2019+	Oidis Framework era	Bootstrap 5 (check namespace)
Oidis 2025+	Recent CORE additions	Bootstrap 5

Files with Oidis 2019+ copyright may still belong to legacy if they are in Primitives/ namespace — these are legacy files that received maintenance updates after the Oidis transition.

---

See also: Page-Panel-Controller | Architecture Overview | Panels and Controllers