====== WvdS.DokuWiki.AcMenu Plugin ======

**Plugin:** wvdsacmenu\\
**Version:** 1.0.0\\
**Namespace:** ''lib/plugins/wvdsacmenu/''\\
**Base:** [[https://www.dokuwiki.org/plugin:acmenu|AcMenu]] by Torpedo\\
**Extensions:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**License:** GPL 2

----

===== Definition =====

The **wvdsacmenu** plugin displays an accordion menu for namespaces and pages. It extends the original AcMenu with wiki syntax, dynamic namespace detection, and multilingual support.

===== Use Cases =====

  * **Namespace Navigation** - Automatic menu for documentation structure
  * **Multilingual Wikis** - Separate menus per language namespace
  * **Project Documentation** - Hierarchical navigation in sub-namespaces
  * **Sidebar Integration** - Compact navigation in the sidebar

----

===== Syntax =====

<code>
{{wvds:acmenu}}
{{wvds:acmenu ns="namespace"}}
{{wvds:acmenu dynamic="N"}}
</code>

==== Parameters ====

^ Parameter ^ Type ^ Default ^ Description ^
| ''ns'' | string | //(auto)// | Explicit namespace for the menu |
| ''dynamic'' | integer | //(off)// | Levels above current page |

----

===== Parameter Details =====

==== ns - Explicit Namespace ====

Shows a specific namespace regardless of current page:

<code>
{{wvds:acmenu ns="en:crypto"}}
{{wvds:acmenu ns="en:docs:api"}}
</code>

==== dynamic - Dynamic Namespace ====

Calculates namespace relative to current page:

^ Value ^ Meaning ^ Example (at en:crypto:openssl:start) ^
| ''dynamic="1"'' | 1 level up | Shows ''en:crypto:openssl'' |
| ''dynamic="2"'' | 2 levels up | Shows ''en:crypto'' |
| ''dynamic="3"'' | 3 levels up | Shows ''en'' |

----

===== Namespace Detection =====

==== Sidebar Boundary Detection ====

The plugin detects namespace boundaries through ''sidebar*'' files:

  * ''sidebar.txt''
  * ''sidebar1.txt''
  * ''sidebar2.txt''
  * ''sidebar_name.txt''

If a namespace contains one of these files, it is treated as a standalone area.

==== Detection Logic ====

<code>
1. Without parameters
   └── Searches upward for sidebar* file
   └── Starts menu from that namespace

2. With ns="..."
   └── Uses the specified namespace directly

3. With dynamic="N"
   └── Calculates: current_namespace - N levels
   └── Shows from that point
</code>

----

===== Examples =====

==== Example 1: Automatic Menu ====

**Requirement:** Menu should automatically show current namespace area.

**sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

**Result:**
  * Plugin searches upward for sidebar* file
  * Starts menu from found namespace
  * Shows all sub-namespaces and pages

==== Example 2: Language Namespace ====

**Requirement:** Menu for English documentation area.

**en/sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu dynamic="2"}}
</code>

**Result at en:crypto:openssl:start:**
  * ''dynamic="2"'' goes 2 levels up
  * Starts at ''en:crypto''
  * Shows all crypto documentation

==== Example 3: Explicit Namespace ====

**Requirement:** Always show the same namespace.

<code>
{{wvds:acmenu ns="en:api"}}
</code>

**Result:**
  * Always shows ''en:api'' regardless of current page
  * Useful for fixed navigation blocks

==== Example 4: Multilingual Structure ====

**Structure:**
<code>
/
├── sidebar.txt          (Main menu)
├── de/
│   ├── sidebar1.txt     ({{wvds:acmenu dynamic="2"}})
│   ├── crypto/
│   │   ├── sidebar1.txt ({{wvds:acmenu dynamic="1"}})
│   │   └── openssl/
│   └── docs/
├── en/
│   ├── sidebar1.txt
│   └── ...
└── sl/
    ├── sidebar1.txt
    └── ...
</code>

----

===== Typical Sidebar Configuration =====

==== Root: sidebar.txt ====

<code>
~~NOCACHE~~
{{wvds:snippet>main_menu}}
</code>

==== Language Namespace: en/sidebar1.txt ====

<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu dynamic="2"}}
</code>

==== Sub-Namespace: en/crypto/sidebar1.txt ====

<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu dynamic="1"}}
</code>

----

===== How It Works =====

==== Processing Pipeline ====

<code>
1. Parameter Evaluation
   ├── ns="" → Use explicit namespace
   ├── dynamic="N" → Calculate namespace
   └── (empty) → Search sidebar* upward

2. Namespace Resolution
   └── Determine start namespace for menu
   └── Check access permissions

3. Tree Building
   └── Read all pages and sub-namespaces
   └── Filter by access permissions
   └── Sort alphabetically

4. HTML Generation
   └── Create nested <ul>/<li> structure
   └── Mark current page (.curid)
   └── Mark open paths (.open)

5. JavaScript Integration
   └── Accordion behavior
   └── Cookie storage for open folders
</code>

----

===== CSS Classes =====

==== Container ====

^ Class ^ Description ^
| ''.acmenu'' | Main menu container |
| ''.acmenu ul'' | List container |
| ''.acmenu li'' | List element |

==== Status Classes ====

^ Class ^ Description ^
| ''.open'' | Open folder (namespace) |
| ''.closed'' | Closed folder |
| ''.curid'' | Current page |
| ''.divert'' | External namespace (with own sidebar) |

==== Element Classes ====

^ Class ^ Description ^
| ''.idx'' | Index element |
| ''.level1'', ''.level2'', ... | Nesting depth |
| ''.page'' | Page link |
| ''.ns'' | Namespace folder |

----

===== Configuration =====

==== Admin Settings ====

Via **Admin → Configuration → wvdsacmenu**:

^ Setting ^ Type ^ Default ^ Description ^
| ''startOpen'' | On/Off | Off | Open all folders by default |
| ''sortType'' | Select | alpha | Sorting: alpha, date, custom |
| ''showPageTitle'' | On/Off | On | Show page title instead of ID |
| ''maxDepth'' | Number | 0 | Max depth (0 = unlimited) |

----

===== Cookie Storage =====

Open folders are stored in the browser:

^ Cookie ^ Content ^
| ''plugin_wvdsacmenu_open_items'' | Comma-separated list of open folders |

<note tip>
The cookie allows the menu structure to persist across page changes.
</note>

----

===== Error Handling =====

==== Behavior on Errors ====

^ Scenario ^ Behavior ^
| Namespace not found | Shows empty menu |
| No permission | Filters inaccessible pages |
| Invalid dynamic value | Falls back to root |
| Circular reference | Stops at max depth |

----

===== Performance =====

==== Recommendations ====

| Scenario | Recommendation |
| Small namespaces (<50 pages) | Normal usage |
| Large namespaces (50-200) | Limit ''maxDepth'' |
| Very large namespaces (>200) | Split into sub-namespaces |
| Dynamic content | Use ''~~NOCACHE~~'' |

----

===== Version History =====

^ Version ^ Date ^ Changes ^
| 1.0.0 | 2025-01-06 | WvdS extensions: Wiki syntax, dynamic, sidebar* detection |

----

===== See Also =====

  * [[wvdschunk]] - HTML chunks for menus
  * [[wvdslang]] - Multilingual menu text
  * [[flat]] - Template with sidebar support

----

===== Technical Reference =====

==== Class: syntax_plugin_wvdsacmenu ====

**File:** ''lib/plugins/wvdsacmenu/syntax.php''

^ Method ^ Description ^
| ''getType()'' | Returns ''substition'' |
| ''getSort()'' | Returns ''320'' |
| ''connectTo($mode)'' | Registers pattern |
| ''handle($match, ...)'' | Parses parameters |
| ''render($mode, ...)'' | Generates HTML |

==== Private Methods ====

^ Method ^ Parameters ^ Description ^
| ''_get_ns_acmenu()'' | - | Determines start namespace |
| ''_findSidebar()'' | $dir | Searches for sidebar* file |
| ''_buildTree()'' | $ns, $depth | Builds menu tree |
| ''_renderItem()'' | $item | Renders single element |

==== JavaScript ====

**File:** ''lib/plugins/wvdsacmenu/script.js''

  * Accordion click handler
  * Cookie management
  * Smooth scroll to current element

----

{{wvds:snippet>wvds_audit_badge}}

~~DISCUSSION~~