====== AcMenu Plugin ======

---- plugin ----
description: An accordion menu for namespaces and relative pages
author     : Torpedo
email      : dcstoyanov@gmail.com
type       : syntax
lastupdate : 2023-11-22
compatible : 2017-02-19 "Frusterick Manners", 2018-04-22 "Greebo", 2020-06-01 "Hogfather", 2022-07-31 "Igor", 2023-04-04 "Jack Jackrum", 2024-02-06 "Kaos"
depends    : 
conflicts  : 
similar    : 
tags       : menu, navigation

downloadurl: https://github.com/tormec/AcMenu/archive/master.zip
bugtracker : https://github.com/tormec/AcMenu/issues
sourcerepo : https://github.com/tormec/AcMenu
donationurl: 

screenshot_img : 
----


===== Description =====

AcMenu provides an accordion menu that lists the content of namespaces in a tree-like format.

The namespace tree is built starting from the namespace where the plugin syntax is placed and going through all the sub-namespaces but those containing a sidebar page.

This plugin respects the [[:ACL]] rules besides the [[config:sneaky_index]] and [[config:hidepages]] options that come with your DokuWiki configuration.


===== Installation =====

Search and install ​the plugin using the [[plugin:extension|Extension ​Manager]]. Refer to [[:plugin_installation_instructions|Plugin Installation Instructions]] on how to install plugins manually.


===== Syntax =====

In the [[config:sidebar|sidebar]] page, use the syntax:
<code>
<acmenu>
</code>


===== Examples =====

Just some screenshots to give an overall idea of the final result.

It is supposed the following wiki structure which has two separate sidebars:
<code>
+--sidebar.txt
+--start.txt
+--products
|  +--start.txt
|  +--product_a.txt
+--services
|  +--start.txt
|  +--service_a.txt
+--branch
   +--sidebar.txt
   +--start.txt
   +--private
   |  +--start.txt
   |  +--confidential.txt
   +--products
   |  +--start.txt
   |  +--product_b.txt
   +--services
      +--start.txt
      +--service_b.txt
</code>
where the two ''sidebar.txt'' have the syntax, respectively:
  * in '':sidebar.txt'' <code>
<acmenu>
</code>
  * in '':branch:sidebar.txt'' <code>
[[..:start| Go Back]]
<acmenu>
</code> where the ''Go Back'' link is made according to the [[:namespaces|namespaces]] criterion.

When a visitor is in '':start.txt'' the plugin shows the complete namespace tree collapsed except the namespace containing the root sidebar.

If the visitor decides to open the sub-namespace '':branch'', the plugin shows only its sidebar.

To deny access to certain namespaces or pages, the appropriate rule in the [[:ACL]] management must be set. In addition, it's possible to conceal those namespaces for which the visitor has no read permission defining the [[config:sneaky_index]] option in your Configuration Manager.

Furthermore, it's possible to hide the ''sidebar.txt'' and the ''start.txt'' pages((The explanation of the regular expression used in this example is the following:
  - alternative matches must be separated by ''|''
  - to match a word at the end of a line the ''$'' symbol must be used
  - to be sure that the word to match is preceded by '':'' or by any character ''.'' followed by '':'' use ''%%(?<= )%%''

With that syntax, the following pages will be hidden:
  * '':sidebar''
  * '':namespace:sidebar''
  * '':namespace:start''
Whereas the following one will remain visible:
  * '':start''

Even if the hidden pages are not listed among the search results, they will still be reachable by typing their exact path in the search bar (eg. ''sidebar'' or ''namespace:sidebar'').
)) using the [[config:hidepages]] option in your Configuration Manager:
<code>
(?<=:)sidebar$|(?<=.:)start$|other-matches
</code>

The following image is the behavior of the AcMenu plugin in action.
{{ https://raw.githubusercontent.com/tormec/AcMenu/master/images/acmenu.gif?nolink&recache }}

Since this plugin uses cookies to remember the pages visited (they are automatically deleted as soon as the window browser is closed) if the visitor comes back to '':start.txt'' every namespace untoggled will remain so.

The order in which the directory tree is presented is the following:
  * first, folders from ''0-9A-Za-z''
  * then, files from ''0-9A-Za-z''
This means that, if the option [[config:useheading]] is enabled, it's possible to force the order of files using a progressive numeration in the first heading of each file.

Note also that the [[config:startpage]] is intentionally always kept on top of its menu and it's never renamed with its first heading, in order to provide a visual reference for the navigation.




===== Customization =====


If doesn't exist yet, create a [[devel:css#user_styles|user-style]] CSS ''conf/userstyle.css'' and replace the plugin's CSS instructions as you please.

For instance, the list item markers can be changed with the following code:
<code css userstyle.css>
.acmenu ul.idx li.closed {
    list-style-image: url(../lib/images/plus.gif);
}

.acmenu ul.idx li.open {
    list-style-image: url(../lib/images/minus.gif);
}
</code>

It's also possible to change the DokuWiki's style only inside the plugin:
<code css userstyle.css>
.dokuwiki .acmenu .aside a:visited {
background-color: none;
}

.dokuwiki .acmenu span.curid a {
background-color: silver;
color: black;
}
</code>

Use the Inspect Tool provided with your browser to test all the possible styles.


===== Troubleshooting =====

**Symptom:** AcMenu isn't keeping unfolded any previously opened namespace.

**Possible solution:** be sure that JavaScript and cookies are enabled in your browser, otherwise AcMenu forgets the previously namespaces untoggled whenever a page is loaded.