Dynamix Framework

Overview

The Dynamix Framework is the core PHP framework that powers the Unraid web interface. Understanding this framework is essential for plugin development as it provides access to system state, user preferences, themes, and common utilities.

The $Dynamix Global Array

The $Dynamix array contains essential configuration and state information about the user’s display preferences and system settings.

📷 Screenshot needed: Unraid Display Settings page

<?
// Access the Dynamix configuration
global $Dynamix;

// Example: Check current theme
$theme = $Dynamix['theme'];
?>

Complete $Dynamix Properties Reference

Property	Type	Description	Example Values
theme	string	Current UI theme name	"black", "white", "gray", "azure"
color	string	Theme color variant	Theme-specific color
background	string	Background image path or empty	"", /boot/config/plugins/dynamix/background.png
display['date']	string	Date format preference	"%Y-%m-%d", "%m/%d/%Y", "%d-%m-%Y"
display['time']	string	Time format preference	"%H:%M" (24h), "%I:%M %p" (12h)
display['number']	string	Number format (decimal/thousands)	".,", ",.", ". "
display['scale']	string	Temperature scale	"C" (Celsius), "F" (Fahrenheit)
display['tabs']	int	Tab display mode	0 (top), 1 (bottom), 2 (none)
display['resize']	bool	Enable text area resize	true, false
display['refresh']	int	Auto-refresh interval (seconds)	0 (disabled), 1, 2, etc.
display['banner']	string	Banner image path	Path or empty
display['usage']	bool	Show disk usage colors	true, false
notify['normal']	int	Normal notification setting	Bitfield for agent settings
notify['warning']	int	Warning notification setting	Bitfield for agent settings
notify['alert']	int	Alert notification setting	Bitfield for agent settings
notify['position']	string	Notification popup position	"top-right", "top-left", etc.

Accessing Display Settings

<?
global $Dynamix;

// Date formatting
$dateFormat = $Dynamix['display']['date'] ?? '%Y-%m-%d';
$formattedDate = strftime($dateFormat, time());

// Time formatting  
$timeFormat = $Dynamix['display']['time'] ?? '%H:%M';
$formattedTime = strftime($timeFormat, time());

// Temperature scale
$tempScale = $Dynamix['display']['scale'] ?? 'C';
$temp = ($tempScale == 'F') ? ($celsius * 9/5 + 32) : $celsius;
$tempDisplay = $temp . "°" . $tempScale;

// Number formatting
$numberFormat = $Dynamix['display']['number'] ?? '.,';
$decimal = $numberFormat[0];
$thousands = $numberFormat[1];
$formattedNumber = number_format($value, 2, $decimal, $thousands);
?>

Theme Integration

Detecting Current Theme

📷 Screenshot needed: Plugin page in light vs dark theme

<?
global $Dynamix;

$theme = $Dynamix['theme'];
$isDarkTheme = in_array($theme, ['black', 'gray']);
?>

<style>
<?if ($isDarkTheme):?>
.my-plugin-card {
    background: #1a1a1a;
    color: #e0e0e0;
}
<?else:?>
.my-plugin-card {
    background: #ffffff;
    color: #333333;
}
<?endif;?>
</style>

Theme CSS Variables

Unraid themes define CSS variables you can use for consistent styling:

/* Use theme variables for consistent appearance */
.my-plugin-element {
    background-color: var(--background);
    color: var(--text);
    border-color: var(--border);
}

/* Common theme variables */
/*
--background      Main background color
--header          Header background
--menu            Menu background
--text            Primary text color
--text-secondary  Secondary text color
--border          Border color
--link            Link color
--link-hover      Link hover color
--button          Button background
--button-hover    Button hover background
--success         Success/green color
--warning         Warning/yellow color
--error           Error/red color
*/

Theme-Aware Styling

<?
global $Dynamix;
?>

<style>
/* Use Dynamix-provided classes */
.my-plugin-section {
    @extend .section;  /* Inherits standard section styling */
}

/* Or reference theme settings directly */
.my-custom-bg {
    background-color: <?=$Dynamix['color']?>;
}
</style>

Display Modes

Tab Display Mode

The display['tabs'] setting controls where tabs appear:

<?
global $Dynamix;

$tabMode = $Dynamix['display']['tabs'] ?? 0;
// 0 = Tabs at top
// 1 = Tabs at bottom
// 2 = Tabs hidden (dropdown only)
?>

Responsive Design

<?
// Check for mobile/narrow display hints in session
$isMobile = isset($_SESSION['mobile']) && $_SESSION['mobile'];
?>

<div class="my-plugin-container <?=$isMobile ? 'mobile' : 'desktop'?>">
    <!-- Content adapts to display -->
</div>

Configuration Access

Reading Unraid Settings

System settings are available via state files in /var/local/emhttp/. These INI files are updated by emhttp and contain current system state. Use parse_ini_file() with true as the second parameter to parse sections into nested arrays.

<?
// Read main system variables
$var = parse_ini_file('/var/local/emhttp/var.ini');

// Read disk information  
$disks = parse_ini_file('/var/local/emhttp/disks.ini', true);

// Read share information
$shares = parse_ini_file('/var/local/emhttp/shares.ini', true);

// Read user information
$users = parse_ini_file('/var/local/emhttp/users.ini', true);

// Read network information
$network = parse_ini_file('/var/local/emhttp/network.ini', true);
?>

Common $var Properties

See the complete Var Array Reference for all properties.

<?
global $var;

// System identification
$serverName = $var['NAME'];
$timezone = $var['timeZone'];

// Array state
$arrayState = $var['fsState'];  // Started, Stopped
$mdState = $var['mdState'];     // STARTED, STOPPED

// Unraid version
$version = $var['version'];

// Security
$csrfToken = $var['csrf_token'];
?>

Path Helpers

Standard Plugin Paths

These are the conventional paths used in Unraid plugin development. The emhttp directory in RAM contains active plugin files, while the config directory on the USB flash stores persistent data that survives reboots.

<?
// Your plugin's emhttp directory (RAM)
$emhttpDir = "/usr/local/emhttp/plugins/yourplugin";

// Your plugin's config directory (persistent on flash)
$configDir = "/boot/config/plugins/yourplugin";

// WebGui resources
$webGuiDir = "/usr/local/emhttp/webGui";

// Dynamix includes
$includesDir = "/usr/local/emhttp/webGui/include";
?>

Including Dynamix Helpers

Unraid provides helper libraries for common tasks. Include these files to access utility functions for translation, formatting, and system interaction. The Helpers.php file contains frequently used functions.

<?
// Include common Dynamix utilities
require_once "/usr/local/emhttp/webGui/include/Helpers.php";

// Include translation support
require_once "/usr/local/emhttp/webGui/include/Translations.php";
?>

Utility Functions

File Size Formatting

<?
// Format bytes to human-readable
function my_scale($size, $precision = 1) {
    global $Dynamix;
    $units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
    $unit = 0;
    while ($size >= 1024 && $unit < count($units) - 1) {
        $size /= 1024;
        $unit++;
    }
    $number = $Dynamix['display']['number'] ?? '.,';
    return number_format($size, $precision, $number[0], $number[1]) . ' ' . $units[$unit];
}
?>

Time Formatting

<?
// Format timestamp according to user preferences
function my_time($timestamp = null) {
    global $Dynamix;
    if ($timestamp === null) $timestamp = time();
    $format = ($Dynamix['display']['date'] ?? '%Y-%m-%d') . ' ' . 
              ($Dynamix['display']['time'] ?? '%H:%M');
    return strftime($format, $timestamp);
}
?>

Loading States and Spinners

Standard Spinner CSS

<!-- Standard Dynamix loading spinner -->
<div class="spinner"></div>

<!-- Loading overlay pattern -->
<div id="loading-overlay" style="display:none;">
    <div class="spinner fixed"></div>
</div>

<script>
function showLoading() {
    $('#loading-overlay').show();
}

function hideLoading() {
    $('#loading-overlay').hide();
}
</script>

showStatus() Function

The showStatus() function displays a spinning status indicator in the page header during long-running operations:

// Show status indicator with message
showStatus('Processing...');

// Your long-running operation
$.post('/plugins/myplugin/action.php', data, function(response) {
    // Hide status when done
    hideStatus();
});

openBox() Function

The openBox() function opens a modal dialog box that typically displays command output or progress:

// Open a modal with content
// openBox(content, title, height, width, showCloseButton)
openBox(htmlContent, "Operation Title", 600, 800, true);

// Common pattern: Execute command and show output
$.post('/plugins/myplugin/exec.php', {action: 'runCommand'}, function(data) {
    if (data) {
        openBox(data, "Command Output", 600, 800, true);
    }
});

Parameters:

• content - HTML content to display in the modal
• title - Title shown in the modal header
• height - Modal height in pixels
• width - Modal width in pixels
• showCloseButton - Boolean to show/hide the close button

Progress Frame Pattern

Many plugins use an iframe named progressFrame to display command output:

<form method="POST" action="/plugins/myplugin/action.php" target="progressFrame">
    <input type="hidden" name="csrf_token" value="<?=$var['csrf_token']?>">
    <input type="submit" value="Run Action">
</form>

<!-- The progressFrame receives form submissions -->

When the form targets progressFrame, the response is displayed in a dedicated progress area rather than replacing the current page.

Page Structure Integration

Standard Page Template

Menu="Utilities"
Title="My Plugin"
Icon="icon-myplugin"
---
<?
// Include Dynamix framework helpers
global $Dynamix;
global $var;

// Your plugin logic here
$cfg = parse_plugin_cfg("yourplugin");
?>

<div class="title">
    <span class="left">My Plugin Settings</span>
</div>

<form method="POST" action="/update.php" target="progressFrame">
    <input type="hidden" name="csrf_token" value="<?=$var['csrf_token']?>">
    
    <dl>
        <dt>Setting:</dt>
        <dd><input type="text" name="setting" value="<?=$cfg['setting']?>"></dd>
    </dl>
    
    <dl>
        <dt>&nbsp;</dt>
        <dd><input type="submit" value="Apply"></dd>
    </dl>
</form>

Related Topics

• Plugin Settings Storage
• File Path Reference
• Var Array Reference
• Form Controls

References

• Dynamix plugins source - Official reference implementation