ElementManager

ElementManager is a static utility class (io-oidis-gui) for direct DOM manipulation. Most of its functionality is used internally by the framework. However, a subset of methods is legitimately useful in controllers and custom components when the standard GuiCommons API does not cover the use case.

Package: io-oidis-gui

import { ElementManager } from "@io-oidis-gui/.../Utils/ElementManager.js";

When to Use ElementManager

The standard approach in Oidis controllers is to use the GuiCommons API via data-oidis-bind references:

$instance.panel.Visible(true);   // show panel
$instance.button.Enabled(false); // disable button

Reach for ElementManager when you need to operate on elements that are not available as typed panel references — for example, wrapper containers, dynamically rendered HTML, overlay elements, or when applying global behaviors like dark mode switching.

Do not bypass GuiCommons.Visible() for bound components. Use ElementManager.Show/Hide only for elements that are not managed by the framework's component system.

Visibility Control

Show and hide DOM elements by their element ID or component reference.

// Show an element
ElementManager.Show("myElementId");

// Hide an element
ElementManager.Hide("myElementId");

// Toggle visibility based on current state
ElementManager.ToggleVisibility("myElementId");

// Check current visibility
const visible : boolean = ElementManager.IsVisible("myElementId");

The $id parameter accepts:

A string element ID
A direct HTMLElement reference
An IGuiCommons component reference (e.g., from data-oidis-bind)

IsVisible() checks the CSS display property — an element is considered visible if display is not "none".

CSS Class State (On/Off/Active)

For elements that use CSS class names On, Off, and Active for visual state (common in custom UI components):

ElementManager.TurnOn("myElementId");     // sets className = "On"
ElementManager.TurnOff("myElementId");    // sets className = "Off"
ElementManager.TurnActive("myElementId"); // sets className = "Active"
ElementManager.ToggleOnOff("myElementId"); // switches between "On" and "Off"

Z-Index Management

Use these when you need to control the stacking order of floating elements, overlays, or dialogs that live outside the normal component hierarchy.

// Bring to absolute front — sets z-index: 99999 (also applies position: fixed if not set)
ElementManager.TopMost("overlayElementId");

// Bring forward — sets z-index: 1000 (also applies position: relative if not set)
ElementManager.BringToFront("floatingPanelId");

// Send to back — sets z-index: 0 (also applies position: relative if not set)
ElementManager.SendToBack("backgroundElementId");

All three methods automatically set a position CSS property if the element does not already have one (TopMost uses fixed, the others use relative).

Theme Switching

Apply a global dark/light theme to the entire application. This sets the data-bs-theme attribute on document.documentElement, which Bootstrap and Oidis CSS rules use for theme-aware styling.

import { Theme } from "@io-oidis-gui/.../Enums/Theme.js";

// Apply dark mode
ElementManager.setTheme(Theme.DARK);

// Apply light mode
ElementManager.setTheme(Theme.LIGHT);

// Apply based on system preference (resolved at call time)
ElementManager.setTheme(Theme.AUTO);

Theme.AUTO reads window.matchMedia("(prefers-color-scheme: dark)") at the moment of the call and applies either DARK or LIGHT accordingly. It does not dynamically track system preference changes — call setTheme(Theme.AUTO) again to re-evaluate.

Typical usage: Call setTheme() from a controller when the user switches the theme preference, or during application initialization based on a stored setting.

In a Hub application do not call setTheme() directly — use Utils/ColorSchemeManager from io-oidis-hub-gui, which wraps it. ColorSchemeManager.Apply($scheme) takes a ColorScheme value (LIGHT, DARK, SYSTEM), keeps following prefers-color-scheme while SYSTEM is active, and getCurrent() / IsDark() answer which appearance is on screen. The matching per-user choice, its storage in the account and the target.colorSchemeSupported flag are described in Extending Hub GUI.

Other Capabilities (Framework-Internal)

The following methods exist on ElementManager but are intended for internal CORE use. They are listed here for architectural awareness:

Category	Methods	Used by
Element access	`getElement()`, `Exists()`, `CleanElementCache()`	All GUI rendering
CSS properties	`getCssValue()`, `setCssProperty()`, `ClearCssProperty()`	Component styling
Sizing	`setWidth()`, `setHeight()`, `getEnvelopWidth()`, `getOffsetWidth()`	Layout engine
Positioning	`getAbsoluteOffset()`, `setPosition()`, `getScreenPosition()`	Resize/drag bars
Opacity	`setOpacity()`, `ChangeOpacity()`, `StopOpacityChange()`	Opacity animations
Transform	`Scale()`, `setZoom()`	Zoom/scale effects
Content	`getInnerHtml()`, `setInnerHtml()`, `AppendHtml()`, `PrependHtml()`	Dynamic HTML

If you find yourself needing these internal methods in application code, consider whether the requirement can be met through the component API or a custom UserControl instead.

When to Use ElementManager​

Visibility Control​

CSS Class State (On/Off/Active)​

Z-Index Management​

Theme Switching​

Other Capabilities (Framework-Internal)​