docs: enhance documentation on using unique class names to prevent conflicts with Unraid's JavaScript

Author: mstrhakr

docs/ui/icons-and-styling.md

@@ -149,6 +149,23 @@ Tips for theme compatibility:
 
 ## Custom CSS
 
+### Namespace Your Class Names
+
+Unraid's core pages use common class names with unscoped jQuery selectors. If your plugin uses the same class names, Unraid's JavaScript may inadvertently modify your elements, causing visual glitches.
+
+Always prefix your CSS classes with your plugin name:
+
+| Generic (avoid) | Namespaced (use) |
+|-----------------|------------------|
+| `.sortable` | `.myplugin-sortable` |
+| `.updatecolumn` | `.myplugin-updatecolumn` |
+| `.container` | `.myplugin-container` |
+| `.status` | `.myplugin-status` |
+
+This is especially important when adding tabs to existing Unraid pages like the Docker menu, where your tab's DOM shares the page with Unraid's JavaScript.
+
+### Adding Custom Styles
+
 Add custom styles in your page file:
 
 ```php

docs/ui/javascript-patterns.md

@@ -581,24 +581,26 @@ $(document).on('keydown.mymodal', function(e) {
 
 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.
+Common classes like `.auto_start`, `.advanced`, `.basic`, `tr.sortable`, 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'});
+// BAD - Selects ALL tr.sortable rows on the page
+// Docker tab uses this class too, so you'll iterate over Docker containers
+$('tr.sortable').each(function() {
+    var $updateCell = $(this).find('.updatecolumn');
+    $updateCell.html('<i class="fa fa-refresh fa-spin"></i> checking...');
+});
 
-// GOOD - Only affect your plugin's elements
-$('#myplugin_table .advanced').toggle();
-$('#myplugin_table .basic').toggle();
+// GOOD - Scope to your plugin's table
+$('#myplugin_table tr.sortable').each(function() {
+    var $updateCell = $(this).find('.updatecolumn');
+    $updateCell.html('<i class="fa fa-refresh fa-spin"></i> checking...');
+});
 ```
 
+{: .warning }
+> The Docker tab uses unscoped selectors like `$('tr.sortable')` and `$('.updatecolumn')`. If your plugin uses these same class names, clicking "Check for Updates" on Docker will animate *your* plugin's rows too. See [Namespace Your CSS Classes](#namespace-your-css-classes) below.
+
 For elements added to shared areas (like the tab bar), use plugin-specific class names:
 
 ```javascript
@@ -615,7 +617,41 @@ $('.myplugin-advancedview').change(function(){
 });
 ```
 
-See [Tab Pages - Adding Tabs to Existing Pages](tab-pages.md#adding-tabs-to-existing-pages) for more details.
+See [Tab Pages - Adding Tabs to Existing Pages](tab-pages.md#adding-tabs-to-existing-pages) and [Icons and Styling - Namespace Your Class Names](icons-and-styling.md#namespace-your-class-names) for more details.
+
+### Namespace Your CSS Classes
+
+Even with scoped selectors in your own code, Unraid's core pages use unscoped selectors that will match your elements if you use common class names. The only reliable solution is to use plugin-specific class names.
+
+Classes to avoid (used by Docker tab with unscoped selectors):
+- `sortable` - Used for drag-to-reorder rows
+- `updatecolumn` - Update status column
+- `ct-name` - Container name cells
+
+```html
+<!-- BAD - Docker's JavaScript will target these rows -->
+<tr class="sortable" id="stack-row-1">
+    <td class="ct-name">My Stack</td>
+    <td class="updatecolumn">not checked</td>
+</tr>
+
+<!-- GOOD - Unique class names prevent cross-tab interference -->
+<tr class="myplugin-sortable" id="stack-row-1">
+    <td class="myplugin-name">My Stack</td>
+    <td class="myplugin-updatecolumn">not checked</td>
+</tr>
+```
+
+Update your JavaScript to match:
+
+```javascript
+// Use your namespaced classes
+$('#myplugin_table tr.myplugin-sortable').each(function() {
+    $(this).find('.myplugin-updatecolumn').html('checking...');
+});
+```
+
+This approach ensures your plugin works correctly regardless of what selectors other tabs or Unraid core might use.
 
 ### Namespace Your Timers
 

docs/ui/tab-pages.md

@@ -237,7 +237,23 @@ $('#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:
+Even with scoped selectors in your own code, Unraid's core pages use **unscoped selectors** that will still match your elements. For example, the Docker tab's JavaScript uses `$('tr.sortable')` and `$('.updatecolumn')` without scoping to its own container. If your plugin uses these class names, Docker's "Check for Updates" button will animate your plugin's rows too.
+
+The only reliable solution is to use plugin-specific class names:
+
+```html
+<!-- BAD - Docker's unscoped JavaScript will target these -->
+<tr class="sortable">
+    <td class="updatecolumn">not checked</td>
+</tr>
+
+<!-- GOOD - Unique class names prevent cross-tab interference -->
+<tr class="myplugin-sortable">
+    <td class="myplugin-updatecolumn">not checked</td>
+</tr>
+```
+
+For elements added to shared areas (like an Advanced View toggle in the tab bar), always use plugin-specific class names:
 
 ```javascript
 // BAD - may conflict with Docker tab's advancedview toggle
@@ -272,4 +288,5 @@ function loadMyPluginContent() {
 
 - [Page Files]({% link docs/page-files.md %})
 - [Form Controls]({% link docs/ui/form-controls.md %})
-- [JavaScript Patterns]({% link docs/ui/javascript-patterns.md %})
+- [JavaScript Patterns]({% link docs/ui/javascript-patterns.md %}) - See "Scope Your Selectors" and "Namespace Your CSS Classes"
+- [Icons and Styling]({% link docs/ui/icons-and-styling.md %}) - See "Namespace Your Class Names"