Navigation Back to home

DOM Utility Library

Introduction to the Monster DOM Library

The Monster DOM Library provides a comprehensive set of utilities and classes to efficiently manipulate and interact with the DOM. This documentation offers an overview of key components, usage, and practical examples to assist with development. The library aims to simplify common DOM operations while maintaining full compatibility with modern web standards and best practices.

Document Utilities

getDocument()

The getDocument() function retrieves the global document object. This function provides a direct reference to the document object, useful for DOM manipulations. It helps standardize access to the document, especially when using libraries or frameworks that abstract DOM handling.

const doc = getDocument();
console.log(doc.title); // Outputs the title of the current document

Returns: The global document object.
Throws: Error if the environment does not support the document object.

domReady

domReady is a promise that resolves when the DOMContentLoaded event fires, meaning the DOM is fully loaded and parsed. It is useful for ensuring that DOM manipulations happen only after the document has finished loading, preventing issues with missing elements or incomplete rendering.

domReady.then(() => {
    console.log('DOM is fully loaded');
});

Returns: A Promise that resolves when the DOM is ready.

windowReady

windowReady is a promise that resolves when the window's load event fires, which happens after all resources such as images and stylesheets are fully loaded. This function is useful for delaying certain actions until the entire page is ready, such as initializing scripts that depend on external resources.

windowReady.then(() => {
    console.log('All resources are loaded');
});

Returns: A Promise that resolves when the window is fully loaded.

getWindow()

The getWindow() function retrieves the global window object. This function is essential for accessing browser-related properties and methods, such as localStorage, timers, and other window-specific operations.

const win = getWindow();
console.log(win.location.href); // Outputs the current URL

Returns: The global window object.
Throws: Error if the environment does not support the window object.

Fragment Utilities

getDocumentFragmentFromString(html)

The getDocumentFragmentFromString(html) function creates a DocumentFragment from a given HTML string. This is useful when you want to manipulate or insert a portion of HTML into the document without causing performance issues related to reflow and repaint.

const fragment = getDocumentFragmentFromString('
Example
');
document.body.appendChild(fragment);

Parameters:

  • html (string): The HTML string to convert into a DocumentFragment.

Returns: A DocumentFragment object containing the parsed HTML.
Throws: TypeError if the html parameter is not a valid string.

Assembler

The Assembler class provides utilities for working with DocumentFragment and managing attributes efficiently. It can be used to create fragments and manage complex structures in the DOM, making dynamic content rendering more efficient.

const assembler = new Assembler();
const fragment = assembler.createDocumentFragment('
Hello, World!
');
document.body.appendChild(fragment);

Example Use Case: This is especially useful for single-page applications that need to update the DOM dynamically without causing full-page reloads.

Custom Elements

getRegisteredCustomElements()

The getRegisteredCustomElements() function returns a list of all registered custom elements in the current document. This can be helpful for debugging or dynamically working with custom web components.

const customElementsList = getRegisteredCustomElements();
console.log(customElementsList); // e.g., ['my-custom-element', 'another-element']

Returns: An array of tag names of registered custom elements.

CustomControl

The CustomControl class is the base class for all form controls in this library, extending CustomElement. This abstraction helps in creating reusable, customizable form elements that can handle validation, accessibility, and other form-related features efficiently.

class MyCustomControl extends CustomControl {
    connectedCallback() {
        this.innerHTML = '';
    }
}
customElements.define('my-custom-control', MyCustomControl);

Use Case: Useful for building form controls like input fields, dropdowns, or buttons with custom behavior.

DPI Utilities

getDeviceDPI()

The getDeviceDPI() function returns the current DPI (Dots Per Inch) of the device. This is useful for adjusting the scaling of UI components based on screen resolution.

const dpi = getDeviceDPI();
console.log(dpi); // e.g., 96 for standard displays

Returns: The DPI of the current device.

convertToPixels(value, parentElement, fontSizeElement)

The convertToPixels(value, parentElement, fontSizeElement) function converts a CSS value to pixels. This is useful when dealing with responsive design or when you need to convert relative units (like em or %) to pixels.

const pixels = convertToPixels('2em', document.body);
console.log(pixels); // Outputs the equivalent value in pixels

Parameters:

  • value (string): The CSS value to convert.
  • parentElement (HTMLElement, optional): The parent element to base the conversion on.
  • fontSizeElement (HTMLElement, optional): The element to base the font size conversion on, for em or rem units.

Returns: The equivalent value in pixels.

Event Utilities

fireEvent

The fireEvent(element, type) function dispatches an event of the specified type on the given element. This is useful for triggering native DOM events programmatically.

fireEvent(document.body, 'click');

Parameters:

  • element (HTMLElement): The element to dispatch the event on.
  • type (string): The type of event to dispatch, e.g., click.

Focus Management

FocusManager

The FocusManager class allows managing focus within a document, providing methods to store, recall, and move focus. This is useful for handling accessibility and keyboard navigation in complex interfaces.

const focusManager = new FocusManager();
focusManager.storeFocus();
focusManager.focusNext();

Use Case: This class is particularly helpful when managing focus between modal dialogs, popups, and other interactive elements.

Resource Management

ResourceManager

The ResourceManager class allows for the addition and management of external resources, such as scripts and stylesheets. It simplifies dynamic resource loading in a controlled and efficient way.

const manager = new ResourceManager();
manager.addScript('/path/to/script.js');

Use Case: Helps in dynamically adding resources to your document, reducing the need for static references in your HTML.

Template Management

Template

The Template class allows managing HTML templates and creating DocumentFragment objects from them. This can be used to render dynamic content efficiently, particularly in single-page applications.

const template = document.createElement('template');
template.innerHTML = '
Template content
';
document.body.appendChild(template.content);

Use Case: Efficiently manage reusable sections of HTML content in the DOM.

Theme Management

getDocumentTheme()

The getDocumentTheme() function retrieves the current theme applied to the document, based on the data-monster-theme-name attribute. This function is useful for handling theme-specific styling dynamically in web applications.

const theme = getDocumentTheme();
console.log(`Current theme: ${theme}`);

Returns: The name of the currently applied theme, or the default monster theme if none is specified.

The current width of the area is too small to display the content correctly.