Enhance documentation for Dynamix Framework, Event System, Introduction, and PLG File Reference with additional details on loading states, background processes, learning resources, and embedding base64 content for improved clarity and usability.

mstrhakr · mstrhakr · commit a004fd4d3446 · 2026-02-01T19:11:22.000-05:00
diff --git a/docs/core/dynamix-framework.md b/docs/core/dynamix-framework.md
@@ -313,6 +313,8 @@ function my_time($timestamp = null) {
 
 ## Loading States and Spinners
 
+### Standard Spinner CSS
+
 ```html
 <!-- Standard Dynamix loading spinner -->
 <div class="spinner"></div>
@@ -333,6 +335,60 @@ function hideLoading() {
 </script>
 ```
 
+### showStatus() Function
+
+The `showStatus()` function displays a spinning status indicator in the page header during long-running operations:
+
+```javascript
+// 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:
+
+```javascript
+// 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:
+
+```html
+<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
diff --git a/docs/events.md b/docs/events.md
@@ -25,7 +25,10 @@ For each event, scripts are executed in this order:
 1. **any_event handlers** - Scripts in `event/any_event/` or `event/any_event` receive ALL events
 2. **Specific event handlers** - Scripts matching the event name
 
-Plugins are processed alphabetically by plugin name.
+Plugins are processed **alphabetically by plugin folder name** (ASCII sort order).
+
+{: .note }
+> If your plugin depends on another plugin's event handler running first, you can prefix your plugin name with a character that sorts after the dependency. For example, `z-myplugin` would run after `compose.manager`. However, relying on execution order is fragile—design your event handlers to be independent when possible.
 
 ## Available Events
 
@@ -250,10 +253,43 @@ The emhttp process waits for event scripts to complete. For long tasks:
 sleep 60
 do_long_task
 
-# Good - runs in background
+# Good - runs in background using &
 do_long_task &
 ```
 
+### Using the `at` Command for Background Processes
+
+For more reliable background execution (especially when the parent process may exit), use the `at` command which schedules a job to run independently:
+
+```bash
+#!/bin/bash
+# Using 'at' command - most reliable for background tasks
+
+# Schedule task to run immediately but independently
+echo "/usr/local/emhttp/plugins/myplugin/scripts/long_task.sh" | at now
+
+# With logging
+echo "/usr/local/emhttp/plugins/myplugin/scripts/long_task.sh >> /var/log/myplugin.log 2>&1" | at now
+```
+
+### Using `nohup` for Background Processes
+
+The `nohup` command prevents the process from being killed when the parent exits:
+
+```bash
+#!/bin/bash
+# Using nohup - process continues even if parent exits
+
+nohup /usr/local/emhttp/plugins/myplugin/scripts/long_task.sh > /var/log/myplugin.log 2>&1 &
+
+# Disown to fully detach from shell
+nohup /usr/local/emhttp/plugins/myplugin/scripts/long_task.sh > /var/log/myplugin.log 2>&1 &
+disown
+```
+
+{: .note }
+> The `at` command is generally preferred over `nohup &` because it creates a completely independent process that won't be affected by signal propagation when emhttp continues execution.
+
 ### 2. Use Logger for Debugging
 
 Log messages appear in `/var/log/syslog`:
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -172,3 +172,32 @@ The DocTest plugin validates:
 ## Next Steps
 
 Ready to build your first plugin? Continue to [Your First Plugin](getting-started.md) for a hands-on tutorial.
+
+## Learning Resources
+
+The best way to learn Unraid plugin development is to study existing plugins:
+
+### System Scripts
+
+The `/usr/local/sbin/` directory contains many Unraid system scripts that demonstrate patterns:
+- `emhttp_event` - How events are dispatched to plugins
+- `notify` - Notification system internals
+- Various utility scripts
+
+### Reference Plugins
+
+- **[Dynamix plugins](https://github.com/unraid/dynamix)** - Official Unraid plugins (the reference implementation)
+- **[Community Applications](https://github.com/Squidly271/community.applications)** - Complex PHP patterns
+- **[Compose Manager](https://github.com/dcflachs/compose_plugin)** - Docker Compose integration example
+
+### Community Resources
+
+- **[Unraid Forums - Plugin Support](https://forums.unraid.net/forum/index.php?board=45.0)** - Get help from the community
+- **[Unraid Forums - Programming](https://forums.unraid.net/forum/index.php?board=79.0)** - Technical discussions
+
+### Key Forum Threads
+
+These foundational posts contain detailed plugin development information:
+
+- [How does the plugin system work?](https://forums.unraid.net/topic/38582-how-does-the-plugin-system-work-documentation-added/) - Comprehensive PLG structure guide
+- [Plugin System Documentation](https://forums.unraid.net/topic/52623-plugin-system-documentation/) - Links to essential resources
diff --git a/docs/plg-file.md b/docs/plg-file.md
@@ -204,6 +204,32 @@ The `<LOCAL>` element copies a previously downloaded file:
 
 This caches files on the USB flash so they don't need to be re-downloaded on each boot.
 
+### Embedding Base64 Content
+
+For small files like icons, you can embed them directly in the PLG file using base64 encoding:
+
+```xml
+<FILE Name="/usr/local/emhttp/plugins/myplugin/images/icon.png" Type="base64">
+<INLINE>
+iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAA...
+</INLINE>
+</FILE>
+```
+
+The `Type="base64"` attribute tells the plugin system to decode the content before writing the file.
+
+**When to use base64 embedding:**
+- Small icons (< 10KB recommended)
+- Files that rarely change
+- Reducing external dependencies during install
+
+**Generate base64 content:**
+```bash
+base64 -w 0 icon.png
+# Or with line wrapping (easier to read in PLG)
+base64 icon.png
+```
+
 ## Method Attribute
 
 The `Method` attribute controls when a FILE element is processed:
