Enhance documentation for JavaScript Patterns and Tab Pages with best practices on selector scoping, menu placement, and initialization timing to prevent conflicts when adding tabs to existing Unraid pages.

Author: mstrhakr

docs/ui/javascript-patterns.md

@@ -577,6 +577,46 @@ $(document).on('keydown.mymodal', function(e) {
 
 ## Best Practices
 
+### Scope Your Selectors
+
+When your plugin adds a tab to an existing Unraid page (like adding a tab to the Docker menu), your JavaScript runs in the same context as that page's JavaScript. Unscoped selectors can accidentally target elements from the parent page, causing visual glitches or broken functionality.
+
+Common classes like `.auto_start`, `.advanced`, `.basic`, and `.updatecolumn` are used by multiple Unraid pages. jQuery plugins like `switchButton` should never be re-initialized on elements that are already set up.
+
+```javascript
+// BAD - Selects ALL .auto_start elements on the page
+// If Docker tab already initialized these, you'll break them
+$('.auto_start').switchButton({labels_placement:'right', on_label:'On', off_label:'Off'});
+
+// BAD - Toggles ALL .advanced elements, including Docker tab's columns
+$('.advanced').toggle();
+
+// GOOD - Scope to your plugin's container
+$('#myplugin_table .auto_start').switchButton({labels_placement:'right', on_label:'On', off_label:'Off'});
+
+// GOOD - Only affect your plugin's elements
+$('#myplugin_table .advanced').toggle();
+$('#myplugin_table .basic').toggle();
+```
+
+For elements added to shared areas (like the tab bar), use plugin-specific class names:
+
+```javascript
+// BAD - 'advancedview' class may conflict with Docker tab's toggle
+$(".tabs").append('<span class="status"><input type="checkbox" class="advancedview"></span>');
+$('.advancedview').switchButton({...});
+
+// GOOD - unique class name prevents conflicts
+$(".tabs").append('<span class="status"><input type="checkbox" class="myplugin-advancedview"></span>');
+$('.myplugin-advancedview').switchButton({...});
+$('.myplugin-advancedview').change(function(){
+    // Only toggle your plugin's elements
+    $('#myplugin_table .advanced').toggle();
+});
+```
+
+See [Tab Pages - Adding Tabs to Existing Pages](tab-pages.md#adding-tabs-to-existing-pages) for more details.
+
 ### Namespace Your Timers
 
 Unraid's core JavaScript uses a global `timers` object to manage intervals and timeouts. If your plugin declares `var timers = {}`, you'll overwrite Unraid's object and break functionality like auto-refresh and status polling. Always use a plugin-specific name like `myPluginTimers` to avoid this collision.

docs/ui/tab-pages.md

@@ -190,6 +190,81 @@ TODO: Document the Menu numbering system for related pages
 - Consider user workflow when ordering tabs
 - Save tab state for better UX
 
+## Adding Tabs to Existing Pages
+
+Plugins can add new tabs to existing Unraid pages (like the Docker page) using the `Menu` header in `.page` files. This creates a seamless integrated experience but requires careful attention to avoid conflicts.
+
+### Menu Placement
+
+To add a tab to an existing menu, use the menu name with an optional sort order:
+
+```
+# Add to Docker page as second tab
+Menu="Docker:2"
+Title="Compose"
+Type="php"
+```
+
+### Selector Scoping
+
+{: .warning }
+> When your plugin adds a tab to an existing Unraid page, your JavaScript will run in the same context as the parent page's JavaScript. You **must** scope your CSS selectors to avoid conflicts.
+
+Common classes like `.auto_start`, `.advanced`, `.basic`, and `.updatecolumn` are used by multiple Unraid pages. If your plugin uses these same classes and initializes jQuery plugins on them (like `switchButton`), you'll inadvertently reinitialize or modify elements that belong to the parent page.
+
+**Problem - Unscoped selectors:**
+
+```javascript
+// BAD - This selects ALL .auto_start on the page, including Docker tab's checkboxes
+$('.auto_start').switchButton({labels_placement:'right'});
+
+// BAD - This toggles ALL .advanced elements, affecting Docker tab too  
+$('.advanced').toggle();
+```
+
+**Solution - Scope to your container:**
+
+```javascript
+// GOOD - Only select checkboxes within your plugin's table
+$('#my_plugin_table .auto_start').switchButton({labels_placement:'right'});
+
+// GOOD - Only toggle your plugin's advanced columns
+$('#my_plugin_table .advanced').toggle();
+```
+
+### Use Unique Class Names
+
+For elements that need to be globally unique (like an Advanced View toggle in the tab bar), use plugin-specific class names:
+
+```javascript
+// BAD - may conflict with Docker tab's advancedview toggle
+$(".tabs").append('<span class="status"><input type="checkbox" class="advancedview"></span>');
+$('.advancedview').switchButton({...});
+
+// GOOD - unique class name avoids conflicts
+$(".tabs").append('<span class="status myplugin-view-toggle"><input type="checkbox" class="myplugin-advancedview"></span>');
+$('.myplugin-advancedview').switchButton({...});
+```
+
+### Initialization Timing
+
+When adding a tab to an existing page, that page's JavaScript typically runs first and initializes its own UI components. Your plugin's async content loading can conflict if not properly scoped:
+
+```javascript
+// Load content asynchronously, then initialize
+function loadMyPluginContent() {
+    $.get('/plugins/myplugin/content.php', function(data) {
+        $('#myplugin_content').html(data);
+        
+        // Initialize ONLY your plugin's elements
+        $('#myplugin_content .auto_start').switchButton({...});
+        $('#myplugin_content .auto_start').change(function(){
+            // Handle change
+        });
+    });
+}
+```
+
 ## Related Topics
 
 - [Page Files]({% link docs/page-files.md %})