Skip to content

Commit 9a60a4c

Browse files
mstrhakrmstrhakr
committed
docs: update tab pages documentation with validation details and enhanced header attributes
1 parent 496b868 commit 9a60a4c

1 file changed

Lines changed: 207 additions & 33 deletions

File tree

‎docs/ui/tab-pages.md‎

Lines changed: 207 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ nav_order: 4
77

88
# Tab Pages
99

10-
{: .warning }
11-
> This page is a stub. [Help us expand it!](https://github.com/mstrhakr/plugin-docs/blob/main/CONTRIBUTING.md)
10+
{: .note }
11+
> ✅ **Validated against Unraid 7.2.3** - Menu structures and page types verified against live server.
1212
1313
## Overview
1414

@@ -79,18 +79,43 @@ $(function() {
7979
});
8080
```
8181

82-
## Page Header with Tabs
82+
## Page Header Attributes
83+
84+
Unraid® page files use header attributes to control menu placement, page type, and behavior. Here are the key attributes:
85+
86+
| Attribute | Description | Example |
87+
|-----------|-------------|--------|
88+
| `Menu` | Parent menu and sort order | `Menu="Docker:2"` |
89+
| `Title` | Display name in menu/tab | `Title="Compose"` |
90+
| `Type` | Page type (see below) | `Type="xmenu"` |
91+
| `Icon` | Menu icon (icon class or path) | `Icon="cubes"` |
92+
| `Tag` | Font Awesome icon for tabs | `Tag="fa-cubes"` |
93+
| `Code` | Unicode for custom icon | `Code="f1b3"` |
94+
| `Cond` | PHP condition for visibility | `Cond="$var['fsState'] == 'Started'"` |
95+
| `Tabs` | Enable/disable tabs | `Tabs="true"` or `Tabs="false"` |
96+
| `Lock` | Prevent menu movement | `Lock="true"` |
97+
98+
### Page Types
99+
100+
| Type | Purpose |
101+
|------|--------|
102+
| `xmenu` | Top-level navigation item (appears in header bar) |
103+
| `menu` | Container page that groups child pages into panels |
104+
| `php` | Standard PHP page (default if not specified) |
83105

84-
Some Unraid page types support a `Tab` header attribute that enables the built-in tabbed interface. This integrates with Unraid's native tab styling rather than requiring custom tab implementation.
106+
### The Tabs Attribute
107+
108+
The `Tabs` attribute controls whether child pages appear as tabs:
85109

86110
```
87-
Menu="Settings"
88-
Title="My Plugin"
89-
Icon="cog"
90-
Tab="true"
111+
# Enable built-in tab interface
112+
Menu="Tasks:60"
113+
Type="xmenu"
114+
Tabs="true"
115+
---
91116
```
92117

93-
TODO: Document actual tab header syntax
118+
When `Tabs="true"`, all pages with `Menu="ParentName:N"` appear as tabs. When `Tabs="false"`, child pages are listed but don't use the tab interface.
94119

95120
## Preserving Tab State
96121

@@ -133,25 +158,44 @@ Each tab can have its own form with independent submission:
133158
</div>
134159
```
135160

136-
## Multi-Page Tabs
161+
## Multi-Page Tabs (Menu Numbering System)
137162

138-
For very large plugins, use separate `.page` files that appear as tabs:
163+
Use separate `.page` files with the `Menu` attribute to create multi-tab pages. The format is:
139164

140165
```
141-
# plugins/yourplugin/YourPlugin.page
142-
Menu="Settings"
143-
Title="My Plugin"
144-
Icon="cog"
145-
---
166+
Menu="ParentName:SortOrder"
167+
```
168+
169+
- **ParentName** - The name of the parent page (without `.page` extension)
170+
- **SortOrder** - Numeric value determining tab order (lower numbers appear first)
146171

147-
# plugins/yourplugin/YourPluginAdvanced.page
148-
Menu="Settings:2"
149-
Title="My Plugin Advanced"
150-
Icon="cog"
172+
### Example: Adding a Tab to Docker
173+
174+
```
175+
# compose.manager.page - Adds "Compose" tab to Docker page
176+
Menu="Docker:2"
177+
Title="Compose"
178+
Type="php"
179+
Cond="$var['fsState'] == 'Started' && exec('/etc/rc.d/rc.docker status | grep -v \"not\"')"
151180
---
152181
```
153182

154-
TODO: Document the Menu numbering system for related pages
183+
This creates a second tab on the Docker page (Docker Containers is at position 1).
184+
185+
### Sort Order Conventions
186+
187+
Lower numbers appear first (leftmost). Common patterns observed in Unraid®:
188+
189+
| Range | Usage |
190+
|-------|-------|
191+
| 1-10 | Primary/default tabs |
192+
| 10-50 | Secondary features |
193+
| 50-100 | Plugin additions |
194+
| 100+ | Low-priority or conditional items |
195+
| 999+ | "Other" or catch-all items |
196+
197+
{: .tip }
198+
> Leave gaps between your sort numbers (e.g., use 10, 20, 30 instead of 1, 2, 3) to allow other plugins to insert tabs between yours.
155199
156200
## Styling Tabs
157201

@@ -182,32 +226,162 @@ TODO: Document the Menu numbering system for related pages
182226
}
183227
```
184228

229+
## Unraid® Menu Structure Reference
230+
231+
This reference documents all standard menu locations in Unraid® where plugins can add pages or tabs.
232+
233+
### Header Navigation Bar (Tasks)
234+
235+
The main navigation bar uses `Menu="Tasks:N"` with these standard positions:
236+
237+
| Position | Page | Description |
238+
|----------|------|-------------|
239+
| `Tasks:1` | Main, Dashboard | Array status and dashboard (shared position) |
240+
| `Tasks:2` | Shares, Favorites | User shares and favorites (shared position) |
241+
| `Tasks:3` | Users | User management (conditionally shown) |
242+
| `Tasks:4` | Settings | System settings container |
243+
| `Tasks:50` | Plugins | Plugin manager |
244+
| `Tasks:60` | Docker | Docker container management |
245+
| `Tasks:61` | *Available* | Compose Manager uses this for standalone menu |
246+
| `Tasks:70` | VMs | Virtual machine management |
247+
| `Tasks:80` | Apps | Community Applications |
248+
| `Tasks:90` | Tools | System tools container |
249+
250+
{: .tip }
251+
> Positions 1-4 are reserved for core Unraid® pages. Plugins should use positions 50+ to avoid conflicts.
252+
253+
### Settings Submenus
254+
255+
The Settings page (`Tasks:4`) contains these category panels:
256+
257+
| Menu | Title | Type | Description |
258+
|------|-------|------|-------------|
259+
| `Settings:1` | OtherSettings | menu | System Settings panel |
260+
| `Settings:2` | NetworkServices | menu | Network Services panel |
261+
| `Settings:3` | UserPreferences | menu | User Preferences panel |
262+
| `Settings` | Utilities | menu | User Utilities panel (no number = alphabetical) |
263+
264+
### System Settings (OtherSettings)
265+
266+
Pages in the System Settings panel use `Menu="OtherSettings"`:
267+
268+
| Existing Pages | Your Plugin |
269+
|---------------|-------------|
270+
| CPU Pinning, Date and Time, Disk Settings, Docker, Global Share Settings, Identification, Management Access, Network Settings, Power Mode, VM Manager | Add with `Menu="OtherSettings"` |
271+
272+
### Network Services
273+
274+
Pages in the Network Services panel use `Menu="NetworkServices"` or `Menu="NetworkServices:N"`:
275+
276+
| Position | Page |
277+
|----------|------|
278+
| `NetworkServices:2` | NFS |
279+
| `NetworkServices:3` | SMB (has sub-tabs) |
280+
| `NetworkServices:999` | FTP Server |
281+
| `NetworkServices` | VPN Manager, Outgoing Proxy, Syslog Server (no number = alphabetical) |
282+
283+
### User Utilities
284+
285+
Plugin settings pages commonly go here using `Menu="Utilities"`:
286+
287+
| Existing Pages |
288+
|---------------|
289+
| Community Applications, User Scripts, TurboWrite, Backup/Restore Appdata, Fix Common Problems, Stats Settings, System Temp, Custom Tab, rclone, etc. |
290+
291+
### User Preferences (UserPreferences)
292+
293+
User-specific settings use `Menu="UserPreferences"`:
294+
295+
| Existing Pages |
296+
|---------------|
297+
| Confirmations, Console Settings, Display Settings, Notification Settings, Scheduler |
298+
299+
### Tools Submenus
300+
301+
The Tools page (`Tasks:90`) contains:
302+
303+
| Menu | Title | Type |
304+
|------|-------|------|
305+
| `Tools:10` | UNRAID-OS | menu (Unraid OS utilities) |
306+
| `Tools:20` | WebGui | menu (WebUI debugging tools) |
307+
| `Tools:90` | About | menu (Credits, EULA) |
308+
| `Tools` | System Information | menu (no number) |
309+
310+
### Unraid OS (UNRAID-OS)
311+
312+
System utilities use `Menu="UNRAID-OS"`:
313+
314+
| Existing Pages |
315+
|---------------|
316+
| Diagnostics, Hardware Profile, Log Viewer, New Config, New Permissions, Open Terminal, Processes, System Devices, System Drivers, System Log |
317+
318+
### About Menu
319+
320+
Documentation and system info use `Menu="About"` or `Menu="About:N"`:
321+
322+
| Position | Page |
323+
|----------|------|
324+
| `About:10` | Update OS |
325+
| `About:20` | Downgrade OS |
326+
| `About:30` | Registration |
327+
| `About` | Credits, EULA (no number = alphabetical) |
328+
329+
### Adding Tabs to Existing Pages
330+
331+
These are common parent pages that support tabs:
332+
333+
| Parent | Your Menu Value | Example Use |
334+
|--------|----------------|-------------|
335+
| Docker | `Menu="Docker:N"` | Add compose/stack management |
336+
| VMs | `Menu="VMs:N"` | Add VM-related features |
337+
| Plugins | `Menu="Plugins"` | Plugin-related pages |
338+
| SMB | `Menu="SMB:N"` | SMB configuration tabs |
339+
| About | `Menu="About:N"` | System info pages |
340+
341+
### Conditional Menu Display
342+
343+
Use the `Cond` attribute to show/hide menu items based on system state:
344+
345+
```
346+
# Only show when Docker is enabled and running
347+
Cond="exec(\"grep -o '^DOCKER_ENABLED=.yes' /boot/config/docker.cfg 2>/dev/null\")"
348+
349+
# Only show when array is started
350+
Cond="$var['fsState'] == 'Started'"
351+
352+
# Only show when a service is running
353+
Cond="is_file('/var/run/dockerd.pid')"
354+
355+
# Combine conditions
356+
Cond="$var['fsState'] == 'Started' && exec('/etc/rc.d/rc.docker status | grep -v \"not\"')"
357+
```
358+
359+
### Dynamic Menu Placement
360+
361+
Some menus use PHP variables for conditional placement:
362+
363+
```
364+
# Users menu - conditionally shown based on display setting
365+
Menu="$display['users'] Tasks:3"
366+
```
367+
185368
## Best Practices
186369

187370
- Keep related settings together
188371
- Use clear, descriptive tab names
189372
- Don't create too many tabs (3-5 is usually ideal)
190373
- Consider user workflow when ordering tabs
191374
- Save tab state for better UX
375+
- Use unique, plugin-prefixed class names to avoid conflicts
376+
- Scope your jQuery selectors to your container elements
192377

193378
## Adding Tabs to Existing Pages
194379

195-
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.
380+
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.
196381

197382
![Docker page with Compose tab](../../assets/images/screenshots/docker-compose-tabs.png)
198383
*Example: Compose Manager adds a "Compose" tab to the Docker page*
199384

200-
### Menu Placement
201-
202-
To add a tab to an existing menu, use the menu name with an optional sort order:
203-
204-
```
205-
# Add to Docker page as second tab
206-
Menu="Docker:2"
207-
Title="Compose"
208-
Type="php"
209-
```
210-
211385
### Selector Scoping
212386

213387
{: .warning }

0 commit comments

Comments
 (0)