SmartApp.js

DOM Magic, Simplified!

SmartApp.js is an enhanced vanilla JavaScript plugin designed for DOM manipulation, UI controls, event handling, security features, and audio management. It provides efficient methods to interact with UI elements, handle class modifications, execute panel actions, play sounds, and more.

Pro Tip: SmartApp.js is designed with security in mind, featuring built-in sanitization for class names, selectors, and data attributes.

Installation

Include the SmartApp.js script in your HTML file:

<script src="path/to/smartApp.js"></script>

Initialize the plugin:

document.addEventListener('DOMContentLoaded', function() {
appDOM.checkActiveStyles().debug(true);
});

Configuration

SmartApp.js comes with a flexible configuration system:

const config = {
debug: false,
focusDelay: 200,
defaultSoundPath: 'media/sound/',
maxClassNameLength: 50,
maxSelectorLength: 255,
fullscreenConfirmMessage: 'Do you want to enter fullscreen mode?',
selectors: {
    actionButtons: '[data-action]'
},
sound: {
    preload: false,
    volume: 1.0,
    fadeIn: false,
    fadeInDuration: 500
}
};
Important: Security limits like maxClassNameLength and maxSelectorLength help prevent DoS attacks.

Core Features

Style Management

// Reset all styles
appDOM.resetStyle();

// Check active styles
appDOM.checkActiveStyles();

Class Manipulation

// Programmatic Methods
// Toggle class
appDOM.toggleClass('html', 'nav-function-hidden');
appDOM.toggleClass('.my-element', 'active');

// Toggle Replace (swap one class for another)
appDOM.toggleReplace('.my-element', 'btn-default', 'btn-primary');
appDOM.toggleReplace('#myButton', null, 'active'); // Just add without removing

// Toggle Swap (toggle class on specific target)
appDOM.toggleSwap('html', 'nav-function-top');
appDOM.toggleSwap('.drawer', 'active');

// Chain multiple actions
appDOM
  .toggleClass('html', 'nav-function-hidden')
  .toggleReplace('#myButton', 'btn-default', 'btn-primary')
  .toggleSwap('.drawer', 'active');

// Using data attributes
<button data-action="toggle" data-class="dark-mode">Toggle Dark Mode</button>
<button data-action="toggle-replace" data-target=".btn" data-removeclass="btn-default" data-addclass="btn-primary">Update Button</button>
<button data-action="toggle-swap" data-target=".drawer" data-toggleclass="active">Toggle Drawer</button>

Security Features

Class Name Sanitization

// Sanitizes class names to prevent XSS
const sanitizedClass = security.sanitizeClassName(className);

// Only allows valid characters: a-z, A-Z, 0-9, -, _
// Removes invalid characters
// Enforces maximum length

Selector Sanitization

// Prevents CSS injection attacks
const sanitizedSelector = security.sanitizeSelector(selector);

// Blocks dangerous patterns:
// - HTML tags
// - javascript: URLs
// - data: URLs
// - Expression functions
// - Timing functions
Important: All inputs are automatically sanitized to prevent XSS and injection attacks.

Theme Management

SmartApp.js includes a built-in theme management system that handles light and dark themes:

Theme Controls

// Toggle theme programmatically
appDOM.toggleTheme();

// Using data attributes
<button data-action="toggle-theme">Toggle Theme</button>

// Check current theme
const currentTheme = document.documentElement.getAttribute('data-bs-theme');

// Theme is automatically saved to localStorage and restored on page load
// Supports Bootstrap's data-bs-theme attribute
// Toggles between 'light' and 'dark' modes
Pro Tip: Theme preferences are automatically persisted across sessions using localStorage.

Event Handlers

Available Actions

// Theme toggling
<button data-action="toggle-theme">Toggle Theme</button>

// Toggle class
<button data-action="toggle" data-class="active">Toggle</button>

// Replace class
<button data-action="toggle-replace" 
    data-target="#element"
    data-removeclass="hidden"
    data-addclass="visible">Show Element</button>

// Swap class
<button data-action="toggle-swap"
    data-target="#drawer"
    data-toggleclass="open">Toggle Drawer</button>

// Programmatic usage
// Theme
appDOM.toggleTheme();

// Class manipulation
appDOM.toggleClass('html', 'nav-function-hidden');
appDOM.toggleReplace('.button', 'btn-default', 'btn-primary');
appDOM.toggleSwap('.drawer', 'active');

// Method chaining
appDOM
    .toggleTheme()
    .toggleClass('html', 'nav-function-hidden')
    .toggleSwap('.drawer', 'active');
Pro Tip: All methods support chaining and include built-in error handling and logging.

Panel Actions

Available Panel Controls

// Panel action methods
handlers.panelActions.collapse(element);
handlers.panelActions.fullscreen(element);
handlers.panelActions.close(element);

// Example usage
document.querySelector('.panel-collapse-btn').addEventListener('click', function() {
handlers.panelActions.collapse(this);
});

// Using data attributes
<button data-action="panel-collapse">Collapse</button>
<button data-action="panel-fullscreen">Fullscreen</button>
<button data-action="panel-close">Close</button>
Pro Tip: Panel actions automatically handle tooltips and transitions.

Fullscreen Mode

Fullscreen Controls

// Fullscreen methods
fullscreenHandler.enter();
fullscreenHandler.exit();
fullscreenHandler.isFullscreen();

// Example usage
document.querySelector('.fullscreen-btn').addEventListener('click', function() {
handlers.appFullscreen();
});

Audio Features

Sound Management

// Play sound
<button data-action="playsound" data-soundfile="click.mp3">Play Sound</button>

// Pause sound
<button data-action="pausesound">Pause Sound</button>

// Preload sound
appDOM.preloadSound('background.mp3');

// Play and pause sounds programmatically
handlers.playSound(element);
handlers.pauseSound(element);
Note: Sound files are automatically cached for better performance.

Utilities

Debounce Function

const debouncedFunction = utils.debounce(() => {
// Your code here
}, 300);

Element Validation

if (utils.validateElement(element, 'Button')) {
// Element exists, proceed
}

Debugging

Logger Functions

// Enable debug mode
appDOM.debug(true);

// Logger outputs
logger.log('Info message');
logger.error('Error message');
logger.warn('Warning message');
logger.group('Group name');
logger.groupEnd();

// Logging methods
appDOM.log('This is a log message');
appDOM.warn('This is a warning');
appDOM.error('This is an error');
Pro Tip: Debug messages are prefixed with [AppDOM] for easy identification in the console.

Troubleshooting

Common Issues:
  • Class manipulation doesn't work?
    Ensure the target element exists before calling appDOM.addClass().
  • No sound is playing?
    Check if the file path is correct and ensure browser autoplay permissions allow playback.
  • Panel actions not responding?
    Verify that the data attributes are correctly set and the elements exist in the DOM.
  • Security restrictions blocking actions?
    Check the console for security warnings and ensure your selectors and class names meet the security requirements.
On This Page